Export (0) Print
Expand All

Message Class

Represents the unit of communication between endpoints in a distributed environment.

System.Object
  System.ServiceModel.Channels.Message

Namespace:  System.ServiceModel.Channels
Assembly:  System.ServiceModel (in System.ServiceModel.dll)

public abstract class Message : IDisposable

The Message type exposes the following members.

  NameDescription
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsMessageInitializes a new instance of the Message class.
Top

  NameDescription
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsHeadersWhen overridden in a derived class, gets the headers of the message.
Protected propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsIsDisposedReturns a value that indicates whether the Message is disposed.
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsIsEmptyReturns a value that indicates whether the Message is empty.
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsIsFaultGets a value that indicates whether this message generates any SOAP faults.
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsPropertiesWhen overridden in a derived class, gets a set of processing-level annotations to the message.
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsStateGets the current state of this Message.
Public propertySupported by Portable Class LibrarySupported in .NET for Windows Store appsVersionWhen overridden in a derived class, gets the SOAP version of the message.
Top

  NameDescription
Public methodBeginWriteBodyContentsStarts the asynchronous writing of the contents of the message body.
Public methodBeginWriteMessageStarts the asynchronous writing of the entire message.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsCloseCloses the Message and releases any resources.
Public methodSupported in .NET for Windows Store appsCreateBufferedCopyStores an entire Message into a memory buffer for future access.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessage(MessageVersion, String)Creates a message that contains a version and an action.
Public methodStatic memberCreateMessage(MessageVersion, MessageFault, String)Creates a message that contains a SOAP fault, a version and an action.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessage(MessageVersion, String, Object)Creates a message with the specified version, action and body.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessage(MessageVersion, String, BodyWriter)Creates a message with a body that consists of an array of bytes.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessage(MessageVersion, String, XmlDictionaryReader)Creates a message with the specified version, action and body.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessage(MessageVersion, String, XmlReader)Creates a message using the specified reader, action and version.
Public methodStatic memberSupported in .NET for Windows Store appsCreateMessage(XmlDictionaryReader, Int32, MessageVersion)Creates a message using the specified reader, action and version.
Public methodStatic memberSupported in .NET for Windows Store appsCreateMessage(XmlReader, Int32, MessageVersion)Creates a message using the specified reader, action and version.
Public methodStatic memberCreateMessage(MessageVersion, FaultCode, String, String)Creates a message that contains a SOAP fault, the reason for the fault, a version and an action.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsCreateMessage(MessageVersion, String, Object, XmlObjectSerializer)Creates a message using the specified version, action, message body and serializer.
Public methodStatic memberCreateMessage(MessageVersion, FaultCode, String, Object, String)Creates a message that contains a SOAP fault, a reason and the detail for the fault, a version and an action.
Public methodEndWriteBodyContentsEnds the asynchronous writing of the contents of the message body.
Public methodEndWriteMessageEnds the asynchronous writing of the entire message.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetBody<T>()Retrieves the body of this Message instance.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetBody<T>(XmlObjectSerializer)Retrieves the body of this Message using the specified serializer.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetBodyAttributeRetrieves the attributes of the message body.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetReaderAtBodyContentsGets the XML dictionary reader that accesses the body content of this message.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnBeginWriteBodyContentsRaises an event when the message starts writing the contents of the message body.
Protected methodOnBeginWriteMessageRaises an event the writing of entire messages starts.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnBodyToStringCalled when the message body is converted to a string.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnCloseCalled when the message is closing.
Protected methodSupported in .NET for Windows Store appsOnCreateBufferedCopyCalled when a message buffer is created to store this message.
Protected methodOnEndWriteBodyContentsRaises an event when writing of the contents of the message body ends.
Protected methodOnEndWriteMessageRaises an event when the writing of the entire message ends.
Protected methodSupported in .NET for Windows Store appsOnGetBody<T>Called when the body of the message is retrieved.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnGetBodyAttributeCalled when the attributes of the message body is retrieved.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnGetReaderAtBodyContentsCalled when an XML dictionary reader that accesses the body content of this message is retrieved.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnWriteBodyContentsCalled when the message body is written to an XML file.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnWriteMessageCalled when the entire message is written to an XML file.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnWriteStartBodyCalled when the start body is written to an XML file.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnWriteStartEnvelopeCalled when the start envelope is written to an XML file.
Protected methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsOnWriteStartHeadersCalled when the start header is written to an XML file.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsToStringReturns a string that represents the current Message instance. (Overrides Object.ToString().)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteBody(XmlDictionaryWriter)Writes the body element using the specified XmlDictionaryWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteBody(XmlWriter)Serializes the message body using the specified XmlWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteBodyContentsSerializes the body content using the specified XmlDictionaryWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteMessage(XmlDictionaryWriter)Serializes the entire message using the specified XmlDictionaryWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteMessage(XmlWriter)Serializes the entire message using the specified XmlWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartBody(XmlDictionaryWriter)Serializes the start body of the message using the specified XmlDictionaryWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartBody(XmlWriter)Serializes the start body of the message using the specified XmlDictionaryWriter.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWriteStartEnvelopeSerializes the start envelope using the specified XmlDictionaryWriter.
Top

  NameDescription
