XmlMessageFormatter Klasse

Definition

Serialisiert und deserialisiert mithilfe des auf XSD (XML Schema Definition) beruhenden XML-Formats Objekte in den oder aus dem Textkörper einer Meldung.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
Vererbung
XmlMessageFormatter
Implementiert

Beispiele

Das folgende Codebeispiel enthält drei Code Elemente: eine Serverkomponente, eine Order-Klasse und Client Code.The following code example includes three pieces of code: a server component, an order class, and client code. Die Order-Klasse kann vom Hilfsprogramm "XSD. exe" verwendet werden, um ein Schema zu generieren, das der Server innerhalb eingehender Nachrichten erkennt.The order class can be used by the XSD.exe utility to generate schema that the server recognizes within incoming messages. Das Schema ist eine XML-formatierte Datei, die die Form der-Klasse beschreibt.The schema is an XML formatted file that describes the "shape" of the class. Dieses Schema kann dann auf der Clientseite verwendet werden, um eine Client spezifische Order-Klasse zu generieren, die das gleiche Schema wie die Serverklasse verwendet.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.

Das folgende Codebeispiel stellt eine Serverkomponente dar, die Aufträge über eine Nachrichten Warteschlange empfängt.The following code example represents a server component that receives orders through a message queue. Der Nachrichtentext muss ein Order-Objekt sein, dessen Schema mit der Order.cs-Klasse unten übereinstimmt.The body of the message should be an order object whose schema matches the Order.cs class below. Der Server Prozess oder die Anwendung deserialisiert die Reihenfolge.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

Das folgende Codebeispiel stellt die Order-Klasse dar, die ein Schema für die Order-Objekte bereitstellt, die von der Anwendung auf dem Server empfangen und deserialisiert werden.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

Jede Client Anwendung, die mit der Anwendung auf dem Server interagiert, muss Nachrichten an den Server senden, indem Informationen in einer lokal definierten Order-Klasse in den Nachrichtentext serialisiert werden.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. Die lokal definierte Order-Klasse muss das gleiche Schema wie die Server definierte Order-Klasse aufweisen, in der die Anwendung auf dem Server versucht, den Nachrichtentext zu deserialisieren.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. Mit dem Hilfsprogramm "XSD. exe" kann der Manager der Anwendung auf dem Server das Schema erstellen und verteilen, das der Client zum Serialisieren von Nachrichten an den Server verwenden muss.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.

Wenn der Manager der Client Anwendung das Schema für die Order-Klasse empfängt, wird das Dienstprogramm "XSD. exe" erneut verwendet, um eine Client spezifische Order-Klasse aus dem Schema zu generieren.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. Diese Klasse wird im folgenden Client Codebeispiel verwendet, nicht die Order-Klasse des Servers (das Hilfsprogramm "XSD. exe" bewirkt, dass die Schema generierte Klasse denselben Namen wie die ursprüngliche Klasse hat).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). Diese neue Order-Klasse wird verwendet, um die Reihenfolge in den Nachrichtentext zu serialisieren.This new order class is used to serialize the order into the message body.

Das folgende Codebeispiel ist die Client seitige Verarbeitung, die zum Serialisieren einer Bestellung und zum Senden der der Bestellung zugeordneten Informationen an eine Warteschlange verwendet wird.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. Der Code ordnet Element-, Mengen-und Adressinformationen Elementen des Schemas zu, die durch das Hilfsprogramm "XSD. exe" für die Order.cs-Klasse generiert wurden.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. Eine Bestellung wird an die Auftrags Warteschlange auf dem lokalen Computer gesendet.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

Nachdem das Schema aus der Order-Klasse auf dem Server generiert wurde, können Sie die-Klasse ändern.After the schema is generated from the order class on the server, you can modify the class. Wenn das Schema nicht geändert wird, müssen Sie das Schema nicht neu verteilen.Unless the schema changes, you do not need to redistribute the schema. Nachdem Sie das Schema verteilt und eine Client seitige Order-Klasse generiert haben, kann diese Client Klasse auch unabhängig von der Order-Klasse des Servers geändert werden, solange das Schema selbst nicht geändert wird.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. Die beiden Klassen sind lose gekoppelt.The two classes have become loosely coupled.

