Man Linux: Main Page and Category List

NAME

       genxs - Mono's Xml Serializer Generator

SYNOPSIS

       genxs configurationFile [destinationFolder]

DESCRIPTION

       genxs  is  a  tool  for generating custom XML serialization writers and
       readers for classes.

       configurationFile  is  configuration  file  which   specifies   several
       information,  such  as  the  class for which to generate the reader and
       writer, the name and namespace  of  the  classes  to  generate,  and  a
       collection  of  hooks  to  apply.  By  using  hooks  it  is possible to
       customize the behavior of the serializer without needing to modify  the
       generated  file, so you can safely regenerate it if the source class is
       modified.

       destinationFolder  specifies  the  folder  where  the  files  will   be
       generated.

       NOTE:  This  tool  only  runs  in  the Mono runtime, since it uses some
       internal classes not available in other runtimes.

CONFIGURATION FILE FORMAT

       The configuration file is  an  xml  document  based  on  the  following
       grammar ("?" means optional, "*" 0 or more):

            <configuration>
                 <serializer class="name" assembly="name"> *
                      <reader>name</reader> ?
                      <writer>name</writer> ?
                      <namespace>name</namespace> ?
                      <outFileName>name</outFileName> ?
                      <readerHooks> ?
                           <hook ...> *
                      </readerHooks>
                      <writerHooks> ?
                           <hook ...> *
                      </writerHooks>
                 </serializer>
            </configuration>

       A  configuration  file can have multiple "serializer" elements, each of
       which specifies the class for which to generate a  serializer  together
       with  several  generation options. The source class is specified in the
       following attributes:

          * class : name of the class (including namespace).

          * assembly : assembly name. It can include the complete path.

       Generation options are specified in child elements:

          * reader : name of the reader class.

          * noReader : if "true", it does not generate reader class.

          * writer : name of the writer class.

          * baseSerializer : name of the base xml serializer class. This  item
            is 2.0 only.

          * implementation : name of the serializer implementation class. This
            item is 2.0 only.

          * noWriter : if "true", it does not generate writer class.

          * namespace : namespace of the reader and writer classes.

          * generateAsInternal : if "true", it generates classes as  internal.

          * outFileName : name of the generated file.

          * readerHooks : a list of hooks to apply to the reader.

          * writerHooks : a list of hooks to apply to the writer.

SPECIFYING HOOKS

       Using  hooks  you can customize the behavior of readers and writers.  A
       hook specification follows this grammar:

            <hook type="name">
                 <select> ?
                      <typeName>name</typeName> ?
                      <typeAttribute>name</typeAttribute> *
                      <typeMember>name</typeMember> ?
                 </select>
                 <replace>source code</replace> ?
                 <insertBefore>source code</insertBefore> ?
                 <insertAfter>source code</insertAfter> ?
            </hook>

       The "type" attribute  specifies  the  context  in  which  the  hook  is
       applied. It can be one of the following:

          * attributes    :    hook    is   applied   where   attributes   are
            serialized/deserialized.

          * elements    :    hook    is    applied    where    elements    are
            serialized/deserialized.

          * unknownAttribute  :  hook  is applied where unknown attributes are
            processed.

          * unknownElement :  hook  is  applied  where  unknown  elements  are
            processed.

          * member    :    hook    is    applied    where    a    member    is
            serialized/deserialized.

          * type : hook is applied for the whole type.

       The "select" element specifies the classes and  members  to  which  the
       hook has to be added. It can contain the following elements:

          * typeName : the class with that name will be selected (must include
            namespace)

          * typeAttribute : all classes which have that attribute applied will
            be  selected  (specify  the  full  attribute class name, including
            namespace). Several attribute names can be specified.

          * typeMember : name of the class member for which the hook  must  be
            added.

       The  hook  source  code  can  be  specified  using any of the following
       elements:

          * replace  :   the   provided   source   code   will   replace   all
            serialization/deserialization operations in the hook context.

          * insertBefore  :  the  source  code  will  be added before the hook
            context.

          * insertAfter : the  source  code  will  be  added  after  the  hook
            context.

       When  writing  the  code  for a hook you can use some special variables
       that are defined during the code generation process. The variables  are
       the following:

          * $TYPE: name of the class being generated, without namespace.

          * $FULLTYPE:  full  name  of  the  class  being generated, including
            namespace.

          * $OBJECT: the object being serialized or deserialized. When using a
            replace  reader hook of type "type", the hook code must assign the
            deserialized object to this variable.

          * -I  $ELEMENT:  name  of  the   element   of   the   object   being
            serialized/deserialized.

          * $NAMESPACE:   namespace   of  the  element  of  the  object  being
            serialized/deserialized.

          * $MEMBER: name of the member  being  serialized/deserialized.  Only
            valid in the "member" context.

