Documentation

To use ADCG, you must define the wanted data structure: you can do this in two ways:

• Using the proprietary definition xml file (SDF file), that is the simplest way starting from scratch.
• Using a standard Xml Schema (XSD file).

1. Define your data structure using an SDF file

The xml schema for this format of file is available here.
Anyhow, the format is quite simple and we can learn it viewing some examples.

Take a look at this SDF file , that describes a typical structure of personal infomation:

The root tag, <adcg>, allows some general control parameters:

• indentMode (optional, default spaces): controls code indentation type ("tab" or "spaces").
• indentSize (optional, default 2): defines how many characters to be used for indentation.
• implementXmlSerialization (optional, default false): turn on the generation of the code for automatic Xml Serialization.
• implementCloneable (optional, default false): turn on the implementation of ICloneable interface. Default is false.
• lowercaseTags (optional, default false): if true, force to lowercase the element name in the Xml binding, only for the elements with the tag name not customized with the attribute tag.

The <classes> element contains a list of the different classes of the data structure, it also defines the namespace to be used for the classes.
There could be more classes groups, each with a different namespace.

• namespace (optional): the C# namespace to be used for this group of classes.
• xmlNamespace (optional): the Xml namespace to be used for Xml binding for this group of classes.

Every <class> element defines a complex type of the data structure that will be mapped to a C# class.

• name: the name of the complex type.
• tag (optional): customize the tag name in Xml binding. If not specified, name is used.
  Please note that this is used only for top level classes. When a class is used as a property in another class, the tag attribute of the <property> element is used.
  

Inside the class element, the tags <property> defines the list of the properties of the class. Every property could be of a standard type (see the table below for a list of the C# standard types supported) or another complex type.

• name: property name.
• type : property type, could be one of the standard types of the .NET Framework, or another complex custom type defined in the SDF file.
• maxOcc (optional): can be "1" (default value), that mean only one instance of the element, or "*", to indicate an unbounded collection.
• tag (optional): customize the tag or attribute name in Xml binding. If not specified, name is used.
• xmlNodeType (optional, available from 0.3.2): can be "attribute" (default value) or "element".
  This command force the binding as xml element (instead of xml attribute) for standard types elements with single occurrence. If not specified, standard types properties with single multiplicity will be treated as xml attributes. Non standard types (i.e. complex types) or every element with multiple occurrencies are always treated as xml elements.

2. Define your data structure using an XSD file

ADCG does not support all features of XDS technology.
Here there is a summary of the supported and not supported syntax.

Supported XSD Elements

Simple Elements and Attributes declarations, also with restrictions, like:

	<xs:element name="car">
		<xs:simpleType>
 			<xs:restriction base="xs:string">
				<xs:enumeration value="Audi"/>
				<xs:enumeration value="Golf"/>
				<xs:enumeration value="BMW"/>
			</xs:restriction>
		</xs:simpleType>
	</xs:element>

Element type referencing is also supported:

<xs:element ref="lastnameType"/>

Complex Elements declaration are supported,

	<xs:element name="employee">
		<xs:complexType>
			<xs:sequence>
				<xs:element type="xs:string" name="firstname"></xs:element>
				<xs:element type="xs:string" name="lastname"></xs:element>
			</xs:sequence>
		</xs:complexType>
	</xs:element>

Not supported XSD Elements

Other often used xsd elements but not yet supported:

• <xs:complexContent>
• Attribute "mixed" (mixed content are not supported)
• Attribute "use"
• Attribute "default"
• Attibute "fixed"
• <xs:group>
• <xs:attributeGroup>
• <xs:any>
• <xs:anyAttribute>
• <xs:import>
• <xs:include>

ADCG Extensions

• Customize class names, if you want class names that are different from xml element names.
  To do that, simply use an attribute adcg:Name on <xs:element> or <xs:attribute> tags.
• Define the Root element, using the attribute adcg:isRoot="true" on the element to be used as root element.
• Define class namespace (@adcg:classNamespace on <xs:schema> element)

3. Run the tool

To run the tool you can use the Test Page, or download the program and run ADCG from the command line:

ADCG <sdfFilePath> <outputFolder>

<sdfFilePath>: the path of the structure descriptor file (SDF or XSD file, see paragraph above).
<outputFolder>: the folder where to put the generated source files.

Running the tool with the example SDF file described in this documentation, these are the output .cs files generated
Rubric.cs
Person.cs
Address.cs
PersonCollection.cs
AddressCollection.cs
StringCollection.cs

4. Using of the generated classes

Below there is an example on how use the classes and how to make a correct serialization.

Note: if you use the code with .NET 1.1, it does not support XmlRootAttribute when the class implements IXmlSerializable. For .NET 1.1 you have to call CreateXmlSerializer(), a method exposed by the generated classes to obtain a correct XmlSerializer instance to make a correct serialization when using customized tag names.
.NET 2.0 resolves this problem and a normal XmlSerializer instance can be create for serialization.

  //Create the rubric object
  Rubric r = new Rubric();

  //Create a new person
  Person p = new Person();
  p.Name = "Christian";
  p.Surname = "Salvaneschi";
  p.Gender = true;
  p.BirthDate = new DateTime(1975,7,15);

  //Create a new address
  Address a = new Address();
  a.Street = "P.za Aldo Moro";
  a.City = "Casarza Ligure";
  a.ZIPCode = 16030;
  a.State = "Genova";
  a.Country = "Italy";

  //Attach this address as the main address of the person
  p.MainAddress = a;

  //Add the person into the rubric
  r.People.Add(p);

  //Schema generation
  XmlSchema s = r.GetSchema(); 
  XmlTextWriter writer = new XmlTextWriter("c:\\MySchema.xsd", Encoding.ASCII);
  writer.Formatting = Formatting.Indented;
  s.Write(writer);
  writer.Close();
  
  //Xml Serialization
  //For .NET 1.1, get the XmlSerializer from the rubric object
  XmlSerializer serializer = r.CreateXmlSerializer();  
  //For .NET 2.0, create a normal serializer
  XmlSerializer serializer = new XmlSerializer(typeof(Rubric));  
  
  writer = new XmlTextWriter("c:\\MySerialization.xml", System.Text.Encoding.ASCII);
  writer.Formatting = Formatting.Indented;
  serializer.Serialize(writer, r);
  writer.Close();

Using the code above, these are the result files:
MySchema.xsd
MySerialization.xml