Hinweise

Ist das Standardformatierer, das eine Instanz MessageQueue von zum Serialisieren von Nachrichten verwendet, die in die Warteschlange geschrieben werden. XmlMessageFormatterThe XmlMessageFormatter is the default formatter that an instance of MessageQueue uses to serialize messages written to the queue. Wenn Sie eine Instanz von MessageQueueerstellen, wird eine Instanz von XmlMessageFormatter für Sie erstellt und der MessageQueuezugeordnet.When you create an instance of MessageQueue, an instance of XmlMessageFormatter is created for you and associated with the MessageQueue. Sie können ein anderes Formatierungsprogramm angeben, indem Sie es im Code erstellen und es der Formatter -Eigenschaft MessageQueueder zuweisen.You can specify a different formatter by creating it in your code and assigning it to the Formatter property of your MessageQueue.

Die Standard XmlMessageFormatter Instanz einer Warteschlange kann zum Schreiben in die Warteschlange verwendet werden. Sie kann jedoch erst verwendet werden, wenn Sie die TargetTypes -Eigenschaft oder TargetTypeNames die-Eigenschaft für den Formatierer festgelegt haben.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. Sie können entweder einen oder beide Werte für die Standard-formatiererinstanz festlegen, oder Sie können eine neue Instanz des Formatierers erstellen und die Werte automatisch festlegen, indem Sie Sie als Argumente an den XmlMessageFormatter entsprechenden Konstruktor übergeben.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.

Wenn Sie TargetTypes TargetTypeNamesanstelle von angeben, wird das vorhanden sein des Typs zur Kompilierzeit anstelle der Lesezeit überprüft, wodurch die Fehlerwahrscheinlichkeit verringert wird.When specifying TargetTypes rather than TargetTypeNames, type existence is checked at compile time rather than read time, reducing possibility for error. TargetTypeNameserfordert, dass jeder Eintrag voll qualifiziert wird, wobei der Assemblyname angegeben wird.TargetTypeNames requires every entry to be fully qualified, specifying its assembly name. Außerdem muss die Versionsnummer beim Arbeiten mit mehreren gleichzeitigen Versionen ebenfalls an den Zieltyp Namen angehängt werden.Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well.

Die TargetTypeNames Eigenschaften TargetTypes und teilen dem Formatierer mit, welche Schemas beim Deserialisieren einer Nachricht zu vergleichen sind.The TargetTypeNames and TargetTypes properties tell the formatter what schemas to attempt to match when deserializing a message. Dadurch kann der Formatierer den Nachrichtentext interpretieren.This allows the formatter to interpret the message body.

Die im Nachrichtentext serialisierte-Instanz muss einem der im typanray dargestellten Schemas entsprechen.The instance serialized in the message body must comply with one of the schemas represented in the type array. Wenn Sie die Nachricht mithilfe der Receive -Methode lesen, erstellt die-Methode ein Objekt vom Typ, das dem identifizierten Schema entspricht, und liest den Nachrichtentext in diese ein.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.

Beim Lesen aus der Warteschlange muss nur eine der beiden Eigenschaften festgelegt werden, aber Sie können beides festlegen.Only one of the two properties needs to be set when reading from the queue, but you can set both. Der Satz von Typen ist die kombinierte Menge aus den beiden Eigenschaften.The set of types is the combined set from the two properties. Die Entscheidung, welche Eigenschaft verwendet werden soll, ist spezifisch für Ihre Anwendung.The decision of which property to use is specific to your application. Wenn der Nachrichtentext einen Typ enthält, dessen Schema keinem der Typen im Array für eine der Eigenschaften entspricht, wird eine Ausnahme ausgelöst, wenn die Nachricht gelesen wird.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 Ist eine wichtige Komponente des lose verknüpften XML-basierten Messaging.The XmlMessageFormatter is a crucial component of loosely coupled XML-based messaging. Das Hilfsprogramm XSD. exe verwendet das XML-Format, das zum Generieren eines XML-Schemas verwendet wird, z. b. Wenn Sie das Hilfsprogramm verwenden, um eine von Ihrer Anwendung verwendete Klasse zu serialisierenThe 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. Die Klasse muss einen parameterlosen Konstruktor haben.The class must have a parameterless constructor.

