Home

Downloads

Documentation

Links

About

Feedback


SourceForge.net Logo

Old School Programming

ResMagik 1.0 Documentation
Last Updated 16/07/2007

Index

Introduction

This document contains detailed information about every aspect of ResMagik. Consider it the help file, it's detailed enough just in case you're a newbie with resource files. This program is oriented to programmers, i assume you're an experienced one so you probably don't need to read this document.

What's a resource file? Most applications use text, images, sounds, videos and many other external files or data. These objects are also known as resources. These resources are used for multiple purposes depending on the type they are. As you might already noticed, many programs you have downloaded use images but, where are these images stored if the programs are only single executable files and sometimes they come with a few satellite assemblies not even related to an image file? Well, the only answer is that these programs are using resource files. Resource files then are files just like any other file but they act like "packages" to store other files, programs are able to read these packages and retrieve data. There're many custom engines for data retrieval but the main concept and popularity of resource files born with the old Win16 resource. Probably, you're now asking yourself: Why should i use a resource file if there're many cool packaging file formats out there? Because compression formats such as RAR, ZIP, ACE, TAR, etc are used only to package or compress files while resource files store many other data types (including files) such us: Strings, dialogs, menus, accelerators and many other serializable objects. Resource files can be used in web sites (dynamic pages). Resource files differ from other file types in the way they can be used: Resource files may be used directly by an application or (one of the most important feature) they can be embedded inside executables or libraries (the executable reads itself to retrieve data).

"...A resource is any nonexecutable data that is logically deployed with an application..." .NET Framework Developer's Guide.

When the .NET Framework 1.0 appeared around the 2001, two new resource file formats came out with it, we're talking about ".resx" and ".resources" file formats. The first one is a XML structure containing multiple tags and the actual binary state of a resource, .resx files can be easily opened and edited in text mode with any text editor but they can't be embedded in assemblies. In the other hand, .resources files are almost impossible to edit with a text editor because they are in a binary form but they are embeddable with assemblies. Both formats are an evolution from years of implementations, dropping ambiguities like storing different resource types in different tables and adding new features like native support for UTF-8 strings. Now a days, these resource file formats and other implementations store all resources in a single area (not in a specific table) and had excluded certain objects from the specification (for example, dialogs and forms are now part of the program code), these formats now may include only strings, files and generic serializable objects.

Why to use a resource file?

  • Because output text (legible by the user) inside your source files, is "mixed" with the source code. Finding a specific string inside a huge source file can be very tedious and time consuming. Suppose you want to do a spell check, you'd have to find every string in the source and then correct them. If you use resource files, all your strings are stored in a single place (table), making corrections and translation very much easier and faster.
  • Reduce file size by storing repeated strings and objects only once.
  • Because files get packed and the distribution of your software is more efficient. Otherwise when you distribute your software, you have to make sure that every file is available and in the right path. Also if you don't use resource files you'll probably have to distribute hundred of files along with your main executable and libraries, filling your hardrive or file system with files and entries.
  • Because resource files help developers to create applications with multilanguage support. Resources are localized with a specific culture building translated versions of the program.
  • Because resource files secure your data in a very low manner by embedding it with satellite libraries and executables. And protect web content from direct download.
  • Because file access is much faster:

What's ResMagik? ResMagik is a very simple, easy to use and open source command line tool for compiling Microsoft .NET '.resources' files. Technically, is nothing more than a external interface to the .NET libraries with extended functionality. It's designed for neutral culture resources (yet). More about ResMagik and me here.

License

ResMagik is free software, this means you can use and distribute ResMagik and its source code under the terms available in the GNU General Public License version 2. A copy of the GPL license is included in the distribution. You can also read it with the command ResMagik -l.

<DISCLAIMER>

Please note that ResMagik is provided AS IS (with all possible faults) and comes with no warranty. I (Heinz Traub) am not responsible for binary files generated by ResMagik and content (text and files) inside them. You (ResMagik user) are complete responsible for negative results due to incorrect usage of your resource files (virus & malware packaging). If you included copyrighted text or files protected by a copyright, patent or license inside a resource file generated by ResMagik, that's absolutely your responsibility. By using ResMagik or creating a resource file with it means you're in agreement with the terms of this disclaimer.

</DISCLAIMER>

You can also read this disclaimer with the command ResMagik -i.

Download

ResMagik can be downloaded only from SourceForge.net's download system. If you wish to be able to download ResMagik from your website please use a direct link to the file from SourceForge.net's download servers.

 

Version 1.0 (16/07/2007).

The source code is also available for download but it's included in a different package. Go to the download page at SourceForge.net here and select for download the file "ResMagik-1.0-src.zip".

Installation

As a prerequisite for running ResMagik you need Microsoft .NET Framework 2.0 Runtime Libraries which can be downloaded here.

