MessagePropertyFilter Class

Reference

Definition

Namespace:: System.Messaging

Assembly:: System.Messaging.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Controls and selects the properties that are retrieved when peeking or receiving messages from a message queue.

public ref class MessagePropertyFilter

public ref class MessagePropertyFilter : ICloneable

[System.ComponentModel.TypeConverter(typeof(System.ComponentModel.ExpandableObjectConverter))]
public class MessagePropertyFilter

[System.ComponentModel.TypeConverter(typeof(System.ComponentModel.ExpandableObjectConverter))]
public class MessagePropertyFilter : ICloneable

[<System.ComponentModel.TypeConverter(typeof(System.ComponentModel.ExpandableObjectConverter))>]
type MessagePropertyFilter = class

[<System.ComponentModel.TypeConverter(typeof(System.ComponentModel.ExpandableObjectConverter))>]
type MessagePropertyFilter = class
    interface ICloneable

Public Class MessagePropertyFilter

Public Class MessagePropertyFilter
Implements ICloneable

Inheritance: Object
MessagePropertyFilter

Attributes: TypeConverterAttribute

Implements: ICloneable

Examples

The following code example sends two messages of different priorities to the queue, and retrieves them subsequently.


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

using namespace System;
using namespace System::Messaging;

/// <summary>
/// Provides a container class for the example.
/// </summary>
ref class MyNewQueue
{
   //**************************************************
   // Sends a string message to a queue.
   //**************************************************
public:
   void SendMessage( MessagePriority priority, String^ messageBody )
   {
      // Connect to a queue on the local computer.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

      // Create a new message.
      Message^ myMessage = gcnew Message;
      if ( priority > MessagePriority::Normal )
      {
         myMessage->Body = "High Priority: {0}",messageBody;
      }
      else
      {
         myMessage->Body = messageBody;
      }

      // Set the priority of the message.
      myMessage->Priority = priority;

      // Send the Order to the queue.
      myQueue->Send( myMessage );

      return;
   }

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

      // Set the queue to read the priority. By default, it
      // is not read.
      myQueue->MessageReadPropertyFilter->Priority = true;

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

         // Display message information.
         Console::WriteLine( "Priority: {0}",
            myMessage->Priority );
         Console::WriteLine( "Body: {0}",
            myMessage->Body );
      }
      catch ( MessageQueueException^ ) 
      {
         // Handle Message Queuing exceptions.
      }
      // Handle invalid serialization format.
      catch ( InvalidOperationException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

      // 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;

   // Send messages to a queue.
   myNewQueue->SendMessage( MessagePriority::Normal, "First Message Body." );
   myNewQueue->SendMessage( MessagePriority::Highest, "Second Message Body." );

   // Receive messages from a queue.
   myNewQueue->ReceiveMessage();
   myNewQueue->ReceiveMessage();

   return 0;
}

using System;
using System.Messaging;

namespace MyProject
{

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

        //**************************************************
        // Provides an entry point into the application.
        //		
        // This example sends and receives a message from
        // a queue.
        //**************************************************

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

            // Send messages to a queue.
            myNewQueue.SendMessage(MessagePriority.Normal, "First Message Body.");
            myNewQueue.SendMessage(MessagePriority.Highest, "Second Message Body.");

            // Receive messages from a queue.
            myNewQueue.ReceiveMessage();
            myNewQueue.ReceiveMessage();

            return;
        }

        //**************************************************
        // Sends a string message to a queue.
        //**************************************************
        
        public void SendMessage(MessagePriority priority, string messageBody)
        {

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

            // Create a new message.
            Message myMessage = new Message();

            if(priority > MessagePriority.Normal)
            {
                myMessage.Body = "High Priority: " + messageBody;
            }
            else
            {
                myMessage.Body = messageBody;
            }

            // Set the priority of the message.
            myMessage.Priority = priority;

            // Send the Order to the queue.
            myQueue.Send(myMessage);

            return;
        }

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

            // Set the queue to read the priority. By default, it
            // is not read.
            myQueue.MessageReadPropertyFilter.Priority = true;

            // Set the formatter to indicate body contains a string.
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(string)});
            
            try
            {
                // Receive and format the message.
                Message myMessage =	myQueue.Receive();

                // Display message information.
                Console.WriteLine("Priority: " +
                    myMessage.Priority.ToString());
                Console.WriteLine("Body: " +
                    myMessage.Body.ToString());
            }
            
            catch (MessageQueueException)
            {
                // Handle Message Queuing exceptions.
            }

            // Handle invalid serialization format.
            catch (InvalidOperationException e)
            {
                Console.WriteLine(e.Message);
            }
            
            // Catch other exceptions as necessary.

            return;
        }
    }
}

