Setting up jQuery for ASP.NET Web Forms projects

During my recent presentation to the Victoria.NET DevSIG on jQuery, I talked about how to get started using jQuery with ASP.NET Web Forms projects. Part of this was around how I like to set up my projects with jQuery to take advantage of the script management features that ASP.NET & Visual Studio 2008 provide out of the box.

ASP.NET provides support for switching in different versions of your JavaScript files at runtime depending on the compilation setting in your web.config file (debug=true or false) via the ScriptManager control. This allows you to have your development script used during development & debug time, and an optimised script (minimised, obfuscated, etc.) used at release time. You can enable this feature of the ScriptManager with your own files (it does it automatically for the MS AJAX framework files) in a few ways, the easiest of which is to set the ScriptMode property of your ScriptReferences to Inherit.

<asp:ScriptManager runat="server">
     <Scripts>
         <asp:ScriptReference Path="~/script/myScript.js" ScriptMode="Inherit" />
     </Scripts>
</asp:ScriptManager>

Further to this, Visual Studio 2008, by way of a hot fix, adds support for a third type of JavaScript file, used only for providing JavaScript IntelliSense within the Visual Studio IDE. These special versions of your script files (known as “VSDoc” files) are carefully constructed to ensure optimal IntelliSense relevance, information & performance and generally are not able to be used at runtime at all.

So we have three file types in all as follows:

• Release mode file: myscript.js
• Debug mode file: myscript.debug.js
• VSDoc file: myscript-vsdoc.js

When you download jQuery, you have the option of the standard file (jquery-1.3.2.js at time of writing) as well as the “production” file, which is minimised (jquery-1.3.2.min.js). Microsoft have also contributed a VSDoc file which you can download from the official jQuery source repository on Google Code.

So there are three types of jQuery files that match up with what ASP.NET & Visual Studio support, just two of them have the wrong extension. All we need to do is rename the files to match the features in the platform & tools:

• jquery-1.3.2.js => jquery-1.3.2.debug.js
• jquery-1.3.2.min.js => jquery-1.3.2.js

I have this files in a location on my hard drive where I can always get to them for new projects:

To use them in a project, just create a folder to hold them and right-click in solution explorer and choose Add –> Existing Item…

Now simply add a script reference for the jQuery files in the same way as you would for your own script. ASP.NET will use the large debug version when the app is in debug mode & the minimised version when it isn’t, plus you’ll get great IntelliSense support from Visual Studio 2008:

<asp:ScriptManager runat="server">
     <Scripts>
         <asp:ScriptReference Path="~/script/jquery-1.3.2.js" ScriptMode="Inherit" />
         <asp:ScriptReference Path="~/script/myScript.js" ScriptMode="Inherit" />
     </Scripts>
</asp:ScriptManager>

It would be nice if the next version of ASP.NET included support for jQuery’s default file extensions in the ScriptManager control, but until then this works very well.

---