Типы XML и ADO.NET в контрактах данных

Модель контракта данных Windows Communication Foundation (WCF) поддерживает определенные типы, представляющие XML напрямую. При сериализации этих типов в XML сериализатор записывает содержимое XML этих типов без дополнительной обработки. Поддерживаемые типы XmlElement, массивы XmlNode (но не сам тип XmlNode), а также типы, реализующие IXmlSerializable. Типы DataSet и DataTable, а также типизированные наборы данных, часто используются в программировании баз данных. Эти типы реализуют IXmlSerializable интерфейс и поэтому сериализуются в модели контракта данных. Некоторые особые аспекты для этих типов перечислены в конце этого раздела.

Типы XML

Xml-элемент

Тип XmlElement сериализуется с помощью xml-содержимого. Например, используя следующий тип.

[DataContract(Namespace=@"http://schemas.contoso.com")]
public class MyDataContract
{
    [DataMember]
    public XmlElement myDataMember;
    public void TestClass()
    {
        XmlDocument xd = new XmlDocument();
        myDataMember = xd.CreateElement("myElement");
        myDataMember.InnerText = "myContents";
        myDataMember.SetAttribute
         ("myAttribute","myValue");
    }
}

<DataContract([Namespace]:="http://schemas.contoso.com")> _
Public Class MyDataContract
    <DataMember()> _
    Public myDataMember As XmlElement

    Public Sub TestClass()
        Dim xd As New XmlDocument()
        myDataMember = xd.CreateElement("myElement")
        myDataMember.InnerText = "myContents"
        myDataMember.SetAttribute("myAttribute", "myValue")

    End Sub
End Class

Сериализуется в XML следующим образом:

<MyDataContract xmlns="http://schemas.contoso.com">
    <myDataMember>
        <myElement xmlns="" myAttribute="myValue">
            myContents
        </myElement>
    </myDataMember>
</MyDataContract>

Обратите внимание, что элемент-член <myDataMember> данных-оболочки по-прежнему присутствует. Нет способа удаления этого элемента в модели контракта данных. Сериализаторы, обрабатывающие эту модель ( DataContractSerializer и NetDataContractSerializer) могут выдавать специальные атрибуты в этот элемент оболочки. К этим атрибутам относятся стандартный атрибут экземпляра схемы XML "nil" (позволяющий XmlElement быть null) и атрибут "type" (позволяющий XmlElement использовать полиморфно). Кроме того, следующие атрибуты XML относятся к WCF: "Id", "Ref", "Type" и "Assembly". Эти атрибуты могут быть сгенерированы для поддержки использования XmlElement при включенном режиме сохранения графа объектов или NetDataContractSerializer. (Дополнительные сведения о режиме сохранения графа объектов см. в разделе Сериализация и десериализация.)

Массивы или коллекции XmlElement разрешены и обрабатываются как любой другой массив или коллекция. То есть для всей коллекции существует элемент-оболочка и отдельный элемент оболочки (аналогично <myDataMember> предыдущему примеру) для каждого XmlElement из массивов.

При десериализации объект XmlElement создаётся десериализатором из входящего XML. Допустимый родительский объект XmlDocument предоставляется десериализатором.

Убедитесь, что XML-фрагмент, который десериализуется в XmlElement, определяет все используемые префиксы и не полагается на определения префиксов из родительских элементов. Эта проблема возникает только при использовании DataContractSerializer для доступа к XML из другого (не-DataContractSerializer) источника.

При использовании DataContractSerializer с XmlElement его можно полиморфно назначить, но только элементу данных типа Object. Несмотря на то что он реализует IEnumerable, XmlElement нельзя использовать в качестве типа коллекции и не может быть назначен элементу IEnumerable данных. Как и во всех полиморфных назначениях, элемент DataContractSerializer излучает имя контракта данных в результирующем XML. В этом случае это "XmlElement" в http://schemas.datacontract.org/2004/07/System.Xml пространстве имен.

С помощью NetDataContractSerializer поддерживается любое допустимое полиморфное назначение XmlElement в Object или IEnumerable.

Не пытайтесь использовать ни один из сериализаторов с типами, производными от XmlElement, независимо от того, назначены ли они полиморфно или нет.

Массив XmlNode

