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 noReader
  70 : if "true", it does not generate reader class.
  71 .IP "   *" 5
  72 .I writer
  73 : name of the writer class.
  74 .IP "   *" 5
  75 .I baseSerializer
  76 : name of the base xml serializer class. This item is 2.0 only.
  77 .IP "   *" 5
  78 .I implementation
  79 : name of the serializer implementation class. This item is 2.0 only.
  80 .IP "   *" 5
  81 .I noWriter
  82 : if "true", it does not generate writer class.
  83 .IP "   *" 5
  84 .I namespace
  85 : namespace of the reader and writer classes.
  86 .IP "   *" 5
  87 .I generateAsInternal
  88 : if "true", it generates classes as internal.
  89 .IP "   *" 5
  90 .I outFileName
  91 : name of the generated file.
  92 .IP "   *" 5
  93 .I readerHooks
  94 : a list of hooks to apply to the reader.
  95 .IP "   *" 5
  96 .I writerHooks
  97 : a list of hooks to apply to the writer.
  98 .SH SPECIFYING HOOKS
  99 Using hooks you can customize the behavior of readers and writers.
 100 A hook specification follows this grammar:
 101 .PP
 102 .nf
 103         <hook type="name">
 104                 <select> ?
 105                         <typeName>name</typeName> ?
 106                         <typeAttribute>name</typeAttribute> *
 107                         <typeMember>name</typeMember> ?
 108                 </select>
 109                 <replace>source code</replace> ?
 110                 <insertBefore>source code</insertBefore> ?
 111                 <insertAfter>source code</insertAfter> ?
 112         </hook>
 113 .fi
 114 .PP
 115 The "type" attribute specifies the context in which the hook is applied. It can
 116 be one of the following:
 117 .PP
 118 .IP "   *" 5
 119 .I attributes
 120 : hook is applied where attributes are serialized/deserialized.
 121 .IP "   *" 5
 122 .I elements
 123 : hook is applied where elements are serialized/deserialized.
 124 .IP "   *" 5
 125 .I unknownAttribute
 126 : hook is applied where unknown attributes are processed.
 127 .IP "   *" 5
 128 .I unknownElement
 129 : hook is applied where unknown elements are processed.
 130 .IP "   *" 5
 131 .I member
 132 : hook is applied where a member is serialized/deserialized.
 133 .IP "   *" 5
 134 .I type
 135 : hook is applied for the whole type.
 136 .PP
 137 The "select" element specifies the classes and members to which the hook has
 138 to be added. It can contain the following elements:
 139 .PP
 140 .IP "   *" 5
 141 .I typeName
 142 : the class with that name will be selected (must include namespace)
 143 .IP "   *" 5
 144 .I typeAttribute
 145 : all classes which have that attribute applied will be selected (specify the
 146 full attribute class name, including namespace). Several attribute names can be
 147 specified.
 148 .IP "   *" 5
 149 .I typeMember
 150 : name of the class member for which the hook must be added.
 151 .PP
 152 The hook source code can be specified using any of the following elements:
 153 .PP
 154 .IP "   *" 5
 155 .I replace
 156 : the provided source code will replace all serialization/deserialization
 157 operations in the hook context.
 158 .IP "   *" 5
 159 .I insertBefore
 160 : the source code will be added before the hook context.
 161 .IP "   *" 5
 162 .I insertAfter
 163 : the source code will be added after the hook context.
 164 .PP
 165 When writing the code for a hook you can use some special variables that are
 166 defined during the code generation process. The variables are the following:
 167 .PP
 168 .IP "   *" 5
 169 .I $TYPE:
 170 name of the class being generated, without namespace.
 171 .IP "   *" 5
 172 .I $FULLTYPE:
 173 full name of the class being generated, including namespace.
 174 .IP "   *" 5
 175 .I $OBJECT:
 176 the object being serialized or deserialized. When using a replace
 177 reader hook of type "type", the hook code must assign the deserialized object
 178 to this variable.
 179 .IP "   *" 5
 180 -I $ELEMENT:
 181 name of the element of the object being serialized/deserialized.
 182 .IP "   *" 5
 183 .I $NAMESPACE:
 184 namespace of the element of the object being serialized/deserialized.
 185 .IP "   *" 5
 186 .I $MEMBER:
 187 name of the member being serialized/deserialized. Only valid in the "member"
 188 context.
 189 .SH HOOK EXAMPLES
 190 The following example adds a call to a Validate method after the deserialization
 191 of any object:
 192 .PP
 193 .nf
 194 <hook type="type">
 195         <insertAfter>
 196                 System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
 197         </insertAfter>
 198 </hook>
 199 .fi
 200 .PP
 201 This example specifies the code to be used to deserialize the XmlSchema class:
 202 .PP
 203 .nf
 204 <hook type="type">
 205         <select>
 206                 <typeName>System.Xml.Schema.XmlSchema</typeName>
 207         </select>
 208         <replace>
 209                 $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
 210         </replace>
 211 </hook>
 212 .fi
 213 .PP
 214 That one specifies the code to be used to read XmlSchema instances:
 215 .PP
 216 .nf
 217 <hook type="type">
 218         <select>
 219                 <typeName>System.Xml.Schema.XmlSchema</typeName>
 220         </select>
 221         <replace>$OBJECT.Write (Writer);</replace>
 222 </hook>
 223 .fi
 224 .PP
 225 With this two hooks the serializer will print some information when serializing
 226 the class "MyClass":
 227 .PP
 228 .nf
 229 <hook type="type">
 230         <select>
 231                 <typeName>MyNamespace.MyClass</typeName>
 232         </select>
 233         <insertBefore>Console.WriteLine ("Serializing MyClass");</replace>
 234         <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
 235 </hook>
 236 <hook type="member">
 237         <select>
 238                 <typeName>MyNamespace.MyClass</typeName>
 239         </select>
 240         <insertAfter>
 241                 Console.WriteLine ("Serialized member $MEMBER");
 242         </insertAfter>
 243 </hook>
 244 .fi
 245 .PP
 246 This hook writes an additional element for all types that have the custom
 247 attribute "MyAttribute":
 248 .PP
 249 .nf
 250 <hook type="elements">
 251         <select>
 252                 <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
 253         </select>
 254         <insertAfter>
 255                 Writer.WriteStartElement ("privateData");
 256                 Writer.WriteString ($OBJECT.PrivateData);
 257                 Writer.WriteEndElement ();
 258         </insertAfter>
 259 </hook>
 260 .fi
 261 .SH CONFIGURATION FILE EXAMPLE
 262 This is the configuration file used to generate the serializer for ServiceDescription:
 263 .PP
 264 .nf
 265 <configuration>
 266         <serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services">
 267                 <reader>ServiceDescriptionReaderBase</reader>
 268                 <writer>ServiceDescriptionWriterBase</writer>
 269                 <namespace>System.Web.Services.Description</namespace>
 270                 <outFileName>ServiceDescriptionSerializerBase.cs</outFileName>
 271                 <readerHooks>
 272                         <hook type="unknownElement">
 273                                 <select>
 274                                         <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
 275                                 </select>
 276                                 <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
 277                         </hook>
 278                         <hook type="type">
 279                                 <select>
 280                                         <typeName>System.Xml.Schema.XmlSchema</typeName>
 281                                 </select>
 282                                 <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
 283                         </hook>
 284                 </readerHooks>
 285                 <writerHooks>
 286                         <hook type="elements">
 287                                 <select>
 288                                         <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
 289                                 </select>
 290                                 <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
 291                         </hook>
 292                         <hook type="type">
 293                                 <select>
 294                                         <typeName>System.Xml.Schema.XmlSchema</typeName>
 295                                 </select>
 296                                 <replace>$OBJECT.Write (Writer);</replace>
 297                         </hook>
 298                 </writerHooks>
 299         </serializer>
 300 </configuration>
 301 .fi
 302 .SH AUTHORS
 303 Lluis Sanchez Gual (lluis@ximian.com)
 304 .PP
 305 .SH LICENSE
 306 GenXS is released under the terms of the GNU GPL.
 307 .PP
 308 .SH SEE ALSO
 309 mono(1), mcs(1), sgen(1)