Export (0) Print
Expand All
1 out of 3 rated this helpful - Rate this topic

Message Class

Provides access to the properties needed to define a Message Queuing message.

Namespace:  System.Messaging
Assembly:  System.Messaging (in System.Messaging.dll)
public ref class Message : public Component

The Message type exposes the following members.

  NameDescription
Public methodMessage()Initializes a new instance of the Message class with an empty body.
Public methodMessage(Object)Initializes a new instance of the Message class, using the XmlMessageFormatter to serialize the specified object into the body of the message.
Public methodMessage(Object, IMessageFormatter)Initializes a new instance of the Message class using the specified formatter to serialize the specified object into the body of the message.
Top
  NameDescription
Public propertyAcknowledgeTypeGets or sets the type of acknowledgment message to be returned to the sending application.
Public propertyAcknowledgmentGets the classification of acknowledgment that this message represents.
Public propertyAdministrationQueueGets or sets the queue that receives the acknowledgement messages that Message Queuing generates.
Public propertyAppSpecificGets or sets additional, application-specific information.
Public propertyArrivedTimeGets the time that the message arrived in the destination queue.
Public propertyAttachSenderIdGets or sets a value that indicates whether the sender ID should be attached to the message.
Public propertyAuthenticatedGets a value that indicates whether the message was authenticated.
Public propertyAuthenticationProviderNameGets or sets the name of the cryptographic provider used to generate the digital signature of the message.
Public propertyAuthenticationProviderTypeGets or sets the type of cryptographic provider used to generate the digital signature of the message.
Public propertyBodyGets or sets the content of the message.
Public propertyBodyStreamGets or sets the information in the body of the message.
Public propertyBodyTypeGets or sets the type of data that the message body contains.
Protected propertyCanRaiseEventsGets a value indicating whether the component can raise an event. (Inherited from Component.)
Public propertyConnectorTypeGets or sets a value that indicates that some message properties typically set by Message Queuing were set by the sending application.
Public propertyContainerGets the IContainer that contains the Component. (Inherited from Component.)
Public propertyCorrelationIdGets or sets the message identifier used by acknowledgment, report, and response messages to reference the original message.
Protected propertyDesignModeGets a value that indicates whether the Component is currently in design mode. (Inherited from Component.)
Public propertyDestinationQueueGets the intended destination queue for a message.
Public propertyDestinationSymmetricKeyGets or sets the symmetric key used to encrypt application-encrypted messages or messages sent to foreign queues.
Public propertyDigitalSignatureGets or sets the digital signature that Message Queuing uses to authenticate the message.
Public propertyEncryptionAlgorithmGets or sets the encryption algorithm used to encrypt the body of a private message.
Protected propertyEventsGets the list of event handlers that are attached to this Component. (Inherited from Component.)
Public propertyExtensionGets or sets additional, application-defined information associated with the message.
Public propertyFormatterGets or sets the formatter used to serialize an object into or deserialize an object from the message body.
Public propertyHashAlgorithmGets or sets the hashing algorithm that Message Queuing uses when authenticating a message or creating a digital signature for a message.
Public propertyIdGets the message's identifier.
Public propertyIsFirstInTransactionGets a value that indicates whether the message was the first message sent in a transaction.
Public propertyIsLastInTransactionGets a value that indicates whether the message was the last message sent in a transaction.
Public propertyLabelGets or sets an application-defined Unicode string that describes the message.
Public propertyLookupIdIntroduced in MSMQ 3.0. Gets the message's lookup identifier.
Public propertyMessageTypeGets the message type: Normal, Acknowledgment, or Report.
Public propertyPriorityGets or sets the message priority, which determines where in the queue the message is placed.
Public propertyRecoverableGets or sets a value that indicates whether the message is guaranteed to be delivered in the event of a computer failure or network problem.
Public propertyResponseQueueGets or sets the queue that receives application-generated response messages.
Public propertySecurityContextGets or sets the security context for a message.
Public propertySenderCertificateGets or sets the security certificate used to authenticate messages.
Public propertySenderIdGets the identifier of the sending user.
Public propertySenderVersionGets the version of Message Queuing used to send the message.
Public propertySentTimeGets the date and time on the sending computer that the message was sent by the source queue manager.
Public propertySiteGets or sets the ISite of the Component. (Inherited from Component.)
Public propertySourceMachineGets the computer from which the message originated.
Public propertyTimeToBeReceivedGets or sets the maximum amount of time for the message to be received from the destination queue.
Public propertyTimeToReachQueueGets or sets the maximum amount of time for the message to reach the queue.
Public propertyTransactionIdGets the identifier for the transaction of which the message was a part.
Public propertyTransactionStatusQueueGets the transaction status queue on the source computer.
Public propertyUseAuthenticationGets or sets a value that indicates whether the message was (or must be) authenticated before being sent.
Public propertyUseDeadLetterQueueGets or sets a value that indicates whether a copy of the message that could not be delivered should be sent to a dead-letter queue.
Public propertyUseEncryptionGets or sets a value that indicates whether to make the message private.
Public propertyUseJournalQueueGets or sets a value that indicates whether a copy of the message should be kept in a machine journal on the originating computer.
Public propertyUseTracingGets or sets a value that indicates whether to trace a message as it moves toward its destination queue.
Top
  NameDescription
