[OperationContract] Attribute in WCF

By | |

The [OperationContract] attribute includes the method as part of the service contract and identifies the method as a service operation. A method marked as an operation contract is exposed to the public. Methods not marked with this attribute are not exposed externally. [OperationContract] attributes are also mapped to an equivalent WSDL operation definition.
The following list contains the parameters available for use with the [OperationContract] attribute. More than one parameter can be applied to the attribute, and these parameters can be used in any order:

  • Action
  • AsyncPattern
  • IsInitiating
  • IsOneWay
  • IsTerminating
  • Name
  • ProtectionLevel
  • ReplyAction

The following sections discuss these parameters in detail.

Action

The Action parameter gets or sets the WS-Addressing of the request message. It defines the action that identifies the current operation.
The following example illustrates using the Action parameter:

[OperationContract(Action = true)]
void PlaceBookOrder(string isbn, int quantity);

Windows Communication Foundation uses this property to determine which method to send the incoming message to. This makes it necessary for each contract operation to contain a unique action. WCF uses this action to transmit an incoming message to the appropriate method, therefore messages used within a contract operation must have unique actions. This parameter does have a default action, and that is a combination of the contract namespace, the interface or class name, and the operation name. Specifically specifying an action replaces and overrides this default.
You can also specify that an operation handles all incoming messages by specifying an asterisk (*) for this parameter. This comes with a few caveats, though. To enable this type of functionality, the operation needs to do one of the following:

  • The operation method can only accept a message object and return a message object.
  • The operation method can only accept a message object and return nothing.
  • The operation method can be void and accept an IChannel object.

This parameter interacts very closely with the IsInitiating parameter. For more information on this interaction, see the following “IsInitiating” section.

AsyncPattern

The AsyncPattern parameter specifies that an operation is an asynchronous operation. Service operations can be either synchronous or asynchronous. Asynchronous operations are implemented using a BeginXXX and EndXXX method pair within the service contract. It is the AsyncPattern property that tells the runtime that a Begin method has a corresponding and matching End method. Windows Communication Foundation routes incoming messages to the Begin method, and the results of the End method are sent to the outbound message. The AsyncPattern parameter must also be set to true.
The following example illustrates using the AsyncPattern parameter:

[OperationContract(AsyncPattern = true)]
IAsyncResult BeginCheckBookOrderStatus(string OrderNumber, AsyncCallback callback, object state);
void EndCheckBookOrderStatus(IAsyncResult ar);

You should notice that the Begin method contains two additional parameters: the AsyncCallback and state object. To use the AsyncPattern parameter correctly, the Begin operation returns an IAsyncResult object, and the End operation accepts that IAsyncResult result as a parameter and returns the appropriate service operation result.

IsInitiating

The IsInitiating parameter specifies whether or not an operation implemented by the associated method can initiate a session on the server. Session instancing is the ability to have separate instances of a class be maintained for each client channel. This property controls whether an operation is allowed to be the first operation called when a session is created. The default for this parameter is true, meaning that the specified operation can be the first called on a channel. In this scenario, all following calls to this method have no effect (meaning, no other sessions are created). If this parameter is set to false, the client is forced to call other methods prior to calling this method.
This comes in handy when you are trying to set an “order of operation,” meaning that you need a specific method to be called first because the other methods called depend on something returned from the first method.
For example, the following contains three methods, or service operations. The first operation creates the session and must be the first method called. The final operation, Logout, closes the session:

[ServiceContract]
public interface IBuyStock
{
    [OperationContract(IsInitiating = true, IsTerminating = false)]
    void Login(user);
    [OperationContract(IsInitiating = false, IsTerminating = false)]
    void BuyStock(string stocksymbol, int quantity);
    [OperationContract(IsInitiating = false, IsTerminating = true)]
    void Logout(user);
}

Once the initiating method has been called, subsequent calls can be made to that method with no effect to its initiating properties.
If any method other than the initiating method is called first, the following error is returned:

The operation ‘operationname’ cannot be the first operation to be called because IsInitiating is false.

The initiating method must be called first, then other operations can be called.
As mentioned earlier, there is some important interaction between this parameter and the Action parameter. A service contract can only have one operation where the Action property is set to “*”. When the IsInitiating property is set to False, those service contracts that implement a service class can have more than one service operation with the Action property set to “*”. However, the opposite is true when the IsInitiating property is set to True. In those cases, only a single service method can have an Action property set to “*”.

IsOneWay

As you have probably gathered by now, service communication can be either one-way or bi-directional. Service communication by default is bi-directional. Bi-directional service communication means that a service operation can receive incoming messages and send a reply.
The IsOneWay parameter specifies whether a service operation returns a reply message. The default value for this parameter is false, meaning that the method does not return a reply message.
The following example illustrates a one-way communication:

[ServiceContract]
public interface IBuyStock
{
    [OperationContract(IsOneWay = true)]
    void Login(user);
    [OperationContract(IsOneWay = false)]
    void BuyStock(string stocksymbol, int quantity);
}

In a one-way communication, the client initiates the communication and continues code execution and does not wait for a response from the service. In a two-way communication, it waits for a response from the service before continuing code execution.
The downside to using one-way communication is that the caller has no way of knowing whether or not the service processed the message successfully.
Any methods that return a value where the IsOneWay property is set to false will return an exception.

IsTerminating

The IsTerminating property specifies whether a called service operation is to terminate the communication session. The following example, taken from the earlier IsInitiating example, shows the last call, Logout(), has the IsTerminating property set to true:

[ServiceContract]
public interface IBuyStock
{
    [OperationContract(IsInitiating = true, IsTerminating = false)]
    void Login(user);
    [OperationContract(IsInitiating = false, IsTerminating = false)]
    void BuyStock(string stocksymbol, int quantity);
    [OperationContract(IsInitiating = false, IsTerminating = true)]
    void Logout(user);
}

When the IsTerminating property is set to true, the session is closed after the reply message is sent (if a reply message needs to be sent). On the client side, an IsTerminating value of true tells WCF to close the channel only after the reply arrives at the client.

Name

The Name property is used to get or set the name of the operation. This property overrides the <operation> element in WSDL and if this property is left blank, the default name is taken from the method.
In the following example, the Name property sets the name to UserLogin:

[ServiceContract]
public interface IBuyStock
{
    [OperationContract(Name = “UserLogin”)]
    void Login(user);
}

Had the Name property not been specified, the default would have been Login.

ProtectionLevel

The ProtectionLevel parameter specifies the encryption level of the message of an operation. This includes encryption, digital signature, or both, for each endpoint that exposes the contract. The value of this parameter comes from the System.Net.SecurityLevel.ProtectionLevel enumeration. The following enumeration values are available:

  • EncryptAndSign: Encrypt and sign data to ensure the confidentiality and integrity of transmitted data.
  • None: Authentication only.
  • Sign: Sign data to help ensure the integrity of the transmitted data, but do not encrypt.

The following example sets the protection level of the service contract to that of None, meaning that only simple authentication is required. However, a protection level on the Login and BuyStock operations is supplied, setting the protection level to EncryptAndSign. In this scenario, both the Login and BuyStock operations carry the EncryptAndSign protection level, and any other methods inherit the service-level protection level of None.

[ServiceContract(ProtectionLevel = System.Net.Security.ProtectionLevel.None)]
public interface IBuyStock
{
    [OperationContract(ProtectionLevel = System.Net.Security.ProtectionLevel.EncryptAndSign)]
    void Login(user);
    [OperationContract(ProtectionLevel = System.Net.Security.ProtectionLevel.EncryptAndSign)]
    void BuyStock(string stocksymbol, int quantity);
    ...
}

This property has a hierarchical structure, in that the topmost value establishes the default for all lowerlevel scopes ([OperationContract] attribute) unless a specific value is specified for the lower-level scopes.

ReplyAction

This property specifies a reply action for an incoming message. The value for this parameter is a URL, which can be a full URI or simple operation name. If this parameter is left off, the default value will contain the name of the contract plus the name of the reply action. It is also possible to specify an asterisk (*), which tells Windows Communication Foundation not to add a reply action to the message. The following example shows a ReplyAction specifying a full URI response operation:

[ServiceContract]
public interface IBuyStock
{
    [OperationContract(ReplyAction = “http://tempuri.org/IBuyStock/StockBought”)]
}
Tagged . Bookmark the permalink.

Leave a Reply