man/genxs.1

   1 .\"
   2 .\" genxs manual page.
   3 .\" (C) Lluis Sanchez Gual (lluis@ximian.com)
   4 .\"
   5 .TH genxs 1
   6 .SH NAME
   7 genxs \- Mono's Xml Serializer Generator
   8 .SH SYNOPSIS
   9 .PP
  10 .B genxs
  11 configurationFile [destinationFolder]
  12 .SH DESCRIPTION
  13 .I genxs
  14 is a tool for generating custom XML serialization writers and readers for
  15 classes.
  16 .PP
  17 .I configurationFile
  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.
  24 .PP
  25 .I destinationFolder
  26 specifies the folder where the files will be generated.
  27 .PP
  28 .B NOTE:
  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):
  34 .PP
  35 .nf
  36         <configuration>
  37                 <serializer class="name" assembly="name"> *
  38                         <reader>name</reader> ?
  39                         <writer>name</writer> ?
  40                         <namespace>name</namespace> ?
  41                         <outFileName>name</outFileName> ?
  42                         <readerHooks> ?
  43                                 <hook ...> *
  44                         </readerHooks>
  45                         <writerHooks> ?
  46                                 <hook ...> *
  47                         </writerHooks>
  48                 </serializer>
  49         </configuration>
  50 .fi
  51 .PP
  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:
  55 .PP
  56 .IP "   *" 5
  57 .I class
  58 : name of the class (including namespace).
  59 .IP "   *" 5
  60 .I assembly
  61 : assembly name. It can include the complete path.
  62 .PP
  63 Generation options are specified in child elements:
  64 .PP
  65 .IP "   *" 5
  66 .I reader
  67 : name of the reader class.
  68 .IP "   *" 5
  69 .I writer
  70 : name of the writer class.
  71 .IP "   *" 5
  72 .I namespace
  73 : namespace of the reader and writer classes.
  74 .IP "   *" 5
  75 .I outFileName
  76 : name of the generated file.
  77 .IP "   *" 5
  78 .I readerHooks
  79 : a list of hooks to apply to the reader.
  80 .IP "   *" 5
  81 .I writerHooks
  82 : a list of hooks to apply to the writer.
  83 .SH SPECIFYING HOOKS
  84 Using hooks you can customize the behavior of readers and writers.
  85 A hook specification follows this grammar:
  86 .PP
  87 .nf
  88         <hook type="name">
  89                 <select> ?
  90                         <typeName>name</typeName> ?
  91                         <typeAttribute>name</typeAttribute> *
  92                         <typeMember>name</typeMember> ?
  93                 </select>
  94                 <replace>source code</replace> ?
  95                 <insertBefore>source code</insertBefore> ?
  96                 <insertAfter>source code</insertAfter> ?
  97         </hook>
  98 .fi
  99 .PP
 100 The "type" attribute specifies the context in which the hook is applied. It can
 101 be one of the following:
 102 .PP
 103 .IP "   *" 5
 104 .I attributes
 105 : hook is applied where attributes are serialized/deserialized.
 106 .IP "   *" 5
 107 .I elements
 108 : hook is applied where elements are serialized/deserialized.
 109 .IP "   *" 5
 110 .I unknownAttribute
 111 : hook is applied where unknown attributes are processed.
 112 .IP "   *" 5
 113 .I unknownElement
 114 : hook is applied where unknown elements are processed.
 115 .IP "   *" 5
 116 .I member
 117 : hook is applied where a member is serialized/deserialized.
 118 .IP "   *" 5
 119 .I type
 120 : hook is applied for the whole type.
 121 .PP
 122 The "select" element specifies the classes and members to which the hook has
 123 to be added. It can contain the following elements:
 124 .PP
 125 .IP "   *" 5
 126 .I typeName
 127 : the class with that name will be selected (must include namespace)
 128 .IP "   *" 5
 129 .I typeAttribute
 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
 132 specified.
 133 .IP "   *" 5
 134 .I typeMember
 135 : name of the class member for which the hook must be added.
 136 .PP
 137 The hook source code can be specified using any of the following elements:
 138 .PP
 139 .IP "   *" 5
 140 .I replace
 141 : the provided source code will replace all serialization/deserialization
 142 operations in the hook context.
 143 .IP "   *" 5
 144 .I insertBefore
 145 : the source code will be added before the hook context.
 146 .IP "   *" 5
 147 .I insertAfter
 148 : the source code will be added after the hook context.
 149 .PP
 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:
 152 .PP
 153 .IP "   *" 5
 154 .I $TYPE:
 155 name of the class being generated, without namespace.
 156 .IP "   *" 5
 157 .I $FULLTYPE:
 158 full name of the class being generated, including namespace.
 159 .IP "   *" 5
 160 .I $OBJECT:
 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
 163 to this variable.
 164 .IP "   *" 5
 165 -I $ELEMENT:
 166 name of the element of the object being serialized/deserialized.
 167 .IP "   *" 5
 168 .I $NAMESPACE:
 169 namespace of the element of the object being serialized/deserialized.
 170 .IP "   *" 5
 171 .I $MEMBER:
 172 name of the member being serialized/deserialized. Only valid in the "member"
 173 context.
 174 .SH HOOK EXAMPLES
 175 The following example adds a call to a Validate method after the deserialization
 176 of any object:
 177 .PP
 178 .nf
 179 <hook type="type">
 180         <insertAfter>
 181                 System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
 182         </insertAfter>
 183 </hook>
 184 .fi
 185 .PP
 186 This example specifies the code to be used to deserialize the XmlSchema class:
 187 .PP
 188 .nf
 189 <hook type="type">
 190         <select>
 191                 <typeName>System.Xml.Schema.XmlSchema</typeName>
 192         </select>
 193         <replace>
 194                 $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
 195         </replace>
 196 </hook>
 197 .fi
 198 .PP
 199 That one specifies the code to be used to read XmlSchema instances:
 200 .PP
 201 .nf
 202 <hook type="type">
 203         <select>
 204                 <typeName>System.Xml.Schema.XmlSchema</typeName>
 205         </select>
 206         <replace>$OBJECT.Write (Writer);</replace>
 207 </hook>
 208 .fi
 209 .PP
 210 With this two hooks the serializer will print some information when serializing
 211 the class "MyClass":
 212 .PP
 213 .nf
 214 <hook type="type">
 215         <select>
 216                 <typeName>MyNamespace.MyClass</typeName>
 217         </select>
 218         <insertBefore>Console.WriteLine ("Serializing MyClass");</replace>
 219         <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
 220 </hook>
 221 <hook type="member">
 222         <select>
 223                 <typeName>MyNamespace.MyClass</typeName>
 224         </select>
 225         <insertAfter>
 226                 Console.WriteLine ("Serialized member $MEMBER");
 227         </insertAfter>
 228 </hook>
 229 .fi
 230 .PP
 231 This hook writes an additional element for all types that have the custom
 232 attribute "MyAttribute":
 233 .PP
 234 .nf
 235 <hook type="elements">
 236         <select>
 237                 <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
 238         </select>
 239         <insertAfter>
 240                 Writer.WriteStartElement ("privateData");
 241                 Writer.WriteString ($OBJECT.PrivateData);
 242                 Writer.WriteEndElement ();
 243         </insertAfter>
 244 </hook>
 245 .fi
 246 .SH CONFIGURATION FILE EXAMPLE
 247 This is the configuration file used to generate the serializer for ServiceDescription:
 248 .PP
 249 .nf
 250 <configuration>
 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>
 256                 <readerHooks>
 257                         <hook type="unknownElement">
 258                                 <select>
 259                                         <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
 260                                 </select>
 261                                 <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
 262                         </hook>
 263                         <hook type="type">
 264                                 <select>
 265                                         <typeName>System.Xml.Schema.XmlSchema</typeName>
 266                                 </select>
 267                                 <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
 268                         </hook>
 269                 </readerHooks>
 270                 <writerHooks>
 271                         <hook type="elements">
 272                                 <select>
 273                                         <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
 274                                 </select>
 275                                 <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
 276                         </hook>
 277                         <hook type="type">
 278                                 <select>
 279                                         <typeName>System.Xml.Schema.XmlSchema</typeName>
 280                                 </select>
 281                                 <replace>$OBJECT.Write (Writer);</replace>
 282                         </hook>
 283                 </writerHooks>
 284         </serializer>
 285 </configuration>
 286 .fi
 287 .SH AUTHORS
 288 Lluis Sanchez Gual (lluis@ximian.com)
 289 .PP
 290 .SH LICENSE
 291 GenXS is released under the terms of the GNU GPL.
 292 .PP
 293 .SH SEE ALSO
 294 mono(1), mcs(1)