XmlMessageFormatter Класс

Определение

Сериализует объекты в текст сообщения или десериализует текст сообщения в объекты, используя для этого формат XML, основанный на определении схемы XSD.Serializes and deserializes objects to or from the body of a message, using the XML format based on the XSD schema definition.

public ref class XmlMessageFormatter : ICloneable, System::Messaging::IMessageFormatter
public class XmlMessageFormatter : ICloneable, System.Messaging.IMessageFormatter
type XmlMessageFormatter = class
    interface IMessageFormatter
    interface ICloneable
Public Class XmlMessageFormatter
Implements ICloneable, IMessageFormatter
Наследование
XmlMessageFormatter
Реализации

Примеры

Следующий пример кода включает три части кода: серверный компонент, класс заказа и клиентский код.The following code example includes three pieces of code: a server component, an order class, and client code. Класс Order может использоваться служебной программой XSD. exe для создания схемы, которую сервер распознает в входящих сообщениях.The order class can be used by the XSD.exe utility to generate schema that the server recognizes within incoming messages. Схема представляет собой файл в формате XML, описывающий "форму" класса.The schema is an XML formatted file that describes the "shape" of the class. Затем эту схему можно использовать на стороне клиента для создания класса заказов конкретного клиента, который использует ту же схему, что и серверный класс.This schema can then be used on the client side to generate a client-specific order class that shares the same schema as the server class.

В следующем примере кода представлен серверный компонент, который получает заказы через очередь сообщений.The following code example represents a server component that receives orders through a message queue. Тело сообщения должно быть объектом Order, схема которого соответствует классу Order.cs ниже.The body of the message should be an order object whose schema matches the Order.cs class below. Серверный процесс или приложение десериализует порядок.The server process or application deserializes the order.

#using <System.dll>
#using <System.Messaging.dll>

using namespace System;
using namespace System::Messaging;

// placeholder; see complete definition elsewhere in this section
public ref class Order
{
public:
   void ShipItems(){}

};


// Creates the queue if it does not already exist.
void EnsureQueueExists( String^ path )
{
   if (  !MessageQueue::Exists( path ) )
   {
      MessageQueue::Create( path );
   }
}

int main()
{
   Console::WriteLine( "Processing Orders" );
   String^ queuePath = ".\\orders";
   EnsureQueueExists( queuePath );
   MessageQueue^ queue = gcnew MessageQueue( queuePath );
   array<String^>^temp0 = {"Order"};
   (dynamic_cast<XmlMessageFormatter^>(queue->Formatter))->TargetTypeNames = temp0;
   while ( true )
   {
      Order^ newOrder = dynamic_cast<Order^>(queue->Receive()->Body);
      newOrder->ShipItems();
   }
}

using System;
using System.Messaging;
 
 public class Server{
 
     public static void Main(){
 
         Console.WriteLine("Processing Orders");
 
         string queuePath = ".\\orders";
         EnsureQueueExists(queuePath);
         MessageQueue queue = new MessageQueue(queuePath);
         ((XmlMessageFormatter)queue.Formatter).TargetTypeNames = new string[]{"Order"};
 
         while(true){
             Order newOrder = (Order)queue.Receive().Body;
             newOrder.ShipItems();
         }
     }
 
     // Creates the queue if it does not already exist.
     public static void EnsureQueueExists(string path){
         if(!MessageQueue.Exists(path)){
             MessageQueue.Create(path);
         }
     }
 }
Imports System.Messaging



Public Class Server
    
    
    Public Shared Sub Main()
        
        Console.WriteLine("Processing Orders")
        
        Dim queuePath As String = ".\orders"
        EnsureQueueExists(queuePath)
        Dim queue As New MessageQueue(queuePath)
        CType(queue.Formatter, XmlMessageFormatter).TargetTypeNames = New String() {"Order"}
        
        While True
            Dim newOrder As Order = CType(queue.Receive().Body, Order)
            newOrder.ShipItems()
        End While
    End Sub
    
    
    ' Creates the queue if it does not already exist.
    Public Shared Sub EnsureQueueExists(path As String)
        If Not MessageQueue.Exists(path) Then
            MessageQueue.Create(path)
        End If
    End Sub
End Class

В следующем примере кода представлен класс Order, предоставляющий схему для объектов Order, которые получает и десериализует приложение на сервере.The following code example represents the order class that provides a schema for the order objects that the application on the server receives and deserializes.

using namespace System;
public ref class Order
{
public:
   int itemId;
   int quantity;
   String^ address;
   void ShipItems()
   {
      Console::WriteLine( "Order Placed:" );
      Console::WriteLine( "\tItem ID  : {0}", itemId );
      Console::WriteLine( "\tQuantity : {0}", quantity );
      Console::WriteLine( "\tShip To  : {0}", address );
      
      // Add order to the database.
      /* Insert code here. */
   }

};

using System;
 
 public class Order{
 
     public int itemId;
     public int quantity;
     public string address;
 
     public void ShipItems(){
 
         Console.WriteLine("Order Placed:");
         Console.WriteLine("\tItem ID  : {0}",itemId);
         Console.WriteLine("\tQuantity : {0}",quantity);
         Console.WriteLine("\tShip To  : {0}",address);
 
         // Add order to the database.
         /* Insert code here. */
 
     }
 }
Public Class Order
    
    Public itemId As Integer
    Public quantity As Integer
    Public address As String
    
    
    Public Sub ShipItems()
        
        Console.WriteLine("Order Placed:")
        Console.WriteLine(ControlChars.Tab & "Item ID  : {0}", itemId)
        Console.WriteLine(ControlChars.Tab & "Quantity : {0}", quantity)
        Console.WriteLine(ControlChars.Tab & "Ship To  : {0}", address)

        ' Add order to the database.
        ' Insert code here.
 
    End Sub
End Class

Любое клиентское приложение, взаимодействующее с приложением на сервере, должно отсылать сообщения на сервер путем сериализации сведений в локально определенный класс Order в текст сообщения.Any client application that interacts with the application on the server must send messages to the server by serializing information in a locally defined order class into the message body. Локально определенный класс Order должен иметь ту же схему, что и определяемый сервером порядок, в котором приложение на сервере будет пытаться десериализовать текст сообщения.The locally defined order class must have the same schema as the server-defined order class into which the application on the server will attempt to deserialize the message body. Программа XSD. exe позволяет диспетчеру приложения на сервере создать и распространить схему, которую клиент должен использовать для сериализации сообщений, отправляемых на сервер.The XSD.exe utility lets the manager of the application on the server create and distribute the schema the client must use to serialize messages going to the server.

Когда диспетчер клиентского приложения получает схему для класса Order, служебная программа XSD. exe снова используется для создания класса упорядочения, зависящего от клиента, из схемы.When the manager of the client application receives the schema for the order class, the XSD.exe utility is used again to generate a client-specific order class from the schema. Этот класс используется в примере кода клиента, а не в классе порядка сервера (программа XSD. exe заставляет создаваемый схемой класс иметь то же имя, что и исходный класс).It is this class that is used in the client code example below, not the server's order class (the XSD.exe utility causes the schema-generated class to have the same name as the original class). Этот новый класс Order используется для сериализации заказа в текст сообщения.This new order class is used to serialize the order into the message body.

В следующем примере кода показана обработка на стороне клиента, используемая для сериализации заказа и отправки сведений, связанных с заказом, в очередь.The following code example is the client-side processing, used to serialize an order and send the information associated with the order to a queue. Код связывает элементы, количество и сведения об адресе с элементами схемы, созданными для класса Order.cs служебной программой XSD. exe.The code associates Item, Quantity, and Address information with elements of the schema that were generated for the Order.cs class by the XSD.exe utility. Заказ отправляется в очередь заказов на локальном компьютере.An order is sent to the Orders queue on the local computer.

#using <System.dll>
#using <System.Messaging.dll>

using namespace System;
using namespace System::Messaging;

// placeholder; see complete definition elsewhere in this section
public ref class Order
{
public:
   int itemId;
   int quantity;
   String^ address;
   void ShipItems(){}

};


// Creates the queue if it does not already exist.
void EnsureQueueExists( String^ path )
{
   if (  !MessageQueue::Exists( path ) )
   {
      MessageQueue::Create( path );
   }
}

int main()
{
   String^ queuePath = ".\\orders";
   EnsureQueueExists( queuePath );
   MessageQueue^ queue = gcnew MessageQueue( queuePath );
   Order^ orderRequest = gcnew Order;
   orderRequest->itemId = 1025;
   orderRequest->quantity = 5;
   orderRequest->address = "One Microsoft Way";
   queue->Send( orderRequest );
   
   // This line uses a new method you define on the Order class:
   // orderRequest.PrintReceipt();
}

