Edit

How to: Add an ASP.NET AJAX Endpoint Without Using Configuration

  • Article

Windows Communication Foundation (WCF) allows you to create a service that exposes an ASP.NET AJAX-enabled endpoint that can be called from JavaScript on a client Web site. To create such an endpoint, you can either use a configuration file, as with all other WCF endpoints, or use a method that does not require any configuration elements. This topic demonstrates the second approach.

To create services with ASP.NET AJAX endpoints without configuration, the services must be hosted by Internet Information Services (IIS). To activate an ASP.NET AJAX endpoint using this approach, specify the WebScriptServiceHostFactory as the Factory parameter in the @ServiceHost directive in the .svc file. This custom factory is the component that automatically configures an ASP.NET AJAX endpoint so that it can be called from JavaScript on a client Web site.

For a working example, see the AJAX Service Without Configuration.

For an outline of how to configure an ASP.NET AJAX endpoint using configuration elements, see How to: Use Configuration to Add an ASP.NET AJAX Endpoint.

To create a basic WCF service

  1. Define a basic WCF service contract with an interface marked with the ServiceContractAttribute attribute. Mark each operation with the OperationContractAttribute. Be sure to set the Namespace property.

    [ServiceContract(Namespace = "MyService")]]  
public interface ICalculator  
{  
    [OperationContract]  
    // This operation returns the sum of d1 and d2.  
    double Add(double n1, double n2);  

    //Other operations omitted…  

}

  2. Implement the ICalculator service contract with a CalculatorService.

    public class CalculatorService : ICalculator  
{  
    public double Add(double n1, double n2)  
    {  
        return n1 + n2;  
    }  

//Other operations omitted…

  3. Define a namespace for the ICalculator and CalculatorService implementations by wrapping them in a namespace block.

    Namespace Microsoft.Ajax.Samples  
{  
    //Include the code for ICalculator and Calculator here.  
}

To host the service in Internet Information Services without configuration

  1. Create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate @ServiceHost directive information for the service. Specify that the WebScriptServiceHostFactory is to be used in the @ServiceHost directive to automatically configure an ASP.NET AJAX endpoint.

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

  2. Build the service and call it from the client. Internet Information Services (IIS) activates the service when called. For more information about hosting in IIS, see How to: Host a WCF Service in IIS.

To call the service

  1. The endpoint is configured at an empty address relative to the .svc file, so the service is now available and can be invoked by sending requests to service.svc/<operation> - for example, service.svc/Add for the Add operation. You can use it by entering the service URL into the Scripts collection of the ASP.NET AJAX Script Manager control. For an example, see the AJAX Service Without Configuration.

Example

The automatically-configured endpoint is created at an empty address relative to the base URL. A configuration file can also be added and used with this approach. If the configuration file contains endpoint definitions, these endpoints are added to the automatically-configured endpoint.

For example, service.svc uses the WebScriptServiceHostFactory and the service directory contains a Web.config file that defines an endpoint for the same service using the BasicHttpBinding at the "soap" relative address. In this case, the service contains two endpoints: one at service.svc (which responds to ASP.NET AJAX requests) and another at service.svc/soap (which responds to SOAP requests).

If the configuration file defines an endpoint at an empty relative address and the WebScriptServiceHostFactory is used, an exception is thrown and the service fails to start.

You cannot use configuration to modify settings on the automatically-configured endpoint. If any setting (such as a reader quota) must be modified, you must not use the configuration-free approach by removing the WebScriptServiceHostFactory from the .svc file and creating a configuration entry for the endpoint.

If your service requires ASP.NET Compatibility Mode - for example, if it uses the HttpContext class or ASP.NET authorization mechanisms - a configuration file is still required to turn on this mode. The configuration element required is the <serviceHostingEnvironment> element, which must be added as follows.

<system.serviceModel>

<serviceHostingEnvironment aspNetCompatibilityEnabled="true" /> </system.serviceModel>

For more information, see the WCF Services and ASP.NET topic.

The WebScriptServiceHostFactory class is a derived class of ServiceHostFactory. For a detailed explanation of the service host factory mechanism, see the Extending Hosting Using ServiceHostFactory topic.

See also