Export (0) Print
Expand All

 

Connected Services Framework 3.0
Connected Services Framework 3.0 Developers Guide Send comments on this topic.
How to Create a Session
See Also

To create a new session, perform the following steps:

  1. Add the following using directives to your code:

    using Microsoft.ConnectedServices.Sdk;
    using Microsoft.ConnectedServices.Sdk.Addressing;
    using Microsoft.ConnectedServices.Sdk.Client;
    using Microsoft.ConnectedServices.Sdk.Security.Tokens;
    using Microsoft.ConnectedServices.Contracts.Session;

  2. Create a new SessionManifest object:

    SessionManifest manifest = new SessionManifest();

  3. (Optional) Populate the manifest with information about participants and routes. For details, see How to Define a Manifest for a Session.

  4. Create a new SessionRequest object by using the SessionManifest object:

    CreateSessionRequest request = new CreateSessionRequest(manifest);

  5. Create a new Message object, and then specify the SessionActions.CreateRequest action and the Uniform Resource Identifier (URI) of the SessionManagerAdmin Web service (replace servername with the name of the server that is hosting the Connected Services Framework Session Web service):

  6. string sessionManagerAdminUri = "http://servername/Session/SessionManagerAdmin.ashx";
    Message message = Message.CreateMessage(SessionActions.CreateRequest, new Uri(sessionManagerAdminUri));

  7. If you are creating the session asynchronously:

    1. Populate the Header.Addressing.From field of the Message object with the URI of the sending service:

      message.Header.Addressing.From = new EndpointReference(new Uri(sendingServiceUri));

    2. Populate the Header.Addressing.ReplyTo field of the Message object with the URI of the service that will handle the response from the SessionManagerAdmin Web service if it successfully creates a new session (this can be a URI that identifies the same service as the sender):

      message.Header.Addressing.ReplyTo = new EndpointReference(new Uri(responseServiceUri));

    3. Define an operation in the ReplyTo service that catches the SessionActions.CreateResponse action. You should use this operation to cache the session identifier that is generated by the SessionManagerAdmin Web Service; this information is available in the sessionID field in the CreateSessionResponse object, which is passed as a parameter to this operation:

      string sessionId;
      ...
      [Operation(Name ="CreateSessionResponse", Action = SessionActions.CreateResponse)]
      public CreateSessionResponse(CreateSessionResponse response)
      {
          // Cache the session id
          sessionId = response.SessionID


          // Perform any other application-specific processing required
          ...
      }

    4. (Optional) Populate the Header.Addressing.FaultTo field of the Message object with the URI of the service that will handle the SoapFaultException that is thrown by the SessionManagerAdmin Web service if it cannot create the new session (this can be a URL that identifies the same service as the sender):

      message.Header.Addressing.FaultTo = new EndpointReference(new Uri(faultCatchingServiceUri));

    5. (Optional) Define an operation in the service that catches the SessionActions.Fault action. You should use this operation to catch any Simple Object Access Protocol (SOAP) faults thrown by Session while processing the request:

      [Operation(Name="SessionFaultHandler", Action=SessionActions.Fault)]

      public void SessionFaultHandler(SoapFaultException ex)

      {

          // Handle Exception

      }

  8. Set the body of the Message object to the SessionRequest object that you created in step 3:

    message.Body = request;

  9. Provide the credentials of an account that has permission to create new sessions to the Header.Security collection of the Message object. This account must be a member of the role that is specified by the <SessionManagerAdminRoleName> element in the Session.config file:

    // This can also be sent as a Kerberos token (shown here) or as a Username token.
    message.Header.Security.Add(new CSFSecurityTokens.KerberosToken("CSF/OrderManager", ImpersonationLevel.Impersonation));



    Note: You must configure the Kerberos token before you can use it. For more information on configuring Kerberos tokens, see How to Configure Policy to Enable Sending and Receiving Kerberos Tokens.

  10. Create a MessageSender object:

    MessageSender sender = new MessageSender();

  11. If you are creating the session asynchronously, call the SendAsync method of the MessageSender object by passing the Message object as a parameter:

    sender.SendAsync(message);

  12. If you are creating the session synchronously, call the SendSync method of the MessageSender object, specify CreateSessionResponse as the method type parameter, and then pass the Message object to the method. This method call returns a CreateSessionResponse object that contains the session ID. You should enclose your message sender in a try block that will catch any SOAP faults that are thrown by Session while processing the request:

    string sessionId;
    ...



    try

    {

        CreateSessionResponse response = sender.SendSync<CreateSessionResponse>(message);

        sessionId = response.SessionID;

    }



    catch(SoapFaultException ex)

    {

        // Handle the fault here

    }

Fault Handling

In addition to the general Session SOAP fault that is caught in the example code, when creating a session the following SOAP fault exceptions can be thrown:

  • AddRemoveParticipantsFault. For more information on the AddRemoveParticipantsFault, see the example in the topic How to Add and Remove Participants in a Session
  • AddRemoveRoutingEntriesFault. For more information on the AddRemoveRoutingEntriesFault, see the example in the topic How to Add and Remove Routes in a Session.

For a full list of error codes, see the topic Session Fault Codes, Causes and Resolutions.

Example 1 - Creating a Session Asynchronously 

using Microsoft.ConnectedServices.Sdk;
using Microsoft.ConnectedServices.Sdk.Addressing;
using Microsoft.ConnectedServices.Sdk.Client;
using Microsoft.ConnectedServices.Sdk.Security.Tokens;
using Microsoft.ConnectedServices.Contracts.Session;



...



//Create a new Session Manifest

SessionManifest manifest = new SessionManifest();



CreateSessionRequest request = new CreateSessionRequest(manifest)



//Create the request message and set the properties
string sessionManagerAdminUri = "http://servername/Session/SessionManagerAdmin.ashx";
Message message = Message.CreateMessage(SessionActions.CreateRequest, new Uri(sessionManagerAdminUri));

message.Header.Addressing.From = new EndpointReference(new Uri(sendingServiceUri));

message.Header.Addressing.ReplyTo = new EndpointReference(new Uri(responseServiceUri));

message.Header.Addressing.FaultTo = new EndpointReference(new Uri(faultCatchingServiceUri));

message.Body = request;

message.Header.Security.Add(new UsernameToken("user", "password", PasswordOption.SendPlainText));
// This can also be an encrypted Kerberos token 



//Create the message sender and send the message

MessageSender sender = new MessageSender();

sender.SendAsync(message);



...



string sessionId;
...



//Method to catch the response and cache the returned SessionID
[Operation(Name ="CreateSessionResponse", Action = SessionActions.CreateResponse)]
public CreateSessionResponse(CreateSessionResponse response)
{
    // Cache the session id
    sessionId = response.SessionID


    // Perform any other application-specific processing required
    ...
}



...



//Method to handle a Soap Fault

[Operation(Name="SessionFaultHandler", Action=SessionActions.Fault)]

public void SessionFaultHandler(SoapFaultException ex)

{

    // Handle Exception

}

Example 2 - Creating a Session Synchronously 

using Microsoft.ConnectedServices.Sdk;
using Microsoft.ConnectedServices.Sdk.Addressing;
using Microsoft.ConnectedServices.Sdk.Client;
using Microsoft.ConnectedServices.Sdk.Security.Tokens;
using Microsoft.ConnectedServices.Contracts.Session;



...



//Create a variable to cache the SessionID

string sessionId;



...



SessionManifest manifest = new SessionManifest();



CreateSessionRequest request = new CreateSessionRequest(manifest)



string sessionManagerAdminUri = "http://servername/Session/SessionManagerAdmin.ashx";
Message message = Message.CreateMessage(SessionActions.CreateRequest, new Uri(sessionManagerAdminUri));



message.Body = request;

message.Header.Security.Add(new UsernameToken("user", "password", PasswordOption.SendPlainText));
// This can also be an encrypted Kerberos token 



MessageSender sender = new MessageSender();

try

{

    CreateSessionResponse response = sender.SendSync<CreateSessionResponse>(message);

    sessionId = response.SessionID;

}



catch(SoapFaultException ex)

{

    // Handle the fault here

}



...

See Also

Show:
© 2014 Microsoft