A .NET CLI tool to generate XmlSerializer compatible C# classes from XML Schema files.
$ dotnet add package XmlSchemaClassGenerator.Console
A console program and library to generate XmlSerializer compatible C# classes from XML Schema files.
Collection<T> properties
(initialized in constructor and with private setter)INotifyPropertyChangedAllowNullAttribute and MaybeNullAttributeUnsupported:
For command line use, choose your preferred installation:
For use from code use the library NuGet package:
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 => ...
}
};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:
xscgen -n "|a.xsd=Example.NamespaceA" -n "|b.xsd=Example.NamespaceB" a.xsd b.xsd
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.
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:
# Comment
http://example.com = Example.NamespaceA a.xsd
http://example.com = Example.NamespaceB b.xsd
Empty
# or alternatively
= Empty
Use the --nf option to specify the mapping file.
If a xsd file specifies obscure names for their types (classes, enums) or members (properties), you can substitute these using the --tns/--typeNameSubstitute= parameter:
xscgen --tns T:Example_RootType=Example --tns T:Example_RootTypeExampleScope=ExampleScope --tns P:StartDateDateTimeValue=StartDate example.xsd
The syntax for substitution is: {kindId}:{generatedName}={substituteName}
The {kindId} is a single character identifier based on documentation/analysis ID format, where valid values are:
| ID | Scope |
|---|---|
P | Property |
T | Type: class, enum, interface |
A | Any property and/or type |
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:
# Comment
T:Example_RootType = Example
T:Example_RootTypeExampleScope = ExampleScope
P:StartDateDateTimeValue = StartDate
Use the --tnsf/--typeNameSubstituteFile option to specify the substitution file.
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:
<xs:attribute name="id" type="xs:int" use="optional">...</xs:attribute>[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;
}
}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.
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
<xs:attributeGroup name="Common">
<xs:attribute name="name" type="xs:string"></xs:attribute>
</xs:attributeGroup>
<xs:complexType name="A">
<xs:attributeGroup ref="Common"/>
</xs:complexType>
<xs:complexType name="B">
<xs:attributeGroup ref="Common"/>
</xs:complexType>becomes
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; }
}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.
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.
| Minimum (Inclusive) | Maximum (Inclusive) | C# type |
|---|---|---|
| sbyte.MinValue | sbyte.MaxValue | sbyte |
| byte.MinValue | byte.MaxValue | byte |
| ushort.MinValue | ushort.MaxValue | ushort |
| short.MinValue | short.MaxValue | short |
| uint.MinValue | uint.MaxValue | uint |
| int.MinValue | int.MaxValue | int |
| ulong.MinValue | ulong.MaxValue | ulong |
| long.MinValue | long.MaxValue | long |
| decimal.MinValue | decimal.MaxValue | decimal |
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.
| XML Schema type | totalDigits | C# type |
|---|---|---|
| xs:positiveInteger xs:nonNegativeInteger | <3 | byte |
| <5 | ushort | |
| <10 | uint | |
| <20 | ulong | |
| <30 | decimal | |
| >=30 | string | |
| xs:integer xs:nonPositiveInteger xs:negativeInteger | <3 | sbyte |
| <5 | short | |
| <10 | int | |
| <19 | long | |
| <29 | decimal | |
| >=29 | string |
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.
Contributions are welcome. Here are some guidelines: