Invoking a DCS Service from a Client Application
A client application uses the following items to invoke a DCS service operation:
- A request message that encapsulates the parameters for the operation.
- A reference to a response message that encapsulates the response from the operation. If the operation is a one-way operation, then it does not return a response message.
- A DCS Context object that defines the context for the client application. The scope provider uses the data in the Context object to determine the possible scopes for the service that the client application can use. For more information, see DCS Context and DCS Scopes.
- A service proxy object that exposes the operation that you want to invoke. The proxy object contains method stubs to enable you to invoke operations in the service. When you invoke an operation, the proxy object marshals messages and invokes the correct operation on the service endpoint. The proxy object then passes return messages back to the caller when the operation completes.
The following procedure describes how to invoke an operation in a DCS service from a client application. For more information about the process that the DCS infrastructure implements when a client application calls an operation, see How a DCS Client Invokes an Operation.
To Invoke an operation on a DCS Service
Create an instance of the request message to which the operation responds, and populate any properties in the message with appropriate data.
Create a reference to the response message that will be returned by the operation. You will use this reference later to store the returning message.
-
Note
If you are invoking a one-way operation, you can ignore this step because there is no response message from one-way operations.
Create a Context object to use during communication. Make sure that you provide a valid scope for the operation, and that the task filters enable you to invoke a task. If the Discovery Service returns no matching task, the call to invoke an operation will throw an ApplicationException exception.
Create an instance of the service proxy class.
Invoke the operation by using the proxy, passing the request message and Context object as parameters. If you are calling an operation that returns a response, store the return value in the response message reference that you created in step 2.
The following code example shows how to invoke an operation called DemoOperation by using a proxy object called DemoOperationProxy.
DemoOperationRequest request = new DemoOperationRequest();
DemoOperationResponse response = null;
Context context = new Context();
context.Organization = new Organization("Demo", "", "", "");
DemoOperationProxy proxy = new DemoOperationProxy();
DemoOperationResponse = proxy.DemoOperation(request, context);
Handling Operation Exceptions
If you follow best practice guidelines, you should add exception handling to your DCS client application. In addition to the errors that you might expect in any application, you should include exception handling for any custom exceptions that you generate in your service. Also, include handling for the ApplicationException and FrameworkException exceptions. DCS throws an ApplicationException if there are no endpoints available to invoke operations on the service, and throws the FrameworkException class for any exceptions encountered while the service is running.
The following code example includes basic exception handling for the ApplicationException and FrameworkException classes. The example assumes that you are building a console application, and prints console messages when exceptions occur.
Note
FrameworkException derives from ApplicationException. Add the FrameworkException catch handler before that of the ApplicationException.
DemoOperationRequest request = new DemoOperationRequest();
DemoOperationResponse response = null;
try
{
Context context = new Context();
context.Organization = new Organization("Demo", "", "", "");
DemoOperationProxy proxy = new DemoOperationProxy();
DemoOperationResponse = proxy.DemoOperation(request, context);
}
// Add statements to catch custom exceptions here
catch (FrameworkException Fex)
{
Console.WriteLine("FrameworkException thrown: {0}", Fex.Message);
}
catch (ApplicationException Aex)
{
Console.WriteLine("ApplicationException thrown: {0}", Aex.Message);
}
catch (Exception ex)
{
Console.WriteLine("Unknown {0} Exception thrown: {1}", new object[]{ex.GetType().ToString(), ex.Message});
}
finally
{
Console.WriteLine("Test completed");
}
Catching Custom Exceptions
To catch a custom error defined in your service application, you add a catch statement for a FaultException<> object and provide the custom error type to catch. The following code example catches a FaultException of type WeatherError, and displays the Message property of that error object.
catch (FaultException<WeatherError> Wex)
{
Console.WriteLine("Custom Error Successfully Caught: {0}", Wex.Message);
}
Providing Security Credentials
An administrator manages security for a service by specifying a security policy. The DCS security infrastructure is based on the DCS Security Token Service, which implements the WS-Trust protocol to authenticate users. DCS lets you use WCF security configuration settings in the application configuration file to provide user credentials and interact with DCS security. For more information on how DCS authenticates users, see How DCS Authenticates Requests. For more information on how to specify the security policy for a service, see Configuring Security Policy for a Service.
See Also
Models for Implementing DCS Services
How a DCS Client Invokes an Operation