Использование массивов XmlNode очень похоже на использование XmlElement. Использование массивов XmlNode обеспечивает большую гибкость, чем использование XmlElement. Можно написать несколько элементов в элементе упаковки элементов данных. Вы также можете внедрить содержимое, отличное от элементов внутри элемента упаковки элементов данных, таких как XML-комментарии. Наконец, можно поместить атрибуты в элемент данных-оболочки. Все это можно достичь, заполнив массив XmlNode конкретными производными классами, такими как XmlNode, XmlAttribute или XmlElement. Например, используя следующий тип.

[DataContract(Namespace="http://schemas.contoso.com")]
public class MyDataContract
{
    [DataMember]
    public XmlNode[] myDataMember = new XmlNode[4];
    public void TestClass()
    {
        XmlDocument xd = new XmlDocument();
        XmlElement xe = xd.CreateElement("myElement");
        xe.InnerText = "myContents";
        xe.SetAttribute
         ("myAttribute","myValue");
    
        XmlAttribute atr = xe.Attributes[0];
        XmlComment cmnt = xd.CreateComment("myComment");
        
      myDataMember[0] = atr;
      myDataMember[1] = cmnt;
      myDataMember[2] = xe;
      myDataMember[3] = xe;
    }
}

<DataContract([Namespace]:="http://schemas.contoso.com")> _
Public Class MyDataContract
    <DataMember()> _
    Public myDataMember(3) As XmlNode

    Public Sub TestClass()
        Dim xd As New XmlDocument()
        Dim xe As XmlElement = xd.CreateElement("myElement")
        xe.InnerText = "myContents"
        xe.SetAttribute("myAttribute", "myValue")

        Dim atr As XmlAttribute = xe.Attributes(0)
        Dim cmnt As XmlComment = xd.CreateComment("myComment")

        myDataMember(0) = atr
        myDataMember(1) = cmnt
        myDataMember(2) = xe
        myDataMember(3) = xe

    End Sub

End Class

При сериализации результирующий XML-код аналогичен следующему коду.

<MyDataContract xmlns="http://schemas.contoso.com">
  <myDataMember myAttribute="myValue">
     <!--myComment-->
     <myElement xmlns="" myAttribute="myValue">
 myContents
     </myElement>
     <myElement xmlns="" myAttribute="myValue">
       myContents
     </myElement>
  </myDataMember>
</MyDataContract>

Обратите внимание, что элемент <myDataMember> оболочки элемента данных содержит атрибут, комментарий и два элемента. Это четыре XmlNode экземпляра, которые были сериализованы.

Массив XmlNode , который приводит к недопустимому XML-файлу, не может быть сериализован. Например, массив из двух экземпляров XmlNode, где первый является XmlElement, а второй — XmlAttribute, является недопустимым, поскольку эта последовательность не соответствует ни одной допустимой XML структуре (некуда присоединить атрибут).

При десериализации массива XmlNode узлов создаются и заполняются сведениями из входящего XML. Допустимый родительский объект XmlDocument предоставляется десериализатором. Все узлы десериализуются, включая любые атрибуты элемента-оболочки члена данных, но исключая атрибуты, помещенные сериализаторами WCF (например, атрибуты, используемые для указания полиморфного назначения). Предостережение о определении всех префиксов пространства имен в фрагменте XML применяется к десериализации массивов XmlNode так же, как и к десериализации XmlElement.

При использовании сериализаторов с включенным сохранением графа объектов равенство объектов сохраняется только на уровне XmlNode массивов, а не отдельных XmlNode экземпляров.

Не пытайтесь сериализовать массив XmlNode, если один или несколько узлов установлены в null. Разрешено для всего элемента массива null, но не для любого отдельного элемента XmlNode, содержащегося в массиве. Если весь элемент массива имеет значение NULL, элемент-член данных-оболочки содержит специальный атрибут, указывающий, что он имеет значение NULL. При десериализации весь элемент массива также становится null.

Только обычные массивы XmlNode обрабатываются специально сериализатором. Элементы данных, объявленные как другие типы коллекций, содержащие XmlNodeили члены данных, объявленные как массивы типов, производных от XmlNode, не обрабатываются специально. Таким образом, они обычно не сериализуются, если они не соответствуют одному из других критериев сериализации.

Разрешены массивы или коллекции массивов XmlNode . Существует элемент-оболочка для всей коллекции и отдельный элемент оболочки (аналогично <myDataMember> предыдущему примеру) для каждого массива XmlNode во внешнем массиве или коллекции.

Заполнение элемента данных типа Array или Object из Array или IEnumerable экземплярами XmlNode не приводит к тому, что элемент данных обрабатывается как Array из экземпляров XmlNode. Каждый элемент массива сериализуется отдельно.