Public Extension MethodToHttpRequestMessage Creates a HttpRequestMessage instance from an Message instance. (Defined by MessageExtensionMethods.)
Public Extension MethodToHttpResponseMessage Creates a HttpResponseMessage instance from an Message instance. (Defined by MessageExtensionMethods.)
Top

  NameDescription
Explicit interface implemetationPrivate methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsIDisposable.DisposeCloses all the resources used by this message. This method cannot be inherited.
Top

The Message class provides a means of communicating arbitrary information between a sender and a receiver on a network. It can be used to relay information, suggest or demand a course of action, or request data.

The structure of a Message object represents a SOAP envelope. It consists of two distinct parts: the message's body and an optional collection of headers, represented by the Headers class. The message content is application-defined data sent from a sender to a receiver. The message headers enable system and application extensibility to meet the changing requirements, because you can define code to manipulate and respond to specific headers. You can also define your own headers. Message headers are serialized or deserialized along with the contents of the message.

Messages are received and sent in particular formats. Support is provided for two formats: the standard text-based XML format and a binary-based XML format. The Message object can be used to represent both SOAP 1.1 and SOAP 1.2 envelopes. Note that an instance of Message is fixed upon creation and is bound to a specific SOAP version. The Version property represents the SOAP version of the message.

A Message object can be serialized to an external store by using the WriteMessage method. Properties of the message can also be serialized, but they have to be individually identified and serialized separately. Deserializing a message to create an in-memory Message object can be done using CreateMessage. Properties must also be deserialized individually and manually added to the property collection for the specific Message instance.

The size of a Message object is fixed to the size of data it is transmitting. Every body is modeled as an instance of XmlReader, with no predefined limit on the size of the stream that the XmlReader instance is wrapping. However, specific channel providers can have a limit on the size of messages that they process.

A Message can be annotated with useful information generated by an entity that has examined and processed the message. This functionality is provided by the Headers and Properties properties. The Headers collection represents the set of SOAP headers on the message.

The Properties property represents the set of processing-level annotations on the message. Because information in headers is transmitted on the wire, an entity that examines a header must support the underlying version(s) of the protocols used by the header. However, properties provide a more version-independent way of annotating a message.

To create a Message instance, use one of the CreateMessage methods.

It is recommended that a consumer of a message always call Close when the consumer is finished accessing the contents of the message. This action frees finite system resources (for example, sockets, named pipes) that are tied to the lifetime of the message.

Special note for Managed C++ users deriving from this class:

  • Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor.

  • Avoid destructors: they cause the compiler to auto-generate IDisposable.

  • Avoid non-reference members: they can cause the compiler to auto-generate IDisposable.

  • Avoid finalizers; but if you include one, suppress the build warning and call SuppressFinalize(Object) and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated IDisposable behavior.

