September 28, 2006

Using Atlas.NET

I have just recently taken the plunge into using AJAX via the Atlas.net project available from Microsoft. There is a large amount of documentation around showing demonstrations of how to setup an application to use Atlas and AJAX calls, however I haven't found one that covers the basics in great detail which is what I intend to do with this post.

To include Atlas.net with your application you first first perform a number of simple steps. I will first list the steps then provide instructions for each of them.

  1. Install Atlas.net on the development machine
  2. Configure Atlas.net on your existing project, or start a new Atlas.net project
  3. Use the Atlas.net AJAX enabled controls in your project

Install Atlas.net

First you will need to download the ASP.NET AJAX Setup July CTP from http://atlas.asp.net. The July CTP is the msot recent release of Atlas, thankfully Microsoft has provided GoLive authorization with this release which allows you to deploy your AJAX enabled application with the CTP.

Once you have downloaded the installer, simply run the installer and follow the prompts to complete the installation. It will prompt you to add the "'Atlas' Website Template" to Visual Studio, I highly reccomend doing this as it makes AJAX enabling future projects that much easier!

Configure Atlas.net

If you are adding Atlas.net to an existing project, follow the steps below. If you are working on a new project be sure to select the "'Atlas' Website Template" from your template when creating the new project and you will not need to perform any of these steps

You will first need to add a reference to the Atlas DLL, I reccomend copying the DLL to your project's Bin folder prior to adding the reference. The DLL you are looking for is "Microsoft.Web.Atlas.dll", the default installation location is "C:\Program Files\Microsoft ASP.NET\Atlas\v2.0.50727\Atlas". Once you have copied this file to your project simply right click in solution explorer and select "Add Reference". In the add reference dialog use the browse tab to find the copy of Microsoft.Web.Atlas.dll in your project's bin folder. This completes the first configuration step.

Atlas also requires additional configuration options in your project's web.config file, so we will now copy the needed sections over from the sample web.config file provided in the Atlas installation directory. The first section you should copy are the "configSections" and "microsoft.web" elements. A sample of these sections is below:

<configSections>
  <sectionGroup name="microsoft.web" 
      type="Microsoft.Web.Configuration.MicrosoftWebSectionGroup">
    <section name="converters" 
      type="Microsoft.Web.Configuration.ConvertersSection" 
      requirePermission="false" />
    <section name="webServices" 
      type="Microsoft.Web.Configuration.WebServicesSection" 
      requirePermission="false" />
    <section name="authenticationService" 
      type="Microsoft.Web.Configuration.AuthenticationServiceSection" 
      requirePermission="false" />
    <section name="profileService" 
      type="Microsoft.Web.Configuration.ProfileServiceSection" 
      requirePermission="false" />
  </sectionGroup>
</configSections>

This section sets up the custom configuration settings and well as script serialization converts that are needed by Atlas. This information should be placed directly inside the "" element of the web.config file. NOTE: line breaks in the section tags were only included for online display, they should not exist in your application.

The final section to copy over involves registering the "atlas" control tag for all pages, as well as the AJAX httpModules and httpHandlers. This section is as follows:

<microsoft.web>
  <converters>
    <add type="Microsoft.Web.Script.Serialization.Converters.DataSetConverter"/>
    <add type="Microsoft.Web.Script.Serialization.Converters.DataRowConverter"/>
    <add type="Microsoft.Web.Script.Serialization.Converters.DataTableConverter"/>
  <converters>
  <webServices enableBrowserAccess="true" />
</microsoft.web>
<pages>
  <controls>
    <add namespace="Microsoft.Web.UI" assembly="Microsoft.Web.Atlas" tagPrefix="atlas"/>
    <add namespace="Microsoft.Web.UI.Controls" assembly="Microsoft.Web.Atlas" tagPrefix="atlas"/>
  </controls>
</pages>
<compilation debug="false">
  <buildProviders>
      <add extension=".asbx" type="Microsoft.Web.Services.BridgeBuildProvider" />
  </buildProviders>
</compilation>
  
<httpHandlers>
  <remove verb="*" path="*.asmx"/>
  <add verb="*" path="*.asmx" type="Microsoft.Web.Services.ScriptHandlerFactory" validate="false"/>
  <add verb="*" path="atlasbatchcall.axd" type="Microsoft.Web.Services.MultiRequestHandler" validate="false"/>
  <add verb="*" path="atlasglob.axd" type="Microsoft.Web.Globalization.GlobalizationHandler" validate="false"/>
  <add verb="*" path="*.asbx" type="Microsoft.Web.Services.ScriptHandlerFactory" validate="false"/>
</httpHandlers>
<httpModules>
  <add name="ScriptModule" type="Microsoft.Web.Services.ScriptModule"/>
  <add name="BridgeModule" type="Microsoft.Web.Services.BridgeModule"/>
  <add name="WebResourceCompression" type="Microsoft.Web.Services.WebResourceCompressionModule"/>
</httpModules>

This section of code should be placed in the "<system.web>" configuration element.</system.web>

Adding AJAX controls to your Page

The final step is to add AJAX controls to your page to allow your code to use AJAX requests. Every page that uses AJAX calls must include a ScriptManager object. This is a non display object that manages all javascript necessary to execute the AJAX Calls. You declare a ScriptManager as follows, be sure to set the EnablePartialRendering property to true as that is what enables AJAX on the page.

    <atlas:ScriptManager ID="oScriptManager" runat="server" 
            EnablePartialRendering="true">atlas:ScriptManager>

Once you have the ScriptManager declared you now can add an UpdatePanel control to the page. You include the various Server Components you wish to have postback in the of the UpdatePanel. Once this is completed everything in the contentTemplate will just AJAX to postback and no additional changes are necessary. The code for an UpdatePanel is below.

    <atlas:UpdatePanel ID="apnlUpdate" runat="server" Mode="always">
    <ContentTemplate>
    </ContentTemplate>
</atlas:UpdatePanel>

This covers my overview of Atlas, if there is a desire I can create further posts regarding additional features/options with Atlas. Such as the UpdateProgress control, conditional triggers for UpdatePanel and other topics.

tags: Tutorials, ASP.NET, .NET 2.0
comments powered by Disqus

Content provided in this blog is provided "AS-IS" and the information should be used at your own discretion.  The thoughts and opinions expressed are the personal thoughts of Mitchel Sellers and do not reflect the opinions of his employer.

Content Copyright

Content in this blog is copyright protected.  Re-publishing on other websites is allowed as long as proper credit and backlink to the article is provided.  Any other re-publishing or distribution of this content is prohibited without written permission from Mitchel Sellers.