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

Published Sunday, December 10, 2006 9:39 PM by ScottGu

Comments

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

Monday, December 11, 2006 8:26 AM by Peter Mescalchin

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 <form> 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 :)

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

Monday, December 11, 2006 10:30 AM by ScottGu

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 <form> 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

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

Tuesday, December 12, 2006 3:04 AM by Mads

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

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

Tuesday, December 12, 2006 4:00 AM by vikram

A real good trick while working with Ajax and javascript

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

Wednesday, December 13, 2006 10:41 PM by Philip

I removed the <xhtmlConformance mode="Legacy" />

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 <xhtmlConformance mode="Legacy" />,

I couldn't see the color which I want.

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

Friday, December 15, 2006 3:53 PM by Gary Davis

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:

           <input id="_ctl0__ctl0_eDefaultStore_0" type="radio" name="_ctl0:_ctl0:eDefaultStore" value="1" />

Without legacy:

           <input id="ctl00_ctl00_eDefaultStore_0" type="radio" name="ctl00$ctl00$eDefaultStore" value="1" />

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

Friday, December 22, 2006 9:20 AM by MG

Hmm. Our web application adheres to XHTML1.1 and we use ASP.NET 2.0; but its hard work.

I'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.

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

Saturday, January 6, 2007 12:14 AM by Eilon

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

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

Friday, January 26, 2007 10:52 AM by Sara

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 <xhtmlConformance mode="Transitional"/> it work again. But the question is why did it work with the relase candidate? :-) No changes in the code....

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

Tuesday, January 30, 2007 12:20 AM by ScottGu

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

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

Thursday, February 8, 2007 5:01 AM by Cenk

"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 <xhtmlConformance mode="Legacy"/> functionality on some aspx, not the whole application.

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

Thursday, February 22, 2007 10:31 AM by Uwe

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

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

Thursday, March 1, 2007 7:27 AM by Cenk

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 <xhtmlConformance mode="Legacy"/> add the following lines to web.config.

 <location path="<project ajax path>">

   <system.web>

     <xhtmlConformance mode="Transitional"/>

   </system.web>

 </location>

2) else if you have more ajax code

 <location path="<project non ajax path>">

   <system.web>

     <xhtmlConformance mode="Legacy"/>

   </system.web>

 </location>

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