Conditional Get and Put
This sample demonstrates how to use the new conditional retrieve and update APIs for the WCF REST programming model. Because conditional retrieve and update are most appropriate for resource-oriented and REST services, this sample extends the Basic Resource Service sample. This sample focuses on adding support for conditional retrieve and update to the Basic Resource Service sample using the new APIs introduced in .NET Framework version 4.
Conditional Retrieve and Update
The WCF service in this sample exposes a collection of customers in a resource-oriented and REST manner. For a detailed description of the service implementation, please see the Basic Resource Service sample.
This sample adds conditional retrieve and update capabilities to the Basic Resource Service sample. Conditional retrieve and update use HTTP entity tags and the HTTP If-None-Match and If-Match headers to validate that clients either have or do not have the most current entity for a given resource. However, implementing the code to correctly parse the HTTP If-None-Match and If-Match headers can be tedious and error-prone. Therefore, the CheckConditionalRetrieve and CheckConditionalUpdate methods have been added to the IncomingWebRequestContext, which can be accessed using the current instance of the WebOperationContext. In addition, the
SetETag method has been added to the OutgoingWebRequestContext, making it easier to return valid entity tags.
The CheckConditionalRetrieve method is intended to be used with [WebGet] operations. It takes the current entity tag for the given resource as the
entityTag parameter, which can be a
Guid. The CheckConditionalRetrieve method checks the entity tag against the HTTP If-None-Match header of the request. If the entity tag is present in the HTTP If-None-Match header, then a WebFaultException with a status code of Not Modified (304) is thrown; otherwise the method returns. The conditional retrieve mechanism allows the client to tell the server that it has this entity and to only send the current entity if the client does not already have it. Example usage of the CheckConditionalRetrieve method can be seen in the
GetCustomers operations of the service. It is important to note that calls to CheckConditionalRetrieve may not return. Developers should implement the operation so that the request is already known to be successful before the call to CheckConditionalRetrieve is executed, such that if the call to CheckConditionalRetrieve was not present, the service would send a response with a successful status code.
The CheckConditionalUpdate method is similar to the CheckConditionalRetrieve method. It also takes the current entity tag for the given resource. However, it is intended to be used with [WebInvoke] operations in which the method is set to "PUT" or "DELETE". The CheckConditionalUpdate method checks the entity tag against the HTTP If-Match header of the request. If the entity tag is not present in the HTTP If-Match header, then a WebFaultException with a status code of Precondition Failed (412) is thrown. The conditional update mechanism allows the client to tell the server that it has this entity for the resource and to only allow the client to alter the resource; if the entity it has is current. Example usage of the CheckConditionalUpdate method can be seen in the
DeleteCustomer operations of the service. Just as with CheckConditionalRetrieve, it is important to note that calls to CheckConditionalUpdate may not return. Developers should implement the operation such that the request is already known to be successful before the call to CheckConditionalUpdate is executed, such that if the call to CheckConditionalUpdate was not present, the service would respond with a successful status code.
The sample consists of a self-hosted service and a client that runs within a console application. As the console application runs, the client makes requests to the service and writes the pertinent information from the responses to the console window.
To run the sample
Open the solution for the Conditional Get and Put sample. When launching Visual Studio 2012, you must run as an administrator to execute the sample successfully. Do this by right-clicking the Visual Studio 2012 icon and choosing Run as Administrator from the context menu.
Press CTRL+SHIFT+B to build the solution and then press CTRL+F5 to run the console application project. If running this project with debugging enabled (by pressing F5 instead of CTRL+F5), the debugger stops when an exception is thrown by the conditional GET and PUT checking. When this happens, press F5 to continue executing the sample.
The console window appear sand provides the URI of the running service and the URI of the HTML help page for the running service.
As the sample runs, the client sends requests to the service and writes the responses to the console window.
Press any key to terminate the sample.
The samples may already be installed on your machine. Check for the following (default) directory before continuing.
If this directory does not exist, go to Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) Samples for .NET Framework 4 to download all Windows Communication Foundation (WCF) and WF samples. This sample is located in the following directory.