Notes to Inheritors

When you inherit from Message, you must override the following members: Headers, and Version.

The following code example shows a client that uses the channel factory to send a message and read the reply.


using System;
using System.Messaging;

public class Order
{
    private int _orderId;
    private DateTime _orderTime;

    public int orderId
    {
        get
        {
            return _orderId;
        }
        set
        {
            _orderId = value;
        }
    }
    public DateTime orderTime
    {
        get
        {
            return _orderTime;
        }
        set
        {
            _orderTime = value;
        }
    }

    public Order()
    {
    }
};	

public class OrderProcessor
{
    public static void Main()
    {
        // Create a new instance of the class.
        OrderProcessor processor = new OrderProcessor();

        try
        {
            // Create a non-transactional queue on the local computer. 
            // Note that the queue might not be immediately accessible, and 
            // therefore this example might throw an exception of type 
            // System.Messaging.MessageQueueException when trying to send a 
            // message to the newly created queue.
            CreateQueue(".\\orderQueue", false);

            // Send a message to a queue.
            processor.SendMessage();

            // Receive a message from a queue.
            processor.ReceiveMessage();

            // Create a transactional queue on the local computer.
            CreateQueue(".\\orderTransQueue", true);

            // Send a message to a transactional queue.
            processor.SendMessageToTransQueue();

            // Receive a message from a transactional queue.
            processor.ReceiveMessageFromTransQueue();
        }
        catch(System.Exception e)
        {
            // Write the exception information to the console.
            Console.WriteLine(e);
        }
    }

    // Creates a new queue. 
    public static void CreateQueue(string queuePath, bool transactional)
    {
        if(!MessageQueue.Exists(queuePath))
        {
            MessageQueue.Create(queuePath, transactional);
        }
        else
        {
            Console.WriteLine(queuePath + " already exists.");
        }
    }

    // Sends an Order to a queue. 
    public void SendMessage()
    {
        // Create a new order and set values.
        Order sentOrder = new Order();
        sentOrder.orderId = 3;
        sentOrder.orderTime = DateTime.Now;

        // Connect to a queue on the local computer.
        MessageQueue queue = new MessageQueue(".\\orderQueue");

        // Create the new order.
        Message orderMessage = new Message(sentOrder);

        // Set the message's TimeToReachQueue property to five minutes.
        orderMessage.TimeToReachQueue = TimeSpan.FromMinutes(5.0);

        // Display the new value of the message's TimeToReachQueue property.
        Console.WriteLine("Message.TimeToReachQueue: {0}",
            orderMessage.TimeToReachQueue.ToString());

        // Set the message's TimeToBeReceived property to five minutes.
        orderMessage.TimeToBeReceived = TimeSpan.FromMinutes(5.0);

        // Display the new value of the message's TimeToBeReceived property.
        Console.WriteLine("Message.TimeToBeReceived: {0}",
            orderMessage.TimeToBeReceived.ToString());

        // Set the message's UseTracing property to true.
        orderMessage.UseTracing = true;

        // Display the new value of the message's UseTracing property.
        Console.WriteLine("Message.UseTracing: {0}", orderMessage.UseTracing);

        // Set the message's Label property.
        orderMessage.Label = "Order Message";

        // Display the new value of the message's Label property.
        Console.WriteLine("Message Label: {0}", orderMessage.Label);

        // Set the message's AttachSenderId property.
        orderMessage.AttachSenderId = true;

        // Display the new value of the message's AttachSenderId property.
        Console.WriteLine("Message.AttachSenderId: {0}",
            orderMessage.AttachSenderId);

        // Set the message's Recoverable property.
        orderMessage.Recoverable = true;

        // Display the new value of the message's Recoverable property.
        Console.WriteLine("Message.Recoverable: {0}",
            orderMessage.Recoverable);

        // Set the message's ResponseQueue property. 
        // (You must have a connection to a queue.)
        orderMessage.ResponseQueue = queue;

        // Display the new value of the message's ResponseQueue property.
        Console.WriteLine("Message.ResponseQueue.QueueName: {0}",
            orderMessage.ResponseQueue.QueueName);

        // Set the message's TimeToReachQueue property to Message.InfiniteTimeout.
        orderMessage.TimeToReachQueue = Message.InfiniteTimeout;

        // Display the new value of the message's TimeToReachQueue property.
        Console.WriteLine("Message.TimeToReachQueue: {0}",
            orderMessage.TimeToReachQueue.ToString());

        // Set the message's UseDeadLetterQueue property.
        orderMessage.UseDeadLetterQueue = true;

        // Display the new value of the message's UseDeadLetterQueue property.
        Console.WriteLine("Message.UseDeadLetterQueue: {0}",
            orderMessage.UseDeadLetterQueue);

        // Set the message's UseJournalQueue property.
        orderMessage.UseJournalQueue = true;

        // Display the new value of the message's UseJournalQueue property.
        Console.WriteLine("Message.UseJournalQueue: {0}",
            orderMessage.UseJournalQueue);

        // Set the message's UseEncryption property.
        orderMessage.UseEncryption = true;

        // Display the new value of the message's UseEncryption property.
        Console.WriteLine("Message.UseEncryption: {0}",
            orderMessage.UseEncryption);

        // Send the order to the queue.
        queue.Send(orderMessage);
    }

