[API Proposal]: XSD DCS Schema API's from 4.8

[StephenMolloy]

Background and motivation

We're trying to bring DCS and friends back to par with .Net 4.8 in this release. One of the capabilities of the DCS library in .Net 4.8 is to generate XSD schemas or import XSD schemas into usable code. This functionality is used to support WCF and svcutil. The code that handles schema importing however, had a dependency on System.CodeDom. After some extended discussion around the goals and motivations, we decided to take a two-pronged approach here. The existing DCS assembly in the runtime will be receiving updates to align with 4.8 and to support this schema work under the covers... but the top-level functionality (and public surface area) of the schema support will live in a separate package in dotnet/runtime that is not part of the runtime. (Like the System.CodeDom package it depends on.) See the PR #71752 and other half of the API review #72242.

This is the corresponding API review for the external Schema package. The public surface area it presents is almost exactly as it was in .Net 4.8, so it's a proven design. There is one difference though - because .Net Core originally started with a strange Silverlight-based port of DataContractSerializer. The way it handled surrogates was changed and limited. The other API proposal contains an extended surrogate interface with the missing parts of the corresponding interface in 4.8... except for one method which we could not include on the runtime side because it has CodeDom types in the signature. (We can't define that interface in this 'external' package though because it is used pretty deep in the workings of the newly 4.8-aligned DCS.) In this review, I've placed that method as a Func<> on the ImportOptions class. We have also considered creating yet another extending interface in this project to round out the complete functionality of IDataContractSurrogate from 4.8. I honestly have no preference which way to go. Hoping the API experts have input on that one.

API Proposal

namespace System.Runtime.Serialization.Schema
{
    // This ExportOptions class is defined similarly to the public System.Runtime.Serialization.ExportOptions class in 4.8.
    // The surrogate type had changed in Core, so it changed here as well, and thats the only difference.
    // https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.exportoptions?view=netframework-4.8
    public sealed class ExportOptions
    {
        public Collection<Type> KnownTypes { get; }
        public ISerializationSurrogateProvider? SurrogateProvider { get; set; }
    }

    // This ImportOptions API is almost exactly the same as the ImportOptions API in 4.8, with the exception of the surrogate
    // type of course - since that changed between NetFx and Core - and one extra Func that used to be part of the surrogate
    // provider interface in 4.8, but was pulled out into this options class because it uses CodeDom types.
    // https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.importoptions?view=netframework-4.8
    public sealed class ImportOptions
    {
        public System.CodeDom.Compiler.CodeDomProvider? CodeProvider { get; set; }
        public bool EnableDataBinding { get; set; }
        public bool GenerateInternal { get; set; }
        public bool GenerateSerializable { get; set; }
        public bool ImportXmlType { get; set; }
        public IDictionary<string, string> Namespaces { get; }
        public ICollection<Type> ReferencedCollectionTypes { get; }
        public ICollection<Type> ReferencedTypes { get; }
        public ISerializationSurrogateProvider? SurrogateProvider { get; set; }

        // This is the Func which is the new API. The naming and intent of this Func is to be the last method
        // from the old IDataContractSurrogate interface that we couldn't stick in the runtime interfaces.
        // I'm open to feedback here if people don't like sticking a Func on an options class.
        public Func<System.CodeDom.CodeTypeDeclaration, System.CodeDom.CodeCompileUnit, System.CodeDom.CodeTypeDeclaration?>? ProcessImportedType;
    }

    // This XsdDataContractExporter class is the exact same API as the one in 4.8.
    // https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.xsddatacontractexporter?view=netframework-4.8
    // This class also exists in-box with DCS in Core... but it mostly does not work. It does not depend on CodeDom, so it could
    // probably be completed in-box, but it made sense to us to keep schema import and export together in the same package. The in-box
    // implementation should get marked as obsolete. (This also applies to the ExportOptions class above.)
    public sealed class XsdDataContractExporter
    {
        public XsdDataContractExporter() { }
        public XsdDataContractExporter(System.Xml.Schema.XmlSchemaSet? schemas) { }

        public ExportOptions? Options { get; set; }
        public System.Xml.Schema.XmlSchemaSet Schemas { get; }

        [RequiresUnreferencedCodeAttribute()]
        public bool CanExport(ICollection<System.Reflection.Assembly> assemblies) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanExport(ICollection<Type> types) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanExport(Type type) { }

        [RequiresUnreferencedCodeAttribute()]
        public void Export(ICollection<System.Reflection.Assembly> assemblies) { }
        [RequiresUnreferencedCodeAttribute()]
        public void Export(ICollection<Type> types) { }
        [RequiresUnreferencedCodeAttribute()]
        public void Export(Type type) { }

        [RequiresUnreferencedCodeAttribute()]
        public System.Xml.XmlQualifiedName? GetRootElementName(Type type) { }
        [RequiresUnreferencedCodeAttribute()]
        public System.Xml.Schema.XmlSchemaType? GetSchemaType(Type type) { }
        [RequiresUnreferencedCodeAttribute()]
        public System.Xml.XmlQualifiedName GetSchemaTypeName(Type type) { }
    }

    // This XsdDataContractImporter class is the exact same API as the one in 4.8.
    // https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.xsddatacontractimporter?view=netframework-4.8
    public sealed class XsdDataContractImporter
    {
        public XsdDataContractImporter() { }
        public XsdDataContractImporter(System.CodeDom.CodeCompileUnit codeCompileUnit) { }

