2. Configuration File and Probing
The application configuration file can be used to alter the search path. The
configuration file contains XML and can only be associated with a process
assembly. It is named after the process and has the extension
.config (ASP.NET is
an exception to these rules). The runtime will read some of the sections in a
configuration file automatically, whereas other sections are only read when you
specifically request it in your code. When a section is read the runtime will
first read the corresponding section in the
machine.config file and then read
the section in the application's configuration file. The two sections are merged
with the values in the application's configuration file overriding any values in
The XML in the section is then converted to a configuration object by a handler, and the object is cached in memory. When code requests configuration data their request is passed to the handler object. This means that the configuration file is read just once for a particular section, and all subsequent requests for the same section will be passed to the configuration object in the cache, so any changes to the configuration file will not be picked up by the application. Note that there is a cache for each application domain, so if you create a new application domain the configuration file will be re-read.
In this section we will examine the sections in the configuration file that are used to alter how Fusion locates assemblies. Use the process and version 1.0 of the library from the previous section.
2.1 Customizing the Private Path
When you install .NET on a machine the configuration utility will be installed in the Administration Tools folder in the Control Panel. This tool can be used to edit the configuration file for a process assembly. When you start the configuration tool it will not know about your application, so you will have to tell it what application to configure.
Start the configuration utility from Administration Tools folder in the
Control Panel. In the left hand panel there is an entry called Applications,
select this and from the list of tasks select Add an Application to Configure.
You will see a dialog similar to the one shown above. This shows
a list of configured applications that have run recently, you'll see where this
information is located later on in this workshop. Since our test application is
not in this list click on the Other button and navigate to the folder where the
test process is located. Note that the search dialog shows both library and
process assemblies, but it is only applicable for process assemblies. Select the
.NET Version 3.0|
The configuration tool has changed in version 3.0/2.0 of the framework. The most immediate change is that in the left hand pane you'll see a note beneath My Computer called .NET Framework 2.0 Configuration and beneath this are the nodes for security, remoting and configuration. Screeneshot.
The assembly will be listed under the Applications node. If you click on the Assembly Dependencies node you'll see a list of the assemblies that the process uses (you may have to select the View Assembly Dependencies link in the right hand page). The tool obtains this list by reading the application's manifest.
can use this tool to alter the search path that Fusion uses to find the private
assemblies that your process uses. To do this, right click on the
node and select the Properties item.
This dialog lists information about the assembly, its location and version. The item that we are interested in is at the bottom Relative search path or additional assemblies. This is a semicolon separated list of folders in the application folder where Fusion will look for private assemblies.
In the edit box type
bin;bin2 and click on the OK button. Now
create a folder called
bin and move
lib.dll to this
move lib.dll bin). Run the process and confirm that Fusion
is now using the private path in the configuration file. If you wish, you can
also create a folder called
bin2, move the library there and
confirm that Fusion is checking that folder too.
Now take a look at the application folder. You'll see that the configuration
tool created a file called
app.exe.config. It looks like this:
<gcConcurrent enabled="true" />
<publisherPolicy apply="yes" />
<probing privatePath="bin;bin2" />
<gcConcurrent> node indicates that a separate thread is used by the garbage
enabled="true" is the default); the
<publisherPolicy> node indicates
that the versions of the assemblies used by the process will be subject to
separate rules given in a publisher policy file, a process that will be
described later in this workshop. The entry that we are interested in is the
This node contains information about the general location of assemblies and
(as you'll see later) it contains information about specific assemblies. In
general, you should edit this file using the configuration tool because if you
change it by hand you are likely to make mistakes. For example, the
attribute is important, if you omit it then you will not be able to alter the
<assemblyBinding> can also have an optional attribute called
appliesTo which indicates the version of the runtime that the information
applies to (for example
appliesTo="v1.0.3505"), if you omit this then the
settings apply to all versions of the runtime. The
privatePath is useful for applications that have many private assemblies
and you prefer to keep the libraries in a separate folder. Note that the folder
must be a subfolder of the application's folder.
Now remove path from the
<probing> node from the configuration file using the
configuration tool by removing the paths from the Relative search path box.
2.2 Customizing Codebase
You can use the configuration file to identify an absolute path to the file. For now, this path must be under the application folder, although you will be able to change this later. You will use the configuration tool to add the appropriate values. Right click on the Configured Assemblies node under your application's node and select Add.
This dialog gives you three ways to select the library assembly that you want to configure. By default this dialog will have the second option, Choose an assembly from the assembly cache, selected. This will allow you to select an assembly from the assemblies installed in the Global Assembly Cache which are usually system assemblies but, as you'll learn later, you can also put your assemblies in the GAC.
For this example, you are going to configure a private assembly, and there are two ways that you can do this. The first way is to use the third option on this page, Enter the assembly information manually. This is the least useful of the three options because you have to know specific information about the assembly, for example the second piece of assembly information, Public key token, is an eight byte number that is difficult to remember. Since you are unlikely to know such information we will use the second method of selecting a private assembly. This is the first option in the list, Choose an assembly from the list of assemblies this application uses.
Select the first option in this list and click on the Choose Assembly button. You will be shown a dialog with a list of the libraries used by the process, a list gleaned from the process's manifest.
this dialog select the
lib entry and click on the Select button.
click on the Finish button of the Configure an Assembly dialog.
Once you have done this, you have 'configured' the library. For this first time
the tool will give you a properties dialog to change the assembly configuration.
In the future when you want to change the configuration for this library you can click
on the Configured
Assemblies node under your process's node, right click on the library and
then select Properties.
|I have to stress at this point that the configuration that you are performing is for the application. You can see this because you have selected the Configured Assemblies node under the application node. Although you are specifying settings for libraries, they are only applicable when the library is used in this application. If you use the same library (shared, or as a private assembly) it will not use the settings you have specified here.|
you have configured the library you will see a dialog with its configuration
settings. Click on the Codebases tab and in the list view control type
126.96.36.199 in the Requested Version and
in the URI column. Here,
TestFolder is the application folder. Note
that the drive letter must be uppercase. The path is the absolute path to the
library, but this path must be to a folder under the application folder. Now
create a new subfolder called
md bin3) and move
the library there (
move bin/lib.dll bin3). Run the application
and confirm that the library has been loaded from the new folder.
|Note that you are not specifying a search folder, instead, you are specifying an absolute path to the actual assembly. If you get a probing error check that you have given the exact path including the assembly name.|
Open the configuration file. You'll see that the configuration tool has added
a new node to the
<assemblyIdentity name="lib" />
<dependentAssembly> node must have exactly one
<codeBase> node has a version attribute but this is
ignored if the assembly does not have a strong name, indeed, you can use notepad
to edit this file and remove the version attribute and the library will still be
loaded using the absolute path. (However, note that the configuration tool will
not allow you to enter a codeBase without a version.)
|I hope that you enjoy this tutorial and value the knowledge that you will gain from it. I am always pleased to hear from people who use this tutorial (contact me). If you find this tutorial useful then please also email your comments to firstname.lastname@example.org.|
If you see an error on this page, please contact me and I will fix the problem.