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 : if "true", it does not generate reader class.
73 : name of the writer class.
76 : if "true", it does not generate writer class.
79 : namespace of the reader and writer classes.
82 : if "true", it generates classes as internal.
85 : name of the generated file.
88 : a list of hooks to apply to the reader.
91 : a list of hooks to apply to the writer.
93 Using hooks you can customize the behavior of readers and writers.
94 A hook specification follows this grammar:
99 <typeName>name</typeName> ?
100 <typeAttribute>name</typeAttribute> *
101 <typeMember>name</typeMember> ?
103 <replace>source code</replace> ?
104 <insertBefore>source code</insertBefore> ?
105 <insertAfter>source code</insertAfter> ?
109 The "type" attribute specifies the context in which the hook is applied. It can
110 be one of the following:
114 : hook is applied where attributes are serialized/deserialized.
117 : hook is applied where elements are serialized/deserialized.
120 : hook is applied where unknown attributes are processed.
123 : hook is applied where unknown elements are processed.
126 : hook is applied where a member is serialized/deserialized.
129 : hook is applied for the whole type.
131 The "select" element specifies the classes and members to which the hook has
132 to be added. It can contain the following elements:
136 : the class with that name will be selected (must include namespace)
139 : all classes which have that attribute applied will be selected (specify the
140 full attribute class name, including namespace). Several attribute names can be
144 : name of the class member for which the hook must be added.
146 The hook source code can be specified using any of the following elements:
150 : the provided source code will replace all serialization/deserialization
151 operations in the hook context.
154 : the source code will be added before the hook context.
157 : the source code will be added after the hook context.
159 When writing the code for a hook you can use some special variables that are
160 defined during the code generation process. The variables are the following:
164 name of the class being generated, without namespace.
167 full name of the class being generated, including namespace.
170 the object being serialized or deserialized. When using a replace
171 reader hook of type "type", the hook code must assign the deserialized object
175 name of the element of the object being serialized/deserialized.
178 namespace of the element of the object being serialized/deserialized.
181 name of the member being serialized/deserialized. Only valid in the "member"
184 The following example adds a call to a Validate method after the deserialization
190 System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
195 This example specifies the code to be used to deserialize the XmlSchema class:
200 <typeName>System.Xml.Schema.XmlSchema</typeName>
203 $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
208 That one specifies the code to be used to read XmlSchema instances:
213 <typeName>System.Xml.Schema.XmlSchema</typeName>
215 <replace>$OBJECT.Write (Writer);</replace>
219 With this two hooks the serializer will print some information when serializing
225 <typeName>MyNamespace.MyClass</typeName>
227 <insertBefore>Console.WriteLine ("Serializing MyClass");</replace>
228 <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
232 <typeName>MyNamespace.MyClass</typeName>
235 Console.WriteLine ("Serialized member $MEMBER");
240 This hook writes an additional element for all types that have the custom
241 attribute "MyAttribute":
244 <hook type="elements">
246 <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
249 Writer.WriteStartElement ("privateData");
250 Writer.WriteString ($OBJECT.PrivateData);
251 Writer.WriteEndElement ();
255 .SH CONFIGURATION FILE EXAMPLE
256 This is the configuration file used to generate the serializer for ServiceDescription:
260 <serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services">
261 <reader>ServiceDescriptionReaderBase</reader>
262 <writer>ServiceDescriptionWriterBase</writer>
263 <namespace>System.Web.Services.Description</namespace>
264 <outFileName>ServiceDescriptionSerializerBase.cs</outFileName>
266 <hook type="unknownElement">
268 <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
270 <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
274 <typeName>System.Xml.Schema.XmlSchema</typeName>
276 <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
280 <hook type="elements">
282 <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
284 <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
288 <typeName>System.Xml.Schema.XmlSchema</typeName>
290 <replace>$OBJECT.Write (Writer);</replace>
297 Lluis Sanchez Gual (lluis@ximian.com)
300 GenXS is released under the terms of the GNU GPL.