Downloading and Installing WinSCP .NET Assembly

WinSCP .NET assembly is available in a separate package named winscpXXXautomation.zip on WinSCP download page. Follow the .NET assembly/COM library link.

To use the assembly, you need to have WinSCP installed (or download the portable package). You have to use the same version of the assembly as your version of WinSCP.

WinSCP .NET assembly interacts with WinSCP winscp.exe. By default it looks for the winscp.exe in the same folder, where the assembly is stored. For that reason, you should extract the package into the same folder, where you have WinSCP installed/extracted. You can also copy all binaries, winscp.exe and winscpnet.dll (winscp.dll in the releases before the latest beta version), into separate folder.

If you cannot store the assembly into the same folder, you can alternatively make use of Session.ExecutablePath property to force the assembly to look for the winscp.exe in a different location.

Note that your runtime or development environment may copy the assembly into an another location. In that case you need to copy winscp.exe into that location too.

E.g. If you reference WinSCP assembly from your project in Microsoft Visual Studio, it copies the assembly during build into the project Output path (e.g. <your_project_path>/obj/Debug). Similar case is when you install the assembly into Global Assembly Cache (GAC).

You may want to add winscp.exe to your Visual Studio project, to have it copied to Output path automatically (by setting file properties Builder action to None and Copy to Output Directory to Copy if newer). Note that, in releases before the latest beta version, it makes winscp.dll and winscp.exe to conflict. You need to rename the winscp.dll to give it a different base name, e.g. winscpnet.dll. In the latest beta version, the assembly has already name winscpnet.dll.

In special cases, you may need to install the assembly into Global Assembly Cache (GAC), particularly to use it from SSIS.

When you install the assembly to GAC, you need to use it, as if it is installed to alternative location.

To install the assembly into GAC on development machine, i.e. the one that has Windows SDK installed, use following command (use WinSCP.dll in the releases before the latest beta version):

gacutil.exe /i WinSCPnet.dll

Windows SDK comes with Microsoft Visual Studio. You can also install it separatelly.

Use correct gacutil.exe for your version of .NET framework:

• For .NET framework 4.0, use gacutil from Windows SDK 7.1 (or 7.0): C:\Program Files\Microsoft SDKs\Windows\v7.1\bin\gacutil.exe;
• For .NET framework 3.5, use gacutil from Windows SDK 6.0: C:\Program Files\Microsoft SDKs\Windows\v6.0A\Bin\gacutil.exe

To install the assembly into GAC on production or user’s machine, you may install the assembly into GAC using:

• Windows Installer, by creating .msi package;
• Any other installer system that suppors installing to GAC, e.g. Inno Setup;
• System.EnterpriseServices.Internal.Publish.GacInstall method.

WinSCP .NET assembly exposes its full interface to COM. As a COM library, it needs to be registered before use. If you are going to use the COM interface, register the assembly using1 (use WinSCP.dll in the releases before the latest beta version):

%WINDIR%\Microsoft.NET\Framework\<version>\RegAsm.exe WinSCPnet.dll /codebase /tlb

Where the %WINDIR% is path to your Windows installation, what is typically C:\Windows or C:\WINNT. Note that you can keep %WINDIR% as this environment variable should be set on your system to point to the Windows folder. The Framework needs to be replaced by Framework64 to register the assembly for use from 64-bit applications2. The <version> is version of .NET framework to register the assembly with. It is recommended to use the latest available, what currently is v4.0.30319. You may however use any framework version from 2.0 (v2.0.50727) up. Note that framework 3.0 and 3.5 do not ship with RegAsm.exe. For these versions use RegAsm.exe from 2.0.

Typical registration command for .NET 4.0 would be (use WinSCP.dll in the releases before the latest beta version):

%WINDIR%\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe WinSCPnet.dll /codebase /tlb

If you register multiple versions of the WinSCP .NET assembly, the .NET framework will always use the latest version registered.

If you want to use different version (i.e. downgrade), you need to unregister all newer versions of the assembly and re-register the version you want to use.

If you happen to remove the newest registered assembly, without unregistering it first, you will not be able to instatiate classes from the assembly, no matter that you have older versions of the assembly registered too. You need to download the the version you have removed again and unregister it. Exact physical location of the assembly, when unregistering, does not need to match the original location of the removed assembly (as long as the versions match)..

When deploying the assembly, make sure that WinSCP is installed along with the assembly on the target system and that WinSCP assembly can find the winscp.exe.