How to: Configure ASP.NET Services in Microsoft Ajax

  • [アーティクル]

This topic describes how to set the configuration that enables ASP.NET AJAX-enabled client applications to call ASP.NET Web services (.asmx files). Tasks described in this topic include the following:

  • Configuring Web services to enable calls from client script.

  • Configuring JSON serialization.

  • Configuring the authentication service.

  • Configuring the role service.

  • Configuring the profile service.

The configuration settings are all made in the system.web.extension configuration group. For more information, see system.web.extensions Element (ASP.NET Settings Schema).

Configuring Web Services to Enable Calls from Client Script

The following procedure describes how to configure ASP.NET Web services so that they can be called from client script. For more information, see Exposing Web Services to Client Script.

For Web service calls that are not issued from ASP.NET AJAX-enabled clients (script), the ScriptHandlerFactory handler class delegates the call to the default handler, which uses SOAP instead of JSON format. This is accomplished internally and you do not have to take any action. You can also disable SOAP protocol for Web services.

To disable SOAP protocol for Web services

  • In the Web site's Web.config file, clear all protocols for Web services, as shown in the following example:

    <system.web>
  <webServices>
    <protocols>
      <clear/>
    </protocols>
  </webServices>
</system.web>

To configure Web services to enable calls from client script

  • In the Web site's Web.config file, register the ScriptHandlerFactory HTTP handler.

    This handler processes calls made from script to Web services.

    Note

    These configuration settings are part of the Web.config file template for any new AJAX-enabled Web site that you create in Microsoft Visual Studio 2005. 

    The following example shows the Web.config element for registering the handler.

    <system.web>
  <httpHandlers>
    <remove verb="*" path="*.asmx"/>
    <add verb="*" path="*.asmx"
      type="System.Web.Script.Services.ScriptHandlerFactory"
       validate="false"/>
  </httpHandlers>
<system.web>

Configuring JSON Serialization

When client script calls ASP.NET Web services, data is exchanged in JSON format. You can configure JSON serialization settings through the jsonSerialization element.

To configure JSON serialization

  1. Open the Web site's Web.config file.

    Note

    If you create a Web service in Microsoft Visual Studio 2005, the Web.config file contains the system.web.extensions section with child elements commented out.

  2. In the webServices element, add the jsonSerialization element.

    This element lets you specify custom converters and override default settings.

  3. Define the following serialization attributes. All attributes are optional.

    • recursionLimit. Specifies the maximum depth to which to serialize types. The default recursion limit is 100.

    • maxJsonLength. Specifies the maximum length of the JSON string (the maximum number of UTF-8 characters). The default length is 102400.

    The following example shows how to configure the jsonSerialization element. In the example, maxJsonLength is set to 5000.

    <configuration>
  <system.web.extensions>
    <scripting>
      <webServices>
        <jsonSerialization maxJsonLength="5000"/>
      </webServices>
    </scripting>
  </system.web.extensions>
</configuration>

  4. If you want to use a custom converter, in the jsonSerialization element, add the converters element.

    The element requires the following attributes:

    • name   A unique identifier.

    • type   The fully qualified type name of the converter.

    The following example shows how to configure a custom converter.

    <configuration>
  <system.web.extensions>
    <scripting>
      <webServices>
        <jsonSerialization maxJsonLength="50"/>
          <converters>
            <add name="MyCustomConverter" 
              type="MyCompany.ConvertersNameSpace.MyTypeConverter"/>
          </converters>
        </jsonSerialization>
      </webServices>
    </scripting>
  </system.web.extensions>
</configuration>

Configuring Application Services to Enable Calls from Client Script

The following procedures describe how to configure the built-in application services to enable calls from script in AJAX-enabled Web applications that are running in the browser.

For more information about ASP.NET application services, see the following topics:

To configure the authentication service

  1. Open the Web site's Web.config file.

  2. In the authentication element, enable forms authentication.

    The following example shows an authentication element that is configured to use forms authentication. Any attempt by an unauthenticated user to access a protected resource is redirected to the Login.aspx page in the root of the Web site.

    <system.web>
  <authentication mode="Forms">
    <forms cookieless="UseCookies" 
      loginUrl="~/login.aspx"/>
  </authentication>
<system.web>

    For more information, see Using Forms Authentication with Microsoft Ajax.

  3. In the system.web.extensions element, enable the authentication service.

    The following example shows how to enable the authentication service.

    <system.web.extensions>
  <scripting>
    <webServices>
       <authenticationService enabled="true" />
    </webServices>
  </scripting>
</system.web.extensions>

To configure the roles service

  1. Open the Web site's Web.config file.

  2. In the system.web.extensions element, enable the roles service.

    The following example shows how to enable the roles service.

    <system.web.extensions>
  <scripting>
    <webServices>
      <roleService enabled="true" />
    </webServices>
  </scripting>
</system.web.extensions>

To configure the profile service

  1. Open the Web site's Web.config file.

  2. If they are not already defined, define the profile properties that you want to expose in the application.

    You define the profile properties in the profile section by using syntax such as the one in the following example. For grouped properties, use the group element.

    <system.web>
  <profile enabled="true">
    <add name=" Backgroundcolor" type="System.String"
       defaultValue="white" />
    <add name=" Foregroundcolor" type="System.String"
     defaultValue="black" />
    <properties>
      <group name="Address">
       <add name="Street" type="System.String" />
       <add name="City" type="System.String"/>
       <add name="PostalCode" type="System.String" />
      </group>
    </properties>
  </profile>
</system.web>

    For more information, see ASP.NET Profile Properties Overview.

  3. In the system.web.extensions element, enable the profile service.

    The following example shows how to enable the profile service.

    <system.web.extensions>
  <scripting>
    <webServices>
      < profileService enabled="true" />
    </webServices>
  </scripting>
</system.web.extensions>

  4. For each profile property that you want to make available in a client application, add the property name to the readAccessProperties attribute of the profileService element.

  5. For each server profile property that can be updated from client script, add the property name to the writeAccessProperties attribute.

    The following example shows how to expose individual properties and set whether a client application can read and write them.

    <profileService enabled="true" 
    readAccessProperties="Backgroundcolor,Foregroundcolor" 
    writeAccessProperties=" Backgroundcolor,Foregroundcolor"/>

See Also

Tasks

How to: Configure WCF Services in Microsoft Ajax

Reference

system.web.extensions Element (ASP.NET Settings Schema)

System.Web.Configuration

Concepts

ASP.NET Configuration Overview

ASP.NET Configuration File Hierarchy and Inheritance

Editing ASP.NET Configuration Files

Other Resources

ASP.NET Configuration Settings

ASP.NET Configuration API