    // Receives a message containing an order. 
    public void ReceiveMessage()
    {
        // Connect to a queue on the local computer.
        MessageQueue queue = new MessageQueue(".\\orderQueue");

        // Set the formatter to indicate the message body contains an order.
        queue.Formatter = new XmlMessageFormatter(new Type[]
            {typeof(Order)});

        // Set the queue's MessageReadPropertyFilter properties to ensure that 
        // the message includes the properties in which we are interested.
        queue.MessageReadPropertyFilter.ArrivedTime = true;
        queue.MessageReadPropertyFilter.DestinationQueue = true;
        queue.MessageReadPropertyFilter.SenderVersion = true;
        queue.MessageReadPropertyFilter.SentTime = true;
        queue.MessageReadPropertyFilter.SourceMachine = true;
        queue.MessageReadPropertyFilter.Authenticated = true;

        // Receive the message. Time out after ten seconds in case the message 
        // was not delivered.
        Message orderMessage = queue.Receive(TimeSpan.FromSeconds(10.0));

        // Format the message.
        Order sentOrder = (Order)orderMessage.Body;

        // Display message information.
        Console.WriteLine("Order ID: {0}", sentOrder.orderId.ToString());
        Console.WriteLine("Sent: {0}", sentOrder.orderTime.ToString());

        // Display the value of the message's MessageType property.
        Console.WriteLine("Message Type: {0}", orderMessage.MessageType);

        // Display the value of the message's SourceMachine property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.SourceMachine property must be set to 
        // true before the message is received.
        Console.WriteLine("Source Machine: {0}", orderMessage.SourceMachine);

        // Display the value of the message's DestinationQueue property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.DestinationQueue property must be set to 
        // true before the message is received.
        Console.WriteLine("Message.DestinationQueue.QueueName: {0}",
            orderMessage.DestinationQueue.QueueName);

        // Display the value of the message's SentTime property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.SentTime property must be set to 
        // true before the message is received.
        Console.WriteLine("Time sent from source queue: {0}",
            orderMessage.SentTime.ToString());

        // Display the value of the message's ArrivedTime property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.ArrivedTime property must be set to 
        // true before the message is received.
        Console.WriteLine("Time arrived in destination queue: {0}",
            orderMessage.ArrivedTime.ToString());

        // Display the value of the message's Authenticated property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.Authenticated property must be set to 
        // true before the message is received.
        Console.WriteLine("Authentication requested for this message: {0}",
            orderMessage.Authenticated.ToString());

        // Display the value of the message's SenderVersion property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.SenderVersion property must be set to 
        // true before the message is received.
        Console.WriteLine("Message.SenderVersion: {0}",
            orderMessage.SenderVersion);

        // Message Queuing sets this property when the message is sent. 
        // Display the value of the message's BodyType property.
        Console.WriteLine("Message.BodyType: {0}",
            orderMessage.BodyType.ToString());
    }

