Apresentando a serialização XMLIntroducing XML Serialization

A serialização é o processo de conversão de um objeto em um formulário que possa ser prontamente transportado.Serialization is the process of converting an object into a form that can be readily transported. Por exemplo, você pode serializar um objeto e transportá-lo pela Internet usando HTTP entre um cliente e um servidor.For example, you can serialize an object and transport it over the Internet using HTTP between a client and a server. Na outra extremidade, a desserialização reconstrói o objeto a partir do fluxo.On the other end, deserialization reconstructs the object from the stream.

A serialização XML serializa apenas os valores de propriedades e de campos públicos de um objeto em um fluxo XML.XML serialization serializes only the public fields and property values of an object into an XML stream. A serialização XML não inclui informações de tipo.XML serialization does not include type information. Por exemplo, se você tiver um objeto Book no namespace Library, não haverá garantia de que ele será desserializado em um objeto do mesmo tipo.For example, if you have a Book object that exists in the Library namespace, there is no guarantee that it is deserialized into an object of the same type.

Observação

A serialização XML não converte métodos, indexadores, campos privados nem propriedades somente leitura (exceto coleções somente leitura).XML serialization does not convert methods, indexers, private fields, or read-only properties (except read-only collections). Para serializar todos os campos e propriedades (públicos e privados) de um objeto, use DataContractSerializer, em vez da serialização XML.To serialize all an object's fields and properties, both public and private, use the DataContractSerializer instead of XML serialization.

A classe central na serialização XML é a classe XmlSerializer e os métodos mais importantes nessa classe são os métodos Serialize e Deserialize.The central class in XML serialization is the XmlSerializer class, and the most important methods in this class are the Serialize and Deserialize methods. O XmlSerializer cria arquivos C# e compila-os em arquivos .dll para executar essa serialização.The XmlSerializer creates C# files and compiles them into .dll files to perform this serialization. No .NET Framework 2.0, a Ferramenta Geradora de Serializador XML (Sgen.exe) tem como objetivo gerar com antecedência esses assemblies de serialização a serem implantados com seu aplicativo e melhorar o desempenho da inicialização.In .NET Framework 2.0, the XML Serializer Generator Tool (Sgen.exe) is designed to generate these serialization assemblies in advance to be deployed with your application and improve startup performance. O fluxo XML gerado pelo XmlSerializer está em conformidade com o World Wide Web Consortium (W3C) linguagem de definição de esquema XML (XSD) 1.0 recomendação.The XML stream generated by the XmlSerializer is compliant with the World Wide Web Consortium (W3C) XML Schema definition language (XSD) 1.0 recommendation. Além disso, os tipos de dados gerados estão em conformidade com o documento intitulado "XML Schema Part 2: Tipos de dados."Furthermore, the data types generated are compliant with the document titled "XML Schema Part 2: Datatypes."

Os dados em seus objetos são descritos com o uso de construções de linguagem de programação como classes, campos, propriedades, tipos primitivos, matrizes e até mesmo XML inserido na forma de objetos XmlElement ou XmlAttribute.The data in your objects is described using programming language constructs like classes, fields, properties, primitive types, arrays, and even embedded XML in the form of XmlElement or XmlAttribute objects. Você tem a opção de criar suas próprias classes, anotadas com atributos, ou de usar a ferramenta de definição de esquema XML para gerar as classes com base em um esquema XML existente.You have the option of creating your own classes, annotated with attributes, or using the XML Schema Definition tool to generate the classes based on an existing XML Schema.

Se você tiver um esquema XML, poderá executar a ferramenta de definição de esquema XML para gerar um conjunto de classes fortemente tipadas para o esquema e anotadas com atributos.If you have an XML Schema, you can run the XML Schema Definition tool to produce a set of classes that are strongly typed to the schema and annotated with attributes. Quando uma instância desse tipo de classe é serializada, o XML adere ao esquema XML.When an instance of such a class is serialized, the generated XML adheres to the XML Schema. Se você tiver uma classe desse tipo, poderá programar com um modelo de objeto facilmente manipulado com a certeza de que o XML gerado está de acordo com o esquema XML.Provided with such a class, you can program against an easily manipulated object model while being assured that the generated XML conforms to the XML schema. Trata-se de uma alternativa ao uso de outras classes do .NET Framework, tais como as classes XmlReader e XmlWriter, para analisar e gravar um fluxo XML.This is an alternative to using other classes in the .NET Framework, such as the XmlReader and XmlWriter classes, to parse and write an XML stream. Para obter mais informações, consulte Documentos e dados XML.For more information, see XML Documents and Data. Essas classes permitem analisar qualquer fluxo XML.These classes allow you to parse any XML stream. Em contraste, use XmlSerializer quando o fluxo XML precisar estar em conformidade com um esquema XML conhecido.In contrast, use the XmlSerializer when the XML stream is expected to conform to a known XML Schema.

