Gotcha: Don't use <xhtmlConformance mode="Legacy"/> with ASP.NET AJAX

Recently I've helped a few developers who have been having some weird JavaScript issues (both when using ASP.NET AJAX and with some other custom JavaScript routines they were using).  The culprit was that they had automatically migrated a VS 2003 Web Project to VS 2005, and still had the <xhtmlConformance mode="Legacy"/> switch configured within their web.config file. 

If you are writing custom client-side JavaScript in your web application and/or are going to be using AJAX, please read-on to learn how to avoid a common gotcha (note: for a list of other tips, tricks, recipes and gotchas I've previously posted, please check out this page here).

Symptom:

You see strange behavior when adding new client-side JavaScript to a project that was previously upgraded (successfully) from VS 2003 to VS 2005.  When using ASP.NET AJAX UpdatePanel controls, this strange behavior can sometimes include cases where the page does a full-page postback instead of just incrementally updating pieces of a page. 

When you open up your web.config file, you also see a <xhtmlConformance/> element within it like so:

<configuration>

    <system.web>
        <xhtmlConformance mode="Legacy" />
    </system.web>

</configuration>

Background:

ASP.NET 1.0 and 1.1 didn't emit XHTML compliant markup from many of its server controls.  ASP.NET 2.0 changed this and by default emits XHTML compliant markup from all controls (note: you can learn more about ASP.NET 2.0's standards compliance from this excellent MSDN article).

One of the things we noticed in the early ASP.NET 2.0 betas, though, was that when upgrading customer applications a lot of the applications had assumptions that the page output was not XHTML compliant.  By changing our default output of the server controls to be XHTML, it sometimes modified the visual rendering of a page.  For backwards compatibility purposes we added the <xhtmlConformance> switch above that allows developers to render controls in "Legacy" mode (non-XHTML markup the same as ASP.NET 1.1) as well as Transitional mode (XHTML Transitional) as well as Strict mode (XHTML Strict). 

By default when you use the VS 2003->VS 2005 Web Project Migration wizard (for both web sites and web application projects), your web.config file will have the legacy switch added.

Solution:

Unless you know of known issues that your site has when running in XHTML mode (and which you don't have time yet to fix), I'd always recommend removing the <xhtmlConformance> section from your web.config file (or you can explicitly set it to "Transitional" or "Strict"). 

This will make your HTML output standards compliant.  Among other things, this will cause the HTML from your server controls to be "well formed" - meaning open and close tag elements always match.  This is particularly important when you are using AJAX techniques to dynamically replace the contents of certain HTML elements on your page (otherwise the client-side JavaScript sometimes gets confused about container elements and can lead to errors).  It will also ensure that ASP.NET AJAX works fine with your site.

Hope this helps,

Scott

13 Comments

  • Thanks for that Scott.

    Not totally on the topic you were explaining, but it has annoyed me for ages not being able to have the control emit XHTML strict code (e.g. omit the name="" attribute). And therefore only being able to serve up XHTML transitional pages..

    This switch set to "Strict" does the trick. Excellent! I guess its one of those RTFM moments :)

  • Hi Peter,

    Yep - we support both transitional and strict XHTML rendering. The only actual difference with the ASP.NET controls is with the "name" attribute on the element.

    We origionally were strict only - but ran into cases where a lot of people had client-side Javascript that was referencing form elements using the name attribute. That is why we added the transitional mode (and made it the default) - since the name attribute is supported with transitional.

    Hope this helps,

    Scott

  • Is it possible to read the XHTML Conformance Mode from code?

  • A real good trick while working with Ajax and javascript

  • I removed the
    I found the style of page is diffence with before.
    For example:I write a server control which inherit from DataGrid. I set the BorderColor like that :
    this.BorderColor = System.Drawing.Color.FromArgb(173, 172, 175);
    but problem happened if i remove the ,
    I couldn't see the color which I want.

  • Minor Gotcha:

    Removing the Legacy element from the Web.Config broke some code that looked at the control's name which scanned for a ":" and no longer found it (without the Legacy, the name had "$"s instead of ":"s).

    With legacy, this is the emitted html:





    Without legacy:



  • Hmm. Our web application adheres to XHTML1.1 and we use ASP.NET 2.0; but its hard work.
    I&#39;m not convinced on the out the box support for compliance, happy to be told otherwise, but we still see non-compliant code, for example, form elements such as checkboxes generated in tables.
    The article referred to does this in examples, and empty DIV tags, all non-compliant. I do find it frustrating for accessibility compliance articles to be illustrated with non-compliant code examples.
    ...so we are still using our own custom controls.
    Some things to remember:
    - ID values CANNOT contain underscores*
    - DIV tags must have attributes
    - Forms must be done without table HTML
    Thanks.
    Matt.

  • To those who are interested, we made a change in Atlas' ScriptManager to disable partial rendering by default when legacy rendering is enabled. This way at least your pages won't break, though partial rendering won't be enabled for that page.

    - Eilon

  • This problem occured to me when I change from Ajax RC to Ajax 1.0. Then it simply did not work anymore... When changing to it work again. But the question is why did it work with the relase candidate? :-) No changes in the code....

  • Hi Sara,

    That is pretty odd if it was working for you with the RC. It should have had problems with both the RC and the final release.

    Thanks,

    Scott

  • "This problem occured to me when I change from Ajax RC to Ajax 1.0. Then it simply did not work anymore... "

    Same comment from me. I removed it from web.config but this time some pages have a different look. I have to find a way to put functionality on some aspx, not the whole application.

  • Costs me one day, to figure out by myself. Arrgh! ;-).

  • if you need to use it like I do, do one of the following:
    1) if you have more pages that is rendered incorrectly after removing add the following lines to web.config.





    2) else if you have more ajax code






    This line may be added before tag at the end of config. Hope it helps

Comments have been disabled for this content.