        public System.CodeDom.CodeCompileUnit CodeCompileUnit { get; }
        public ImportOptions? Options { get; set; }

        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas, ICollection<System.Xml.XmlQualifiedName> typeNames) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.XmlQualifiedName typeName) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.Schema.XmlSchemaElement element) { }

        [RequiresUnreferencedCodeAttribute()]
        public void Import(System.Xml.Schema.XmlSchemaSet schemas) { }
        [RequiresUnreferencedCodeAttribute()]
        public void Import(System.Xml.Schema.XmlSchemaSet schemas, ICollection<System.Xml.XmlQualifiedName> typeNames) { 
        [RequiresUnreferencedCodeAttribute()]
        public void Import(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.XmlQualifiedName typeName) { }
        [RequiresUnreferencedCodeAttribute()]
        public System.Xml.XmlQualifiedName? Import(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.Schema.XmlSchemaElement element) { }

        [RequiresUnreferencedCodeAttribute()]
        public System.CodeDom.CodeTypeReference GetCodeTypeReference(System.Xml.XmlQualifiedName typeName) { }
        [RequiresUnreferencedCodeAttribute()]
        public System.CodeDom.CodeTypeReference GetCodeTypeReference(System.Xml.XmlQualifiedName typeName, System.Xml.Schema.XmlSchemaElement element) { }
        [RequiresUnreferencedCodeAttribute()]
        public ICollection<System.CodeDom.CodeTypeReference>? GetKnownTypeReferences(System.Xml.XmlQualifiedName typeName) { }
    }
}

API Usage

See XsdDataContractImporter and XsdDataContractExporter in .Net 4.8.

Alternative Designs

No response

Risks

No response

[stephentoub]

I'm open to feedback here if people don't like sticking a Func on an options class.

We have other options types that have delegates on them. Seems fine.

[bartonjs]

Video

• ImportOptions.ProcessImportedType feels like it needs to be an ISerializationCodeDomSurrogateProvider to provide parity with the object flow from .NET Framework
• ExportOptions shouldn't be redefined in System.Runtime.Serialization.Schema, it just needs to merge with the one already present in System.Runtime.Serialization.
  • Similarly for the concrete exporter types

namespace System.Runtime.Serialization
{
    public partial class ExportOptions
    {
        public ISerializationSurrogateProvider? SurrogateProvider { get; set; }
    }

    // This ImportOptions API is almost exactly the same as the ImportOptions API in 4.8, with the exception of the surrogate
    // type of course - since that changed between NetFx and Core - and one extra Func that used to be part of the surrogate
    // provider interface in 4.8, but was pulled out into this options class because it uses CodeDom types.
    // https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.importoptions?view=netframework-4.8
    public class ImportOptions
    {
        public System.CodeDom.Compiler.CodeDomProvider? CodeProvider { get; set; }
        public bool EnableDataBinding { get; set; }
        public bool GenerateInternal { get; set; }
        public bool GenerateSerializable { get; set; }
        public bool ImportXmlType { get; set; }
        public IDictionary<string, string> Namespaces { get; }
        public ICollection<Type> ReferencedCollectionTypes { get; }
        public ICollection<Type> ReferencedTypes { get; }
        public ISerializationSurrogateProvider? DataContractSurrogate { get; set; }
    }

    public class XsdDataContractImporter
    {
        public XsdDataContractImporter() { }
        public XsdDataContractImporter(System.CodeDom.CodeCompileUnit codeCompileUnit) { }

        public System.CodeDom.CodeCompileUnit CodeCompileUnit { get; }
        public ImportOptions? Options { get; set; }

        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas, ICollection<System.Xml.XmlQualifiedName> typeNames) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.XmlQualifiedName typeName) { }
        [RequiresUnreferencedCodeAttribute()]
        public bool CanImport(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.Schema.XmlSchemaElement element) { }

        [RequiresUnreferencedCodeAttribute()]
        public void Import(System.Xml.Schema.XmlSchemaSet schemas) { }
        [RequiresUnreferencedCodeAttribute()]
        public void Import(System.Xml.Schema.XmlSchemaSet schemas, ICollection<System.Xml.XmlQualifiedName> typeNames) { 
        [RequiresUnreferencedCodeAttribute()]
        public void Import(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.XmlQualifiedName typeName) { }
        [RequiresUnreferencedCodeAttribute()]
        public System.Xml.XmlQualifiedName? Import(System.Xml.Schema.XmlSchemaSet schemas, System.Xml.Schema.XmlSchemaElement element) { }

        [RequiresUnreferencedCodeAttribute()]
        public System.CodeDom.CodeTypeReference GetCodeTypeReference(System.Xml.XmlQualifiedName typeName) { }
        [RequiresUnreferencedCodeAttribute()]
        public System.CodeDom.CodeTypeReference GetCodeTypeReference(System.Xml.XmlQualifiedName typeName, System.Xml.Schema.XmlSchemaElement element) { }
        [RequiresUnreferencedCodeAttribute()]
        public ICollection<System.CodeDom.CodeTypeReference>? GetKnownTypeReferences(System.Xml.XmlQualifiedName typeName) { }
    }

    public interface ISerializationCodeDomSurrogateProvider
    {
        CodeTypeDeclaration ProcessImportedType(CodeTypeDeclaration typeDeclaration, CodeCompileUnit compileUnit);
    }
}

[StephenMolloy]

Implemented in #71752