ResMagik comes packaged in a single ZIP file. You only need to unzip the file with your preferred program in any folder you want and that's it. No external files or registry entries are required for installation or use (clean install).

The package should contain the following files.

  • ResMagik.exe (Main program file)
  • gpl.txt (License)
  • readme.txt (Please open this one first)
  • list.txt (Sample list file for your common use, rename it and edit as you like)
  • template.bat (Sample batch file for your common use, rename it and edit as you like)

A good idea could be to include ResMagik's path into the global variable PATH. By doing this you can call ResMagik from any working directory.

Usage

This section will explain in full detail how ResMagik works and how to use it. A few examples are listed in the Examples section below just in case you didn't understood or want to learn directly from implementation. If you read only the explanation i recommend to take a look at the examples too because they give useful tips and have downloadable C# source code and precompiled binaries with example programs that make use of resource files.

In order to create a resource file you need of course external resources. ResMagik retrieves external resources information from a list, this list contains resource declarations such as strings (id & value), file locations and directories. The list is a physical file in plain text format with ANSI or UTF-8 encoding and whatever extension you want. More about the list later, we'll now start from the beginning.

ResMagik is a flexible tool, it takes certain parameters as instructions to perform specific task for specific resources. In order to compile a resource file we must tell ResMagik what to do by passing parameters. Parameters are string values separated by a white space character and are passed by calling ResMagik's executable followed by the strings.

 

Parameters example
ResMagik.exe -cvx MyList.txt MyResourceFile
In this example the three colored strings are parameters.

Usage > Options

Ok, i know what a parameter is but, what parameters should i pass and how do i use them? ResMagik takes at least 3 parameters (see example above. Links to each parameter explanation: 1 2 3) and they must be in the correct order, a fourth parameter or more will be ignored, passing less than 3 will show the help screen: The first parameter is reserved for a set of special instructions called 'options'. This parameter tells ResMagik what to do. It must be present, it must start with the character '-' (ASCII code 0x2D) and it must contain at least one character *. Each character of this parameter is an option and it represents a specific instruction, characters are case sensitive. Options are divided into 3 categories:

  1. Environment options: These options modify internal flags to be used by ResMagik and affect the behavior of the program and final results.
  2. Command options: Most important options available. These are the ones who tells ResMagik which action should perform: Compile, help, etc...If two or more command options are present only the first one is considered.
  3. List options: These options may be added inside the list at the beginning of a resource declaration and affects to that specific resource. List options must start with the character '-', this means that a resource declaration can't start with the character '-' or it will be considered an option (character is reserved).

* Remark: The first parameter must contain at least one character and it must be a command option.

Check the table below for a full list of all available options:

Option table
Character Type Description
c Command Compile a resource file. Most used one.
e Environment Do not output error messages. Errors are thrown when a resource coudn't be added. If a resource throws an error, the program will continue with next resource in the list.
h Command Call a help screen showing all available options and usage.
i Command Show disclaimer. Please read before use.
l Command Show distribution and usage terms available in the license.
n List Allow use of reserved characters. Useful if you want to start a resource's id with the character '-' or ';'. Technically this option does nothing to the program behavior.
p List Force the declaration to be a path (file or directory). This option is useful if the path contains the reserved character '=' used to recognize strings.
r List Make path relative to working directory *. Applies to partial paths. By default partial paths are relative to the list, if the specified path couldn't be found then make the path relative to the working directory. This option reverts the search, it first looks for an available path relative to the working directory and if it fails it makes the path relative to the list.

This option is useful if you have 2 files with the same name and extension but the path of one file relative to the list is the same for the other file relative to the working directory and in the declaration you are referring to the second.

Example:

