Click here to Skip to main content
15,868,010 members
Articles / Programming Languages / C#
Article

Understanding Embedded Resources in Visual Studio .NET

Rate me:
Please Sign up or sign in to vote.
4.84/5 (60 votes)
24 Oct 2002BSD5 min read 948.9K   8K   131   45
A short article to guide you through how to use embedded resources in .NET projects using Visual Studio .NET

Introduction

Time and again questions have come up in the C# and .NET forums relating to the use of embedded resources in VS.NET.  For most projects there are no problems, but as you get into more complicated projects this quickly becomes a problem.  This article will attempt to put the information needed in a more permanent place, making it easier to find and link to.

First things first

There are a couple different ways resources can be used in VS.NET.  The most common way is how the Form stores the resources it uses, this is done by creating a .resx file containing all of the resources for the Form.  This article will not cover these files because the developer generally doesn't need to worry about them, instead the various designers will interact with them writing most of the needed code to use them.

The second way to use resources, and the one this article will focus on, relies on adding the file to the project and setting the file's "Build Type" property to "Embedded Resource".  This is only the first step though!

What's in a name?

When you embed a resources as I outlined above you will typically need to know its name.  This can be as little as the filename, but usually it is more than that.

The name is made up of three parts: 

<default namespace.><extended 
namespace.><filename>

The first and last parts are easy to identify; the default namespace is set in the project's properties and the filename is...well, the filename of the file.  The middle part is where most people get lost. 

Quickly put, the extended namespace is made up of directory structure of the project itself.  If you place the file in the root of the project, then there is no extended namespace and the name of the file as an embedded resource is <default namespace.><filename>.  But it is possible to create folders with in your project, this is where the extended namespace comes into play.  If you create a folder called Images, and place the file there, then the name of the resource becomes <default namespace.>Images.<filename>.  If you create another folder under Images called FormGraphics then the name becomes

<default 
namespace.>Images.FormGraphics.<filename>

See the pattern?  You can use this for your code as well.  When you create a class in the root of the project the namespace is automatically generated for you, the namespace follows the same pattern: 

<default 
namespace><.extended namespace>
  Once the code has been generated you are, of course, free to change this namespace to whatever you want; but you need to keep this in mind, but you can't cannot change the extended namespace used to name an embedded resource.

Getting the resources

Universal access

The standard way to access an embedded resource is to use the Assembly class's GetManifestResource* methods.  In the first demo application we will use the GetManifestResourceNames and GetManifestResourceStream methods.

The purpose of this demo application will be to list the resources in an assembly, and be able to save selected resources out to a file.  An added feature will let us view the contents of a particular resource if it is an image.  If you don't have any assemblies with embedded resources handy, the second demo application has one embedded in it which you can use.

The interesting code happens inside of the ListBox's SelectedIndexChanged event

C#
System.IO.Stream stream = loadedAssembly.GetManifestResourceStream(
    (string) resources.SelectedItem);

System.Drawing.Image img = Image.FromStream(stream);

The demo application loads an assembly and stores a reference to the

Assembly
in the loadedAssembly variable.  In your applications you probably don't want to get resources from an external assembly, you want resources from the assembly your class is defined in.

The easiest way to get a reference to the Assembly object for a particular class is to use the Type class' Assembly property.  You can get the Type by using typeof(<class>) or if you have an instance of the class, use its GetType() method (inherited from System.Object, the root of all types in .NET).

With this technique you can use any resource embedded in an Assembly, you just need to know the name of the resource.

There is another way

There are actually two overloads of the GetManifestResourceStream function, one which takes the name of the resource to get a Stream for.  The other takes a Type and a string.  This one helps to simplify getting the name to use for the resource.  It takes the Namespace from the Type and appends the string passed in (with a "." between them as well) to form the name.

A few classes in the .NET framework use this pattern as well, but instead of returning Stream objects they construct the particular object.  The Bitmap class is one of these; it has a constructor with the same pattern, and can be used to load an embedded resource into a Bitmap object. 

Another one is the ToolboxBitmapAttribute class, which VS.NET uses to get a bitmap to display in the toolbox for controls/components.  At runtime VS.NET will take the values stored by the attribute to retrieve the Bitmap embedded in the assembly.  Attributes are beyond the scope of this article, but I have written an article that focuses on them.

The second demo uses the second method to display a bitmap embedded in its own assembly. 

Aside from placing the controls on the Form, there was only one line of code I added.

C#
picture.Image = new Bitmap(typeof(Form1), "demo1.gif");