При использовании с DataContractSerializer массивами XmlNode их можно полиморфно назначать, но только элементу данных типа Object. Несмотря на то, что он реализует IEnumerable, массив XmlNode не может использоваться в качестве типа коллекции и быть назначен элементу IEnumerable данных. Как и во всех полиморфных назначениях, DataContractSerializer выдает имя контракта данных в результирующем XML; в этом случае оно "ArrayOfXmlNode" в пространстве имен http://schemas.datacontract.org/2004/07/System.Xml. При использовании с NetDataContractSerializer, поддерживается любое допустимое назначение массива XmlNode.

Соображения по схеме

Дополнительные сведения о сопоставлении схем типов XML см. в справочнике по схеме контракта данных. В этом разделе представлена сводка важных моментов.

Элемент данных типа XmlElement сопоставляется с элементом, определенным с помощью следующего анонимного типа.

<xsd:complexType>
   <xsd:sequence>
      <xsd:any minOccurs="0" processContents="lax" />
   </xsd:sequence>
</xsd:complexType>

Элемент данных массива XmlNode типов сопоставляется с элементом, определенным с помощью следующего анонимного типа.

<xsd:complexType mixed="true">
   <xsd:sequence>
      <xsd:any minOccurs="0" maxOccurs="unbounded" processContents="lax" />
   </xsd:sequence>
   <xsd:anyAttribute/>
</xsd:complexType>

Типы, реализующие интерфейс IXmlSerializable

Типы, которые реализуют интерфейс IXmlSerializable, полностью поддерживаются DataContractSerializer. Атрибут XmlSchemaProviderAttribute всегда должен применяться к этим типам для управления схемой.

Существует три разновидности типов, реализующих IXmlSerializable: типы, представляющие произвольное содержимое, типы, представляющие один элемент и устаревшие DataSet типы.

Типы контента используют метод поставщика схем, указанный атрибутом XmlSchemaProviderAttribute . Метод не возвращает null, а свойство IsAny атрибута остается по умолчанию значением false. Это наиболее распространенное использование IXmlSerializable типов.
Типы элементов используются, когда IXmlSerializable тип должен управлять собственным корневым именем элемента. Чтобы указать тип как тип элемента, задайте свойство IsAny атрибута XmlSchemaProviderAttribute в true, или же верните null из метода поставщика схемы. Может быть необязательным использование метода поставщика схемы для типов элементов — вместо имени метода в элементе XmlSchemaProviderAttribute можно указать значение NULL. Однако, если IsAny является true и указан метод провайдера схемы, метод должен возвращать значение null.
Устаревшие DataSet типы — это IXmlSerializable типы, которые не помечены атрибутом XmlSchemaProviderAttribute . Вместо этого они полагаются на GetSchema метод для создания схемы. Этот шаблон используется для DataSet типа, и в более ранних версиях .NET Framework его типизированный набор данных производит класс, но теперь он устарел и поддерживается только по причинам наследия. Не полагайтесь на этот шаблон и всегда применяйте XmlSchemaProviderAttribute к типам IXmlSerializable.

Типы контента IXmlSerializable

При сериализации элемента данных типа, реализующего IXmlSerializable и являющегося типом контента, как определено ранее, сериализатор записывает элемент оболочки для элемента данных и передает элемент управления методу WriteXml . Реализация WriteXml может записывать любой XML-код, включая добавление атрибутов в элемент оболочки. После завершения WriteXml сериализатор закрывает элемент.

При десериализации элемента данных типа, реализующего IXmlSerializable и являющегося типом контента, как определено ранее, десериализатор помещает средство чтения XML на элемент оболочки для элемента данных и передает элемент управления методу ReadXml . Метод должен считывать весь элемент, включая начальные и конечные теги. Убедитесь, что ReadXml код обрабатывает случай, когда элемент пуст. Кроме того, реализация ReadXml не должна полагаться на элемент оболочки, который называется определенным способом. Имя, выбранное сериализатором, может отличаться.

Можно назначать IXmlSerializable типы контента полиморфно, например членам данных типа Object. Кроме того, для экземпляров типов допускается значение NULL. Наконец, можно использовать типы IXmlSerializable с включенным сохранением графа объектов и с использованием NetDataContractSerializer. Все эти функции требуют, чтобы сериализатор WCF присоединял определенные атрибуты к элементу-оболочке ('nil' и 'type' в пространстве имен экземпляра схемы XML и 'Id', 'Ref', 'Type' и 'Assembly' в пространстве имен, специфичном для WCF).

