Dasher Schema

Dasher tolerates some degree of mismatch in structure between types when they are deserialised, relative to the structure of the type that was used for serialisation. This repository provides build-time tooling to generate explicit externalised schemas (in XML) for your serialisable types and to check that Dasher's compatibility rules have been adhered to.

Dasher.Schema

This library assembly provides attribute annotations for classes that you will serialise or deserialise using Dasher. The schema generation tool (see below) can then use those annotations to generate an explicit schema for your serialisable types. It also provides Serialiser and Deserialiser wrapper classes which check (on construction via their GetSerialiser and GetDeserialiser factory methods) that their generic type arguments are annotated with the [DasherSerialisable] attribute parameterised with the correct usage mode (SerialiseOnly, DeserialiseOnly or SerialiseDeserialise, as appropriate).

Annotate types that you wish to mark for inclusion in the schema as follows:

using Dasher.Schema;

[DasherSerialisable(SupportedOperations.SerialiseDeserialise, "Optional description of this type")]
public sealed class UserScoreWithDefaultScore
{
    public UserScoreWithDefaultScore(string name, int score = 100)
    {
        Name = name;
        Score = score;
    }

    public string Name { get; }
    public int Score { get; }
}

The optional description will be put into the schema if provided, but is not used otherwise by the tooling in this repository.

Dasher.Schema.Generation

This tool uses the annotations above to generate an explicit schema file.

On a rebuild of the project an XML file will be created or updated in the project directory and also the output directory.

To make use of this, add the following step to the Post-build Event Command Line in your Visual Studio project (right-click the project then choose Properties, then go to the Build Events tab):

PATH-TO-EXE\Dasher.Schema.Generation --targetDir="$(TargetDir)\" --targetPath="$(TargetPath)" --projectDir="$(ProjectDir)\" --outputFileName="App.manifest" --rootElementTag=App --typeElementTag="Message" --serialisableTypesTag="SendsMessages" --deserialisableTypesTag="ReceivesMessages"

If you have installed using NuGet from Nuget Gallery then PATH-TO-EXE will be $(SolutionDir)\packages\Dasher.Schema.Generation.VERSION\tools where VERSION is the version you have installed (hopefully being the latest). You can check that from the badge above.

The parameters shown will lead to the manifest being called App.manifest and having contents similar to this:

<?xml version="1.0" encoding="utf-8"?>
<App>
  <SendsMessages>
    <Message name="UserScoreWithDefaultScore">
      <Field name="name" type="System.String" />
      <Field name="score" type="System.Int32" default="100" />
    </Message>
  <SendsMessages>
  <ReceivesMessages>
    <Message name="UserScoreWithDefaultScore">
      <Field name="name" type="System.String" />
      <Field name="score" type="System.Int32" default="100" />
    </Message>
  <ReceivesMessages>
</App>

(Note that the XML element names for the document root, the two sections below that which hold the type entries and the individual entries themselves are specified by command parameters, but the overall structure is fixed.)

Dasher.Schema.Comparison

This tool compares manifests generated by Dasher.Schema.Generation and checks for compatibility between serialisation and deserialisation.

To use this tool, add the following step to the Post-build Event Command Line in your Visual Studio project (right-click the project then choose Properties, then go to the Build Events tab):

PATH-TO-EXE\Dasher.Schema.Comparison --manifestPath="$(ProjectDir)\App.manifest" --otherManifestsDir="%TEMP%\manifests" --manifestFileGlob=*.manifest --typeElementTag="Message" --serialisableTypesTag="SendsMessages" --deserialisableTypesTag="ReceivesMessages"

If you have installed using NuGet from Nuget Gallery then PATH-TO-EXE will be $(SolutionDir)\packages\Dasher.Schema.Comparison.VERSION\tools where VERSION is the version you have installed (hopefully being the latest). You can check that from the badge above.

Set otherManifestsDir to where all your other manifests are stored. This directory is searched recursively. Set manifestFileGlob to a glob that will match the files, e.g., "\*.\*" to match everything, App.manifest to only match files called App.manifest. The remaining parameters specify the XML tag names that will be used when reading the manifest, and should match the ones used for generation.

License

Copyright 2015 Andy Sturrock

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.