Configuring ASP.NET AJAX

Introduction

This topic describes the elements in the Web.config file that support Microsoft ASP.NET AJAX. It also describes how to incorporate those elements into the Web.config file for an existing ASP.NET application.

Using the ASP.NET AJAX Web Configuration File in a New Web Site

When you create a new AJAX-enabled Web site, you can use the Web.config file provided in the installation package to add the required configuration settings. In Visual Studio, the Web.config file for Microsoft ASP.NET AJAX is included in your project when you create a new ASP.NET AJAX-enabled Web Site.

If you have to manually add the Web.config file to a new Web site, you can get a copy of it from the installation path. By default, the file is in the following location:

drive:\Program Files\Microsoft ASP.NET\ASP.NET 2.0 AJAX Extensions\v1.0.nnnn

Adding ASP.NET AJAX Configuration Elements to an Existing Web Site

In an existing Web site, you typically have values in the Web.config file that you want to retain. In that case, you can add the new ASP.NET AJAX elements into the existing Web.config file. 

The new elements are part of the following configuration sections:

  • The <configSections> element

  • The <controls> element

  • The <assemblies> element

  • The <httpHandlers> element

  • The <httpModules> element

  • The <system.web.extensions> element

  • The <system.webserver> element

The <configSections> Element

The <configSections> element creates a configuration section and subsections for the SystemWebExtensionsSectionGroup class. You set the properties for these sections in the <system.web.extensions> element.

The following example shows the <configSections> element for ASP.NET AJAX. Add this section to the existing Web.config file as a child of the <configuration> element.

<configuration>
  <configSections>
    <sectionGroup name="system.web.extensions" 
        type="System.Web.Configuration.SystemWebExtensionsSectionGroup, 
        System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, 
         PublicKeyToken=31bf3856ad364e35">
      <sectionGroup name="scripting" 
        type="System.Web.Configuration.ScriptingSectionGroup, 
        System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, 
         PublicKeyToken=31bf3856ad364e35">
          <section name="scriptResourceHandler" 
            type="System.Web.Configuration.ScriptingScriptResourceHandlerSection, 
            System.Web.Extensions, Version=1.0.61025.0, 
             Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
            requirePermission="false" 
            allowDefinition="MachineToApplication"/>
        <sectionGroup name="webServices" 
             type="System.Web.Configuration.ScriptingWebServicesSectionGroup, 
            System.Web.Extensions, Version=1.0.61025.0, 
            Culture=neutral, PublicKeyToken=31bf3856ad364e35">
          <section name="jsonSerialization" 
               type="System.Web.Configuration.ScriptingJsonSerializationSection, 
              System.Web.Extensions, Version=1.0.61025.0, 
              Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
               requirePermission="false" allowDefinition="Everywhere" />
          <section name="profileService" 
              type="System.Web.Configuration.ScriptingProfileServiceSection, 
               System.Web.Extensions, Version=1.0.61025.0, 
              Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
              requirePermission="false" 
              allowDefinition="MachineToApplication" />
           <section name="authenticationService" 
              type="System.Web.Configuration.ScriptingAuthenticationServiceSection, 
              System.Web.Extensions, Version=1.0.61025.0, 
              Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
               requirePermission="false" 
              allowDefinition="MachineToApplication" />
        </sectionGroup>
      </sectionGroup>
    </sectionGroup>
  </configSections>
 </configuration>

The <controls> Element

The <controls> element registers ASP.NET AJAX namespaces in the System.Web.Extensions assembly and maps the asp tag prefix as an alias for these namespaces. The controls in the ASP.NET AJAX namespaces can be referenced in a Web page with syntax such as the following:

<asp:ScriptManager ID="ScriptManager1" runat="server" />

The following example shows the <controls> element for ASP.NET AJAX. Add this section to the existing Web.config file as a child of the <system.web><pages> element.

<system.web>
  <pages>
    <controls>
      <add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
     </controls>
  </pages>
</system.web>

The <assemblies> Element

The <assemblies> element registers the System.Web.Extensions assembly.

The following example shows the <assemblies> element for ASP.NET AJAX. Add this section to the existing Web.config file as a child of the <system.web><compilation> element.

<system.web>
  <compilation>
    <assemblies>
      <add assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
    </assemblies>
   </compilation>
