Version 1.x Quickstart

Introducation

As the web progresses and AJAX becomes more and more popular, the amount of javascript in a typical website is growing. As a result, being able to manage your scripts (and css) is becoming critical. From the developer's point of view, you want to be able to organize your code into lots of files and freely include comments in your scripts where necessary. However, as a website grows, having lots of script includes and comments in the scripts has a significant effect on performance for the end user. (more round trips for the browser and larger files to download). What is ideal then, is to be able to break out your scripts into as many files as you want, adding as many comments as you would like, and then put your scripts through a packaging process so that when the website runs, it includes all of your scripts as one or two larger files with all of the comments and insignificant whitespace taken out). Out of the box, ASP.NET does not give you much help in this area, and while there are plenty of libraries out there that can compress and consolidate scripts, automating them and integrating them into your environment is not always easy. This library exists to make that process seem less.

How It Works

This library provides a configuration section where you can create groups in which your .js and .css files will be included on your page. The groups are specified using regular expressions. Here is an example of a config section:
<almWitt.web.resourceManagement consolidate="true">
	<clientScripts compress="true">
		<group consolidatedUrl="~/controls.js">
			<include>
				<add pattern=".ascx.js"/>
				<add pattern=".aspx.js"/>
			</include>
		</group>
		<group consolidatedUrl="~/default.js">
			<!-- no include so everything is included except that which is explicitly excluded -->
			<exclude>
				<add pattern="~/thirdpartyscripts/"/>
				<add pattern="~/scripts/ExcludedScript.js"/>
			</exclude>
		</group>
	</clientScripts>
	<cssFiles>
		<group consolidatedUrl="~/allstyles.css">
			<include>
				<add pattern=".css"/>
			</include>
		</group>
	</cssFiles>
</almWitt.web.resourceManagement>

Getting Started

To get started with the ResourceManagement library, follow these steps:

1. Reference the AlmWitt.Web.ResourceManagement library. You can do this either by copying the compiled AlmWitt.Web.ResourceManagement.dll file to the bin directory of your website, or by adding the .csproj file to your solution and creating a project reference.

2. Declare the configuration section in your web.config file. To do this, place the following declaration in the <configSections> section:
<section name="almWitt.web.resourceManagement" 
type="AlmWitt.Web.ResourceManagement.Configuration.ResourceManagementConfiguration, AlmWitt.Web.ResourceManagement"/>

3. Create the configuration section in your web.config. For a reference, check out the sample above under "How It Works".

4. Register the ResourceManagement HttpHandler and map it to the .cssx and .jsx extensions. You can do that by adding the following line to the <httpHandlers> section under <system.web> in your web.config:
<add verb="GET,HEAD" path="*.jsx,*.cssx"
 type="AlmWitt.Web.ResourceManagement.ResourceHttpHandler, AlmWitt.Web.ResourceManagement"/>


These handlers enable you to have your files consolidated on the fly in your local dev environment. It is recommended that you pre-consolidate the resources when you build your website so that real .js and .css files are used in production. When the resources have been pre-consolidated, the handlers are automatically disabled. See the Pre-Consolidating Resources section for more info.

NOTE: If you are running your site in IIS 6 or below, you will need to also map the .jsx and .cssx extensions to the ASP.NET ISAPI dll. This will ensure that requests for files with those extensions are actually handled by ASP.NET.

5. Modify your build script of either your Web Deployment Project (.wdproj) or your Web Application Project (.csproj) to have it pre-consolidate your scripts and stylesheets during the build. This will ensure that all of your scripts and styles are in static .js and .css files so that they can by cached properly and gzipped. For more details on this, wee the Pre-Consolidating Resources section of the documentation.

6. (optional) If you would like to use ASP.NET controls to register your .js or .css files in the code-in-front of your Pages or UserControls, then you can declare the ResourceManagement controls in your web.config under the <pages>/<controls> section. Just add this line:
<add tagPrefix="resource" namespace="AlmWitt.Web.ResourceManagement.WebForms" assembly="AlmWitt.Web.ResourceManagement"/>

7. Now that everything is setup, you simply need to start using the ResourceManagement library to include your .js and .css files. You have a couple different options for including the files. You can either do it in the code-in-front of your Page or UserControl, or in your code-behind (or any other code library). If you want to do it in the code-in-front, make sure you have followed step 5, and you can then include them like so:
<resource:ClientScriptInclude ScriptUrl="~/MyScript.js" runat="server" />
<resource:CssInclude StylesheetUrl="~/MyStyles.css" runat="server" />

To register your include via code, you can do it like this (in C#):

WebResourceManager.IncludeClientScriptFile("~/MyScript.js", this); //this is either the page or control
WebResourceManager.IncludeCssFile("~/MyStyles.css", this);

Pre-Consolidating Resources

While including your consolidated resource files via the .jsx and .cssx handlers is convenient for development (much more convenient than constantly re-generating static files), it is not ideal for a production environment where things like expires, etag, and last-modified headers play an important role as well as the ability to gzip your content. Thus, it is recommended that as part of your build process, you "Pre-Consolidate" your resources into static files. The ResourceManagement library will then include the static files instead of using the dynamic file handlers. Assuming you compile your website using MSBuild, pre-consolidating is easy. An MSBuild task is provided for you that takes care of everything...you just need to call the task from within your build script.

To import the MSBuild task into your script, you will need a UsingTask directive that looks something like this:

<UsingTask TaskName="PreConsolidateResources" AssemblyFile=".\Bin\AlmWitt.Web.ResourceManagement.dll"/> 

Notice the AssemblyFile property points to the dll in your bin directory of your website. Depending on where your MSBuild file resides, you may need to adjust the relative path accordingly. Once the task is imported, you will then need to execute the task in the AfterBuild target of your website project. It will look something like this:

<Target Name="AfterBuild">
    <PreConsolidateResources WebRoot="$(OutputPath)" />
</Target>

Note that WebRoot points to the root of the output path of your website on your file system. If you are using a Web Deployment Project, then you can just use the $(OutputPath) property as shown above.

That is all there is to it. The MSBuild task takes care of consolidating your scripts and stylesheets into files that you specify in the configuration, as well as modifying the configuration file to tell it that things have been pre-consolidated. That is how the RM library knows that it can include the static .js and .css files instead of the dynamic .jsx and .cssx files. It also disables the .jsx and .cssx handlers so that they will not work in the production environment.

Last edited May 5, 2011 at 4:21 AM by andyalm, version 3

Comments

No comments yet.