    // Sends an Order to a transactional queue. 
    public void SendMessageToTransQueue()
    {
        // Create a new order and set values.
        Order sentOrder = new Order();
        sentOrder.orderId = 3;
        sentOrder.orderTime = DateTime.Now;

        // Connect to a queue on the local computer.
        MessageQueue queue = new MessageQueue(".\\orderTransQueue");

        // Create the new order.
        Message orderMessage = new Message(sentOrder);

        // Create a message queuing transaction.
        MessageQueueTransaction transaction = new MessageQueueTransaction();

        try
        {
            // Begin a transaction.
            transaction.Begin();

            // Send the order to the queue.
            queue.Send(orderMessage, transaction);

            // Commit the transaction.
            transaction.Commit();
        }
        catch (MessageQueueException e)
        {
            // Abort the transaction.
            transaction.Abort();

            // Propagate the exception. 
            throw e;
        }
        finally
        {
            // Dispose of the transaction object.
            transaction.Dispose();
        }
    }

    // Receives a message containing an order. 
    public void ReceiveMessageFromTransQueue()
    {
        Message orderMessage;

        // Connect to the a queue on the local computer.
        MessageQueue queue = new MessageQueue(".\\orderTransQueue");

        // Set the formatter to indicate the message body contains an order.
        queue.Formatter = new XmlMessageFormatter(new Type[]
            {typeof(Order)});

        // Set the queue's MessageReadPropertyFilter properties to ensure that 
        // the message includes the properties in which we are interested.
        queue.MessageReadPropertyFilter.TransactionId = true;
        queue.MessageReadPropertyFilter.TransactionStatusQueue = true;
        queue.MessageReadPropertyFilter.IsFirstInTransaction = true;
        queue.MessageReadPropertyFilter.IsLastInTransaction = true;

        // Create a message queuing transaction.
        MessageQueueTransaction transaction = new MessageQueueTransaction();

        try
        {
            // Begin a transaction.
            transaction.Begin();

            // Receive the message. Time out after ten seconds in case the 
            // message was not delivered.
            orderMessage = queue.Receive(TimeSpan.FromSeconds(10.0),
                transaction);

            // Commit the transaction.
            transaction.Commit();
        }
        catch(System.Exception e)
        {
            // Abort the transaction.
            transaction.Abort();

            // Propagate the exception. 
            throw e;
        }
        finally
        {
            // Dispose of the transaction object.
            transaction.Dispose();
        }

        // Message Queuing sets this property when the message is sent. 
        // Display the value of the message's TransactionStatusQueue property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.TransactionStatusQueue property must be 
        // set to true before the message is received.
        Console.WriteLine("Message.TransactionStatusQueue.QueueName: {0}",
            orderMessage.TransactionStatusQueue.QueueName);

        // Display the value of the message's TransactionId property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.TransactionId property must be set to true 
        // before the message is received.
        Console.WriteLine("Message.TransactionId: {0}",
            orderMessage.TransactionId);

        // Display the value of the message's IsFirstInTransaction property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.IsFirstInTransaction property must be set 
        // to true before the message is received.
        Console.WriteLine("Message.IsFirstInTransaction: {0}",
            orderMessage.IsFirstInTransaction);

        // Display the value of the message's IsLastInTransaction property. 
        // To view this property value, the queue's 
        // MessageReadPropertyFilter.IsLastInTransaction property must be set 
        // to true before the message is received.
        Console.WriteLine("Message.IsLastInTransaction: {0}",
            orderMessage.IsLastInTransaction);
    }
}

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft