Sessions and queues

The Session sample demonstrates how to send and receive a set of related messages in queued communication over the Message Queuing (MSMQ) transport. This sample uses the netMsmqBinding binding. The service is a self-hosted console application to enable you to observe the service receiving queued messages.

In queued communication, the client communicates to the service using a queue. More precisely, the client sends messages to a queue. The service receives messages from the queue. The service and client therefore, do not have to be running at the same time to communicate using a queue.

Sometimes, a client sends a set of messages that are related to each other in a group. When messages must be processed together or in a specified order, a queue can be used to group them together, for processing by a single receiving application. This is particularly important when there are several receiving applications on a group of servers and it is necessary to ensure that a group of messages is processed by the same receiving application. Queued sessions are a mechanism used to send and receive a related set of messages that must get processed all at once. Queued sessions require a transaction to exhibit this pattern.

In the sample, the client sends a number of messages to the service as part of a session within the scope of a single transaction.

The service contract is IOrderTaker, which defines a one-way service that is suitable for use with queues. The SessionMode used in the contract shown in the following sample code indicates that the messages are part of the session.

[ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples", SessionMode=SessionMode.Required)]
public interface IOrderTaker
{
    [OperationContract(IsOneWay = true)]
    void OpenPurchaseOrder(string customerId);

    [OperationContract(IsOneWay = true)]
    void AddProductLineItem(string productId, int quantity);

    [OperationContract(IsOneWay = true)]
    void EndPurchaseOrder();
}

The service defines service operations in such a way that the first operation enlists in a transaction but does not automatically complete the transaction. Subsequent operations also enlist in the same transaction but do not automatically complete. The last operation in the session automatically completes the transaction. Thus, the same transaction is used for several operation invocations in the service contract. If any of the operations throw an exception, then the transaction rolls back and the session is put back into the queue. Upon successful completion of the last operation, the transaction is committed. The service uses PerSession as the InstanceContextMode to receive all messages in a session on the same instance of the service.

[ServiceBehavior(InstanceContextMode=InstanceContextMode.PerSession)]
public class OrderTakerService : IOrderTaker
{
    PurchaseOrder po;

    [OperationBehavior(TransactionScopeRequired = true,
                                 TransactionAutoComplete = false)]
    public void OpenPurchaseOrder(string customerId)
    {
        Console.WriteLine("Creating purchase order");
        po = new PurchaseOrder(customerId);
    }

    [OperationBehavior(TransactionScopeRequired = true,
                                  TransactionAutoComplete = false)]
    public void AddProductLineItem(string productId, int quantity)
    {
        po.AddProductLineItem(productId, quantity);
        Console.WriteLine("Product " + productId + " quantity " +
                            quantity + " added to purchase order");
    }

    [OperationBehavior(TransactionScopeRequired = true,
                                  TransactionAutoComplete = true)]
    public void EndPurchaseOrder()
    {
       Console.WriteLine("Purchase Order Completed");
       Console.WriteLine();
       Console.WriteLine(po.ToString());
    }
}

The service is self hosted. When using the MSMQ transport, the queue used must be created in advance. This can be done manually or through code. In this sample, the service contains System.Messaging code to check for the existence of the queue and creates it, if necessary. The queue name is read from the configuration file using the AppSettings class.

// Host the service within this EXE console application.
public static void Main()
{
    // Get MSMQ queue name from app settings in configuration.
    string queueName = ConfigurationManager.AppSettings["queueName"];

    // Create the transacted MSMQ queue if necessary.
    if (!MessageQueue.Exists(queueName))
        MessageQueue.Create(queueName, true);

    // Create a ServiceHost for the OrderTakerService type.
    using (ServiceHost serviceHost = new ServiceHost(typeof(OrderTakerService)))
    {
        // Open the ServiceHost to create listeners and start listening for messages.
        serviceHost.Open();

        // The service can now be accessed.
        Console.WriteLine("The service is ready.");
        Console.WriteLine("Press <ENTER> to terminate service.");
        Console.WriteLine();
        Console.ReadLine();

        // Close the ServiceHost to shutdown the service.
        serviceHost.Close();
    }
}

The MSMQ queue name is specified in an appSettings section of the configuration file. The endpoint for the service is defined in the system.serviceModel section of the configuration file and specifies the netMsmqBinding binding.

<appSettings>
  <!-- Use appSetting to configure MSMQ queue name. -->
  <add key="queueName" value=".\private$\ServiceModelSamplesSession" />
</appSettings>

<system.serviceModel>
  <services>
    <service name="Microsoft.ServiceModel.Samples.OrderTakerService"
        behaviorConfiguration="CalculatorServiceBehavior">
      ...
      <!-- Define NetMsmqEndpoint -->
      <endpoint address="net.msmq://localhost/private/ServiceModelSamplesSession"
                binding="netMsmqBinding"
                contract="Microsoft.ServiceModel.Samples.IOrderTaker" />
      ...
    </service>
  </services>
  ...
</system.serviceModel>

The client creates a transaction scope. All messages in the session are sent to the queue within the transaction scope, causing it to be treated as an atomic unit where all messages succeed or fail. The transaction is committed by calling Complete.

//Create a transaction scope.
using (TransactionScope scope = new TransactionScope(TransactionScopeOption.Required))
{
    // Create a client with given client endpoint configuration.
    OrderTakerClient client = new OrderTakerClient("OrderTakerEndpoint");
    // Open a purchase order.
    client.OpenPurchaseOrder("somecustomer.com");
    Console.WriteLine("Purchase Order created");

    // Add product line items.
    Console.WriteLine("Adding 10 quantities of blue widget");
    client.AddProductLineItem("Blue Widget", 10);

    Console.WriteLine("Adding 23 quantities of red widget");
    client.AddProductLineItem("Red Widget", 23);

    // Close the purchase order.
    Console.WriteLine("Closing the purchase order");
    client.EndPurchaseOrder();

    //Closing the client gracefully closes the connection and cleans up resources.
    client.Close();

    // Complete the transaction.
    scope.Complete();
}

When you run the sample, the client and service activities are displayed in both the service and client console windows. You can see the service receive messages from the client. Press ENTER in each console window to shut down the service and client. Because queuing is in use, the client and service do not have to be up and running at the same time. You can run the client, shut it down, and then start up the service and it still receives its messages.

On the client.

Purchase Order created
Adding 10 quantities of blue widget
Adding 23 quantities of red widget
Closing the purchase order

Press <ENTER> to terminate client.

On the service.

The service is ready.
Press <ENTER> to terminate service.

Creating purchase order
Product Blue Widget quantity 10 added to purchase order
Product Red Widget quantity 23 added to purchase order
Purchase Order Completed

Purchase Order: 7c86fef0-2306-4c51-80e6-bcabcc1a6e5e
        Customer: somecustomer.com
        OrderDetails
                Order LineItem: 10 of Blue Widget @unit price: $2985
                Order LineItem: 23 of Red Widget @unit price: $156
        Total cost of this order: $33438
        Order status: Pending

Set up, build, and run the sample

1. Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

2. To build the C#, C++, or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.

3. To run the sample in a single- or cross-machine configuration, follow the instructions in Running the Windows Communication Foundation Samples.

By default with the NetMsmqBinding, transport security is enabled. There are two relevant properties for MSMQ transport security namely, MsmqAuthenticationMode and MsmqProtectionLevel. By default, the authentication mode is set to Windows and the protection level is set to Sign. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria, you receive an error.

Run the sample on a computer joined to a workgroup

1. If your computer is not part of a domain or does not have active directory integration installed, turn off transport security by setting the authentication mode and protection level to None as shown in the following sample configuration.

   <system.serviceModel>
     <services>
       <service name="Microsoft.ServiceModel.Samples.OrderTakerService"
                behaviorConfiguration="OrderTakerServiceBehavior">
         <host>
           <baseAddresses>
             <add baseAddress=
            "http://localhost:8000/ServiceModelSamples/service"/>
           </baseAddresses>
         </host>
         <!-- Define NetMsmqEndpoint -->
         <endpoint
             address=
           "net.msmq://localhost/private/ServiceModelSamplesSession"
             binding="netMsmqBinding"
             bindingConfiguration="Binding1"
          contract="Microsoft.ServiceModel.Samples.IOrderTaker" />
         <!-- The mex endpoint is exposed at-->
         <!--http://localhost:8000/ServiceModelSamples/service/mex. -->
         <endpoint address="mex"
                   binding="mexHttpBinding"
                   contract="IMetadataExchange" />
       </service>
     </services>
   
     <bindings>
       <netMsmqBinding>
         <binding name="Binding1">
           <security mode="None" />
         </binding>
       </netMsmqBinding>
     </bindings>
   
       <behaviors>
         <serviceBehaviors>
           <behavior name="OrderTakerServiceBehavior">
             <serviceMetadata httpGetEnabled="True"/>
           </behavior>
         </serviceBehaviors>
       </behaviors>
   
     </system.serviceModel>
   

2. Ensure that you change the configuration on both the server and the client before you run the sample.

   Note

   Setting security mode to None is equivalent to setting MsmqAuthenticationMode, MsmqProtectionLevel, and Message security to None.