This is an old revision of the document!
- Installing to GAC
- Registering for COM
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,
winscpnet.dll, 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 property Copy to Output Directory to Copy if newer). The Build Action should be automatically set to Content, what means that the file will be included when deploying your application (e.g. an Azure WebJob application).
WinSCP .NET assembly in available as NuGet package with the same name.
The NuGet package includes the assembly itself and a required WinSCP executable. When installed, it adds the assembly as reference to your project and sets up WinSCP executable to be copied to project output directory, so that it can be found on run-time, as described above.
No other setup is needed, so you can start coding straight away after installation.
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:
gacutil.exe /i WinSCPnet.dll
Windows SDK comes with Microsoft Visual Studio. You can also install it separately.
gacutil.exe for your version of .NET framework:
- For .NET framework 4.0, use
gacutilfrom Windows SDK 7.1 (or 7.0):
C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1\bin\gacutil.exe;
- For .NET framework 3.5, use
gacutilfrom Windows SDK 6.0:
C:\Program Files (x86)\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
- Any other installer system that supports installing to GAC, e.g. Inno Setup;
- System.EnterpriseServices.Internal.Publish.GacInstall method. PowerShell example:
Add-Type -AssemblyName "System.EnterpriseServices" $publish = New-Object System.EnterpriseServices.Internal.Publish $publish.GacInstall("WinSCPnet.dll")
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:
%WINDIR%\Microsoft.NET\Framework\<version>\RegAsm.exe WinSCPnet.dll /codebase /tlb
%WINDIR% is path to your Windows installation, what is typically
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. On 64-bit system, you should generally register the assembly both for 32-bit and 64-bit application. 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 commands for .NET 4.0 on 64-bit system would be:
%WINDIR%\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe WinSCPnet.dll /codebase /tlb %WINDIR%\Microsoft.NET\Framework64\v4.0.30319\RegAsm.exe WinSCPnet.dll /codebase /tlb
The above examples assume that
WinSCPnet.dll is in current working directory. Otherwise you need to specify an absolute path to the
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 instantiate classes from the assembly, no matter that you have older versions of the assembly registered too. You need to download 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