Creating WCF AJAX Services without ASP.NET

Windows Communication Foundation (WCF) AJAX services can be accessed from any JavaScript-enabled Web page, without requiring ASP.NET AJAX. This topic describes how to create such a WCF service.

For instructions on using WCF with ASP.NET AJAX, see Creating WCF Services for ASP.NET AJAX.

There are three parts to a creating a WCF AJAX service:

• Creating an AJAX endpoint that can be accessed from the browser.

• Creating an AJAX-compatible service contract.

• Accessing WCF AJAX services.

Creating an AJAX Endpoint

The most basic way to enable AJAX support in a WCF service is to use the WebServiceHostFactory in the .svc file associated with the service, as in the following example.

<%ServiceHost
    language=c#  
    Debug="true"  
    Service="Microsoft.Ajax.Samples.CityService"  
    Factory=System.ServiceModel.Activation.WebServiceHostFactory  
%>  

Alternatively, you can also use configuration to add an AJAX endpoint. Use the WebHttpBinding on the service endpoint and configure that endpoint with the WebHttpBehavior as shown in the following code snippet.

<configuration>  
  <system.serviceModel>  
    <behaviors>  
      <endpointBehaviors>  
        <behavior name="AjaxBehavior">  
          <webHttp/>  
        </behavior>  
      </endpointBehaviors>  
    </behaviors>  
    <services>  
      <service name="Microsoft.Ajax.Samples.CityService">  
        <endpoint
          address="ajaxEndpoint"  
          behaviorConfiguration="AjaxBehavior"  
          binding="webHttpBinding"  
          contract="Microsoft.Ajax.Samples.ICityService" />  
      </service>  
    </services>  
  </system.serviceModel>  
</configuration>  

For a working example, see the AJAX Service with JSON and XML.

Creating an AJAX-Compatible Service Contract

By default, service contracts exposed over an AJAX endpoint return data in the XML format. Also, by default service operations are accessible through HTTP POST requests to URLs that include the endpoint address followed by the operation name, as shown in the following example.

[OperationContract]  
string[] GetCities(string firstLetters);  

This operation is accessible using an HTTP POST to http://serviceaddress/endpointaddress/GetCities and return an XML message.

You can use the full Web Programming Model to customize these basic aspects. For example, you can use the WebGetAttribute or WebInvokeAttribute attributes to control the HTTP verb to which the operation responds or use the UriTemplate property of these respective attributes to specify custom URIs. For more information, see the WCF Web HTTP Programming Model topic.

The JSON data format is often used in AJAX services. To create an operation that returns JSON instead of XML, set the ResponseFormat (or the ResponseFormat) property to Json. The Stand-Alone JSON Serialization topic shows how built-in .NET types and data contract types map to JSON.

Normally, JSON requests and responses consist of just one item. For the preceding GetCities operation, the request resembles the following statement.

"na"  

The response to that request resembles the following statement.

["Nairobi", "Naples", "Nashville"]  

If the operation takes an extra parameter, the request style must be wrapped to wrap both parameters in a single JSON object. An example of this style JSON message is in the following example.

{"firstLetters": "na", "maxNumber": 2}  

The following contract accepts this message.

[WebInvoke(BodyStyle=WebMessageBodyStyle.WrappedRequest, ResponseFormat=WebMessageFormat.Json)]  
[OperationContract]  
string[] GetCities(string firstLetters, int maxNumber);  

Accessing AJAX Services

WCF AJAX endpoints always accept both JSON and XML requests.

HTTP POST requests with a content-type of "application/json" are treated as JSON, and those with content-type that indicate XML (for example, "text/xml") are treated as XML.

HTTP GET requests contain all the request parameters in the URL itself.

It is up to the user to decide how to create the HTTP request to the endpoint. Also, the user has full control over constructing the JSON that forms the body of the request. For an example of creating a request from JavaScript, see the AJAX Service with JSON and XML.