Атрибуты, которые следует игнорировать при реализации ReadXml

Перед передачей элемента управления в ReadXml код десериализатор проверяет XML-элемент, обнаруживает эти специальные XML-атрибуты и выполняет соответствующие действия. Например, если "nil" имеет значение true, десериализуется null, и ReadXml не вызывается. Если обнаружен полиморфизм, содержимое элемента десериализировано, как будто это был другой тип. Вызывается полиморфная реализация ReadXml типа. В любом случае, реализация ReadXml должна игнорировать эти специальные атрибуты, поскольку они обрабатываются десериализатором.

Типы элементов IXmlSerializable

IXmlSerializable Типы элементов имеют либо свойство IsAny, установленное в true, либо их метод поставщика схем возвращает null.

Сериализация и десериализация типа элемента очень похожа на сериализацию и десериализацию типа контента. Однако существуют некоторые важные различия:

Ожидается, что реализация WriteXml будет записывать ровно один элемент, который, конечно, может содержать несколько дочерних элементов. Не следует писать атрибуты за пределами этого одного элемента, нескольких одноуровневых элементов или смешанного содержимого. Элемент может быть пустым.
Реализация ReadXml не должна считывать элемент оболочки. Ожидается, что он считывает один элемент, который WriteXml создает.
При регулярной сериализации типа элемента (например, в качестве члена данных в контракте данных) сериализатор выводит элемент оболочки перед вызовом WriteXml, так же, как и для типов содержимого. Однако при сериализации типа элемента на верхнем уровне сериализатор обычно не выводит элемент-оболочку вокруг элемента, который записывается WriteXml, если только корневое имя и пространство имен не были явно указаны при создании сериализатора в конструкторах DataContractSerializer или NetDataContractSerializer. Дополнительные сведения см. в разделе Сериализация и десериализация.
При сериализации типа элемента на верхнем уровне без указания корневого имени и пространства имен во время построения, WriteStartObject и WriteEndObject по сути ничего не делают, а WriteObjectContent вызывает WriteXml. В этом режиме сериализованный объект не может иметь значение NULL и не может быть полиморфно назначен. Кроме того, сохранение графа объектов не может быть включено и NetDataContractSerializer не может использоваться.
При десериализации элемента на верхнем уровне без указания корневого имени и пространства имен во время построения IsStartObject возвращает true, если может найти начало любого элемента. ReadObject с параметром verifyObjectName установленным true ведет себя таким же образом, как IsStartObject, перед фактическим чтением объекта. ReadObject затем передает управление методу ReadXml.

Схема, экспортируемая для типов элементов, такая же, как для типа XmlElement, как описано в предыдущем разделе, за исключением того, что метод поставщика схем может добавить любую дополнительную схему в XmlSchemaSet, как и для типов контента. Использование атрибута XmlRootAttribute с типами элементов не допускается, а глобальные объявления элементов никогда не создаются для этих типов.

Различия от XmlSerializer

Интерфейс IXmlSerializable и атрибуты XmlSchemaProviderAttribute и XmlRootAttribute также распознаются системой XmlSerializer. Однако существуют некоторые различия в том, как они обрабатываются в модели контракта данных. Важные различия приведены в следующих статьях:

Метод поставщика схем должен быть общедоступным для использования в XmlSerializer, но не обязательно быть общедоступным для использования в модели контракта данных.
Метод поставщика схемы вызывается, когда IsAny имеет значение true в модели контракта данных, но не когда XmlSerializer имеет значение true.
Если атрибут XmlRootAttribute не присутствует для типов содержимого или устаревших наборов данных, XmlSerializer экспортирует глобальное объявление элемента в пустом пространстве имен. В модели контракта данных обычно используется пространство имен контракта данных, как описано ранее.

Учитывайте эти различия при создании типов, используемых с обеими технологиями сериализации.

Импорт схемы IXmlSerializable

При импорте схемы, созданной из IXmlSerializable типов, существует несколько возможностей:

