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 machine.config file.

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.

For this example use the process and library assembly code that you developed on the last page. Compile this code.

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 assembly app.exe.

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.

You 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 app.exe 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 folder (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:

The <gcConcurrent> node indicates that a separate thread is used by the garbage collector (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 <assemblyBinding> node.

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 xmlns attribute is important, if you omit it then you will not be able to alter the probing. 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.

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.

From this dialog select the lib entry and click on the Select button. Next, 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.

When 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 1.0.0.0 in the Requested Version and file:///C:/TestFolder/bin3/lib.dll 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 bin3 (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.

Open the configuration file. You'll see that the configuration tool has added a new node to the <assemblyBinding> node:

A <dependentAssembly> node must have exactly one <assemblyIdentity> element. The <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.)

Errata

If you see an error on this page, please contact me and I will fix the problem.

Page Three