Os atributos controlam o fluxo XML gerado pela classe XmlSerializer, permitindo que você defina itens do fluxo XML, como o namespace de XML, o nome do elemento, o nome do atributo e assim por diante.Attributes control the XML stream generated by the XmlSerializer class, allowing you to set the XML namespace, element name, attribute name, and so on, of the XML stream. Para obter mais informações sobre como esses atributos e como eles controlam a serialização XML, consulte Controlando a serialização XML usando atributos.For more information about these attributes and how they control XML serialization, see Controlling XML Serialization Using Attributes. Para ver uma tabela desses atributos que são usados para controlar o XML gerado, consulte Atributos que controlam a serialização XML.For a table of those attributes that are used to control the generated XML, see Attributes That Control XML Serialization.

A classe XmlSerializer pode serializar ainda mais um objeto e gerar um fluxo XML SOAP codificado.The XmlSerializer class can further serialize an object and generate an encoded SOAP XML stream. O XML gerado adere à seção 5 do documento "Simple Object Access Protocol (SOAP) 1.1" do World Wide Web Consortium.The generated XML adheres to section 5 of the World Wide Web Consortium document titled "Simple Object Access Protocol (SOAP) 1.1." Para obter mais informações sobre esse processo, consulte como: Serializar um objeto como um Stream XML com codificação SOAP.For more information about this process, see How to: Serialize an Object as a SOAP-Encoded XML Stream. Para ver uma tabela dos atributos que controlam o XML gerado, consulte Atributos que controlam a serialização SOAP codificada.For a table of the attributes that control the generated XML, see Attributes That Control Encoded SOAP Serialization.

A classe XmlSerializer gera as mensagens SOAP criadas por serviços Web XML e passadas para eles.The XmlSerializer class generates the SOAP messages created by, and passed to, XML Web services. Para controlar as mensagens SOAP, você pode aplicar atributos às classes, aos valores de retorno, aos parâmetros e aos campos localizados em um arquivo de serviço Web XML (.asmx).To control the SOAP messages, you can apply attributes to the classes, return values, parameters, and fields found in an XML Web service file (.asmx). É possível usar ambos os atributos listados em "Atributos que controlam a serialização XML" e em "Atributos que controlam a serialização SOAP codificada" porque um serviço Web XML pode usar o estilo SOAP literal ou codificado.You can use both the attributes listed in "Attributes That Control XML Serialization" and "Attributes That Control Encoded SOAP Serialization" because an XML Web service can use either the literal or encoded SOAP style. Para obter mais informações sobre como usar atributos para controlar o XML gerado por um serviço Web XML, consulte Serialização XML com Serviços Web XML.For more information about using attributes to control the XML generated by an XML Web service, see XML Serialization with XML Web Services. Para obter mais informações sobre os serviços Web XML e SOAP, consulte personalizando formatação das mensagens SOAP.For more information about SOAP and XML Web services, see Customizing SOAP Message Formatting.

Considerações de segurança para aplicativos XmlSerializerSecurity Considerations for XmlSerializer Applications

