Assemblies: locating, binding and deploying

How to plan, up front, for service packs, upgrades and hot fixes as they come along.

Introduction

This article describes how the CLR locates and binds assemblies and how to change the default behavior when needed (e.g. in the deployment stage).

Any developer and system administrator who deals with .NET assemblies, especially commercial applications, must be familiar with these topics. This knowledge is the best way to plan for service packs, upgrades and hot fixes as they come along.

The .NET Framework is loaded (almost inflated) with a bunch of terms and features related to assembly deployment, locating and binding.

Here is a short list:

Static and dynamic loading

Public and private

GAC and private folder

Probing

Codebase

BindingRedirect

App.Config and Machine.config

Strongly named and weakly named

DevelopmentMode

Audience

The article is not at the beginner level, readers with basic knowledge in configuration files and assembly structure can also benefit from it right in the first reading.

The quest for type resolving

The CLR – Common Language Runtime – is responsible for the process of locating and binding referenced assemblies. Locating is the process of finding the correct assembly in the hard disk. Binding is the process of loading the assembly in the application address space.

The quest begins when the JIT encounters user defined types that need to be resolved. Then the CLR tries to detect where the type definition is:

Same file in the same assembly

Different file in the same assembly

Different assembly

This article deals with the third option.

General process blocks

The CLR moves from stage to stage, as described above, in order to determine the exact assembly to load. The reason for this flow is that each stage might override the information in the previous stage. Although, it might look like a cry out redundancy it is really necessary, because of the need to make changes in the deployment files after installation. For example, when installing a Service Pack, the system administrator would like to keep the previous installation up and running. This need requires changes in the locating and the binding process of new assemblies with new versions.

1) Search for referenced assembly upon name and version

Configuration File - App.config

The CLR checks the App.config after the manifest check. In case the referenced assembly version is overridden the App.config setting has the upper hand.

Publisher policy file

The CLR checks for the publisher policy file after the App.config check. Publisher policy files are deployed as part of an update, hot fix or service pack. A publisher policy file is used when the updated shared/public assembly has a new version (that it is different from the assembly's manifest). The setting in the publisher policy file has the upper hand unless the App.config file sets the safe mode (<PUBLISHERPOLICY apply= "no">).

Machine configuration file

The CLR checks in the machine.config file after the publisher policy file check. The file is shared by all .NET applications on the machine. In case of a version difference, the setting in the Machine.config has the upper hand.

2) Checking for previously referenced assemblies

The CLR checks if the assembly is already loaded (due to previous code execution statements). If found the CLR uses it. At first it looks like the fox in Redmond has a design bug - why not checking the assembly in the previous loaded assembly list in the first stage? The reason for that is the need to examine first which version is required.

3) Check in the GAC (Global Assembly Cache)

If not found in stage 2 and the manifest implies that the assembly is strongly named, the CLR checks the GAC. If exists, the GAC has the upper hand.

4) Codebase or Probing

The prior stages inform the CLR what is the required assembly version. In this stage, the CLR attempts to find and load the assembly.

Codebase

If the Codebase tag is defined in the application configuration file, the CLR checks only the defined location. If the assembly is not in the given URL, the probing process is terminated.

Probing

In case there is no Codebase tag in the configuration file or if the attempt to retrieve the file from the URL fails, the CLR starts the Probing process.

Subdirectories

Search in the application directory and then in the subdirectories with the assembly name.

Tip: The CLR terminates the probing process as soon as the reference assembly is found (name search only). In case the assembly is correct - all is well - else the binding fails (Filenotfound exception raised).

Features and Terms

Static and Dynamic loading

In static loading, the CLR checks for assemblies in the assembly manifest. The list of statically referenced assemblies is entered to the file in the build process. In dynamic loading, the CLR is introduced to the assembly in run time. This feature is wrapped up in the System.Reflection assembly, which exposes methods like Assembly.Load (similar to the LoadLibrary function).

Private and Public/Shared assemblies

Shared assemblies are not deployed in the same directory of the application that uses them. The CLR will not complain if you do, but it is a deployment error to copy the shared assembly in one of the base application's directory and direct others to it. Typically shared assemblies are registered in the GAC or in a share directory (the application that uses them needs to know about).

Strongly and weakly named assemblies

