Monday, June 08, 2009 11:21 AM
One concept that I don’t see people using, understanding, or even being aware of much in .NET development circles is the Embedded Resource. Declaring a file as an embedded resource within your project means that it will be compiled into the assembly, so that you don’t have to distribute the actual file with the assembly.
Down at the end of this post, I’ll also talk about embedding files that are intended to be loaded in memory to be used, rather than accessed through the web. In that case, it’s much more convenient to already have the file in the assembly, rather than having to search through the file system for it.
So, how do you invoke this magic to place regular, non-compiled files into your compiled assemblies? It all starts, as many things do, in Visual Studio. With the file added to your project, take a gander at the file’s properties (by pressing F4 if you don’t have some crazy keyboard setup). The property page for a file is rather short, and we need to look no farther than the first property of the file to accomplish our purpose. The Build Action property of the file is usually set to Content, meaning “[the] file is not compiled, but is included in the Content output group.” By changing this to Embedded Resource, “[the] file is embedded in the main project build output as a DLL or executable.” This is most of the magic we need, but we’re not quite done yet.
So, to accomplish this, we need to add an assembly-level attribute. These usually live in the AssemblyInfo file, which, by default, is under the Properties folder of your project. After adding a
So, this brings us to the issue of naming. The file is assigned a name when it is embedded into the assembly. This name is the default namespace of the project, plus the folder path, plus the file name itself, all joined together with periods. One important thing to note is that VB.NET assemblies do not have default namespaces (they have root namespaces, a source of continual confusion and frustration for C# programmers who switch back and forth). Therefore, the resource names just start with the folder path. In this case, the name would be
Now that we’ve handled that, how do we actually get the script on the page? The same way you get any script on the page, you use the ClientScriptManager (you do use the ClientScriptManager to manage your client scripts, right?). This is accessible through the page’s ClientScript property, from which you can call RegisterClientScriptResource (when using an embedded resource, you don’t get to choose whether it is a “startup script” [added at the bottom of the page] or “script block,” [added at the top1] it’s always a “block”, so you can’t use the ClientScriptManager if you want to use this technique for a “startup script”).
The RegisterClientScriptResource method takes a Type and the name of the resource. The Type, as far as I can tell, is just used to provide an additional “namespace” for the include, i.e. trying to include the same resource twice with the same Type will result in only one script being added to the page, but if they have different Types specified, the script’ll be added twice. So, in our case (working with a class called DemoPage), this looks like the following call during the page’s Load event:
If you have a case where you want to add a reference to an embedded script but the provided methods don’t work for you, you can use the ClientScriptManager.GetWebResourceUrl method to get a URL to that resource that you can use anywhere URLs are accepted, worldwide.
using (var schemaStream = typeof(DemoPage).Assembly.GetManifestResourceStream(typeof(DemoPage),
// validate something...
One further note about naming. In this situation, the first Type parameter is used to lend its namespace to the resource, so, in this case, since the full name of DemoPage is Engage.Demos.EmbeddedResources.DemoPage, I don’t have to specify the Engage.Demos.EmbeddedResources part of the resource’s name.
From there, you can go wild, doing whatever you want to do with the stream of your file.
Hopefully this clears some things up, and hopefully introduces you to a tool that you may not have known about or may not have known enough about. Make sure and let me know if you have any questions, or see any better ways to go about this stuff.
1 The ClientScriptManager actually only messes with the form element on the page, so it’s really the top and bottom of the page’s form that’s where the scripts get placed.