Ao criar um aplicativo que use XmlSerializer, esteja ciente dos seguintes itens e de suas implicações:When creating an application that uses the XmlSerializer, you should be aware of the following items and their implications:

  • O XmlSerializer cria arquivos C# (.cs) e compila-os em arquivos .dll no diretório nomeado pela variável de ambiente TEMP; a serialização ocorre com essas DLLs.The XmlSerializer creates C# (.cs) files and compiles them into .dll files in the directory named by the TEMP environment variable; serialization occurs with those DLLs.

    Observação

    Esses assemblies de serialização podem ser gerados com antecedência e assinados com o uso da ferramenta SGen.exe.These serialization assemblies can be generated in advance and signed by using the SGen.exe tool. Isso não funciona em um servidor de serviços Web.This does not work a server of Web services. Em outras palavras, esses assemblies são apenas para uso de cliente e para serialização manual.In other words, it is only for client use and for manual serialization.

    O código e as DLLs ficam vulneráveis a um processo mal-intencionado no momento de criação e compilação.The code and the DLLs are vulnerable to a malicious process at the time of creation and compilation. Quando um computador que execute o Microsoft Windows NT 4.0 ou posterior é usado, é possível que dois ou mais usuários compartilhem o diretório TEMP.When using a computer running Microsoft Windows NT 4.0 or later, it might be possible for two or more users to share the TEMP directory. O compartilhamento de um diretório TEMP é perigoso quando as duas contas têm privilégios de segurança diferentes e a conta com maior privilégio executa um aplicativo usando o XmlSerializer.Sharing a TEMP directory is dangerous if the two accounts have different security privileges and the higher-privilege account runs an application using the XmlSerializer. Nesse caso, um usuário pode violar a segurança do computador substituindo o arquivo .cs ou .dll compilado.In this case, one user can breach the computer's security by replacing either the .cs or .dll file that is compiled. Para eliminar essa preocupação, sempre verifique se cada conta no computador tem seu próprio perfil.To eliminate this concern, always be sure that each account on the computer has its own profile. Por padrão, as variáveis de ambiente TEMP apontam para um diretório diferente para cada conta.By default, the TEMP environment variable points to a different directory for each account.

  • Se algum usuário mal-intencionado enviar um fluxo contínuo de dados XML para um servidor Web (um ataque de negação de serviço), então o XmlSerializer continuará a processar os dados até o computador ser executado com um número insuficiente de recursos.If a malicious user sends a continuous stream of XML data to a Web server (a denial of service attack), then the XmlSerializer continues to process the data until the computer runs low on resources.

    Esse tipo de ataque será eliminado se você usar um computador que execute o IIS (Serviços de Informações da Internet) e seu aplicativo for executado no IIS.This kind of attack is eliminated if you are using a computer running Internet Information Services (IIS), and your application is running within IIS. Os IIS apresenta um portão que não processa fluxos maiores do que uma quantidade especificada (o padrão é de 4 KB).IIS features a gate that does not process streams longer than a set amount (the default is 4 KB). Se você criar um aplicativo que não use o IIS e que desserialize com o XmlSerializer, você deverá implementar um portão similar que evite um ataque de negação de serviço.If you create an application that does not use IIS and deserializes with the XmlSerializer, you should implement a similar gate that prevents a denial of service attack.

  • O XmlSerializer serializa dados e executa qualquer código usando qualquer tipo especificado para ele.The XmlSerializer serializes data and runs any code using any type given to it.

    Existem duas maneiras de um objeto mal-intencionado apresentar uma ameaça.There are two ways in which a malicious object presents a threat. Ele pode executar o código mal-intencionado ou injetar o código mal-intencionado no arquivo C# criado pelo XmlSerializer.It could run malicious code or it could inject malicious code into the C# file created by the XmlSerializer. No primeiro caso, se um objeto mal-intencionado tentar executar um procedimento destrutivo, a segurança de acesso do código ajudará a evitar danos.In the first case, if a malicious object tries to run a destructive procedure, code access security helps prevent any damage from being done. No segundo caso, há uma possibilidade teórica de que um objeto mal-intencionado possa, de alguma forma, injetar o código no arquivo C# criado pelo XmlSerializer.In the second case, there is a theoretical possibility that a malicious object may somehow inject code into the C# file created by the XmlSerializer. Embora esse problema tenha sido examinado detalhadamente e um ataque desse tipo seja considerado improvável, é preciso tomar cuidado para nunca serializar dados com um tipo desconhecido e não confiável.Although this issue has been examined thoroughly, and such an attack is considered unlikely, you should take the precaution of never serializing data with an unknown and untrusted type.

  • Dados confidenciais serializados podem ficar vulneráveis.Serialized sensitive data might be vulnerable.

    Após o XmlSerializer serializar os dados, ele pode ser armazenado como um arquivo XML ou outro armazenamento de dados.After the XmlSerializer has serialized data, it can be stored as an XML file or other data store. Se seu repositório de dados estiver disponível para outros processos, ou estiver visível em uma intranet ou na Internet, os dados poderão ser roubados e usados de maneira mal-intencionada.If your data store is available to other processes, or is visible on an intranet or the Internet, the data can be stolen and used maliciously. Por exemplo, quando você cria um aplicativo que serializa pedidos que incluam números de cartão de crédito, os dados são altamente confidenciais.For example, if you create an application that serializes orders that include credit card numbers, the data is highly sensitive. Para ajudar a evitar problemas, sempre proteja o repositório dos dados e siga as etapas para mantê-lo privado.To help prevent this, always protect the store for your data and take steps to keep it private.