Public methodCreateObjRefCreates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Public methodDispose()Releases all resources used by the Component. (Inherited from Component.)
Protected methodDispose(Boolean)Releases the unmanaged resources used by the Component and optionally releases the managed resources. (Inherited from Component.)
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeReleases unmanaged resources and performs other cleanup operations before the Component is reclaimed by garbage collection. (Inherited from Component.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetLifetimeServiceRetrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodGetServiceReturns an object that represents a service provided by the Component or by its Container. (Inherited from Component.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodInitializeLifetimeServiceObtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodMemberwiseClone()Creates a shallow copy of the current Object. (Inherited from Object.)
Protected methodMemberwiseClone(Boolean)Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Public methodToStringReturns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component.)
Top
  NameDescription
Public eventDisposedOccurs when the component is disposed by a call to the Dispose method. (Inherited from Component.)
Top
  NameDescription
Public fieldStatic memberInfiniteTimeoutSpecifies that no time-out exists.
Top

Use the Message class to peek or receive messages from a queue, or to have fine control over message properties when sending a message to a queue.

MessageQueue uses the Message class when it peeks or receives messages from queues, because both the MessageQueue::Peek and MessageQueue::Receive methods create a new instance of the Message class and set the instance's properties. The Message class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When MessageQueue peeks or receives a message from a queue, its MessageReadPropertyFilter property determines which of the message's properties are retrieved.

The MessageQueue class's Send method allows you to specify any object type for a message being sent to that queue. You can use the MessageQueue instance's DefaultPropertiesToSend property to specify settings for generic messages sent to the queue. The types of settings include formatter, label, encryption, and authentication. You can also specify values for the appropriate DefaultPropertiesToSend members when you coordinate your messaging application to respond to acknowledgment and report messages. Using a Message instance to send a message to the queue gives you the flexibility to access and modify many of these properties—either for a single message or on a message-by-message basis. Message properties take precedence over DefaultPropertiesToSend.

Message data is stored in the Body property and to a lesser extent, the AppSpecific and Extension properties. When message data is encrypted, serialized, or deserialized, only the contents of the Body property are affected.

The contents of the Body property are serialized when the message is sent, using the Formatter property you specify. The serialized contents are found in the BodyStream property. You can also set the BodyStream property directly, for example, to send a file as the data content of a message. You can change the Body or Formatter properties at any time before sending the message, and the data will be serialized appropriately when you call Send.

The properties defined by the MessageQueue::DefaultPropertiesToSend property apply only to messages that are not of type Message. If you specify the DefaultPropertiesToSend property for a MessageQueue, the identically named properties in a Message instance sent to that queue cause these default properties to be ignored.

For a list of initial property values for an instance of Message, see the Message constructor.

The following code example demonstrates formatting a message body using BinaryMessageFormatter.

#using <system.dll>
#using <system.messaging.dll>
#using <system.drawing.dll>

using namespace System;
using namespace System::Messaging;
using namespace System::Drawing;
using namespace System::IO;

/// <summary> 
/// Provides a container class for the example. 
/// </summary> 
ref class MyNewQueue
{
public:

   //************************************************* 
   // Creates a new queue. 
   //************************************************* 
   static void CreateQueue( String^ queuePath )
   {
      try
      {
         if (  !MessageQueue::Exists( queuePath ) )
         {
            MessageQueue::Create( queuePath );
         }
         else
         {
            Console::WriteLine(  "{0} already exists.", queuePath );
         }
      }
      catch ( MessageQueueException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

   }


   //************************************************* 
   // Sends an image to a queue, using the BinaryMessageFormatter. 
   //************************************************* 
   void SendMessage()
   {
      try
      {

         // Create a new bitmap. 
         // The file must be in the \bin\debug or \bin\retail folder, or 
         // you must give a full path to its location.
         Image^ myImage = Bitmap::FromFile( "SentImage::bmp" );

         // Connect to a queue on the local computer.
         MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
         Message^ myMessage = gcnew Message( myImage,gcnew BinaryMessageFormatter );

         // Send the image to the queue.
         myQueue->Send( myMessage );
      }
      catch ( ArgumentException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

      return;
   }


   //************************************************* 
   // Receives a message containing an image. 
   //************************************************* 
   void ReceiveMessage()
   {
      try
      {

         // Connect to the a queue on the local computer.
         MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

         // Set the formatter to indicate body contains an Order.
         myQueue->Formatter = gcnew BinaryMessageFormatter;

         // Receive and format the message. 
         Message^ myMessage = myQueue->Receive();
         Bitmap^ myImage = static_cast<Bitmap^>(myMessage->Body);

         // This will be saved in the \bin\debug or \bin\retail folder.
         myImage->Save( "ReceivedImage::bmp", System::Drawing::Imaging::ImageFormat::Bmp );
      }
      catch ( MessageQueueException^ ) 
      {

         // Handle Message Queuing exceptions.
      }
      // Handle invalid serialization format. 
      catch ( InvalidOperationException^ e ) 
      {
         Console::WriteLine( e->Message );
      }
      catch ( IOException^ e ) 
      {

         // Handle file access exceptions.
      }


      // Catch other exceptions as necessary. 
      return;
   }

};


//************************************************* 
// Provides an entry point into the application. 
//          
// This example sends and receives a message from 
// a queue. 
//************************************************* 
int main()
{

   // Create a new instance of the class.
   MyNewQueue^ myNewQueue = gcnew MyNewQueue;

   // Create a queue on the local computer.
   MyNewQueue::CreateQueue( ".\\myQueue" );

   // Send a message to a queue.
   myNewQueue->SendMessage();

   // Receive a message from a queue.
   myNewQueue->ReceiveMessage();
   return 0;
}

The following code example demonstrates formatting a message body using XmlMessageFormatter.

#using <system.dll>
#using <system.messaging.dll>
#using <system.drawing.dll>

using namespace System;
using namespace System::Messaging;
using namespace System::Drawing;
using namespace System::IO;
ref class Order
{
public:
   int orderId;
   DateTime orderTime;
};

ref class MyNewQueue
{
public:
   static void CreateQueue( String^ queuePath )
   {
      try
      {
         if (  !MessageQueue::Exists( queuePath ) )
         {
            MessageQueue::Create( queuePath );
         }
         else
         {
            Console::WriteLine(  "{0} already exists.", queuePath );
         }
      }
      catch ( MessageQueueException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

   }

   void SendMessage()
   {
      try
      {
         // Create a new order and set values.
         Order^ sentOrder = gcnew Order;
         sentOrder->orderId = 3;
         sentOrder->orderTime = DateTime::Now;

         // Connect to a queue on the local computer.
         MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

         // Create the new order.
         Message^ myMessage = gcnew Message( sentOrder );

         // Send the order to the queue.
         myQueue->Send( myMessage );
      }
      catch ( ArgumentException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

      return;
   }

   void ReceiveMessage()
   {
      // Connect to the a queue on the local computer.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

      // Set the formatter to indicate body contains an Order. 
      array<Type^>^p = gcnew array<Type^>(1);
      p[ 0 ] = Order::typeid;
      myQueue->Formatter = gcnew XmlMessageFormatter( p );
      try
      {
         // Receive and format the message. 
         Message^ myMessage = myQueue->Receive();
         Order^ myOrder = dynamic_cast<Order^>(myMessage->Body);

         // Display message information.
         Console::WriteLine( "Order ID: {0}", myOrder->orderId );
         Console::WriteLine( "Sent: {0}", myOrder->orderTime );
      }
      catch ( MessageQueueException^ ) 
      {
         // Handle Message Queuing exceptions.
      }
      // Handle invalid serialization format. 
      catch ( InvalidOperationException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

      // Catch other exceptions as necessary. 
      return;
   }
};

int main()
{
   // Create a new instance of the class.
   MyNewQueue^ myNewQueue = gcnew MyNewQueue;

   // Create a queue on the local computer.
   MyNewQueue::CreateQueue( ".\\myQueue" );

   // Send a message to a queue.
   myNewQueue->SendMessage();

   // Receive a message from a queue.
   myNewQueue->ReceiveMessage();
   return 0;
}

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

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.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.