Suzanne Cook's .NET CLR Notes

Channel 9 Interview

Suzanne Cook — Sat, 12 Feb 2005 02:01:00 GMT

Charles Torre and Robert Scoble (behind the camera) dropped by my office to chat with me about the loader for MSDN's Channel 9: part I and part II.
Also, check out the PDC video I was in for Channel 9: http://channel9.msdn.com/ShowPost.aspx?PostID=79591

New Assembly, Old .NET (and Vice-Versa)

Suzanne Cook — Thu, 27 Jan 2005 01:40:00 GMT

I typically recommend that you build and test your assemblies against the same version of .NET that you will be running them against. That way, you'll have correct references and avoid surprises from behavior differences between builds.

Older assembly, newer .NET

But, sometimes you don't run against the same version that you built against. For example, the latest available CLR is the default when interop causes it to be loaded. Or, if the version of the CLR the assembly was built against is not available, the latest version can also be used instead. If there is a compatibility problem with that for your application, you can force the use of a preferred CLR version by using an app.config.

Compatibility

Yes, there are going to be behavior differences between versions - no way around it. It is the .NET team's goal to be as backwards compatible as realistically possible between versions. But, some changes are required - new features are added which sometimes require (hopefully minimal) behavior changes in other features. If we were required to never break any app, ever, we wouldn't be able to fix any bugs or add any features for fear that someone, somewhere relied on the broken behavior in some strange way. As Dll Hell has shown in the past, new versions of components aren't really compatible. The only guaranteed 100% compatible version is the same one you tested against.

V2+ assembly, older .NET

Say you see a BadImageFormatException for hresult 0x80131107 (CLDB_E_FILE_OLDVER) with message "Version [...] is not a compatible version." That means that you've tried to load an assembly built against a newer version of the CLR than was running.

This fails because new files can't be opened on an older CLR that does not understand them. You will need to either use the v2 CLR to load the v2/v1 assemblies, or load only v1 assemblies on the v1 CLR. That's just good practice, anyway. If you try to use an older .NET than you built against, a method you built against may not exist, etc.

Versioning/Deploying Unmanaged Files

Suzanne Cook — Fri, 29 Oct 2004 00:37:00 GMT

An unmanaged dll can be wrapped in a managed assembly by adding it as a file of a multi-module assembly. Then, it can be deployed and versioned in the same way as managed assemblies. (So, that assembly could contain nothing but metadata and unmanaged code - no managed code, if you prefer. It can also contain multiple unmanaged files in the same assembly.)

If your compiler does not support this directly, you can get this to work by adding that file as a linked managed resource. For example, see Visual Studio's /linkresource option (if using it for command line compiling).

This is useful in the case where DllImport() is used to access a function in that file. That call should be updated with the new assembly's info. For example, in the place of "unmanagedfile.dll", change it to include the display name like this: "unmanagedfile.dll, managedassembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089".

