Message Class

Definition

Namespace:

System.ServiceModel.Channels

Assembly:

System.ServiceModel.Primitives.dll

Package:

System.ServiceModel.Primitives v8.1.0

Source:

Message.cs

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

public ref class Message abstract : IDisposable

public abstract class Message : IDisposable

type Message = class
    interface IDisposable

Public MustInherit Class Message
Implements IDisposable

Inheritance

Object

Message

Implements

IDisposable

Examples

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

using System;
using System.Collections.Generic;
using System.Text;
using System.ServiceModel;
using System.ServiceModel.Channels;
using System.Runtime.Serialization;

namespace ConsoleApplication1
{
    class client
    {

        static void RunClient()
        {
            //Step1: create a binding with just HTTP
            CustomBinding binding = new CustomBinding();
            binding.Elements.Add(new HttpTransportBindingElement());
            //Step2: use the binding to build the channel factory
            IChannelFactory<IRequestChannel> factory =
            binding.BuildChannelFactory<IRequestChannel>(
                             new BindingParameterCollection());
            //open the channel factory
            factory.Open();
            //Step3: use the channel factory to create a channel
            IRequestChannel channel = factory.CreateChannel(
               new EndpointAddress("http://localhost:8080/channelapp"));
            channel.Open();
            //Step4: create a message
            Message requestmessage = Message.CreateMessage(
                MessageVersion.Soap12WSAddressing10,
                "http://contoso.com/someaction",
                 "This is the body data");
            //send message
            Message replymessage = channel.Request(requestmessage);
            Console.WriteLine("Reply message received");
            Console.WriteLine("Reply action: {0}",
                                  replymessage.Headers.Action);
            string data = replymessage.GetBody<string>();
            Console.WriteLine("Reply content: {0}", data);
            //Step5: don't forget to close the message
            requestmessage.Close();
            replymessage.Close();
            //don't forget to close the channel
            channel.Close();
            //don't forget to close the factory
            factory.Close();
        }
        public static void Main()
        {
            Console.WriteLine("Press [ENTER] when service is ready");
            Console.ReadLine();
            RunClient();
            Console.WriteLine("Press [ENTER] to exit");
            Console.ReadLine();
        }
    }
}

Imports System.Collections.Generic
Imports System.Text
Imports System.ServiceModel
Imports System.ServiceModel.Channels
Imports System.Runtime.Serialization

Namespace ConsoleApplication1
    Friend Class client


        Private Shared Sub RunClient()
            'Step1: create a binding with just HTTP
            Dim binding As New CustomBinding()
            binding.Elements.Add(New HttpTransportBindingElement())
            'Step2: use the binding to build the channel factory
            Dim factory As IChannelFactory(Of IRequestChannel) = binding.BuildChannelFactory(Of IRequestChannel)(New BindingParameterCollection())
            'open the channel factory
            factory.Open()
            'Step3: use the channel factory to create a channel
            Dim channel As IRequestChannel = factory.CreateChannel(New EndpointAddress("http://localhost:8080/channelapp"))
            channel.Open()
            'Step4: create a message
            Dim requestmessage As Message = Message.CreateMessage(MessageVersion.Soap12WSAddressing10, "http://contoso.com/someaction", "This is the body data")
            'send message
            Dim replymessage As Message = channel.Request(requestmessage)
            Console.WriteLine("Reply message received")
            Console.WriteLine("Reply action: {0}", replymessage.Headers.Action)
            Dim data = replymessage.GetBody(Of String)()
            Console.WriteLine("Reply content: {0}", data)
            'Step5: don't forget to close the message
            requestmessage.Close()
            replymessage.Close()
            'don't forget to close the channel
            channel.Close()
            'don't forget to close the factory
            factory.Close()
        End Sub
        Public Shared Sub Main()
            Console.WriteLine("Press [ENTER] when service is ready")
            Console.ReadLine()
            RunClient()
            Console.WriteLine("Press [ENTER] to exit")
            Console.ReadLine()
        End Sub
    End Class
End Namespace

Remarks

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 Implementers

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

Constructors