Das Format wird im umgekehrten Prozess wieder verwendet, wenn das Hilfsprogramm eine Klasse basierend auf dem Schema generiert, das Sie zur Beschreibung der Klassen Daten verteilen.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. Durch die Verwendung des-Hilfsprogramms und des generierten XML-Schemas können Sie das erneute Verteilen von DLL-Dateien vermeiden, wenn Sie eine Klasse neu kompilieren, nachdem sich die Implementierung der Klasse geändert hat.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. Solange das Schema auf dem Client oder dem Server nicht geändert wird, wirken sich andere Änderungen auf beiden Seiten nicht auf das andere aus.As long as the schema does not change on the client or the server, other changes on either side do not affect the other.

Konstruktoren

XmlMessageFormatter()

Initialisiert eine neue Instanz der XmlMessageFormatter-Klasse ohne Angabe einer Gruppe von Zieltypen.Initializes a new instance of the XmlMessageFormatter class, without target types set.

XmlMessageFormatter(String[])

Initialisiert eine neue Instanz der XmlMessageFormatter-Klasse und legt die übergebenen Zieltypen als ein Array von (voll gekennzeichneten) Zeichenfolgenwerten fest.Initializes a new instance of the XmlMessageFormatter class, setting target types passed in as an array of (fully qualified) string values.

XmlMessageFormatter(Type[])

Initialisiert eine neue Instanz der XmlMessageFormatter-Klasse und legt die übergebenen Zieltypen als ein Array von Objekttypen fest.Initializes a new instance of the XmlMessageFormatter class, setting target types passed in as an array of object types.

Eigenschaften

TargetTypeNames

Gibt die Gruppe der möglichen Typen an, die vom Formatierungsprogramm aus der bereitgestellten Meldung deserialisiert werden können.Specifies the set of possible types that will be deserialized by the formatter from the message provided.

TargetTypes

Gibt die Gruppe der möglichen Typen an, die vom Formatierungsprogramm aus der bereitgestellten Meldung deserialisiert werden können.Specifies the set of possible types that will be deserialized by the formatter from the message provided.

Methoden

CanRead(Message)

Ermittelt, ob das Formatierprogramm die Meldung deserialisieren kann.Determines whether the formatter can deserialize the message.

Clone()

Erstellt eine Instanz der XmlMessageFormatter-Klasse, das dieselben Lese-/Schreibeigenschaften (die Gruppe von Zieltypen) besitzt wie die aktuelle XmlMessageFormatter-Instanz.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)

Bestimmt, ob das angegebene Objekt mit dem aktuellen Objekt identisch ist.Determines whether the specified object is equal to the current object.

(Geerbt von Object)
GetHashCode()

Fungiert als Standardhashfunktion.Serves as the default hash function.

(Geerbt von Object)
GetType()

Ruft den Type der aktuellen Instanz ab.Gets the Type of the current instance.

(Geerbt von Object)
MemberwiseClone()

Erstellt eine flache Kopie des aktuellen Object.Creates a shallow copy of the current Object.

(Geerbt von Object)
Read(Message)

Liest den Inhalt aus der angegebenen Meldung und erstellt ein Objekt, das die deserialisierte Meldung enthält.Reads the contents from the given message and creates an object that contains the deserialized message.

ToString()

Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt.Returns a string that represents the current object.

(Geerbt von Object)
Write(Message, Object)

Serialisiert ein Objekt in den Textkörper der Meldung.Serializes an object into the body of the message.

Gilt für:

Siehe auch