This tells the Bitmap constructor to find the resource named using the namespace from Form1 (since Form1 is at the root of the project, and I didn't change its namespace it has the default namespace assigned to it).  Then it appends a ".", then the string value passed in.  In this case I just added the image to the root of the project and set its Build Type to "Embedded Resource".

See?  That wasn't so bad :-)

Conclusion

Once you get the hang of it, using embedded resources in your .NET applications is easy.  The only hard part is figuring out the name that VS.NET gives to your resources

Updates

  • October 25, 2002 - Initial posting

License

This article, along with any associated source code and files, is licensed under The BSD License


Written By
Software Developer (Senior) InfoPlanIT, LLC
United States United States
James has been programming in C/C++ since 1998, and grew fond of databases in 1999. His latest interest has been in C# and .NET where he has been having fun writing code starting when .NET v1.0 was in its first beta.

He is currently a senior developer and consultant for InfoPlanIT, a small international consulting company that focuses on custom solutions and business intelligence applications.

He was previously employed by ComponentOne where he was a Product Manager for the ActiveReports, Data Dynamics Reports, and ActiveAnalysis products.

Code contained in articles where he is the sole author is licensed via the new BSD license.

Comments and Discussions

 
SuggestionVery good, but namespace in folder can be disabled Pin
niko785-Nov-13 7:32
niko785-Nov-13 7:32 
GeneralMy vote of 5 Pin
Ivaylo Slavov15-Mar-13 16:39
Ivaylo Slavov15-Mar-13 16:39 
SuggestionHere you go you will be a cracker after a while !! Pin
Mazen el Senih13-Mar-12 9:04
professionalMazen el Senih13-Mar-12 9:04 
GeneralMy vote of 5 Pin
Eric Ouellet16-Feb-12 8:35
professionalEric Ouellet16-Feb-12 8:35 
QuestionVery useful Pin
PM819-Feb-12 9:06
PM819-Feb-12 9:06 
GeneralMy vote of 5 Pin
kpierce016-May-11 16:35
kpierce016-May-11 16:35 
Generalnice tip Pin
sstoyan21-Feb-08 5:04
sstoyan21-Feb-08 5:04 
GeneralNo Reflection Pin
Gilad Kapelushnik25-Jun-07 1:41
Gilad Kapelushnik25-Jun-07 1:41 
GeneralWriting to a resource file embedded in a dll programmatically Pin
ShaimaaAli21-Sep-06 3:10
ShaimaaAli21-Sep-06 3:10 
GeneralRe: Writing to a resource file embedded in a dll programmatically Pin
djhenrya22-Jan-12 1:18
djhenrya22-Jan-12 1:18 
You can not write to an embedded resource file.
http://msdn.microsoft.com/en-us/library/ht9h2dk8.aspx[^]
QuestionReading a video file same way Pin
Josh19911826-Feb-06 16:48
Josh19911826-Feb-06 16:48 
GeneralI think I've got the wrong namespace Pin
Dave Midgley24-Jan-06 6:25
Dave Midgley24-Jan-06 6:25 
QuestionAdd Resource At Runtime? Pin
veverkap17-Jul-05 4:25
veverkap17-Jul-05 4:25 
GeneralPersisting the Panel object of external assembly Pin
ArunHcl19-Jun-05 22:42
ArunHcl19-Jun-05 22:42 
Questionembed file at compile time ? Pin
Alon Ronen29-Nov-04 23:55
Alon Ronen29-Nov-04 23:55 
AnswerRe: embed file at compile time ? Pin
James T. Johnson30-Nov-04 0:13
James T. Johnson30-Nov-04 0:13 
QuestionHow to look up default namespace at runtime? Pin
AArnott21-Sep-04 12:48
AArnott21-Sep-04 12:48 
GeneralNamespace Pin
Sacrilege13-Jun-04 12:18
Sacrilege13-Jun-04 12:18 
QuestionEmbedded .dll ? Pin
BillyDvd30-May-04 20:07
BillyDvd30-May-04 20:07 
Generalshowhelp embedded chm resource file Pin
mdg179-Jul-03 10:58
mdg179-Jul-03 10:58 
GeneralRe: showhelp embedded chm resource file Pin
James T. Johnson9-Jul-03 11:14
James T. Johnson9-Jul-03 11:14 
GeneralRe: showhelp embedded chm resource file Pin
jfreets15-Dec-06 5:42
jfreets15-Dec-06 5:42 
GeneralEmbedding exe as a resource Pin
desertspring23-Jun-03 3:36
desertspring23-Jun-03 3:36 
GeneralRe: Embedding exe as a resource Pin
James T. Johnson23-Jun-03 4:46
James T. Johnson23-Jun-03 4:46 
GeneralRe: Embedding exe as a resource Pin
iliyang26-Dec-04 23:46
iliyang26-Dec-04 23:46 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.