A console program and library to generate
XmlSerializer compatible C# classes
from XML Schema files.
Features
Map XML namespaces to C# namespaces, either explicitly or through a (configurable) function
Generate C# XML comments from schema annotations
Generate attributes
from schema restrictions
<pre>
Usage: xscgen [OPTIONS]+ xsdFile...
Generate C# classes from XML Schema files.
Version ...
xsdFiles may contain globs, e.g. "content\{schema,xsd}\**\*.xsd", and URLs.
Append - to option to disable it, e.g. --interface-.
Options:
-h, --help show this message and exit
-n, --namespace=VALUE map an XML namespace to a C# namespace
Separate XML namespace and C# namespace by '='.
A single value (no '=') is taken as the C#
namespace the empty XML namespace is mapped to.
One option must be given for each namespace to
be mapped.
A file name may be given by appending a pipe
sign (|) followed by a file name (like schema.
xsd) to the XML namespace.
If no mapping is found for an XML namespace, a
name is generated automatically (may fail).
--nf, --namespaceFile=VALUE
file containing mappings from XML namespaces to C#
namespaces
The line format is one mapping per line: XML
namespace = C# namespace [optional file name].
Lines starting with # and empty lines are
ignored.
--tns, --typeNameSubstitute=VALUE
substitute a generated type/member name
Separate type/member name and substitute name by
'='.
Prefix type/member name with an appropriate kind
ID as documented at: <a href="https://t.ly/HHEI">https://t.ly/HHEI</a>.
Prefix with 'A:' to substitute any type/member.
--tnsf, --typeNameSubstituteFile=VALUE
file containing generated type/member name
substitute mappings
The line format is one mapping per line:
prefixed type/member name = substitute name.
Lines starting with # and empty lines are
ignored.
-o, --output=FOLDER the FOLDER to write the resulting .cs files to
-d, --datetime-offset map xs:datetime, xs:date and xs:time to System.
DateTimeOffset instead of System.DateTime
--do, --dateOnly map xs:date and xs:time to System.DateOnly and
System.TimeOnly instead of System.DateTime
-i, --integer=TYPE map xs:integer and derived types to TYPE instead
of automatic approximation
TYPE can be i[nt], l[ong], or d[ecimal]
--fb, --fallback, --use-integer-type-as-fallback
use integer type specified via -i only if no type
can be deduced
-e, --edb, --enable-data-binding
enable INotifyPropertyChanged data binding
-r, --order emit order for all class members stored as XML
element
-c, --pcl PCL compatible output
-p, --prefix=PREFIX the PREFIX to prepend to auto-generated namespace
names
-v, --verbose print generated file names on stdout
-0, --nullable generate nullable adapter properties for optional
elements/attributes w/o default values
-f, --ef generate Entity Framework Code First compatible
classes
-t, --interface generate interfaces for groups and attribute
groups (default is enabled)
-a, --pascal use Pascal case for class and property names (
default is enabled)
--av, --assemblyVisible
use the internal visibility modifier (default is
false)
-u, --enableUpaCheck should XmlSchemaSet check for Unique Particle
Attribution (UPA) (default is enabled)
--ct, --collectionType=VALUE
collection type to use (default is System.
Collections.ObjectModel.Collection`1)
--cit, --collectionImplementationType=VALUE
the default collection type implementation to use (
default is null)
--csm, --collectionSettersMode=Private, Public, PublicWithoutConstructorInitialization, Init, InitWithoutConstructorInitialization
generate a private, public, or init-only setter
with or without backing field initialization for
collections
(default is Private; can be: Private, Public,
PublicWithoutConstructorInitialization, Init,
InitWithoutConstructorInitialization)
--ctro, --codeTypeReferenceOptions=GlobalReference, GenericTypeParameter
the default CodeTypeReferenceOptions Flags to use (
default is unset; can be: GlobalReference,
GenericTypeParameter)
--tvpn, --textValuePropertyName=VALUE
the name of the property that holds the text value
of an element (default is Value)
--dst, --debuggerStepThrough
generate DebuggerStepThroughAttribute (default is
enabled)
--dc, --disableComments
do not include comments from xsd
--nu, --noUnderscore do not generate underscore in private member name (
default is false)
--da, --description generate DescriptionAttribute (default is true)
--cc, --complexTypesForCollections
generate complex types for collections (default is
true)
-s, --useShouldSerialize use ShouldSerialize pattern instead of Specified
pattern (default is false)
--sf, --separateFiles generate a separate file for each class (default
is false)
--nh, --namespaceHierarchy
generate a separate folder for namespace hierarchy.
Implies "separateFiles" if true (default is
false)
--sg, --separateSubstitutes
generate a separate property for each element of a
substitution group (default is false)
--dnfin, --doNotForceIsNullable
do not force generator to emit IsNullable = true
in XmlElement annotation for nillable elements
when element is nullable (minOccurs < 1 or
parent element is choice) (default is false)
--cn, --compactTypeNames
use type names without namespace qualifier for
types in the using list (default is false)
--cl, --commentLanguages=VALUE
comment languages to use (default is en; supported
are en, de)
--un, --uniqueTypeNames
generate type names that are unique across
namespaces (default is false)
--gc, --generatedCodeAttribute
add version information to GeneratedCodeAttribute (
default is true)
--nc, --netCore generate .NET Core specific code that might not
work with .NET Framework (default is false)
--nr, --nullableReferenceAttributes
generate attributes for nullable reference types (
default is false)
--ar, --useArrayItemAttribute
use ArrayItemAttribute for sequences with single
elements (default is true)
--es, --enumAsString Use string instead of enum for enumeration
--ca, --commandArgs generate a comment with the exact command line
arguments that were used to generate the source
code (default is true)
--uc, --unionCommonType
generate a common type for unions if possible (
default is false)
--dtd, --allowDtdParse
allow DTD parsing (default is false)
--oxi, --omitXmlIncludeAttribute
omit generation of XmlIncludeAttribute for derived
types (default is false)
--ecl, --enumCollection
generate typed enum collections for xs:list types
instead of string collections (default is false)
--ns, --namingScheme use the specified naming scheme for class and
property names (default is Pascal; can be:
Direct, Pascal, Legacy)
--fu, --forceUriScheme=VALUE
force URI scheme when resolving URLs (default is
none; can be: none, same, or any defined value
for scheme, like https or http)
--ema, --emitMetadataAttributes
emit metadata helper attributes (default is false)
--mn, --metadataNamespace=VALUE
namespace for generated metadata helper attributes (
default is XmlSchemaClassGenerator.Metadata)
</pre>
<table>
<tr>
<th>Minimum (Inclusive)</th>
<th>Maximum (Inclusive)</th>
<th>C# type</th>
<tr><td>sbyte.MinValue</td><td>sbyte.MaxValue</td><td>sbyte</td></tr>
<tr><td>byte.MinValue</td><td>byte.MaxValue</td><td>byte</td></tr>
<tr><td>ushort.MinValue</td><td>ushort.MaxValue</td><td>ushort</td></tr>
<tr><td>short.MinValue</td><td>short.MaxValue</td><td>short</td></tr>
<tr><td>uint.MinValue</td><td>uint.MaxValue</td><td>uint</td></tr>
<tr><td>int.MinValue</td><td>int.MaxValue</td><td>int</td></tr>
<tr><td>ulong.MinValue</td><td>ulong.MaxValue</td><td>ulong</td></tr>
<tr><td>long.MinValue</td><td>long.MaxValue</td><td>long</td></tr>
<tr><td>decimal.MinValue</td><td>decimal.MaxValue</td><td>decimal</td></tr>
</tr>
</table>
<table>
<tr>
<th>XML Schema type</th>
<th>totalDigits</th>
<th>C# type</th>
</tr>
<tr><td rowspan="6">xs:positiveInteger<br>xs:nonNegativeInteger</td><td><3</td><td>byte</td></tr>
<tr><td><5</td><td>ushort</td></tr>
<tr><td><10</td><td>uint</td></tr>
<tr><td><20</td><td>ulong</td></tr>
<tr><td><30</td><td>decimal</td></tr>
<tr><td>>=30</td><td>string</td></tr>
<tr><td rowspan="6">xs:integer<br>xs:nonPositiveInteger<br>xs:negativeInteger</td><td><3</td><td>sbyte</td></tr>
<tr><td><5</td><td>short</td></tr>
<tr><td><10</td><td>int</td></tr>
<tr><td><19</td><td>long</td></tr>
<tr><td><29</td><td>decimal</td></tr>
<tr><td>>=29</td><td>string</td></tr>
</table>
Generate custom attributes for schema restrictions that aren't covered by standard DataAnnotations (see below)
Use Collection<T> properties
(initialized in constructor and with private setter)
Map xs:integer and derived types to the closest possible .NET type, if not possible - fall back to string. Can be overriden by explicitly defined type (int, long, or decimal)
Automatic properties
Pascal case for classes and properties
Generate nullable adapter properties for optional elements and attributes without default values (see below)
var generator = new Generator
{
OutputFolder = outputFolder,
Log = s => Console.Out.WriteLine(s),
GenerateNullables = true,
NamespaceProvider = new Dictionary<NamespaceKey, string>
{
{ new NamespaceKey("http://wadl.dev.java.net/2009/02"), "Wadl" }
}
.ToNamespaceProvider(new GeneratorConfiguration { NamespacePrefix = "Wadl" }.NamespaceProvider.GenerateNamespace)
};
generator.Generate(files);
Specifying the NamespaceProvider is optional. If you don't provide one, C# namespaces will be generated automatically. The example above shows how to create a custom NamespaceProvider that has a dictionary for a number of specific namespaces as well as a generator function for XML namespaces that are not in the dictionary. In the example the generator function is the default function but with a custom namespace prefix. You can also use a custom generator function, e.g.
var generator = new Generator
{
NamespaceProvider = new NamespaceProvider
{
GenerateNamespace = key => ...
}
};
Mapping xsd files to C# namespaces
Using the optional | syntax of the -n command line option you can map individual xsd files to C# namespaces. If you have several input files using the same XML namespace you can still generate an individual C# namespace for the types defined within a single xsd file. For example, if you have two input files a.xsd and b.xsd both of which have the same targetNamespace of http://example.com/namespace you can generate the C# namespaces Example.NamespaceA and Example.NamespaceB:
In order to provide a C# namespace name for an empty XML namespace you can specify it on the command line like this:
xscgen -n Example example.xsd
An alternative form that is also valid is -n =Example. Note the space between -n and =Example.
Using mapping files
Instead of specifying the namespace mappings on the command line you can also use a mapping file which should contain one mapping per line in the following format:
If a xsd file specifies obscure names for their types (classes, enums) or members (properties), you can substitute these using the --tns/--typeNameSubstitute= parameter:
Instead of specifying the substitutions on the command line you can also use a substitution file which should contain one substitution per line in the following format:
Use the --tnsf/--typeNameSubstituteFile option to specify the substitution file.
Nullables<a name="nullables"></a>
XmlSerializer has been present in the .NET Framework since version 1.1
and has never been updated to provide support for nullables
which are a natural fit for the problem of signaling the absence or presence of a value type
but have only been present since .NET Framework 2.0.
Instead XmlSerializer has support for a pattern where you provide an additional bool property
with "Specified" appended to the name to signal if the original property should be serialized.
For example:
[System.Xml.Serialization.XmlAttributeAttribute("id", Form=System.Xml.Schema.XmlSchemaForm.Unqualified, DataType="int")]
public int Id { get; set; }
[System.Xml.Serialization.XmlIgnoreAttribute()]
public bool IdSpecified { get; set; }
XmlSchemaClassGenerator can optionally generate an additional nullable property that works as an adapter to both properties:
[System.Xml.Serialization.XmlAttributeAttribute("id", Form=System.Xml.Schema.XmlSchemaForm.Unqualified, DataType="int")]
public int IdValue { get; set; }
[System.Xml.Serialization.XmlIgnoreAttribute()]
public bool IdValueSpecified { get; set; }
[System.Xml.Serialization.XmlIgnoreAttribute()]
public System.Nullable<int> Id
{
get
{
if (this.IdValueSpecified)
{
return this.IdValue;
}
else
{
return null;
}
}
set
{
this.IdValue = value.GetValueOrDefault();
this.IdValueSpecified = value.HasValue;
}
}
Choice Elements<a name="choice"></a>
The support for choice elements differs from that provided by xsd.exe.
Xsd.exe generates a property called Item of type object and, if not all choices have a distinct type,
another enum property that selects the chosen element.
Besides being non-typesafe and non-intuitive, this approach breaks apart if the choices have a more complicated structure (e.g. sequences),
resulting in possibly schema-invalid XML.
XmlSchemaClassGenerator currently simply pretends choices are sequences.
This means you'll have to take care only to set a schema-valid combination of these properties to non-null values.
Interfaces<a name="interfaces"></a>
Groups and attribute groups in XML Schema are reusable components that can be included in multiple type definitions. XmlSchemaClassGenerator can optionally generate interfaces from these groups to make it easier to access common properties on otherwise unrelated classes. So
public partial interface ICommon
{
string Name { get; set; }
}
public partial class A: ICommon
{
public string Name { get; set; }
}
public partial class B: ICommon
{
public string Name { get; set; }
}
Collection types
Values for the --collectionType and --collectionImplementationType options have to be given in the format accepted by
the Type.GetType() method. For the System.Collections.Generic.List<T> class this means System.Collections.Generic.List`1.
Make sure to escape the backtick character (`) to prevent it from being interpreted by the shell.
Integer and derived types
Not all numeric types defined by XML Schema can be safely and accurately mapped to .NET numeric data types, however, it's possible to approximate the mapping based on the integer bounds and restrictions such as totalDigits.
If an explicit integer type mapping is specified via --integer=TYPE, that type will be used, otherwise an approximation will be made based on the table below. If you additionally specify --fallback, the type specified via --integer=TYPE will be used only if no type can be deduced by applying the rules below.
If the restrictions minInclusive and maxInclusive are present on the integer element, then the smallest CLR type that fully encompasses the specified range will be used. Unsigned types are given precedence over signed types. The following table shows the possible ranges and their corresponding CLR type, in the order they will be applied.
If the range specified by minInclusive and maxInclusive does not fit in any CLR type, or if those restrictions are not present, then the totalDigits restriction will be used, as shown in the following table.
Unions
If you specify --unionCommonType, XmlSchemaClassGenerator will try to determine a common type for a union's member types. If, for example, the member types
are all integer types, then the narrowest integer type will be used that can fit all member types.
Note that semantic issues might arise with this approach. For example, DateTime values are serialized with both date and time information included. See discussion at #397.
Restriction attributes
When EmitMetadataAttributes is enabled, the generator emits custom attributes for XML schema restrictions that aren't covered by standard DataAnnotations. For example, xs:fractionDigits becomes FractionDigitsAttribute.
The attribute definition is automatically generated in the namespace specified through --metadataNamespace. If not specified, the default namespace is XmlSchemaClassGenerator.Metadata.
Contributing
Contributions are welcome. Here are some guidelines:
If it's not a trivial fix, please submit an issue first
Try and blend new code with the existing code's style