HOOK EXAMPLES

       The  following  example  adds  a  call  to  a Validate method after the
       deserialization of any object:

       <hook type="type">
            <insertAfter>
                 System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
            </insertAfter>
       </hook>

       This example specifies the code to be used to deserialize the XmlSchema
       class:

       <hook type="type">
            <select>
                 <typeName>System.Xml.Schema.XmlSchema</typeName>
            </select>
            <replace>
                 $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
            </replace>
       </hook>

       That one specifies the code to be used to read XmlSchema instances:

       <hook type="type">
            <select>
                 <typeName>System.Xml.Schema.XmlSchema</typeName>
            </select>
            <replace>$OBJECT.Write (Writer);</replace>
       </hook>

       With  this  two  hooks  the serializer will print some information when
       serializing the class "MyClass":

       <hook type="type">
            <select>
                 <typeName>MyNamespace.MyClass</typeName>
            </select>
            <insertBefore>Console.WriteLine ("Serializing MyClass");</replace>
            <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter>
       </hook>
       <hook type="member">
            <select>
                 <typeName>MyNamespace.MyClass</typeName>
            </select>
            <insertAfter>
                 Console.WriteLine ("Serialized member $MEMBER");
            </insertAfter>
       </hook>

       This hook writes an additional element for  all  types  that  have  the
       custom attribute "MyAttribute":

       <hook type="elements">
            <select>
                 <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
            </select>
            <insertAfter>
                 Writer.WriteStartElement ("privateData");
                 Writer.WriteString ($OBJECT.PrivateData);
                 Writer.WriteEndElement ();
            </insertAfter>
       </hook>

CONFIGURATION FILE EXAMPLE

       This  is  the  configuration  file  used to generate the serializer for
       ServiceDescription:

       <configuration>
            <serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services">
                 <reader>ServiceDescriptionReaderBase</reader>
                 <writer>ServiceDescriptionWriterBase</writer>
                 <namespace>System.Web.Services.Description</namespace>
                 <outFileName>ServiceDescriptionSerializerBase.cs</outFileName>
                 <readerHooks>
                      <hook type="unknownElement">
                           <select>
                                <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
                           </select>
                           <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace>
                      </hook>
                      <hook type="type">
                           <select>
                                <typeName>System.Xml.Schema.XmlSchema</typeName>
                           </select>
                           <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace>
                      </hook>
                 </readerHooks>
                 <writerHooks>
                      <hook type="elements">
                           <select>
                                <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute>
                           </select>
                           <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore>
                      </hook>
                      <hook type="type">
                           <select>
                                <typeName>System.Xml.Schema.XmlSchema</typeName>
                           </select>
                           <replace>$OBJECT.Write (Writer);</replace>
                      </hook>
                 </writerHooks>
            </serializer>
       </configuration>

AUTHORS

       Lluis Sanchez Gual (lluis@ximian.com)

LICENSE

       GenXS is released under the terms of the GNU GPL.

SEE ALSO

       mono(1), mcs(1), sgen(1)

                                                                      genxs(1)