Serialização de uma classe simplesSerialization of a Simple Class

O exemplo de código a seguir mostra uma classe básica com um campo público.The following code example shows a basic class with a public field.

Public Class OrderForm
    Public OrderDate As DateTime
End Class
public class OrderForm
{
    public DateTime OrderDate;
}

Quando uma instância dessa classe é serializada, ela pode ser similar ao exemplo a seguir.When an instance of this class is serialized, it might resemble the following.

<OrderForm>
    <OrderDate>12/12/01</OrderDate>
</OrderForm>

Para obter mais exemplos de serialização, consulte Exemplos de Serialização XML.For more examples of serialization, see Examples of XML Serialization.

Itens que podem ser serializadosItems That Can Be Serialized

Os itens a seguir podem ser serializados com a classe XmLSerializer:The following items can be serialized using the XmLSerializer class:

  • Propriedades e campos de leitura/gravação públicos de classes públicas.Public read/write properties and fields of public classes.

  • Classes que implementam ICollection ou IEnumerable.Classes that implement ICollection or IEnumerable.

    Observação

    Somente as coleções são serializadas, não propriedades públicas.Only collections are serialized, not public properties.

  • Objetos XmlElement.XmlElement objects.

  • Objetos XmlNode.XmlNode objects.

  • Objetos DataSet.DataSet objects.

Para obter mais informações sobre a serialização ou desserialização de objetos, consulte como: Serializar um objeto e como: Desserializar um objeto.For more information about serializing or deserializing objects, see How to: Serialize an Object and How to: Deserialize an Object.

Vantagens de usar a serialização XMLAdvantages of Using XML Serialization

O XmlSerializer classe lhe dá controle total e flexível quando você serializa um objeto como XML.The XmlSerializer class gives you complete and flexible control when you serialize an object as XML. Se você estiver criando um serviço Web XML, poderá aplicar atributos que controlam a serialização para classes e membros para garantir que a saída XML esteja de acordo com um esquema específico.If you are creating an XML Web service, you can apply attributes that control serialization to classes and members to ensure that the XML output conforms to a specific schema.

Por exemplo, XmlSerializer permite que você:For example, XmlSerializer enables you to:

  • Especificar se um campo ou propriedade deve ser codificado como atributo ou como elemento.Specify whether a field or property should be encoded as an attribute or an element.

  • Especificar um namespace XML a ser usado.Specify an XML namespace to use.

  • Especificar o nome de um elemento ou atributo se um nome de campo ou de propriedade estiver incorreto.Specify the name of an element or attribute if a field or property name is inappropriate.

Outra vantagem da serialização XML é que não há restrições aos aplicativos que você desenvolve, contanto que o fluxo XML gerado esteja de acordo com o esquema especificado.Another advantage of XML serialization is that you have no constraints on the applications you develop, as long as the XML stream that is generated conforms to a given schema. Imagine um esquema usado para descrever livros.Imagine a schema that is used to describe books. Ele apresenta os elementos título, autor, editor e número ISBN.It features a title, author, publisher, and ISBN number element. Você pode desenvolver um aplicativo que processe os dados XML da forma que desejar, por exemplo, como um pedido de livro ou como um inventário de livros.You can develop an application that processes the XML data in any way you want, for example, as a book order, or as an inventory of books. Em ambos os casos, o único requisito é que o fluxo XML esteja de acordo com o esquema XSD especificado.In either case, the only requirement is that the XML stream conforms to the specified XML Schema definition language (XSD) schema.

Considerações de serialização XMLXML Serialization Considerations