If that unmanaged file needs to be loaded by LoadLibrary() outside of DllImport(), however, it will need to follow the rules of LoadLibrary(), like the usual unmanaged file use outside the CLR. (See Junfeng's blog for an extra tip regarding that when using v2.)

Load(AssemblyName)

Suzanne Cook — Wed, 04 Aug 2004 23:20:00 GMT

Calling Load(AssemblyName) is not necessarily the same as calling Load(String). If the AssemblyName.CodeBase is not set, then they do do the same thing. So, if you've set the AssemblyName.Name, CultureInfo, public key token / public key and/or Version properties, it would be the same as if you had specified those properties in a String (as a display name) and passed that to Load(String).

If the CodeBase is set, but the Name is not, however, then it's the same as calling Assembly.LoadFrom() on that CodeBase.

When both the CodeBase and the Name are set, then the bind is tried with all the given binding information except the CodeBase (so, again, just like calling Load(String)). If that succeeds, we're done. But, if that fails, then the bind is tried again with just the CodeBase (just like LoadFrom()). If it fails again, then, of course, the whole bind fails. But, if it succeeds, then we verify that the binding properties in the AssemblyName match the found assembly. If they don't match, a FileLoadException will be thrown for hresult FUSION_E_REF_DEF_MISMATCH.

So, setting both the CodeBase and the Name is useful for when you want to both load an assembly at a given path into the LoadFrom context, and verify that it has the public key token, etc. that you expect. Of course, as described above (and due to binding context rules), keep in mind that just because you call Load(AssemblyName) with a CodeBase, it does not mean that it will be loaded from that path.

Debugging an InvalidCastException

Suzanne Cook — Thu, 03 Jun 2004 04:57:00 GMT

First, obviously, find the two types for which the cast failed and verify that they are the same type or otherwise castable.

Next, if the type was just deserialized, also verify that its assembly successfully loaded in the target appdomain.

If everything seems fine, check to see if the assemblies for those two types are loaded from different locations and in the same appdomain. (The actual cast is done in just one appdomain, even if the exception happens when passing a type between two appdomains.) Even if the bits of those assemblies are totally identical, if they are loaded from different paths, they will be considered different, so their types will be considered different. (See Comparing Already-Loaded Assemblies.)

A quick way to check for that is to examine the loaded module window of a debugger to see if that assembly was loaded multiple times. If it was, break on module loads to get the callstack for the unexpected load. If that's inconvenient, try getting the Fusion log.

Usually, the problem is that:

The assembly is available in the GAC (or the ApplicationBase) and loaded there by static reference (something was compiled against that assembly).
It has also been loaded dynamically by path, from another path (LoadFrom(), LoadFile(), etc.).
Then, the code tries to cast the type from (2) to the corresponding type from (1).

To fix this, once you find the offending caller, you will need to either cause the two types to be loaded from the same assembly from the exact same path, or avoid doing the cast. To decide between the assemblies at paths (1) and (2), see Choosing a Binding Context. Usually, I recommend using (1) - see Switching to the Load Context for help with implementing that.

App.config Examples

Suzanne Cook — Fri, 14 May 2004 16:25:00 GMT

Below are three examples of useful application configuration files.

Forces the v1.0 CLR to be run. If the v1.0 CLR is not installed, the app will fail to run.

<?xml version ="1.0"?>
<configuration>
    <startup>
         <requiredRuntime version="v1.0.3705"/>
         <supportedRuntime version="v1.0.3705"/>
     </startup>
</configuration>
Redirects “assemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=25283151a234958d“ to version 2.0.0.0 of that assembly. This is only useful for strongly-named assemblies, since versions don't matter for those that are simply-named.

<?xml version ="1.0"?>
<configuration>
<runtime>

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

                <dependentAssembly>
                        <assemblyIdentity name="assemblyName" culture="" publicKeyToken="25283151a234958d"/>
                        <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0"/>

                </dependentAssembly>
        </assemblyBinding>

</runtime>
</configuration>
Redirects “assemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8968ee41e78ce97a“ to codebase “http://www.yourwebsite.com/filename.dll“. 'Href' can also be set to something like “file:///c:/localfile/filename.dll“. Note that redirecting to a codebase causes a System.Net.WebPermission or System.IO.FileIOPermissionAccess.Read + PathDiscovery demand when loading that assembly.

<?xml version ="1.0"?>
<configuration>
<runtime>

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

                <dependentAssembly>
                        <assemblyIdentity name="assemblyName" culture="" publicKeyToken="8968ee41e78ce97a"/>
                        <codeBase version="1.0.0.0" href="http://www.yourwebsite.com/filename.dll"/>

                </dependentAssembly>
        </assemblyBinding>

</runtime>
</configuration>

Determining Whether a File Is an Assembly

Suzanne Cook — Thu, 18 Mar 2004 08:37:00 GMT

A file is an assembly if and only if it's managed and it contains an Assembly entry in its CLR metadata.

Determining by hand

A fast way to determine whether a file is an assembly is to run ildasm.exe on it. If it immediately gives an error saying that it may not be a PE file, then it's not a managed file. But, if it is an assembly, then ildasm will show an entry for the Assembly definition (“.assembly“ in the MANIFEST window or at the bottom of the original window).

Determining programmatically

From unmanaged code, you can call GetAssemblyFromScope() on the IMetaDataAssemblyImport interface for the file. If it returns S_OK, it's an assembly. If it returns CLDB_E_RECORD_NOTFOUND, it's not an assembly.

From managed code, if AssemblyName.GetAssemblyName(), Assembly.Load*(), etc. succeeds when given that file, then it's an assembly. If the load failed with a BadImageFormatException, then it may not be an assembly. There are other reasons, however, why that exception may have been thrown (maybe it's an assembly but could not be loaded because it has an incorrect format). Coming soon in v2, if the hresult for BadImageFormatException is COR_E_ASSEMBLYEXPECTED, then it's because it's not an assembly. Catch the exception and call System.Runtime.InteropServices.Marshal.GetHRForException() to get its hresult to find out.