using System;
using System.Messaging;
 
 class Client{
 
     public static void Main(){
 
         string queuePath = ".\\orders";
         EnsureQueueExists(queuePath);
         MessageQueue queue = new MessageQueue(queuePath);
 
         Order orderRequest = new Order();
         orderRequest.itemId = 1025;
         orderRequest.quantity = 5;
         orderRequest.address = "One Microsoft Way";
 
         queue.Send(orderRequest);
         // This line uses a new method you define on the Order class:
         // orderRequest.PrintReceipt();
     }
 
     // Creates the queue if it does not already exist.
     public static void EnsureQueueExists(string path){
         if(!MessageQueue.Exists(path)){
             MessageQueue.Create(path);
         }
     }
 
 }
Imports System.Messaging

Class Client
    
    
    Public Shared Sub Main()
        
        Dim queuePath As String = ".\orders"
        EnsureQueueExists(queuePath)
        Dim queue As New MessageQueue(queuePath)
        
        Dim orderRequest As New Order()
        orderRequest.itemId = 1025
        orderRequest.quantity = 5
        orderRequest.address = "One Microsoft Way"
        
        queue.Send(orderRequest)
        ' This line uses a new method you define on the Order class:
        ' orderRequest.PrintReceipt()

    End Sub
    
    ' Creates the queue if it does not already exist.
    Public Shared Sub EnsureQueueExists(path As String)
        If Not MessageQueue.Exists(path) Then
            MessageQueue.Create(path)
        End If
    End Sub
End Class

После создания схемы из класса Order на сервере можно изменить класс.After the schema is generated from the order class on the server, you can modify the class. Если схема не изменяется, повторное распространение схемы не требуется.Unless the schema changes, you do not need to redistribute the schema. После распространения схемы и создания класса заказа на стороне клиента этот клиентский класс также может быть изменен независимо от класса порядка сервера, если сама схема не изменена.After you have distributed the schema and generated a client-side order class, that client class can also be modified independently of the server's order class, as long as the schema itself is not modified. Эти два класса стали слабо связанными.The two classes have become loosely coupled.

Комментарии

— Это модуль форматирования по умолчанию, который MessageQueue используется экземпляром для сериализации сообщений, записанных в очередь. XmlMessageFormatterThe XmlMessageFormatter is the default formatter that an instance of MessageQueue uses to serialize messages written to the queue. При создании экземпляра MessageQueue XmlMessageFormatter экземпляр создается для MessageQueueвас и связывается с.When you create an instance of MessageQueue, an instance of XmlMessageFormatter is created for you and associated with the MessageQueue. Можно указать другой модуль форматирования, создав его в коде и назначив его Formatter свойству. MessageQueueYou can specify a different formatter by creating it in your code and assigning it to the Formatter property of your MessageQueue.

Экземпляр очереди по умолчанию XmlMessageFormatter может быть использован для записи в очередь, но не может использоваться для чтения из очереди, пока не задано TargetTypes свойство или TargetTypeNames модуля форматирования.A queue's default XmlMessageFormatter instance can be used to write to the queue, but it cannot be used to read from the queue until you set either the TargetTypes or TargetTypeNames property on the formatter. Можно задать одно или оба этих значения в экземпляре модуля форматирования по умолчанию или создать новый экземпляр модуля форматирования и задать значения автоматически, передав их в качестве аргументов в соответствующий XmlMessageFormatter конструктор.You can either set one or both of these values on the default formatter instance, or you can create a new instance of the formatter and set the values automatically by passing them as arguments into the appropriate XmlMessageFormatter constructor.

При указании TargetTypes TargetTypeNames, а не, тип существование проверяется во время компиляции, а не на время чтения, уменьшая вероятность ошибки.When specifying TargetTypes rather than TargetTypeNames, type existence is checked at compile time rather than read time, reducing possibility for error. TargetTypeNamesтребует, чтобы каждая запись была полностью квалифицирована, указывая ее имя сборки.TargetTypeNames requires every entry to be fully qualified, specifying its assembly name. Кроме того, при работе с несколькими параллельными версиями номер версии также должен быть добавлен к имени целевого типа.Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well.

Свойства TargetTypeNames иTargetTypes указывают модулю форматирования, какие схемы следует пытаться сопоставить при десериализации сообщения.The TargetTypeNames and TargetTypes properties tell the formatter what schemas to attempt to match when deserializing a message. Это позволяет модулю форматирования интерпретировать текст сообщения.This allows the formatter to interpret the message body.

