310 строки
8.4 KiB
Groff
310 строки
8.4 KiB
Groff
.\"
|
|
.\" 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 noReader
|
|
: if "true", it does not generate reader class.
|
|
.IP " *" 5
|
|
.I writer
|
|
: name of the writer class.
|
|
.IP " *" 5
|
|
.I baseSerializer
|
|
: name of the base xml serializer class. This item is 2.0 only.
|
|
.IP " *" 5
|
|
.I implementation
|
|
: name of the serializer implementation class. This item is 2.0 only.
|
|
.IP " *" 5
|
|
.I noWriter
|
|
: if "true", it does not generate writer class.
|
|
.IP " *" 5
|
|
.I namespace
|
|
: namespace of the reader and writer classes.
|
|
.IP " *" 5
|
|
.I generateAsInternal
|
|
: if "true", it generates classes as internal.
|
|
.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), sgen(1)
|