dotnet-xscgen-proj 2.1.1144

dotnet add package dotnet-xscgen-proj --version 2.1.1144
NuGet\Install-Package dotnet-xscgen-proj -Version 2.1.1144
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="dotnet-xscgen-proj" Version="2.1.1144" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add dotnet-xscgen-proj --version 2.1.1144
#r "nuget: dotnet-xscgen-proj, 2.1.1144"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install dotnet-xscgen-proj as a Cake Addin
#addin nuget:?package=dotnet-xscgen-proj&version=2.1.1144

// Install dotnet-xscgen-proj as a Cake Tool
#tool nuget:?package=dotnet-xscgen-proj&version=2.1.1144

XmlSchemaClassGenerator

Nuget Build status codecov.io netstandard2.0 net462

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 DataAnnotations attributes from schema restrictions
  • 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)
  • Optional support for PCL
  • Optional support for INotifyPropertyChanged
  • Optional support for Entity Framework Code First (automatically generate key properties)
  • Optionally generate interfaces for groups and attribute groups
  • Optionally generate one file per class
  • Support for nullable reference types (NRTs) through AllowNullAttribute and MaybeNullAttribute
  • Optionally generate a common specific type for union member types

Unsupported:

  • Some restriction types
  • Recursive choices and choices whose elements have minOccurs > 0 or nillable="true" (see below)
  • Possible name clashes and invalid identifiers when names contain non-alphanumeric characters
  • Groups with maxOccurs > 0

Usage

For command line use, choose your preferred installation:

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: https://t.ly/HHEI.
                               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 and derived types to System.
                               DateTimeOffset 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)

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 => ...
    }
};

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:

xscgen -n "|a.xsd=Example.NamespaceA" -n "|b.xsd=Example.NamespaceB" a.xsd b.xsd
Mapping empty XML namespaces

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:

# 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.

Substituting generated C# type and member names

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
Using substitution files

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.

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:

<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;
    }
}

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

<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; }
}

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.

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.

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

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.

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

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.

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
  • Add unit tests
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.1.1144 76 5/31/2024
2.1.1142 97 5/17/2024
2.1.1141 92 5/14/2024
2.1.1130 100 4/19/2024
2.1.1127 105 4/12/2024
2.1.1107 253 2/19/2024
2.1.1094 252 2/12/2024
2.1.1092 235 2/9/2024
2.1.1057 453 12/14/2023
2.1.1051 477 12/11/2023
2.1.963 471 10/31/2023
2.1.959 437 10/30/2023
2.1.956 442 10/23/2023
2.1.954 451 10/17/2023
2.1.915 747 10/2/2023
2.1.910 487 9/27/2023
2.1.908 500 9/22/2023
2.0.894 548 9/5/2023
2.0.878 601 8/9/2023
2.0.874 599 8/8/2023
2.0.864 589 7/26/2023
2.0.863 628 7/25/2023
2.0.862-beta 611 7/24/2023
2.0.861 654 7/20/2023
2.0.859 600 7/18/2023
2.0.858 626 7/17/2023
2.0.810 670 5/16/2023
2.0.805 741 3/16/2023
2.0.792 851 1/26/2023
2.0.732 1,025 8/23/2022
2.0.719 1,351 7/26/2022
2.0.718 935 6/28/2022
2.0.717 935 6/24/2022
2.0.714 910 6/21/2022
2.0.711 924 6/17/2022
2.0.703 942 6/8/2022
2.0.692 1,031 5/31/2022
2.0.662 990 4/4/2022
2.0.660 954 3/21/2022
2.0.646 955 2/7/2022
2.0.642 933 2/2/2022
2.0.634 915 1/21/2022
2.0.633 953 1/18/2022
2.0.631 935 1/6/2022
2.0.630 797 12/16/2021
2.0.629 804 11/30/2021
2.0.627 1,385 11/29/2021
2.0.594 828 9/8/2021
2.0.579 817 8/25/2021
2.0.567 870 8/11/2021
2.0.566 845 8/5/2021
2.0.565 835 7/26/2021
2.0.560 909 5/31/2021
2.0.521 1,316 4/9/2021
2.0.517 1,041 3/17/2021
2.0.513 936 3/15/2021
2.0.512 859 3/10/2021
2.0.509 928 3/9/2021
2.0.502 907 1/29/2021
2.0.495 910 1/14/2021
2.0.494 922 1/12/2021
2.0.490 1,096 12/24/2020
2.0.488 956 12/23/2020
2.0.487 930 12/17/2020
2.0.486 964 12/10/2020
2.0.484 925 12/9/2020
2.0.479 923 11/20/2020
2.0.478 942 11/15/2020
2.0.460 994 10/28/2020
2.0.459 1,006 10/20/2020
2.0.444 1,050 7/28/2020
2.0.439 948 7/14/2020
2.0.436 1,013 6/22/2020
2.0.434 995 6/9/2020
2.0.425 980 5/18/2020
2.0.424 1,004 5/14/2020
2.0.421 983 5/13/2020
2.0.419 1,017 5/13/2020
2.0.414 990 5/4/2020
2.0.412 1,031 5/3/2020
2.0.405 995 5/1/2020
2.0.395 1,071 4/30/2020
2.0.390 1,001 4/29/2020
2.0.373 985 4/24/2020
2.0.370 1,000 4/23/2020
2.0.365 1,003 4/23/2020
2.0.349 1,036 3/27/2020
2.0.347 1,024 3/13/2020
2.0.346 975 3/11/2020
2.0.345 1,010 2/28/2020
2.0.341 971 1/24/2020
2.0.340 1,007 1/23/2020
2.0.334 1,119 1/21/2020
2.0.322 1,092 12/28/2019
2.0.310 2,798 11/22/2019
2.0.301 1,191 11/6/2019
2.0.300 1,053 10/16/2019
2.0.296 1,006 10/2/2019
2.0.267 1,078 9/12/2019
2.0.261 1,082 9/3/2019
2.0.257 1,059 8/23/2019
2.0.254 1,193 7/17/2019
2.0.252 1,084 7/8/2019
2.0.241 1,082 6/25/2019
2.0.232 1,141 3/28/2019
2.0.230 1,170 3/11/2019
2.0.214 1,120 3/6/2019
2.0.212 1,182 2/21/2019
2.0.210 1,230 2/20/2019
1.0.0 1,260 1/31/2019