Shadow Copying Assemblies

Shadow copying enables assemblies that are used in an application domain to be updated without unloading the application domain. This is particularly useful for applications that must be available continuously, such as ASP.NET sites.

The common language runtime locks an assembly file when the assembly is loaded, so the file cannot be updated until the assembly is unloaded. The only way to unload an assembly from an application domain is by unloading the application domain, so under normal circumstances, an assembly cannot be updated on disk until all the application domains that are using it have been unloaded.

When an application domain is configured to shadow copy files, assemblies from the application path are copied to another location and loaded from that location. The copy is locked, but the original assembly file is unlocked and can be updated.

This article contains the following sections:

• Enabling and Using Shadow Copying describes the basic use and the options that are available for shadow copying.

• Startup Performance describes the changes that are made to shadow copying in the .NET Framework 4 to improve startup performance, and how to revert to the behavior of earlier versions.

• Obsolete Methods describes the changes that were made to the properties and methods that control shadow copying in the .NET Framework 2.0.

Enabling and Using Shadow Copying

You can use the properties of the AppDomainSetup class as follows to configure an application domain for shadow copying:

• Enable shadow copying by setting the ShadowCopyFiles property to the string value "true".

  By default, this setting causes all assemblies in the application path to be copied to a download cache before they are loaded. This is the same cache maintained by the common language runtime to store files downloaded from other computers, and the common language runtime automatically deletes the files when they are no longer needed.

• Optionally set a custom location for shadow copied files by using the CachePath property and the ApplicationName property.

  The base path for the location is formed by concatenating the ApplicationName property to the CachePath property as a subdirectory. Assemblies are shadow copied to subdirectories of this path, not to the base path itself.

  Note

  If the ApplicationName property is not set, the CachePath property is ignored and the download cache is used. No exception is thrown.

  If you specify a custom location, you are responsible for cleaning up the directories and copied files when they are no longer needed. They are not deleted automatically.

  There are a few reasons why you might want to set a custom location for shadow copied files. You might want to set a custom location for shadow copied files if your application generates a large number of copies. The download cache is limited by size, not by lifetime, so it is possible that the common language runtime will attempt to delete a file that is still in use. Another reason to set a custom location is when users running your application do not have write access to the directory location the common language runtime uses for the download cache.

• Optionally limit the assemblies that are shadow copied by using the ShadowCopyDirectories property.

  When you enable shadow copying for an application domain, the default is to copy all assemblies in the application path — that is, in the directories specified by the ApplicationBase and PrivateBinPath properties. You can limit the copying to selected directories by creating a string that contains only those directories you want to shadow copy, and assigning the string to the ShadowCopyDirectories property. Separate the directories with semicolons. The only assemblies that are shadow copied are the ones in the selected directories.

  Note

  If you don’t assign a string to the ShadowCopyDirectories property, or if you set this property to null, all assemblies in the directories specified by the ApplicationBase and PrivateBinPath properties are shadow copied.

  Important

  Directory paths must not contain semicolons, because the semicolon is the delimiter character. There is no escape character for semicolons.

Startup Performance

When an application domain that uses shadow copying starts, there is a delay while assemblies in the application directory are copied to the shadow copy directory, or verified if they are already in that location. Before the .NET Framework 4, all assemblies were copied to a temporary directory. Each assembly was opened to verify the assembly name, and the strong name was validated. Each assembly was checked to see whether it had been updated more recently than the copy in the shadow copy directory. If so, it was copied to the shadow copy directory. Finally, the temporary copies were discarded.

Beginning with the .NET Framework 4, the default startup behavior is to directly compare the file date and time of each assembly in the application directory with the file date and time of the copy in the shadow copy directory. If the assembly has been updated, it is copied by using the same procedure as in earlier versions of the .NET Framework; otherwise, the copy in the shadow copy directory is loaded.

The resulting performance improvement is largest for applications in which assemblies do not change frequently and changes usually occur in a small subset of assemblies. If a majority of assemblies in an application change frequently, the new default behavior might cause a performance regression. You can restore the startup behavior of previous versions of the .NET Framework by adding the <shadowCopyVerifyByTimestamp> element to the configuration file, with enabled="false".

Obsolete Methods

The AppDomain class has several methods, such as SetShadowCopyFiles and ClearShadowCopyPath, that can be used to control shadow copying on an application domain, but these have been marked obsolete in .NET Framework version 2.0. The recommended way to configure an application domain for shadow copying is to use the properties of the AppDomainSetup class.

See also

• AppDomainSetup.ShadowCopyFiles
• AppDomainSetup.CachePath
• AppDomainSetup.ApplicationName
• AppDomainSetup.ShadowCopyDirectories
• <shadowCopyVerifyByTimestamp> Element