File 1 = C:\folder1\folder2\........\folder100\mydoc.pdf
File 2 = C:\folder1\mydoc.pdf (We're referring to this one).
List = C:\folder1\folder2\........\folder100\mylist.txt
Working Directory = C:\folder1\

The resource declaration in the list for file 1 would be "mydoc.pdf" but if you want to add file 2 the declaration would be "-r mydoc.pdf".

This is useful too if for a file, the path relative to the working directory is shorter to write than the path relative to the list.

s List Search for files in subfolders. Applies to folders and paths with a search pattern (*.pdf).
v Environment Verbose mode. Prints detailed information about the process.
x Environment Add the extension '.resources' to the output file if it's not specified.

* Working Directory: Directory from where ResMagik is called.

Ok, i read the whole introduction to options, what's next? Well, we now give the first step by passing the first parameter which is a command option and a few environment options:

 

Example
ResMagik.exe -cvx
We add the command option 'c' to compile a resource file. The other options are not a requirement.

If you add an invalid option or don't add a command option, the help screen will be shown.

Usage > List

You said we needed al least 3 parameters, where's the second? The second parameter is nothing more than the list's path. The path is either absolute or partial (relative to the working directory), it doesn't need to start with a '-' character, that's for identifying options only. So, lets add the second parameter to our previously example:

 

Example
ResMagik.exe -cvx MyList.txt
In this case the list's path is in the working directory.

OBSERVATION: When calling an executable file with multiple parameters, they must be separated by white spaces right? Then, What if you want to pass a parameter, a path for example that has white spaces in it?: C:\Program files\my folder\myfile.txt. Here we are passing one parameter with 2 white spaces in it. So, the program will recognize 3 parameters and that's an unwanted result. What to do to solve this issue? Replace all white spaces with the character '?'. Our example would end like this: C:\Program?files\my?folder\myfile.txt. ResMagik will then replace back '?' characters with white spaces and will continue with the program flow normally.

We have successfully declared the list to be used but, it must exist or an error will be throw. I'll now explain how to create a list and add resources to it.

Create a text file in plain text format with Notepad or whatever text editor you want. The file must be in ANSI or UTF-8 encoding. Choose the name and extension you prefer and save the file in any location. That's enough and our list is ready, now, lets add resources to it.

Usage > Adding Resources

There're 2 types of resources: Strings and files. Strings are just text strings used by your application for output. Files are external resources used by your application such as icons, images, sounds, videos and binary files of any kind for multiple purposes. Each resource is added (declared) by writing a line in the list with a few information related to the resource, each line in the list represents a resource. Special characters may be used such as ';' which comments a line if it starts with this character (comments are skipped), also you can start a line with '-' for adding options for that resource (we'll cover this topic later). We now refer to a line in the list as a "resource declaration". Every resource (strings and files) inside a resource file has an identifier (id), this identifier is used inside your program code to call (use) a specific resource. Identifiers are unique, trying to add 2 different resources with the same id will throw an error at the second resource. Resources in the Microsoft .NET platform are stored with the type or class they are, this helps the .NET libraries and 3rd party software to easily identify resources and tells how to work with them, ResMagik automatically generates this field by the following criteria:

 

Resource Class
String / File Classes

Strings

System.String
Files: ico System.Drawing.Icon
Files: bmp, gif, jpg, jpeg, png System.Drawing.Bitmap
All other file extensions not listed hereare treated as System.Byte[].

More extensions may be added in future versions.

Because strings and files are declared in a different manner, we'll cover both cases:

Usage > Adding Resources > Adding Strings

Strings are declared by writing the id and the text separated by the character '='. The id must contain at least one character, it can contain white spaces. The text is the actual value of the string, it can be whatever you want (no character restrictions), it can be null and it can contain character literals (output format will vary on your implementation). As you might already read, you can add list options before declaring a resource. For strings this isn't the case, strings don't support options. Do not add options for a string declaration because they will be ignored and do not start a string declaration with the character '-' because it will be recognized as an option.

 

String declaration
str1=Hello World
str2= Hello = "ResMagik" World
str3=
a b c str4=; Hello
;str5=Hello World
-r ;str6=Hello World
Value for str1 is Hello World, str2 is  Hello = "ResMagik" World , str3 is null, a b c str4 is ; Hello, ;str5 isn't a resource because the line is commented and ;str6 is also commented (-r is ignored).

In conclusion, all text to the left from the first '=' is the id and the text to the right is the value. ResMagik looks for the character "=" to recognize the declaration as a string, so this character is reserved specially for strings and if you're trying to declare a file that contains "=" it will be recognized as a string, the list option 'p' is used in cases like this but it will be covered next (Adding Files). If you want a string id to start with '-' or ';', a good technique is to start the declaration with the list option 'n' because this option was specially made for these cases, the rest of the options will be ignored except for 'p' so please don't use it if you wish to declare a string:

 

Example
-n -str1=Hello World
-np -str1=Hello World
Result: -str1=Hello World. The first '-' is ignored because it's considered an option. CAUTION: The second case will look for a file or folder called -str1=Hello World because of the 'p'.

If you want to add strings with special international characters then make sure you save your list file with UTF-8 encoding.

Usage > Adding Resources > Adding Files

