Welcome to the NAR Loader Project
Maybe some of you know the concept of JAR archives from Java. A lot of things
from Java have found their way to the Dot Net world. Having the same functionality
for Dot Net would be a nice feature. Since Dot Net 2, Microsoft has included some
very interesting features in the CLR and the framework. These features makes it
possible to create the functionality needed to handle archives for Dot Net -
called NAR archives. The loader works only with .Net 2.x. .Net 1.x is not supported.
Mono will be tested when the windows version is stable.
Additional infos about the NAR loader can be found in this
XCOPY deployment was yesterday,
today we have single file deployment!
Table of contents
The latest stable version is 1.2 as of October 2006.
|1.2||2006.10.26||binaries||source||password & AES encryption support, archive comments|
|1.1||2006.08.17||binaries||source||self running archive support|
|1.0||2005.03.03||binaries||source||First public release - no longer available|
Un- / Installation
To install the loader, copy the executable NARLoader.exe to a place of your
choice on your harddisk and start it with:
Optionally you can
NARLoader.exe -d -i
to install the loader. This enables debug mode. In debug mode you can watch
debug messages of the loader in a separate console window while the loader
runs an application. To disable debug mode just install the loader again without
the -d parameter.
To uninstall the loader just start it with the -u parameter. This removes the .nar
file extension mapping and the NARLoader CAS CodeGroup from your system.
After installation you can start your .nar archives by entering their
names on the command line like:
NARLoader.exe MyApp.nar param1 param2 ...
(Everything after the archivename is used as command line arguments for the application
inside the archive). It's not necessarry to specify NARLoader.exe so:
MyApp.nar param1 param2 ...
would be enough.
Another way to start your archives is just double clicking them.
The loader uses the following command line parameters.
NARLoader [-d] [-p Password] Archive
- -d Turns debugging on
Turns debugging on which means that you will see a console
window while your application is running where you can see whats going on
behind the scenes.
- -p Password
The password for a encrypted archive can be specified with this parameter.
If no password is specified and an encrypted archive is used a dialog
is displayed for entering the password.
Install / Uninstall
NARLoader [-d] -i | -u
- -i Installs the loader
so that files with .nar extension are
seamless integrated into the OS. You can double click .nar files or
start .nar archives from the command line.
- -u Uninstalls the .nar handling
This is the opposite of the -i parameter.
Creation of self running archives
NARLoader [-d] [-c SelfRunningName] [-I IconFileName] [-p Password] -d Archive
- -c Creates a self running archive
This creates a stand alone .exe archive which does not need the loader.
When used with the -d parameter the self running archive starts in
debug mode. When a self running archive is run on a machine where the
NARLoader is not installed a "silent install" is done the first time
such an archive is run on this machine. This "silent install" only
creates the necessary CAS code goup - no .nar file mapping is
installed. If NARLoader was already installed on the machine
(using the -i parameter nothing is installed by the self
If you use a encrypted archive for your self running archive it is possible
to embed the password inside the self running archive in encrypted form. Thus
it is possible to create a strong AES encrypted archive without the need for
the user to enter a password. This can be used as a form of obfuscator for
your applications assemblies.
- -o EXEFile - is used in conjunction with -c to specify
the name of the self running archive. If this is omitted the
original archivename with appended .exe is used.
- -I IconFile - also used in conjunction with -c to specify
the name of an Icon for the self running exe. This can either be
the name of an .ico file or of a .exe or .dll file. When a .exe
or .dll file is used the first Icon from this file is used. The
Icon of a self running archive can also be specified in the archives
manifest file. In this case the Icon must reside inside the archive
again as .ico, .exe or .dll file. The -I command line parameter
overrules the Icon parameter in the manifest. If both Icon parameters
are missing or the given Icon files could not be processed for any
reason the standard NARLoader Icon is used for the self running archive.
Help & Version information
NARLoader [-d] -v | -h
- -v Shows version information
- -h Shows a short help about command line parameters.
Starts the application inside the archive Test.nar
NARLoader.exe -d Test.nar
Same as above but with debugging enabled
NARLoader.exe -d -i
Installs the loader to handle .nar files automatically
The opposite from the above
NARLoader.exe -d -I World.ico -O World.exe -c NARTest.nar
Creates a self running archive World.exe with Icon World.ico from the archive
NARTest.nar. The Icon parameter from the archives manifest is ignored.
How to create an archive
This is really simple! Just take your favourite ZIP utility (like WinZip) and
pack your applications base directory. Name the archive like your EXE's name
and replace .exe with .nar. That's it. You can do more with a so called manifest
file. It must be named like your archive with extension .manifest. It's basically
a simple XML file where you can specify which assembly should be the start assembly
and which app.config file should be used.
Here is the testproject included in the loader distribution shown with
It consists of the main .exe assembly NARTest, an assembly NARTestDLL1 in the
application directory and NARTestDLL2 in the testdir subdirectory as well as some
sattelite assemblies with localized strings and a multifile assembly with three modules.
Included in this archive is the manifest NARTest.nar.manifest:
<?xml version="1.0" encoding="utf-8"?>
specifies which assembly to load
the entrypoint (Main) of which type should be called
which app.config file should be used
Anything other than 0 allows the display of archive comments (if any). Archive comments
are standard zip archive comments. See your zip utility for how to create them.
Used when creating self running archives. Specifies a .ico, .exe or .dll file
which icon should be used for the self running archive .exe file. The given
.ico, .exe or .dll file must reside inside the archive. It can be overriden
by the -I command line parameter.
You can have many different manifest files within an archive. They are used depending on the
name of the archive. If there is no manifest file in the archive or if there is a
manifest file but some parameters like Assembly or AppConfig are
missing (or empty) in the manifest then the name of the archive is taken instead. So for
example if there is no manifest and the archive is named Test.nar then the
startassembly is Test, the type is Test.Program and the configfile is
Test.exe.config. Id does not matter if the assemblyname is fully qualified or not.
Probing is the same as on the local filesystem.
See here for more information's about probing.
If an archive contains a comment (zip file comment) it is displayed a applicationstartup if
the ShowComment manifest parameter is set. This feature can be used to display license
The loader supports encrypted archives based on standard, weak ZIP encryption but also
based on strong 128, 192 and 255 bit AES encryption. As the weak ZIP encryption is standardized
every ZIP utility supporting it can be used when creating archives. AES support was
tested with WinZip
Version 10 in 128 and 255 bit mode
and not every zip utility supporting AES might work.
Every file in an archive can (theoretically) be encrypted using a different password
(if the used zip utility supports this). Every time the loader accesses a encrypted
file inside the archive it looks if a password was entered (either using the -p
command line parameter or the password dialog). If no password is available the user
is prompted with the password dialog until the correct password was entered or the
dialog was aborted. In case of an abort the loader cancels any further activities and
the application is terminated. If the correct password was entered it will be used
for any further archive access as long as it is correct for the current access. If
the password is wrong the password dialog is displayed again.
How it works
The loader uses the new version 2.x hosting interfaces to provide an assembly store
which is the .nar archive. The loader tries to mimic the same behaviour when
resolving assemblies as the default loader does. So your application should
normally see no difference running under the .nar loader compared to running
under the standard loader. During installation the loader creates a file
association for the .nar file extension and creates a CAS CodeGroup called
What it [ is | can | does ]
- The NAR Loader is a single hybrid executable consisting of a managed and
an unmanaged part (contained in a single executable).
- You can use the -i or -d[il] command line parameter to install the loader to
handle .nar files automatically. This means you can start your archives by just
double-clicking on it or by just entering the archive name on the command line.
- You can use command line arguments with NAR archives. Everything following the
archive name is handed over to the application in the archive as command line
- You can use subdirectories inside the archive the same way as you would
in the real filesystem (binPath probing)
- The loader may create a small temporary file in the users temp directory. This
will be changed in one of the next version. This temporary file represents the app.config
file. Unlike assemblies it is not possible to bring the content of the app.config
file into the CLR from unmanaged code without using a file. This temp file is deleted
when the application exits. SetConfigBytes seems not to work as expected.
- The ApplicationBase for the application inside the archive is set to the directory
in which the archive is.
- Every resolve step first checks the physical directory in which the archive is
for the requested assembly or app.config file. If it is found the native file on the
disk is used instead of the file in the archive. This is by design. In this way you can
simply update your application in the archive by just copying the needed files besides
the archive without the need to repackage the archive. Later version may expand this
mechanism about security (only files with given security attributes will be considered)
and autoupdate of the archive (files will be automatically merged into the archive and
deleted on disk afterwards so that you always have only one archive)
What it [ is | can | does ] NOT
- It is not a replacement for multimodule assemblies (although you can use multimodule
assemblies inside .nar archives)
- It does not extract the archive content to some place on your disk and starts
the application from there. Instead when an assembly is requested from the archive
all handling is done in memory without write disk access.
- It does not read the whole archive into memory and holds it there. Even
when your archive is 10Gb in size only the things needed from the archive are
loaded into memory and only when they are needed.
- For the moment the loader can not provide application data like text or database
files the application will read from inside the archive. They must be in the
normal filesystem like without the loader. But in one of the next versions of the loader
there meight be a sollution for keeping application data files within the archive and
give the application read/write access to these data. Thus providing a way to have
application binaries and application data within a single entity: a .nar archive.
Nobody is perfect
The loader is primary a design study about CLR hosting. Nevertheless I've done
my best to track and kill most bugs and problems. In case you find one of the
remaining bugs or want to tell me what you think about the loader just drop me a line
Running the NAR Loader under Windows Vista
The NAR Loader and NAR Loader self executable archives work under Windows Vista.
But for the installation one point should be noted: ensure that the loader
executable has the "Require Administrator Privileges" set and click Allow
you are asked if you would like to continue. The loader contains a manifest resource
which ensures this but in case something goes wrong check this. This procedure is also
true for self executable archives if no loader is installed. If the loader is already
installed this flag is not needed for self running executables.
Known issues, FAQ, Help
The following issues are known and maybe (or not) changed in one of the
next versions, the following questions where asked by others:
- The binary package of the loader contains two test archives: NARTest.nar and NARTestP.nar.
NARTestP.nar is a password protected archive. The password for this archive is TopSecret! . So you can test
the password and protection features of the loader.
- app.config must be physical on disk for ConfigurationManager to work correct.
- Loading multifile assemblies sometimes crashes the loader - reason unknown - has to be fixed
- The loader needs a security.config file where it can add it's CAS code group during install.
If there is no security.config but only a security.config.cch you can create one by just starting
Control Panel/Administrative Tools/Microsoft .NET Framework 2.0 Configuration
mscorcfg.msc from your DotNet SDK's bin directory
and closing if without any further action. After this you should have a security.config and
can install the loader.
Another way to create a security.config is to run CasPol.exe:
CasPol.exe -all -reset
This are ideas which might be usefull and possibly integrated in one
of the next versions of the loader.
- Extend the functionality of the privatePath configuration option to
probe for assemblies in other .nar archives (aka. linked .nar archives)
- Application data inside archives with transparent acces to the application
inside the archive see here
The following links maybe usefull to learn more about CLR hosting, assembly packing, deployment
and other projects or products
THIS SITE INCLUDING ALL ITS CONTENT (TEXT, PICTURES, BINARIES ETC.) IS NOT
ALLOWED TO BE USED IN CRIMINAL, ILLEGAL ACTIVITIES! THE PURPOSE OF THIS SITE
IS TO DESCRIBE THE SOFTWARE "NAR Loader" WHICH STARTS APPLICATIONS OUT OF
ARCHIVE FILES. I AM IN NO WAY RESPONSIBLE FOR ANY EXTERNAL CONTENT POINTED TO
FROM THIS SITE. USE THIS SITE AND ALL OF ITS CONTENT AT YOUR OWN RISK!
BY USING THIS SITE AND ITS CONTENT YOU HAVE ACCEPTED THIS DISCLAIMER.
||The content of this Page is under