Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
genxs(1)		    General Commands Manual		      genxs(1)

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	infor-
       mation,	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	gener-
       ated.

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

CONFIGURATION FILE FORMAT
       The  configuration file is an xml document based	on the following gram-
       mar ("?"	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  ap-
       plied. It can be	one of the following:

	  * attributes : hook is applied where attributes are serialized/dese-
	    rialized.

	  * elements : hook is applied where elements are serialized/deserial-
	    ized.

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

	  * unknownElement : hook is applied where unknown elements  are  pro-
	    cessed.

	  * member  :  hook  is	applied	where a	member is serialized/deserial-
	    ized.

	  * 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 ele-
       ments:

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

	  * insertBefore  : the	source code will be added before the hook con-
	    text.

	  * insertAfter	: the source code will be added	after  the  hook  con-
	    text.

       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 name-
	    space.

	  * $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  serial-
	    ized/deserialized.

	  * $NAMESPACE:	 namespace  of the element of the object being serial-
	    ized/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 dese-
       rialization 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 se-
       rializing 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 cus-
       tom 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 Ser-
       viceDescription:

       <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)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION FILE FORMAT | SPECIFYING HOOKS | HOOK EXAMPLES | CONFIGURATION FILE EXAMPLE | AUTHORS | LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=genxs&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help