Rebex

Skip to content, Skip to navigation

Upgrading FTP for .NET

Introduction

The first release of Rebex FTP for .NET was 1.0.0.0. There are also bugfix versions 1.1.0.0 - 1.2.*.0 and 1.3.0.0 incorporates many enhancements. All of those are backward compatible with 1.0.0.0, the interface has not changed.

However, as far as the class loader is concerned, version 1.0.0.0 and version 1.3.0.0 of an assembly are completely different identities and therefore considered incompatible. The same applies to versions that only differ in build or revision number.

Therefore, applications compiled with FTP for .NET 1.0.0.0 or 1.2.0.0 will refuse to work with 1.3.0.0. This applies both to FTP for .NET installed as a shared assembly in Global Assembly Cache (GAC) and as an application-private assembly.

This document describes how to make your existing applications use the new version instead the old one without the need of recompiling your code.

Version Policies

Microsoft .NET Framework supports version policies. These policies are stored in XML files and are simply a requests to load one version of an assembly instead of another. This is exactly what we need here.

The policy for redirecting from old versions of Rebex FTP for .NET (1.0.0.0 - 1.2.2.0) to 1.3.0.0: 

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> 
    <dependentAssembly> 
        <assemblyIdentity 
            name="Rebex.Net.Ftp" 
            publicKeyToken="1c4638788972655d" /> 
        <bindingRedirect 
            oldVersion="1.0.0.0-1.2.2.0" 
            newVersion="1.3.0.0" /> 
    </dependentAssembly> 
</assemblyBinding> 

There are three levels at which version policy can be applied in .NET, and four possible ways of upgrading Rebex FTP for .NET:



1. Application-specific policy

Each application has an optional configuration file that can specify the redirections. The name of the configuration file is the name of the executable + a ".config" extension (eg. WinFormClient.exe.config) for executable files and web.config for ASP.NET applications.

To enforce binding to a different version than the application was linked with, place the version policy under the <runtime> node of the <configuration> root node: 

<configuration> 
    <runtime> 
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> 
            <dependentAssembly> 
                <assemblyIdentity 
                    name="Rebex.Net.Ftp" 
                    publicKeyToken="1c4638788972655d" /> 
                <bindingRedirect 
                    oldVersion="1.0.0.0-1.2.2.0" 
                    newVersion="1.3.0.0" /> 
            </dependentAssembly> 
        </assemblyBinding> 
    </runtime></configuration> 


2. Manually specified policy

This only works if the component is installed in Global Assembly Cache. The binding policy can be specified manually using .NET Configuration Management Console (see the screenshot) after adding FTP for .NET assembly into "Configured Assemblies" group.





3. Publisher policy

Publisher policy is Rebex' statement of compatibility regarding different versions of FTP for .NET. It is expressed in XML just as application-specific policy, but it is distributed as an assembly and is signed by the same key-pair as the FTP component itself. This is required by .NET and it is to ensure the authenticity of the publisher policy. It has to be installed into Global Assembly Cache. (The component itself does not have to be installed into GAC, this decision is still up to you.)

Publisher policy assemblies are called Policy.1.?.Rebex.Net.Ftp.dll and reside in the /policy folder of each distribution package. There are several different policy assemblies - Policy.1.0.Rebex.Net.Ftp.dll only redirects versions 1.0 to the current version, Policy.1.1.Rebex.Net.Ftp.dll redirects versions 1.1, and so on.

Install the policies you need either by:

  • Using the gacutil command line utility: gacutil -i Policy.1.0.Rebex.Net.Ftp.dll (more information on gacutil: http://msdn.microsoft.com/library/en-us/cptools/html/cpgrfglobalassemblycacheutilitygacutilexe.asp) (gacutil can be usually found in C:\Windows\Microsoft.NET\Framework\v1.0.3705 or \v1.1.4322 or inside the .NET Framework SDK directory tree)
  • Using .NET Configuration Management Console - see the screenshot. (It can be found in Start -> Settings -> Control Panel -> Administrative Tools -> .NET Configuration)

Note: The XML policy file has to be placed in the same folder as the policy assemblies.





4. Machine-wide policy.

Machine-wide policy is stored in machine.config. Policy statements made in machine.config affect all applications running on the machine. Edit this file only if you know what you are doing. See .NET Framework documentation for more information.