Note that this assumes that you are not concerned about performance. If you are concerned about that, then the way to optimize for it is to not try to determine whether files are assemblies at runtime at all. (Some people are concerned about the exception that is thrown if the file is not an assembly. They overlook that in order to determine that it is not one, it has to be loaded and then thrown away, which can be even more expensive than catching an exception!) Instead, require that only assemblies are given to you. Then, if a file is not an assembly, it will be an exceptional situation. That way, you avoid the bad perf of both the exception and the unnecessary file loading.

Debugging a MissingMethodException, MissingFieldException, TypeLoadException

Suzanne Cook — Sat, 14 Feb 2004 03:03:00 GMT

Say you've just installed some assemblies from a third party and now you're seeing a MissingMethodException, MissingFieldException, or TypeLoadException (during the run of an application using those assemblies). Below are the common causes.

Loading failures
First, check for assembly binding failures by getting the Fusion log. Look for the assembly containing that method/field/type or assemblies containing types referenced by it. If an assembly failed to load, use the instructions at the same link to help resolve that issue.

Unexpected assembly version loaded
But, if that's not the problem, turn on the Fusion log for everything - not just failures - and check to see if the wrong version of those assemblies is being loaded. Look at the display names requested. Are any requesting outdated versions, even after policy has been applied (see further down in the log for the post-policy display name)? If so, you may want to recompile part of your app so that it has current references.

Loaded from unexpected path
If that doesn't help, run filever.exe on the file at the path it was loaded from. You can get that from the loaded modules list in a debugger. It's also the last path listed in the Fusion log, for a successful log (if it's in the GAC, no path is listed). Make sure it is the same path as you would expect.

Not in this version of the assembly
Next, run ildasm.exe on the file at the path it was loaded from at runtime. Make sure that the method/field/type is there and is defined how you would expect it. Maybe the file has changed, adding or removing methods or the like, but the assembly version and location have stayed the same.

Invalid IL
Now, try running peverify.exe on the file containing the method/field/type using the path it was loaded from at runtime. If it gives an error, check back to see if there was a warning at compile-time for this file.

Where to Find Technical Support

Suzanne Cook — Sat, 06 Dec 2003 02:13:00 GMT

Microsoft's official support website is http://support.microsoft.com/. It has all kinds of resources like product FAQs, downloads, searchable KB articles, newsgroup pointers, and ways to reach people to help with your individual needs or feedback.

Unfortunately, I can't give attention to individual customer issues. That's because I work in product design and development, not customer support. Someone has to be focused on that or else we'd never ship anything! So, I'm going to have to leave your questions and comments to MS's official channels which specialize in that. Please keep comments you post here general and about the loader or performance.

Determining the Referencing Assembly

Suzanne Cook — Sat, 15 Nov 2003 10:23:00 GMT

Say you're debugging your application and you see that version 1.0 of an assembly is being loaded when you thought it should be version 2.0. Where is the reference to 1.0 coming from?

The easiest way to find out is to look at the Fusion log for this bind. If the version 1.0 assembly was successfully loaded, use the ForceLog/"Log all binds" option of FusLogVw. Then, look for the line in the log showing the calling assembly:

Calling assembly : referencingAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=12ab3bf24c56c45b.

It shows the display name of the calling assembly when available. It doesn't tell you whether this is a static or a dynamic reference because Fusion doesn't know or care (that doesn't matter for binding purposes). So, this could mean that referencingAssembly was built against the other 1.0 assembly, or that it asked for it at runtime via Assembly.Load(), etc.

Sometimes the calling assembly is not specified in the log. There are a few possible cases where that happens:

The assembly was requested by unmanaged code (interop).
The calling assembly was in another appdomain (AppDomain.CreateInstance(), etc.).
The calling assembly had not been loaded through Fusion (Assembly.Load(byte[]), Assembly.LoadFile(), etc.).