Understanding ScriptResource and WebResource in ASP.NET

Here are some common questions about ASP.NET and web resources:

• What is a web resource?
• How do I get my embedded scripts to be delivered by ScriptResource.axd handler?
• How do I get my embedded scripts to be delivered by WebResource.axd handler?
• What is the difference between ScriptResource.axd and WebResource.axd?

First, let’s tackle the first question.  What is a web resource and why would you use such a thing?

Web Resources

A web resource is a file embedded in an assembly.  This file can either be a JavaScript file or a BMP, or any other emendable type of resource in an assembly.  Just take a look at System.Web and all the embedded resources that are defined:

You’ll notice there are both, Images and Scripts.  There’s even some html!  So, web resources (at an assembly level) can be composed of just about anything you want.

How do you define Web Resources?

Meet the [WebResource] attribute.  You define web resources by using the WebResource attribute.  The WebResourceAttribute acts as an access marker to allow resource handlers to find your resources.  The first parameter to WebResource is the name of the web resource, the second parameter is the ContentType.

 [WebResource(  
   webResourceName  
     Type: System.String  
     The name of the of Web resource.  
   ,  
   contentType  
     Type: System.String  
     The type of resource, such as "image/gif" or "text/javascript".  
 )]

Once you have your [WebResource] defined in your assembly, the next step is to mark the file you want embedded as an “Embedded Resource” in Visual Studio.

Working with Assembly Resources

There are two basic ways to getting at your assembly resources loaded on your ASP.NET web page.  ScriptResource.axd and WebResource.axd.

Using WebResource.axd

Generally, you’ll want to use WebResource.axd when you are dealing with binary resources.  Things like emendable images or other types of media.  You can use WebResource for serving out JavaScript files but there is a better alternative.  However, if you’re stuck in ASP.NET 2.0 land with out Microsoft AJAX, then WebResource.axd is your only option to serve out your embedded assembly resources.  To make your assembly resources available on your ASP.NET page, simply use:

104  //Uses WebResource.axd
105  this.Page.ClientScript.RegisterClientScriptResource(
106     typeof(SwfObject), "ProjectBase.Web.Scripts.swfobject.js" );
107 
108  string urlToFunnyWebResourceUrl =
109     this.Page.ClientScript.GetWebResourceUrl(
110     typeof(SwfObject), "ProjectBase.Web.Images.Header.gif" );

urlToFunnyWebResourceUrl is the the actual absolute path to your webresource.  So you could potentially use it to link to an image or script.  ClientScript.Register* are generally reserved for loading JavaScript.  It’s pretty straight forward, pass in the typeof(Control) that’s requesting the resource, and the full name to the assembly resource.  The result of these calls will generate URLs to WebResource.axd.

Using ScriptResource.axd

As I mentioned earlier, there is a better alternative for loading your JavaScript assets if you’re working with ASP.NET AJAX.  Using ScriptResource.axd handler actually has some interesting features.  Some features include:

• Automatically GZip/Compressing your scripts over HTTP for delivery.
• Dynamically resolving Release/Debug scripts based on build parameters.  This is useful, if you keep two types of the same script: one for debug, and one packed for release.
• Can be used for Non-MsAJAX Framework script assets such as jQuery.

The ScriptManager object is how we can get our embedded JavaScript into our page using ScriptResource.axd:

112  //Uses ScriptManager.axd
113  ScriptManager.RegisterClientScriptResource(
114     this, typeof(SwfObject), "ProjectBase.Web.Scripts.swfobject.js" );

The calling semantics are pretty much the same as the previous calls to WebResource.axd, the only difference is that we are passing in this instance of the control that wants to register the script.  The effect of calling this method results in scripts being loaded from ScriptResource.axd.

That’s it!  Happy coding!  I’ll probably add some more tips on this post if I come across any.

Brian Chavez