The main difference between the two is that a strongly named assembly contains a public token. The token uniquely identifies the assembly. It is required for shared assemblies that are installed in the GAC. The reason for that is the slight chance that some developer creates an assembly with the same name, culture and version as one that happens to be installed in the same PC. Another difference (implied from the previous) is that strong name assemblies can be deployed privately and publicly (GAC) whereas weakly named assemblies can only be deployed privately.

Tip: Do not copy the assembly to the GAC folder ([windows main folder]\assembly). The assembly must be registered in the GAC. Use the GacUtil via the .NET command prompt or drag and drop the assembly to the GAC window.

Shared assembly and the GAC

A shared assembly that is copied outside the application base directory must be strongly named but is not required to be installed in the GAC. In this case the shared assembly location must be specified in the configuration file using the Codebase tag. Application suites can create a shared folder and copy the shared assemblies to it.

The following is a list of reasons that helps to decide when to use the GAC instead of a proprietary shared folder:

Third party applications might use the shared assembly. Copying the assemblies to a shared folder obligates the application that uses them to know about its location.

Side by side execution is easier when new version assemblies are installed in the GAC. It saves the time of dealing with different paths for different versions. Moreover, using proprietary, shared folders might cause DLL Hell.

Only a user who is defined in the Windows administration group can install assemblies in the GAC (security).

Shared folder is more accessible for reckless user mistakes like delete and override.

Save disk storage: this is quite a stupid reason - I know. Today, disks are very cheap, but you can not ignore the fact that copying an assembly to different locations over and over again will have some storage impact.

Probing

This is one of the two ways to define an assembly location. The instruction is done in a configuration file. You can specify only subdirectories under the application base directory (see snippet).

CodeBase

This is one of the two ways to define an assembly location. The CLR, first checks the assembly version, then searches for an override CodeBase definition in the configuration file. The version attribute is required, only, for strong named assemblies. For weakly named assemblies the href attribute must be assigned, only, to a subdirectory. This URL can refer to a directory on the user's hard disk or to a Web address. In the case of a Web address, the CLR will automatically download the file and store it in the user's download cache (a subdirectory under <Documents and Settings>\<UserName>\Local Settings\Application Data\Assembly). When referenced in the future, the CLR will load the assembly from this directory rather than access the URL. The CodeBase tag should only be defined in the machine configuration or publisher policy files that also redirect the assembly version (see snippet).

BindingRedirect

This feature enables the binding of a certain assembly to a different file version and it is very useful for service pack installations. Usually the redirect is done to a GAC registered assembly. The GAC allows us to install the same assembly with different versions. The CLR checks the configuration file and redirects the binding accordingly (see snippet).

Locating Assemblies Using DEVPATH

The DEVPATH is nice feature for the development stage. The feature eases the development life cycle by delaying the decisions in regards to the deployment stage.

The developer can create a DEVPATH environment variable that points to the build output directory for the assembly. Follow these steps to enjoy this feature:

Specify the element in the machine configuration file. Make sure you add it to the relevant framework version.

The CLR searches for the referenced assemblies in the path described in the DEVPATH environment variable.

Define an environment variable. Name: DEVPATH. Value: path. Make sure that you enter it as a system variable and that the path value is ending with \.

Tools

Fuslogvw – Assembly Binding Log Viewer

"The Assembly Binding Log Viewer displays details for failed assembly binds. This information helps you to diagnose why the .NET Framework cannot locate an assembly at run time. These failures are usually the result of an assembly deployed to the wrong location or a mismatch in version numbers or cultures. The common language runtime's failure to locate an assembly typically shows up as a TypeLoadException in your application" (MSDN)

Tip: make sure you set the HKLM\Software\Microsoft\Fusion\ForceLog registry value to 1 (the value is a DWORD).

Conclusions

The Process of loading and binding .NET assemblies is complex. Nevertheless, it is an important, inevitable, subject to know what it is going on under the scenes. The familiarity with this process is the only good way to start preparing for deployment and to answer some important questions like:

What are the configuration/overriding options?

What is the correct configuration file to use?

How to successfully install Hot Fix and Service Packs?

How to troubleshoot the FileNotFound exception?

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