</system.web>

The <httpHandlers> Element

The <httpHandlers> element adds new handlers for script requests.

The following example shows the <httpHandler> element for ASP.NET AJAX. Add this section to the existing Web.config file as a child of the <system.web> element.

<system.web>
  <httpHandlers>
    <remove verb="*" path="*.asmx"/>
    <add verb="*" path="*.asmx" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
     <add verb="*" path="*_AppService.axd" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
     <add verb="GET,HEAD" path="ScriptResource.axd" type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" validate="false"/>
   </httpHandlers>
</system.web>

The <httpModules> Element

The <httpModules> element defines HTTP modules used in ASP.NET AJAX.

The following example shows the <httpModules> element for ASP.NET AJAX. Add this section to the existing Web.config file as a child of the <system.web> element.

<system.web>
  <httpModules>
    <add name="ScriptModule" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
   </httpModules>
</system.web>

The <system.web.extensions> Element

The <system.web.extensions> element provides elements that can be uncommented to configure how Web services are called from Microsoft ASP.NET AJAX applications. The <jsonSerialization> element is used to specify custom type converters and to override default settings for JSON serialization. The <converters> element specifies custom type converters. The <authenticationService> element is used to enable or disable the authentication service. The <profileService> element is used to enable or disable the profile service and to specify which properties are exposed by the service. The <scriptResourceHandler> element is used to enable or disable caching and compression of resources used with scripts.

The <scriptResourceHandler> element, <authenticationService> element, and <profileService> element can be defined only in the Machine.config file or in the Web.config file in the application root directory. The <jsonSerialization> element can be defined in the Machine.config file, in the Web.config file in the application root directory, or in a Web.config file in a subfolder of the Web site.

The following example shows the <system.web.extensions> element for ASP.NET AJAX. Add this section and its subsections to the existing Web.config file as a child of the <configuration> element.

<system.web.extensions>
  <scripting>
    <webServices>
    <!-- Uncomment this line to customize maxJsonLength and add a 
         custom converter -->
      <!--
      <jsonSerialization maxJsonLength="500">
         <converters>
          <add name="ConvertMe" 
             type="Acme.SubAcme.ConvertMeTypeConverter"/>
        </converters>
      </jsonSerialization>
      -->
       <!-- Uncomment this line to enable the authentication service. 
           Include requireSSL="true" if appropriate. -->
      <!--
      <authenticationService enabled="true" requireSSL = "true|false"/>
       -->

      <!-- Uncomment these lines to enable the profile service. To 
           allow profile properties to be retrieved
           and modified in ASP.NET AJAX applications, you need to add 
            each property name to the readAccessProperties and
           writeAccessProperties attributes. -->
      <!--
      <profileService enabled="true"
        readAccessProperties="propertyname1,propertyname2"
         writeAccessProperties="propertyname1,propertyname2" />
      -->
    </webServices>
    <!-- 
    <scriptResourceHandler enableCompression="true" 
        enableCaching="true" />
     -->
  </scripting>
</system.web.extensions>

The <system.webserver> Element

The <system.webserver> element contains configuration settings used by Microsoft Internet Information Server (IIS) 7.0.

The following example shows the <system.webserver> element for ASP.NET AJAX. Add this section to the existing Web.config file as a child of the <configuration> element.

<system.webServer>
  <validation validateIntegratedModeConfiguration="false" />
  <modules>
    <add name="ScriptModule" 
      preCondition="integratedMode" 
       type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
  </modules>
  <handlers>
    <remove name="WebServiceHandlerFactory-ISAPI-2.0"/>
     <add name="ScriptHandlerFactory" verb="*" path="*.asmx" 
      preCondition="integratedMode"
      type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
     <add name="ScriptHandlerFactoryAppServices" verb="*" 
      path="*_AppService.axd" preCondition="integratedMode"
      type="System.Web.Script.Services.ScriptHandlerFactory, 
       System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, 
      PublicKeyToken=31bf3856ad364e35"/>
    <add name="ScriptResource" preCondition="integratedMode" 
      verb="GET,HEAD" path="ScriptResource.axd" 
       type="System.Web.Handlers.ScriptResourceHandler, 
      System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, 
      PublicKeyToken=31bf3856ad364e35" />
  </handlers>
</system.webServer>

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)