--- /dev/null
+.\"
+.\" genxs manual page.
+.\" (C) Lluis Sanchez Gual (lluis@ximian.com)
+.\"
+.TH genxs 1
+.SH NAME
+genxs \- Mono's Xml Serializer Generator
+.SH SYNOPSIS
+.PP
+.B genxs
+configurationFile [destinationFolder]
+.SH DESCRIPTION
+.I genxs
+is a tool for generating custom XML serialization writers and readers for
+classes.
+.PP
+.I 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.
+.PP
+.I destinationFolder
+specifies the folder where the files will be generated.
+.PP
+.B NOTE:
+This tool only runs in the Mono runtime, since it uses some internal
+classes not available in other runtimes.
+.SH CONFIGURATION FILE FORMAT
+The configuration file is an xml document based on the following grammar
+("?" means optional, "*" 0 or more):
+.PP
+.nf
+ <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>
+.fi
+.PP
+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:
+.PP
+.IP " *" 5
+.I class
+: name of the class (including namespace).
+.IP " *" 5
+.I assembly
+: assembly name. It can include the complete path.
+.PP
+Generation options are specified in child elements:
+.PP
+.IP " *" 5
+.I reader
+: name of the reader class.
+.IP " *" 5
+.I writer
+: name of the writer class.
+.IP " *" 5
+.I namespace
+: namespace of the reader and writer classes.
+.IP " *" 5
+.I outFileName
+: name of the generated file.
+.IP " *" 5
+.I readerHooks
+: a list of hooks to apply to the reader.
+.IP " *" 5
+.I writerHooks
+: a list of hooks to apply to the writer.
+.SH SPECIFYING HOOKS
+Using hooks you can customize the behavior of readers and writers.
+A hook specification follows this grammar:
+.PP
+.nf
+ <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>
+.fi
+.PP
+The "type" attribute specifies the context in which the hook is applied. It can
+be one of the following:
+.PP
+.IP " *" 5
+.I attributes
+: hook is applied where attributes are serialized/deserialized.
+.IP " *" 5
+.I elements
+: hook is applied where elements are serialized/deserialized.
+.IP " *" 5
+.I unknownAttribute
+: hook is applied where unknown attributes are processed.
+.IP " *" 5
+.I unknownElement
+: hook is applied where unknown elements are processed.
+.IP " *" 5
+.I member
+: hook is applied where a member is serialized/deserialized.
+.IP " *" 5
+.I type
+: hook is applied for the whole type.
+.PP
+The "select" element specifies the classes and members to which the hook has
+to be added. It can contain the following elements:
+.PP
+.IP " *" 5
+.I typeName
+: the class with that name will be selected (must include namespace)
+.IP " *" 5
+.I 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.
+.IP " *" 5
+.I typeMember
+: name of the class member for which the hook must be added.
+.PP
+The hook source code can be specified using any of the following elements:
+.PP
+.IP " *" 5
+.I replace
+: the provided source code will replace all serialization/deserialization
+operations in the hook context.
+.IP " *" 5
+.I insertBefore
+: the source code will be added before the hook context.
+.IP " *" 5
+.I insertAfter
+: the source code will be added after the hook context.
+.PP
+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:
+.PP
+.IP " *" 5
+.I $TYPE:
+name of the class being generated, without namespace.
+.IP " *" 5
+.I $FULLTYPE:
+full name of the class being generated, including namespace.
+.IP " *" 5
+.I $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.
+.IP " *" 5
+-I $ELEMENT:
+name of the element of the object being serialized/deserialized.
+.IP " *" 5
+.I $NAMESPACE:
+namespace of the element of the object being serialized/deserialized.
+.IP " *" 5
+.I $MEMBER:
+name of the member being serialized/deserialized. Only valid in the "member"
+context.
+.SH HOOK EXAMPLES
+The following example adds a call to a Validate method after the deserialization
+of any object:
+.PP
+.nf
+<hook type="type">
+ <insertAfter>
+ System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT);
+ </insertAfter>
+</hook>
+.fi
+.PP
+This example specifies the code to be used to deserialize the XmlSchema class:
+.PP
+.nf
+<hook type="type">
+ <select>
+ <typeName>System.Xml.Schema.XmlSchema</typeName>
+ </select>
+ <replace>
+ $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);
+ </replace>
+</hook>
+.fi
+.PP
+That one specifies the code to be used to read XmlSchema instances:
+.PP
+.nf
+<hook type="type">
+ <select>
+ <typeName>System.Xml.Schema.XmlSchema</typeName>
+ </select>
+ <replace>$OBJECT.Write (Writer);</replace>
+</hook>
+.fi
+.PP
+With this two hooks the serializer will print some information when serializing
+the class "MyClass":
+.PP
+.nf
+<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>
+.fi
+.PP
+This hook writes an additional element for all types that have the custom
+attribute "MyAttribute":
+.PP
+.nf
+<hook type="elements">
+ <select>
+ <typeAttribute>MyNamespace.MyAttribute</typeAttribute>
+ </select>
+ <insertAfter>
+ Writer.WriteStartElement ("privateData");
+ Writer.WriteString ($OBJECT.PrivateData);
+ Writer.WriteEndElement ();
+ </insertAfter>
+</hook>
+.fi
+.SH CONFIGURATION FILE EXAMPLE
+This is the configuration file used to generate the serializer for ServiceDescription:
+.PP
+.nf
+<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>
+.fi
+.SH AUTHORS
+Lluis Sanchez Gual (lluis@ximian.com)
+.PP
+.SH LICENSE
+GenXS is released under the terms of the GNU GPL.
+.PP
+.SH SEE ALSO
+mono(1), mcs(1)
projects / mono.git / blobdiff