I spent a while frustrated trying to figure out why it wasn't working like it clearly should. I googled and googled to no avail. I finally walked through a C# example from a site and it worked. Then after more thrasing, I tried a VB example from a book from scratch and got it to work and compared my app.config files and realized that on the code snippets, at least for me, some of the hyphens are showing up as questionmarks. This is the case for the probing example, how my browswer shows it:

assemblyBinding xmlns="urn:schemas?microsoft?com:asm.v1"

Whereas how it should be (and is on the Binding example):

assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"

Once I figured this out it worked like a charm without even needing a recompile. Hopefully if anyone else is seeing this (and is not that familair with the syntax of these files like me) this will help them not have to bang their head repeatedly against the wall

Hi,I need that all applications and assemblies that use microsoft System.Xml.dll (as a reference in their projects) on current server will not load it from GAC - instead they will load my.dll (that provides the same functionality).My.dll does not have the same strong name as microsoft's version, because I don't have microsoft's public key.What do I need to do?

I am not sure I understood you: In my case, if there is already System.Xml.dll in GAC - it will be loaded from there and will not check the <assemblyBinding section? That GAC comes prior to assemblyBinding ?

If the answer is yes, what do you think of this solution:1. I can uninstall real System.Xml.dll from GAC 2. I will place this code in machine.config (correct me please):

Anyway I guess you don’t have the code of the .Net applications on that server, otherwise you would have change the reference to your “my.dll”.

Your solution is very problematic. Doing so will create a constellation where no other .Net application will never work with the System.xml.

What you actually trying to do is to replace the use of a certain DLL with entirely different one.From my knowledge the fox in Redmond never aim for that. They thought about other stuff like: > Configuration Section Settings > Specifying an Assembly's Location > Redirecting Assembly Versions

Since you don’t have the code plus due to the fact the System.XML is a SYSTEM-Strong-Name I am afraid you will not be able to pull this out.

In any case Do not Uninstall from the GAC:Pay attention to the fact that other MS assemblies use the System.xml assembly and there for you will end up with unused .Net Framework.

You are right:1. I don't have the code on the target server - The product we develop is design to interfere with existing .net applications - when no change or even rebuild is needed.

2. Indeed we want all applications on that server to work with our dll. Actually our dll is like an envelope that wrap the real one, by loading with System.Relection.Assembly.LoadFile and exposing (and invoking) all methods and classes of the real one. but it does some interfering in some special cases.

We really need to find a solution for this. Otherwise we will have a serious business problem...

Other direction for us is to create a CLR Host. But, since it involves serious C++ native code - we wanted to check all other simplier solutions.

Hi Vladimir,Sorry for delay.Your case is really interesting.As I can see you have some options:

1.Parse the byte code of the third party assemblies and change all the references to system.xml a.This can be done statically (scan the server): find & replace operation b.This can be done dynamically if you active the third party application by CLR hosting

2. File hooking: In this scenario you should write a hooking code like dll load image in the kernel mode level. What I mean is that you intercept the load of system.xml file and replace it under the hood.

Tell my how it end,(I would like to thank Nadav Rubinstein for the information) Oren

The 1.a option is not very good for us, because as you know a real application can be updated by the developer organization many times (new features, bugs etc.).

The 1.b option is better but there could be several problems with it that should be handled - installtion process for yeach application will be harder, potential problems with remoting, different CLR host for different application types (windows host, web host - that is supposed to be harder to do, service host - etc.)

The second direction looks much more interesting. I believe that you talk about creating a process using Window API? But there can be a lot of issues with the signing security (that maybe can be handled too).

Last week, thanks to Sasha Goldshtein, I found that there is a real API that MSFT provided to perform this kind of stuff. It is called .Net CLR Profiling API. Using this API you can write native code that can will interfere in the compilation process of the DLL by JIT. At that point you can change that code to whatever you need. http://msdn.microsoft.com/msdnmag/issues/05/01/CLRProfiler/default.aspx[^]There can be some issues due to the fact that MSFT dll are NGEN'ed - but we believe that it can be handled too. This, I believe, maybe the deepest digging in the .Net, so it took me a really while just to find out about it (most of MVPs could not give me any good answers).

I will continue research on it, and if you would like I can update you too.

I have search but failed to find an intelligent solution for your needs.I thought maybe regasm have a /list argument

The only thing I can think of is that the interop dll are registered in a unique way in the registry.It is of course up to your needs but you can run (enumerate) for each and every registry key under CLSID (HKEY_CLASSES_ROOT\CLSID\<guid>\InprocServer32)and look for those who have key named Assembly