Созданная схема может быть допустимой схемой контракта данных, как описано в справочнике по схеме контракта данных. В этом случае схема может быть импортирована как обычно, и генерируются стандартные типы контрактов данных.
Созданная схема может не быть допустимой схемой контракта данных. Например, метод поставщика схем может создать схему, которая включает атрибуты XML, которые не поддерживаются в модели контракта данных. В этом случае схему данных можно импортировать как IXmlSerializable типы. Этот режим импорта не включен по умолчанию, но его можно легко включить. Например, при /importXmlTypes переключении командной строки на средство служебной программы метаданных ServiceModel (Svcutil.exe). Это подробно описано в Импорт схемы для генерации классов. Обратите внимание, что вы должны работать непосредственно с XML для объектов типов. Вы также можете использовать другую технологию сериализации, которая поддерживает более широкий диапазон схем. См. раздел об использовании XmlSerializer.
Вместо создания новых типов может потребоваться повторно использовать существующие IXmlSerializable типы в прокси-сервере. В этом случае функция ссылочных типов, описанная в разделе импорта схемы для создания типов, может использоваться для указания типа для повторного использования. Это соответствует использованию переключателя /reference на svcutil.exe, указывающего сборку, содержащую типы для повторного использования.

Представление произвольного XML-кода в контрактах данных

Типы XmlElement, Массив XmlNode и IXmlSerializable позволяют внедрять произвольный XML-код в модель контракта данных. DataContractSerializer и NetDataContractSerializer передают это XML-содержимое используемому XML-писателю, не вмешиваясь в процесс. Тем не менее авторы XML могут применять определенные ограничения на XML, который они пишут. В частности, ниже приведены некоторые важные примеры:

Создатели XML обычно не поддерживают объявление XML-документа (например, <?xml version='1.0'?>) во время написания другого документа. Вы не можете взять полный XML-документ и сериализовать его как ArrayXmlNode элемент данных. Для этого необходимо либо удалить объявление документа, либо использовать собственную кодировочную схему, чтобы представить документ.
Все записи XML, предоставленные WCF, отклоняют инструкции по обработке XML (<? ...> ) и определения типов документов (<! ... >), так как они не допускаются в сообщениях SOAP. Опять же, вы можете использовать собственный механизм кодирования для обхода этого ограничения. Если вы должны включить их в результирующий XML, можно написать пользовательский кодировщик, использующий XML-писатели, которые их поддерживают.
При реализации WriteXml избегайте вызова метода WriteRaw на записывающем XML. WCF использует различные кодировки XML (включая двоичные), поэтому очень трудно или даже невозможно использовать WriteRaw так, чтобы результат был пригоден для использования в любой кодировке.
При реализации WriteXml избегайте использования методов WriteEntityRef и WriteNmToken, так как они не поддерживаются на XML-писателях, предоставляемых WCF.

Использование набора данных, типизированного набора данных и Таблицы данных

Использование этих типов полностью поддерживается в модели контракта данных. При использовании этих типов следует учитывать следующие моменты:

Схема для этих типов (особенно DataSet и его типизированные производные классы) может не взаимодействовать с некоторыми платформами, отличными от WCF, или может привести к плохому использованию при использовании с этими платформами. Кроме того, использование DataSet типа может иметь последствия для производительности. Наконец, это может затруднить вам управлять версиями вашего приложения в будущем. Рекомендуется использовать явно определенные типы контрактов данных вместо DataSet типов в контрактах.
При импорте DataSet или DataTable схем важно ссылаться на эти типы. С помощью средства командной строки Svcutil.exe это можно сделать, передав имя сборки System.Data.dll в опцию /reference. При импорте схемы типизированного набора данных необходимо ссылаться на типизированный тип набора данных. При Svcutil.exeпередайте расположение сборки типизированного набора данных коммутатору /reference . Дополнительные сведения о типах ссылок см. в статье "Импорт схемы для создания классов".

Поддержка типизированных наборов данных в модели контракта данных ограничена. Типизированные наборы данных можно сериализовать и десериализировать, а также экспортировать их схему. Однако импорт схемы контракта данных не может создавать новые типизированные типы Наборов данных из схемы, так как он может повторно использовать существующие. Вы можете указать существующий типизированный набор данных с помощью /r переключателя на Svcutil.exe. Если вы пытаетесь использовать Svcutil.exe без /r переключателя в службе, используюющей типизированный набор данных, автоматически выбирается альтернативный сериализатор (XmlSerializer). Если вы должны использовать DataContractSerializer и должны создавать наборы данных из схемы, можно использовать следующую процедуру: создайте типизированные типы наборов данных (с помощью средства Xsd.exe с /d переключателем службы), скомпилируйте типы, а затем укажите их с помощью /r переключателя на Svcutil.exe.

См. также

Последнее обновление: 2023-04-11