Message()

Initializes a new instance of the Message class.

Properties

Headers	When overridden in a derived class, gets the headers of the message.
IsDisposed	Returns a value that indicates whether the Message is disposed.
IsEmpty	Returns a value that indicates whether the Message is empty.
IsFault	Gets a value that indicates whether this message generates any SOAP faults.
Properties	When overridden in a derived class, gets a set of processing-level annotations to the message.
State	Gets the current state of this Message.
Version	When overridden in a derived class, gets the SOAP version of the message.

Methods

Close()	Closes the Message and releases any resources.
CreateBufferedCopy(Int32)	Stores an entire Message into a memory buffer for future access.
CreateMessage(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.
CreateMessage(MessageVersion, FaultCode, String, String)	Creates a message that contains a SOAP fault, the reason for the fault, a version and an action.
CreateMessage(MessageVersion, String, BodyWriter)	Creates a message with a body that consists of an array of bytes.
CreateMessage(MessageVersion, String, Object, XmlObjectSerializer)	Creates a message using the specified version, action, message body and serializer.
CreateMessage(MessageVersion, String, Object)	Creates a message with the specified version, action and body.
CreateMessage(MessageVersion, String, XmlDictionaryReader)	Creates a message with the specified version, action and body.
CreateMessage(MessageVersion, String, XmlReader)	Creates a message using the specified reader, action and version.
CreateMessage(MessageVersion, String)	Creates a message that contains a version and an action.
CreateMessage(XmlDictionaryReader, Int32, MessageVersion)	Creates a message using the specified reader, action and version.
CreateMessage(XmlReader, Int32, MessageVersion)	Creates a message using the specified reader, action and version.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetBody<T>()	Retrieves the body of this Message instance.
GetBody<T>(XmlObjectSerializer)	Retrieves the body of this Message using the specified serializer.
GetBodyAttribute(String, String)	Retrieves the attributes of the message body.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetReaderAtBodyContents()	Gets the XML dictionary reader that accesses the body content of this message.
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
OnBodyToString(XmlDictionaryWriter)	Called when the message body is converted to a string.
OnClose()	Called when the message is closing.
OnCreateBufferedCopy(Int32)	Called when a message buffer is created to store this message.
OnGetBody<T>(XmlDictionaryReader)	Called when the body of the message is retrieved.
OnGetBodyAttribute(String, String)	Called when the attributes of the message body is retrieved.
OnGetReaderAtBodyContents()	Called when an XML dictionary reader that accesses the body content of this message is retrieved.
OnWriteBodyContents(XmlDictionaryWriter)	Called when the message body is written to an XML file.
OnWriteMessage(XmlDictionaryWriter)	Called when the entire message is written to an XML file.
OnWriteStartBody(XmlDictionaryWriter)	Called when the start body is written to an XML file.
OnWriteStartEnvelope(XmlDictionaryWriter)	Called when the start envelope is written to an XML file.
OnWriteStartHeaders(XmlDictionaryWriter)	Called when the start header is written to an XML file.
ToString()	Returns a string that represents the current Message instance.
WriteBody(XmlDictionaryWriter)	Writes the body element using the specified XmlDictionaryWriter.
WriteBody(XmlWriter)	Serializes the message body using the specified XmlWriter.
WriteBodyContents(XmlDictionaryWriter)	Serializes the body content using the specified XmlDictionaryWriter.
WriteMessage(XmlDictionaryWriter)	Serializes the entire message using the specified XmlDictionaryWriter.
WriteMessage(XmlWriter)	Serializes the entire message using the specified XmlWriter.
WriteStartBody(XmlDictionaryWriter)	Serializes the start body of the message using the specified XmlDictionaryWriter.
WriteStartBody(XmlWriter)	Serializes the start body of the message using the specified XmlDictionaryWriter.
WriteStartEnvelope(XmlDictionaryWriter)	Serializes the start envelope using the specified XmlDictionaryWriter.

Explicit Interface Implementations

IDisposable.Dispose()

Closes all the resources used by this message. This method cannot be inherited.

Extension Methods