When you add a file, the name is used as the id (it includes the extension if it's present). File declarations support options, so make sure you use an existing option, adding an invalid option will cause an error to be thrown . Use the option 'n ' if the declaration starts with a reserved character ('-' or ';').

There're three ways for adding files (files can be of any extension you want): The first one is to declare the file's path and that's it. The path can be absolute or partial. Remember that by default, partial paths are relative to the list, if the path couldn't be found then the path is relative to the working directory. Use the list option 'r' to revert the search order and make first the path relative to the working directory.

 

Example
C:\My Documents\Misc\file1.dat
Misc\file2.exe
-r file3.doc
file4.zip
../file5.dat
Line 1 is an absolute path, line 2 is relative to the list located in "C:\My Documents" and finally line 3 is relative to the working directory which is "C:\My Documents\Misc". Alternatively in line 3 the declaration could be "Misc\file3.doc" (in this case the path is relative to the list). Line 4 and 5 are random examples.

The second way is able to add multiple files at a time by adding a search pattern to the paths declared. Search patterns are valid only if the character '*' is present in the name or extension of the file. Multiple wildcards may be used.

 

Example
C:\My Documents\Misc\file1.*
-s Misc\file*.*
*.*
..\*le.p*
-rs ..\f*e.doc
All examples will add files that match the search pattern, those containing the option 's' will search in subdirectories too.

And the third way is the most suitable one for adding files. It consist in declaring a folder and all files inside the folder will be added. This is the recommended method for adding files because you can add all your desired files with only one declaration while having all your files in one folder all well organized. You can also include the option 's' to add all files in subfolders too (useful if you want to organize your files by categories).

 

Example
C:\My Documents\Misc
My Folder
..\
..\folder1\folder2
-sr folderx\
Folders may or may not contain a trailing path separator '\'.

OBSERVATION: If you add a path, for example "C:\my folder\myfile.bin". ResMagik will first try to find a file named "myfile.bin" in the folder "C:\my folder", if the file couldn't be found then it will try to find an existing folder called "C:\my folder\myfile.bin". If neither a file or a directory is found then an error will be thrown.

OK, that's all about adding resources. Where were we?

Ah, yes. Finally, where's the third and last parameter? The third parameter is the name of the output file (THE resource file), in fact it's the name or path of the desired resource file. Again, the path may be absolute (aka full path) or partial relative to the working directory. Files should contain the extension ".resources". You can also specify only the name without extension and call ResMagik with the option 'x' for automatically adding the extension for you. Valid examples are:

 

Example
myfile.resources
C:\src\res\english-res.resources
test\images.resources
..\folder\globalres.resources
file
Last example uses option 'x' and produces a file called "file.resources".

OBSERVATION: As with the list parameter, if the path specified contains whites paces, you should replace them with the character '?' in order to be recognized as one parameter. ResMagik will then replace them back to whitespaces.

"That's all folks". I hope at least you get an idea what resource files are, how important they are for a good quality programming and how to create them. Feedback would be much appreciated.

Thanks man, it's all clear to me but, how do i use them in my source code? If you're not already tired of reading then keep reading the examples section. Examples explain how to read resource files with .NET libraries and show also one of the most important features of resource files: Embedding a resource file with an executable or library file.

Examples

ResMagik is a command line tool, this means you must run it from a command prompt. Fortunately, you may run ResMagik from a batch file making repetitive tasks much easier. You can use the same batch file used to compile your application. By doing this, your resources get refreshed every time you recompile your program. Creating a batch file is easy: Just create a text file with Notepad or the text editor of your choice and save it with the extension ".bat". Now edit this file and add all the commands you'd usually use in a command prompt (one command per line), save the file and close it. Now open it by clicking/double clicking the batch file (type its name if you're in a command prompt and press enter) and now all commands inside the batch file will start to execute in the order they were written. The following examples include calling commands to ResMagik, you could insert these commands in a batch file.

I uploaded the following examples just for you to learn from code. Please study the code because i don't want to go into much detail about C# code and .NET libs (that's beyond the scope of this documentation). Check also the batch file that compiles the program and calls ResMagik to create the resource file (that's the primary goal). Finally take a look at the list file to understand a working example, select ids from the list and trace them in the source code, with this you'll learn how to bind your code with a specific resource. A lots of things can be done when you mix resources and code, i just put in the basics for resource output.

Example 1: Resources in console applications.

example1.zip (5 KB) Source & Executable

Instructions: To compile this example register the C# compiler in the global variable PATH then install ResMagik in the same folder you extracted the example. The precompiled binary is in the bin\ folder, to execute this example open the batch file Run.bat.

Example 2: Resources in Winforms applications.

example2.zip (72 KB) Source & Executable

Instructions: To compile this example register the C# compiler in the global variable PATH then install ResMagik in the same folder you extracted the example. The precompiled binary is in the bin\ folder.

Example 3: Multilanguage application with manual culture setting.

[Not Available]

Example 4: Multilanguage application with automatic culture detection.

[Not Available]

Example 5: Resources in dynamic web pages.

[Not Available]

Troubleshooting

As mentioned before: Errors are thrown when a resource coudn't be added. If a resource throws an error, the program will continue with next resource in the list.

Errors will output a short description of the fault within the line number in the list. Try reading the messages and correct the list.


Take me up to the index.

ResMagik...we love you!