1genxs(1) General Commands Manual genxs(1)
2
3
4
6 genxs - Mono's Xml Serializer Generator
7
9 genxs configurationFile [destinationFolder]
10
12 genxs is a tool for generating custom XML serialization writers and
13 readers for classes.
14
15 configurationFile is configuration file which specifies several infor‐
16 mation, such as the class for which to generate the reader and writer,
17 the name and namespace of the classes to generate, and a collection of
18 hooks to apply. By using hooks it is possible to customize the behavior
19 of the serializer without needing to modify the generated file, so you
20 can safely regenerate it if the source class is modified.
21
22 destinationFolder specifies the folder where the files will be gener‐
23 ated.
24
25 NOTE: This tool only runs in the Mono runtime, since it uses some
26 internal classes not available in other runtimes.
27
29 The configuration file is an xml document based on the following gram‐
30 mar ("?" means optional, "*" 0 or more):
31
32 <configuration>
33 <serializer class="name" assembly="name"> *
34 <reader>name</reader> ?
35 <writer>name</writer> ?
36 <namespace>name</namespace> ?
37 <outFileName>name</outFileName> ?
38 <readerHooks> ?
39 <hook ...> *
40 </readerHooks>
41 <writerHooks> ?
42 <hook ...> *
43 </writerHooks>
44 </serializer>
45 </configuration>
46
47 A configuration file can have multiple "serializer" elements, each of
48 which specifies the class for which to generate a serializer together
49 with several generation options. The source class is specified in the
50 following attributes:
51
52 * class : name of the class (including namespace).
53
54 * assembly : assembly name. It can include the complete path.
55
56 Generation options are specified in child elements:
57
58 * reader : name of the reader class.
59
60 * noReader : if "true", it does not generate reader class.
61
62 * writer : name of the writer class.
63
64 * baseSerializer : name of the base xml serializer class. This item
65 is 2.0 only.
66
67 * implementation : name of the serializer implementation class. This
68 item is 2.0 only.
69
70 * noWriter : if "true", it does not generate writer class.
71
72 * namespace : namespace of the reader and writer classes.
73
74 * generateAsInternal : if "true", it generates classes as internal.
75
76 * outFileName : name of the generated file.
77
78 * readerHooks : a list of hooks to apply to the reader.
79
80 * writerHooks : a list of hooks to apply to the writer.
81
83 Using hooks you can customize the behavior of readers and writers. A
84 hook specification follows this grammar:
85
86 <hook type="name">
87 <select> ?
88 <typeName>name</typeName> ?
89 <typeAttribute>name</typeAttribute> *
90 <typeMember>name</typeMember> ?
91 </select>
92 <replace>source code</replace> ?
93 <insertBefore>source code</insertBefore> ?
94 <insertAfter>source code</insertAfter> ?
95 </hook>
96
97 The "type" attribute specifies the context in which the hook is
98 applied. It can be one of the following:
99
100 * attributes : hook is applied where attributes are serialized/dese‐
101 rialized.
102
103 * elements : hook is applied where elements are serialized/deserial‐
104 ized.
105
106 * unknownAttribute : hook is applied where unknown attributes are
107 processed.
108
109 * unknownElement : hook is applied where unknown elements are pro‐
110 cessed.
111
112 * member : hook is applied where a member is serialized/deserial‐
113 ized.
114
115 * type : hook is applied for the whole type.
116
117 The "select" element specifies the classes and members to which the
118 hook has to be added. It can contain the following elements:
119
120 * typeName : the class with that name will be selected (must include
121 namespace)
122
123 * typeAttribute : all classes which have that attribute applied will
124 be selected (specify the full attribute class name, including
125 namespace). Several attribute names can be specified.
126
127 * typeMember : name of the class member for which the hook must be
128 added.
129
130 The hook source code can be specified using any of the following ele‐
131 ments:
132
133 * replace : the provided source code will replace all serializa‐
134 tion/deserialization operations in the hook context.
135
136 * insertBefore : the source code will be added before the hook con‐
137 text.
138
139 * insertAfter : the source code will be added after the hook con‐
140 text.
141
142 When writing the code for a hook you can use some special variables
143 that are defined during the code generation process. The variables are
144 the following:
145
146 * $TYPE: name of the class being generated, without namespace.
147
148 * $FULLTYPE: full name of the class being generated, including
149 namespace.
150
151 * $OBJECT: the object being serialized or deserialized. When using a
152 replace reader hook of type "type", the hook code must assign the
153 deserialized object to this variable.
154
155 * -I $ELEMENT: name of the element of the object being serial‐
156 ized/deserialized.
157
158 * $NAMESPACE: namespace of the element of the object being serial‐
159 ized/deserialized.
160
161 * $MEMBER: name of the member being serialized/deserialized. Only
162 valid in the "member" context.
163
165 The following example adds a call to a Validate method after the dese‐
166 rialization of any object:
167
168 <hook type="type">
169 <insertAfter>
170 System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
171 </insertAfter>
172 </hook>
173
174 This example specifies the code to be used to deserialize the XmlSchema
175 class:
176
177 <hook type="type">
178 <select>
179 <typeName>System.Xml.Schema.XmlSchema</typeName>
180 </select>
181 <replace>
182 $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
183 </replace>
184 </hook>
185
186 That one specifies the code to be used to read XmlSchema instances:
187
188 <hook type="type">
189 <select>
190 <typeName>System.Xml.Schema.XmlSchema</typeName>
191 </select>
192 <replace>$OBJECT.Write (Writer);</replace>
193 </hook>
194
195 With this two hooks the serializer will print some information when
196 serializing the class "MyClass":
197
198 <hook type="type">
199 <select>
200 <typeName>MyNamespace.MyClass</typeName>
201 </select>
202 <insertBefore>Console.WriteLine ("Serializing MyClass");</replace>
203 <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
204 </hook>
205 <hook type="member">
206 <select>
207 <typeName>MyNamespace.MyClass</typeName>
208 </select>
209 <insertAfter>
210 Console.WriteLine ("Serialized member $MEMBER");
211 </insertAfter>
212 </hook>
213
214 This hook writes an additional element for all types that have the cus‐
215 tom attribute "MyAttribute":
216
217 <hook type="elements">
218 <select>
219 <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
220 </select>
221 <insertAfter>
222 Writer.WriteStartElement ("privateData");
223 Writer.WriteString ($OBJECT.PrivateData);
224 Writer.WriteEndElement ();
225 </insertAfter>
226 </hook>
227
229 This is the configuration file used to generate the serializer for Ser‐
230 viceDescription:
231
232 <configuration>
233 <serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services">
234 <reader>ServiceDescriptionReaderBase</reader>
235 <writer>ServiceDescriptionWriterBase</writer>
236 <namespace>System.Web.Services.Description</namespace>
237 <outFileName>ServiceDescriptionSerializerBase.cs</outFileName>
238 <readerHooks>
239 <hook type="unknownElement">
240 <select>
241 <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
242 </select>
243 <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
244 </hook>
245 <hook type="type">
246 <select>
247 <typeName>System.Xml.Schema.XmlSchema</typeName>
248 </select>
249 <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
250 </hook>
251 </readerHooks>
252 <writerHooks>
253 <hook type="elements">
254 <select>
255 <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
256 </select>
257 <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
258 </hook>
259 <hook type="type">
260 <select>
261 <typeName>System.Xml.Schema.XmlSchema</typeName>
262 </select>
263 <replace>$OBJECT.Write (Writer);</replace>
264 </hook>
265 </writerHooks>
266 </serializer>
267 </configuration>
268
270 Lluis Sanchez Gual (lluis@ximian.com)
271
273 GenXS is released under the terms of the GNU GPL.
274
276 mono(1), mcs(1), sgen(1)
277
278
279
280 genxs(1)