Downloading and Installing WinSCP .NET Assembly

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

The package includes the assembly itself (winscpnet.dll) and a required dependency, WinSCP executable winscp.exe.

The binaries interact with each other and must be kept in the same folder for the assembly to work. In rare situations this is not possible (e.g. when installing the assembly to GAC), 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 the 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 ASP.NET web application or Azure WebJob application).

WinSCP .NET assembly is available as NuGet package with the same name.

The NuGet package includes the assembly itself and the 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 configure a path to WinSCP executable.

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.

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

• For .NET framework 4.0 or newer, use gacutil from Windows SDK 7.1 (or newer): C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1\bin\gacutil.exe;
• For .NET framework 3.5, use gacutil from 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 .msi package;
• 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 using command below. You do not need to register the assembly, if you are going to use it directly as a .NET assembly, e.g. from C#, VB.NET or PowerShell.

%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 applications1. On 64-bit systems, you should generally register the assembly both for 32-bit (such as Microsoft Excel) and 64-bit applications. 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:WinSCPnet32.tlb
%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\RegAsm.exe WinSCPnet.dll /codebase /tlb:WinSCPnet64.tlb

The above examples assume that WinSCPnet.dll is in current working directory. Otherwise you need to specify an absolute path to the .dll.

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 executable (winscp.exe) is deployed along with the assembly on the target system and that WinSCP assembly can find the executable.

If you want to avoid having the winscp.exe as a separate file (e.g. when whole your project is a single .exe file and you do not want to have any dependency), you can embed the winscp.exe as a resource to your own executable.

Add the winscp.exe to your Visual Studio project, if not added already (e.g. by the WinSCP NuGet package). Change file property Build Action to the Embedded Resource. If the winscp.exe was added by the NuGet package, reset the property Copy to Output Directory back to the Do not copy.

Now, before you open a session, extract the winscp.exe from resources to a temporary file using a code like:

// Generate random, yet meaningful name of the temporary file
string tempName = Path.GetTempFileName();
string executableName = "WinSCP." + Path.ChangeExtension(Path.GetFileName(tempName), "exe");
string executablePath = Path.Combine(Path.GetDirectoryName(tempName), executableName);
File.Delete(tempName);
 
// Extract the resource to the temporary file
Assembly executingAssembly = Assembly.GetExecutingAssembly();
string resourceName = executingAssembly.GetName().Name + "." + "WinSCP.exe";
 
using (Stream resource = Assembly.GetExecutingAssembly().GetManifestResourceStream(resourceName))
using (Stream file = new FileStream(executablePath, FileMode.Create, FileAccess.Write))
{
    resource.CopyTo(file);
}
 
try
{
    using (Session session = new Session())
    {
        // Use the temporarily extracted executable
        session.ExecutablePath = executablePath;
 
        // Connect
        session.Open(sessionOptions);
 
        // Your code
    }
}
finally
{
    // Clean up
    File.Delete(executablePath);
}