Imports System.Messaging


'Provides a container class for the example.
Public Class MyNewQueue
      
      

      ' Provides an entry point into the application.
      '		 
      ' This example sends and receives a message from
      ' a queue.

      Public Shared Sub Main()
         ' Create a new instance of the class.
         Dim myNewQueue As New MyNewQueue()
         
         ' Send messages to a queue.
         myNewQueue.SendMessage(MessagePriority.Normal, "First Message Body.")
         myNewQueue.SendMessage(MessagePriority.Highest, "Second Message Body.")
         
         ' Receive messages from a queue.
         myNewQueue.ReceiveMessage()
         myNewQueue.ReceiveMessage()
         
         Return
      End Sub
      
      
      

      ' Sends a string message to a queue.

      Public Sub SendMessage(priority As MessagePriority, messageBody As String)
         
         ' Connect to a queue on the local computer.
         Dim myQueue As New MessageQueue(".\myQueue")
         
         ' Create a new message.
         Dim myMessage As New Message()
         
         If priority > MessagePriority.Normal Then
            myMessage.Body = "High Priority: " + messageBody
         Else
            myMessage.Body = messageBody
         End If 
         ' Set the priority of the message.
         myMessage.Priority = priority
         
         
         ' Send the Order to the queue.
         myQueue.Send(myMessage)
         
         Return
      End Sub
      
      
      

      ' Receives a message.

      Public Sub ReceiveMessage()
         ' Connect to the a queue on the local computer.
         Dim myQueue As New MessageQueue(".\myQueue")
         
         ' Set the queue to read the priority. By default, it
         ' is not read.
         myQueue.MessageReadPropertyFilter.Priority = True
         
         ' Set the formatter to indicate body contains a string.
         myQueue.Formatter = New XmlMessageFormatter(New Type() {GetType(String)})
         
         Try
            ' Receive and format the message. 
            Dim myMessage As Message = myQueue.Receive()
            
            ' Display message information.
            Console.WriteLine(("Priority: " + myMessage.Priority.ToString()))
            Console.WriteLine(("Body: " + myMessage.Body.ToString()))
         
         
         
         ' Handle invalid serialization format.
         Catch e As InvalidOperationException
            Console.WriteLine(e.Message)
         End Try
         
         ' Catch other exceptions as necessary.
         Return
      End Sub
   End Class

Remarks

Setting the MessagePropertyFilter on a MessageQueue instance controls the set of properties that are retrieved when peeking or receiving a message. The filter is set on the instance of MessageQueue that retrieves the message information. When you set a MessagePropertyFilter Boolean-valued member to false, you prevent the information of the associated Message property from being retrieved by the MessageQueue.

There are several filter properties that are not Boolean values. They are integer values that get or set the default sizes of the Message.Body, Message.Extension, or Message.Label.

Retrieving a limited set of properties helps improve performance because smaller amounts of data are transferred from the queue.

When setting a property on MessagePropertyFilter, you are only indicating whether that property is retrieved when a message is received or peeked. You are not changing the associated property value for the Message.

The MessagePropertyFilter constructor sets all filter properties to their default values, which for the Boolean values is false. See the constructor topic for the defaults assigned to the integer-valued properties.

Constructors

MessagePropertyFilter()

Initializes a new instance of the MessagePropertyFilter class and sets default values for all properties.

Properties