HiHow can the unmanaged dll that references the .net dll be deployed to client pc without registering in GAC?Application works only when I registered .net dll in GAc by using regasm tooldeployment .But I want a solution without GAC registration.Is it possible? What should I have to do? Regards

MS support two ways interoperability. Managed to un-managed and vise versa.

PInvoke/dllimport allows you to use un-managed code like C/C++ dll in C# code (see http://www.codeproject.com/csharp/EssentialPInvoke.asp).

Using COM dll in C# code is simple as adding a COM reference.

And now for your question: using C# code (managed) in un-managed code like C++ requires COM mediation/translation in between.If you want your C# code to be exposed to C++ code you must follow some rules (defined by MS).Those rules was defined because of this COM component that mediate between the two technologies.

When you set in the project setting that the C# dll should be Interop/expose as COM the Visual Studio will create another dll <assemplyname>.interop... (if I recall correctly). This is the COM component. Since COM component is heavily registered in the Registry the VS create GUIDs for all the expose classes and other data structures in your C# code. But before Visual Studio will do all of this for you it requires that the assembly will be strongly named.

The strong name requirements is a must, because otherwise the CLR runtime won't be able to definitively identify it.Please note there are more must to have requirements:+ must reside in the global assembly cache (GAC) or in the client application's directory.+ Any exposed .NET class that you want COM to create must provide a default constructor.

If you need to create a COM mediator and register it in the registry during deployment you can use the regasm utility:Technical Regasm - In order for a COM client to find the .NET object, you need to make the registry entries that COM requires for a client to locate a server when creating an object.Regasm comes with the .NET SDK.program reads the metadata in a .NET class and makes registry entries that point the COM client to it.

And last but not least, in case you are interested in the flow behind scenes:Flow1)CoCreateInstance 2)the registry directs the request to the registered server, Mscoree.dll.3)Mscoree.dll inspects the requested CLSID 4)reads the registry to find the .NET class 5)starts CCW that converts native COM types to their .NET equivalents—for example, BSTRs to .NET strings—and forwards them to the .NET object

In COM - Communication between OBJECT through interfaces therefore type library is required to define the types.

In .NET - Using the CLR Communication indirectly between OBJECT (the types is in the assembly meta data)

.NET Client to COM server__________________________

.NET --> RCW <-->COMInterface to ObjectsThe .NET SDK provides Runtime Callable Wrapper (RCW)which wraps the COM components and exposes it into to the .NET client application.RCW can be generated by using VS.NET or by the use of TlbImp.exe utilityBoth the ways will read the type library and uses System.Runtime.InteropServices.TypeLibConverter class to generate the RCW. This class reads the type library and converts those descriptions into a wrapper (RCW). After generating the RCW, the .NET client should import its namespace. Now the client application can call the RCW object as native calls.

COM Client to .NET assembly____________________________

COM Callable Wrapper (CCW)Objects to InterfaceCCW will be created by the .NET utility RegAsm.exe. This reads metadata of the .NET component and generates the CCW.This tool will make a registry entry for the .NET components.COM --> CCW <-->NET

- Strongly named assemblies load faster if installed in the GAC, as they have a hash computed on each load when not in the GAC.

- There is a subtle bug you can run into when using LoadFrom, for example with an array of bytes containing the assembly. The same assembly may be loaded twice into memory, once using LoadFrom and once using the other loading mechanism, and the two assemblies will not have the same identity. This means two objects seemingly of the same type, but created using one version of the assembly or the other, cannot be cast from one to another -- it is as if they are different types.

That is a nasty bug and the only way I have seen to solve it is to use strongly named assemblies.

Unfortunatelly it's not a bug. Assemblies loaded by LoadFrom/Load(byte[]) method don't have load context and therefore it is possible to load them multiple times into the same appdomain. When is assembly loaded without load context, this can possibly generate another half a dozen of problems if there are any cross-domain calls, serialization used or if those assemblies are referencing other assemblies outside of GAC. many of those problems just don't have any solution except for not using those methods for assembly loading.

If you use LoadFrom method and the assembly is also located in GAC, then framework will load the assembly from GAC in standard load context so it only looks like that strongly named assembly fixes this "feature by design".