3 .\" (C) Lluis Sanchez Gual (lluis@ximian.com)
7 genxs \- Mono's Xml Serializer Generator
11 configurationFile [destinationFolder]
14 is a tool for generating custom XML serialization writers and readers for
18 is configuration file which specifies several
19 information, such as the class for which to generate the reader and writer, the
20 name and namespace of the classes to generate, and a collection of hooks to
21 apply. By using hooks it is possible to customize the
22 behavior of the serializer without needing to modify the generated file, so you
23 can safely regenerate it if the source class is modified.
26 specifies the folder where the files will be generated.
29 This tool only runs in the Mono runtime, since it uses some internal
30 classes not available in other runtimes.
31 .SH CONFIGURATION FILE FORMAT
32 The configuration file is an xml document based on the following grammar
33 ("?" means optional, "*" 0 or more):
37 <serializer class="name" assembly="name"> *
38 <reader>name</reader> ?
39 <writer>name</writer> ?
40 <namespace>name</namespace> ?
41 <outFileName>name</outFileName> ?
52 A configuration file can have multiple "serializer" elements, each of which
53 specifies the class for which to generate a serializer together with several
54 generation options. The source class is specified in the following attributes:
58 : name of the class (including namespace).
61 : assembly name. It can include the complete path.
63 Generation options are specified in child elements:
67 : name of the reader class.
70 : name of the writer class.
73 : namespace of the reader and writer classes.
76 : name of the generated file.
79 : a list of hooks to apply to the reader.
82 : a list of hooks to apply to the writer.
84 Using hooks you can customize the behavior of readers and writers.
85 A hook specification follows this grammar:
90 <typeName>name</typeName> ?
91 <typeAttribute>name</typeAttribute> *
92 <typeMember>name</typeMember> ?
94 <replace>source code</replace> ?
95 <insertBefore>source code</insertBefore> ?
96 <insertAfter>source code</insertAfter> ?
100 The "type" attribute specifies the context in which the hook is applied. It can
101 be one of the following:
105 : hook is applied where attributes are serialized/deserialized.
108 : hook is applied where elements are serialized/deserialized.
111 : hook is applied where unknown attributes are processed.
114 : hook is applied where unknown elements are processed.
117 : hook is applied where a member is serialized/deserialized.
120 : hook is applied for the whole type.
122 The "select" element specifies the classes and members to which the hook has
123 to be added. It can contain the following elements:
127 : the class with that name will be selected (must include namespace)
130 : all classes which have that attribute applied will be selected (specify the
131 full attribute class name, including namespace). Several attribute names can be
135 : name of the class member for which the hook must be added.
137 The hook source code can be specified using any of the following elements:
141 : the provided source code will replace all serialization/deserialization
142 operations in the hook context.
145 : the source code will be added before the hook context.
148 : the source code will be added after the hook context.
150 When writing the code for a hook you can use some special variables that are
151 defined during the code generation process. The variables are the following:
155 name of the class being generated, without namespace.
158 full name of the class being generated, including namespace.
161 the object being serialized or deserialized. When using a replace
162 reader hook of type "type", the hook code must assign the deserialized object
166 name of the element of the object being serialized/deserialized.
169 namespace of the element of the object being serialized/deserialized.
172 name of the member being serialized/deserialized. Only valid in the "member"
175 The following example adds a call to a Validate method after the deserialization
181 System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
186 This example specifies the code to be used to deserialize the XmlSchema class:
191 <typeName>System.Xml.Schema.XmlSchema</typeName>
194 $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
199 That one specifies the code to be used to read XmlSchema instances:
204 <typeName>System.Xml.Schema.XmlSchema</typeName>
206 <replace>$OBJECT.Write (Writer);</replace>
210 With this two hooks the serializer will print some information when serializing
216 <typeName>MyNamespace.MyClass</typeName>
218 <insertBefore>Console.WriteLine ("Serializing MyClass");</replace>
219 <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
223 <typeName>MyNamespace.MyClass</typeName>
226 Console.WriteLine ("Serialized member $MEMBER");
231 This hook writes an additional element for all types that have the custom
232 attribute "MyAttribute":
235 <hook type="elements">
237 <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
240 Writer.WriteStartElement ("privateData");
241 Writer.WriteString ($OBJECT.PrivateData);
242 Writer.WriteEndElement ();
246 .SH CONFIGURATION FILE EXAMPLE
247 This is the configuration file used to generate the serializer for ServiceDescription:
251 <serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services">
252 <reader>ServiceDescriptionReaderBase</reader>
253 <writer>ServiceDescriptionWriterBase</writer>
254 <namespace>System.Web.Services.Description</namespace>
255 <outFileName>ServiceDescriptionSerializerBase.cs</outFileName>
257 <hook type="unknownElement">
259 <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
261 <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
265 <typeName>System.Xml.Schema.XmlSchema</typeName>
267 <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
271 <hook type="elements">
273 <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
275 <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
279 <typeName>System.Xml.Schema.XmlSchema</typeName>
281 <replace>$OBJECT.Write (Writer);</replace>
288 Lluis Sanchez Gual (lluis@ximian.com)
291 GenXS is released under the terms of the GNU GPL.