Экземпляр, сериализованный в тексте сообщения, должен соответствовать одной из схем, представленных в массиве типов.The instance serialized in the message body must comply with one of the schemas represented in the type array. При чтении сообщения с помощью Receive метода метод создает объект типа, соответствующий указанной схеме, и считывает в него текст сообщения.When you read the message using the Receive method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it.

При чтении из очереди необходимо задать только одно из двух свойств, но можно задать и то, и другое.Only one of the two properties needs to be set when reading from the queue, but you can set both. Набор типов — это объединенный набор из двух свойств.The set of types is the combined set from the two properties. Решение о том, какое свойство следует использовать, зависит от вашего приложения.The decision of which property to use is specific to your application. Если текст сообщения содержит тип, схема которого не совпадает ни с одним из типов в массиве для любого из свойств, при считывании сообщения будет создано исключение.If the message body contains a type whose schema does not match any of the types in the array for either property, an exception will be thrown when the message is read.

XmlMessageFormatter Является важнейшим компонентом слабо связанного обмена сообщениями на основе XML.The XmlMessageFormatter is a crucial component of loosely coupled XML-based messaging. Программа XSD. exe использует формат XML для создания схемы XML, например, при использовании программы для сериализации класса, используемого приложением.The XSD.exe utility uses the XML format is used to generate XML schema, such as when you use the utility to serialize a class used by your application. Класс должен содержать конструктор без параметров.The class must have a parameterless constructor.

Этот формат снова используется в обратном процессе, когда программа создает класс на основе схемы, которую вы распространяете для описания данных класса.The format is used again in the reverse process when the utility generates a class based on the schema you distribute to describe your class data. Использование программы и создаваемой ею схемы XML позволяет избежать повторного распространения DLL-файлов при каждой перекомпиляции класса после изменения реализации класса.The use of the utility and the XML schema it generates enables you to avoid redistributing.dll files every time you recompile a class after the implementation of your class has changed. Пока схема не изменяется на клиенте или сервере, другие изменения на обеих сторонах не влияют на другую.As long as the schema does not change on the client or the server, other changes on either side do not affect the other.

Конструкторы

XmlMessageFormatter()

Инициализирует новый экземпляр класса XmlMessageFormatter без набора типов целевых объектов.Initializes a new instance of the XmlMessageFormatter class, without target types set.

XmlMessageFormatter(String[])

Инициализирует новый экземпляр класса XmlMessageFormatter, устанавливая типы целевых объектов, передаваемых как массив (полностью определенных) строковых значений.Initializes a new instance of the XmlMessageFormatter class, setting target types passed in as an array of (fully qualified) string values.

XmlMessageFormatter(Type[])

Инициализирует новый экземпляр класса XmlMessageFormatter, устанавливая типы целевых объектов, передаваемых как массив типов объектов.Initializes a new instance of the XmlMessageFormatter class, setting target types passed in as an array of object types.

Свойства

TargetTypeNames

Задает набор возможных типов, десериализация которых будет выполняться модулем форматирования из тела предоставляемого сообщения.Specifies the set of possible types that will be deserialized by the formatter from the message provided.

TargetTypes

Задает набор возможных типов, десериализация которых будет выполняться модулем форматирования из тела предоставляемого сообщения.Specifies the set of possible types that will be deserialized by the formatter from the message provided.

Методы

CanRead(Message)

Определяет, может ли модуль форматирования десериализовать сообщение.Determines whether the formatter can deserialize the message.

Clone()

Создает экземпляр класса XmlMessageFormatter, свойства чтения и записи (наборы типов целевых объектов) которого такие же, как и у текущего экземпляра XmlMessageFormatter.Creates an instance of the XmlMessageFormatter class whose read/write properties (the sets of target types) are the same as the current XmlMessageFormatter instance.

Equals(Object)

Определяет, равен ли указанный объект текущему объекту.Determines whether the specified object is equal to the current object.

(Унаследовано от Object)
GetHashCode()

Служит в качестве хэш-функции по умолчанию.Serves as the default hash function.

(Унаследовано от Object)
GetType()

Возвращает объект Type для текущего экземпляра.Gets the Type of the current instance.

(Унаследовано от Object)
MemberwiseClone()

Создает неполную копию текущего объекта Object.Creates a shallow copy of the current Object.

(Унаследовано от Object)
Read(Message)

Читает содержимое из данного сообщения и создает объект, содержащий десериализованное сообщение.Reads the contents from the given message and creates an object that contains the deserialized message.

ToString()

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

(Унаследовано от Object)
Write(Message, Object)

Сериализует объект в текст сообщения.Serializes an object into the body of the message.

Применяется к

Дополнительно