A observação a seguir deve ser considerada ao usar a classe XmlSerializer:The following should be considered when using the XmlSerializer class:

  • A ferramenta Sgen.exe é expressamente destinada a gerar assemblies de serialização para desempenho máximo.The Sgen.exe tool is expressly designed to generate serialization assemblies for optimum performance.

  • Os dados serializados contêm somente os próprios dados e a estrutura de suas classes.The serialized data contains only the data itself and the structure of your classes. A identidade de tipos e as informações de assemblies não são incluídas.Type identity and assembly information are not included.

  • Somente as propriedades e os campos públicos podem ser serializados.Only public properties and fields can be serialized. As propriedades devem ter acessadores públicos (métodos get e set).Properties must have public accessors (get and set methods). Se você precisar serializar dados não públicos, use a classe DataContractSerializer, em vez da serialização XML.If you must serialize non-public data, use the DataContractSerializer class rather than XML serialization.

  • Uma classe deve ter um construtor sem parâmetros a serem serializadas por XmlSerializer.A class must have a parameterless constructor to be serialized by XmlSerializer.

  • Os métodos não podem ser serializados.Methods cannot be serialized.

  • XmlSerializer pode processar classes que implementam IEnumerable ou ICollection de maneira diferente caso elas atendam a determinados requisitos, como a seguir.XmlSerializer can process classes that implement IEnumerable or ICollection differently if they meet certain requirements, as follows.

    Uma classe que implementa IEnumerable deve implementar um método Add público que aceita um único parâmetro.A class that implements IEnumerable must implement a public Add method that takes a single parameter. O parâmetro do método Add deve ser consistente (polimórfico) com o tipo retornado da propriedade IEnumerator.Current, retornada do método GetEnumerator.The Add method's parameter must be consistent (polymorphic) with the type returned from the IEnumerator.Current property returned from the GetEnumerator method.

    Uma classe que implementa ICollection, além de IEnumerable (como CollectionBase), deve ter uma propriedade pública indexada Item (um indexador em C#) que aceite um inteiro e deve ter uma propriedade pública Count do tipo integer.A class that implements ICollection in addition to IEnumerable (such as CollectionBase) must have a public Item indexed property (an indexer in C#) that takes an integer and it must have a public Count property of type integer. O parâmetro passado para o método Add deve ser do mesmo tipo que aquele retornado pela propriedade Item ou deve corresponder a uma das bases desse tipo.The parameter passed to the Add method must be the same type as that returned from the Item property, or one of that type's bases.

    Para as classes que implementam ICollection, os valores a serem serializados são recuperados da propriedade indexada Item, não ao chamar GetEnumerator.For classes that implement ICollection, values to be serialized are retrieved from the indexed Item property rather than by calling GetEnumerator. Além disso, propriedades e campos públicos não são serializados, exceto os campos públicos que retornam outra classe de coleção (que implemente ICollection).Also, public fields and properties are not serialized, with the exception of public fields that return another collection class (one that implements ICollection). Para obter um exemplo, consulte Exemplos de serialização XML.For an example, see Examples of XML Serialization.

Mapeamento de tipo de dados XSDXSD Data Type Mapping

O documento W3C XML Schema Part 2: Tipos de dados Especifica os tipos de dados simples que são permitidos em um esquema XSD (linguagem) de definição de esquema XML.The W3C document titled XML Schema Part 2: Datatypes specifies the simple data types that are allowed in an XML Schema definition language (XSD) schema. Para muitos desses tipos (por exemplo, int e decimal), há um tipo de dados correspondente no .NET Framework.For many of these (for example, int and decimal), there is a corresponding data type in the .NET Framework. No entanto, alguns tipos de dados XML não têm um tipo de dados correspondente no .NET Framework (por exemplo, o tipo de dados NMTOKEN).However, some XML data types do not have a corresponding data type in the .NET Framework (for example, the NMTOKEN data type). Nesses casos, se você usar a ferramenta de definição de esquema XML (Ferramenta de Definição de Esquema XML (Xsd.exe)) para gerar classes de um esquema, um atributo apropriado será aplicado a um membro de tipo string e a respectiva propriedade DataType será definida como o nome do tipo de dados XML.In such cases, if you use the XML Schema Definition tool (XML Schema Definition Tool (Xsd.exe)) to generate classes from a schema, an appropriate attribute is applied to a member of type string, and its DataType property is set to the XML data type name. Por exemplo, se um esquema contiver um elemento nomeado "MyToken" com o tipo de dados XML NMTOKEN, a classe gerada poderá conter um membro conforme mostrado no exemplo a seguir.For example, if a schema contains an element named "MyToken" with the XML data type NMTOKEN, the generated class might contain a member as shown in the following example.

<XmlElement(DataType:="NMTOKEN")> _
Public MyToken As String
[XmlElement(DataType = "NMTOKEN")]
public string MyToken;

Da mesma forma, se você estiver criando uma classe que precise estar em conformidade com um esquema XML (XSD) específico, deverá aplicar o atributo apropriado e definir sua propriedade DataType como o nome do tipo de dados XML desejado.Similarly, if you are creating a class that must conform to a specific XML Schema (XSD), you should apply the appropriate attribute and set its DataType property to the desired XML data type name.

Para obter uma lista completa de mapeamentos de tipo, consulte a propriedade DataType para algumas das seguintes classes de atributos:For a complete list of type mappings, see the DataType property for any of the following attribute classes:

Consulte tambémSee also