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