AcknowledgeType	Gets or sets a value that indicates whether to retrieve AcknowledgeType property information when receiving or peeking a message.
Acknowledgment	Gets or sets a value that indicates whether to retrieve Acknowledgment property information when receiving or peeking a message.
AdministrationQueue	Gets or sets a value that indicates whether to retrieve AdministrationQueue property information when receiving or peeking a message.
AppSpecific	Gets or sets a value that indicates whether to retrieve AppSpecific property information when receiving or peeking a message.
ArrivedTime	Gets or sets a value that indicates whether to retrieve ArrivedTime property information when receiving or peeking a message.
AttachSenderId	Gets or sets a value that indicates whether to retrieve AttachSenderId property information when receiving or peeking a message.
Authenticated	Gets or sets a value that indicates whether to retrieve Authenticated property information when receiving or peeking a message.
AuthenticationProviderName	Gets or sets a value that indicates whether to retrieve AuthenticationProviderName property information when receiving or peeking a message.
AuthenticationProviderType	Gets or sets a value that indicates whether to retrieve AuthenticationProviderType property information when receiving or peeking a message.
Body	Gets or sets a value that indicates whether to retrieve Body property information when receiving or peeking a message.
ConnectorType	Gets or sets a value that indicates whether to retrieve ConnectorType property information when receiving or peeking a message.
CorrelationId	Gets or sets a value that indicates whether to retrieve CorrelationId property information when receiving or peeking a message.
DefaultBodySize	Gets or sets the size, in bytes, of the default body buffer.
DefaultExtensionSize	Gets or sets the size, in bytes, of the default extension buffer.
DefaultLabelSize	Gets or sets the size, in bytes, of the default label buffer.
DestinationQueue	Gets or sets a value that indicates whether to retrieve DestinationQueue property information when receiving or peeking a message.
DestinationSymmetricKey	Gets or sets a value that indicates whether to retrieve DestinationSymmetricKey property information when receiving or peeking a message.
DigitalSignature	Gets or sets a value that indicates whether to retrieve DigitalSignature property information when receiving or peeking a message.
EncryptionAlgorithm	Gets or sets a value that indicates whether to retrieve EncryptionAlgorithm property information when receiving or peeking a message.
Extension	Gets or sets a value that indicates whether to retrieve Extension property information when receiving or peeking a message.
HashAlgorithm	Gets or sets a value that indicates whether to retrieve HashAlgorithm property information when receiving or peeking a message.
Id	Gets or sets a value that indicates whether to retrieve Id property information when receiving or peeking a message.
IsFirstInTransaction	Gets or sets a value that indicates whether to retrieve IsFirstInTransaction property information when receiving or peeking a message.
IsLastInTransaction	Gets or sets a value that indicates whether to retrieve IsLastInTransaction property information when receiving or peeking a message.
Label	Gets or sets a value that indicates whether to retrieve Label property information when receiving or peeking a message.
LookupId	Gets or sets a value that indicates whether to retrieve LookupId property information when receiving or peeking a message.
MessageType	Gets or sets a value that indicates whether to retrieve MessageType property information when receiving or peeking a message.
Priority	Gets or sets a value that indicates whether to retrieve Priority property information when receiving or peeking a message.
Recoverable	Gets or sets a value that indicates whether to retrieve Recoverable property information when receiving or peeking a message.
ResponseQueue	Gets or sets a value that indicates whether to retrieve ResponseQueue property information when receiving or peeking a message.
SenderCertificate	Gets or sets a value that indicates whether to retrieve SenderCertificate property information when receiving or peeking a message.
SenderId	Gets or sets a value that indicates whether to retrieve SenderId property information when receiving or peeking a message.
SenderVersion	Gets or sets a value that indicates whether to retrieve SenderVersion property information when receiving or peeking a message.
SentTime	Gets or sets a value that indicates whether to retrieve SentTime property information when receiving or peeking a message.
SourceMachine	Gets or sets a value that indicates whether to retrieve SourceMachine property information when receiving or peeking a message.
TimeToBeReceived	Gets or sets a value that indicates whether to retrieve TimeToBeReceived property information when receiving or peeking a message.
TimeToReachQueue	Gets or sets a value that indicates whether to retrieve TimeToReachQueue property information when receiving or peeking a message.
TransactionId	Gets or sets a value that indicates whether to retrieve TransactionId property information when receiving or peeking a message.
TransactionStatusQueue	Gets or sets a value that indicates whether to retrieve TransactionStatusQueue property information when receiving or peeking a message.
UseAuthentication	Gets or sets a value that indicates whether to retrieve UseAuthentication property information when receiving or peeking a message.
UseDeadLetterQueue	Gets or sets a value that indicates whether to retrieve UseDeadLetterQueue property information when receiving or peeking a message.
UseEncryption	Gets or sets a value that indicates whether to retrieve UseEncryption property information when receiving or peeking a message.
UseJournalQueue	Gets or sets a value that indicates whether to retrieve UseJournalQueue property information when receiving or peeking a message.
UseTracing	Gets or sets a value that indicates whether to retrieve UseTracing property information when receiving or peeking a message.

Methods

ClearAll()	Sets all Boolean filter values to `false`, so that no message properties are retrieved when receiving a message.
Clone()	Creates a shallow copy of the object.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
SetAll()	Specifies to retrieve all message properties when receiving a message.
SetDefaults()	Sets the filter values of common Message Queuing properties to `true` and the integer-valued properties to their default values.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Applies to

Jaa