Differences
This shows you the differences between the selected revisions of the page.
| library_install 2021-04-23 | library_install 2023-09-28 (current) | ||
| Line 9: | Line 9: | ||
| 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 [[#gac|installing the assembly to GAC]]), make use of the ''[[library_session#executablepath|Session.ExecutablePath]]'' property to force the assembly to look for the ''winscp.exe'' in a different location. | 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 [[#gac|installing the assembly to GAC]]), make use of the ''[[library_session#executablepath|Session.ExecutablePath]]'' property to force the assembly to look for the ''winscp.exe'' in a different location. | ||
| + | |||
| + | The version of ''WinSCPnet.dll'' in the root of the package is .NET Framework ==build== of the assembly. If your project targets .NET (Core) or if you use [[library_powershell#powershell|PowerShell (Core) 6/7]], you have to use .NET Standard build of the assembly, which is located in the ''netstandard2.0'' subfolder. The .NET Standard build has some minor limitations and cannot be used with COM. | ||
| Further steps depend on a development environment/programming languages, that you will use with the assembly: | Further steps depend on a development environment/programming languages, that you will use with the assembly: | ||
| Line 15: | Line 17: | ||
| * Visual Studio (C#, VB.NET): For development, you better use the [[#nuget|NugGet package]], instead of installing the assembly manually. The NuGet package will even care for configuring your project to deploy the assembly. | * Visual Studio (C#, VB.NET): For development, you better use the [[#nuget|NugGet package]], instead of installing the assembly manually. The NuGet package will even care for configuring your project to deploy the assembly. | ||
| * [[library_vb|VBA]], [[library_com_wsh|VBScript, JScript]], [[library_perl|Perl]]: You need to [[#registering|register the assembly for COM]]. | * [[library_vb|VBA]], [[library_com_wsh|VBScript, JScript]], [[library_perl|Perl]]: You need to [[#registering|register the assembly for COM]]. | ||
| - | + | ··* SSIS: Read about [[library_ssis#using|using WinSCP .NET assembly from SSIS]]. | |
| - | The version of ''WinSCPnet.dll'' in the root of the package is .NET Framework build of the assembly. If your project targets .NET (Core) or if you use [[library_powershell#powershell|PowerShell (Core) 6/7]], you have to use .NET Standard build of the assembly, which is located in the ''netstandard2.0'' subfolder. The .NET Standard build has some minor limitations and cannot be used with COM. | + | |
| ==== [[vs]] Using from Visual Studio or other Development or Runtime Environment ==== | ==== [[vs]] Using from Visual Studio or other Development or Runtime Environment ==== | ||
| Line 40: | Line 41: | ||
| When you install the assembly to %%GAC%%, you need to [[#installing|configure a path to WinSCP executable]]. | When you install the assembly to %%GAC%%, you need to [[#installing|configure a path to WinSCP executable]]. | ||
| + | |||
| + | In many cases, instead of using GAC, you can [[library_ssis#subscribe|subscribe ''AppDomain.AssemblyResolve'' event]]. | ||
| ==== On Development Machine ==== | ==== On Development Machine ==== | ||
| - | To install the assembly into %%GAC%% on development machine, i.e. the one that has [[https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/|Windows SDK]] installed, use following command: | + | To install the assembly into %%GAC%% on development machine, i.e. the one that has [[https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/|Windows SDK]] installed, use following command: |
| <code> | <code> | ||
| Line 54: | Line 57: | ||
| * For .NET framework 3.5, use ''gacutil'' from Windows SDK 6.0: \\ ''C:\Program Files (x86)\Microsoft SDKs\Windows\v6.0A\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'' | ||
| - | ==== On Production or User's Machine ==== | + | ==== [[production]] On Production or User's Machine ==== |
| To install the assembly into %%GAC%% on production or user's machine, you may install the assembly into %%GAC%% using: | 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; | * Windows Installer, by creating ''.msi'' package; | ||
| Line 62: | Line 65: | ||
| $publish = New-Object System.EnterpriseServices.Internal.Publish | $publish = New-Object System.EnterpriseServices.Internal.Publish | ||
| $publish.GacInstall("C:\path\WinSCPnet.dll") | $publish.GacInstall("C:\path\WinSCPnet.dll") | ||
| - | </code> An absolute path to the DLL needs to be specified and Administrator privileges are required. Otherwise the above method will fail (and the only indication of the failure is sent to Windows Event log). | + | </code> An absolute path to the DLL needs to be specified and Administrator privileges are required. Otherwise the above method will fail (and the only indication of the failure is sent to Windows Event log).((Check if ''C:\Windows\Microsoft.NET\assembly\GAC_MSIL\WinSCPnet'' &winpath folder containing the assembly was created.)) |
| ===== [[registering]] Registering for COM ===== | ===== [[registering]] Registering for COM ===== | ||
| - | 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 [[library_powershell|PowerShell]]. | + | WinSCP .NET assembly exposes majority of its 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 [[library_powershell|PowerShell]]. |
| <code> | <code> | ||
| %WINDIR%\Microsoft.NET\Framework\<version>\RegAsm.exe WinSCPnet.dll /codebase /tlb | %WINDIR%\Microsoft.NET\Framework\<version>\RegAsm.exe WinSCPnet.dll /codebase /tlb | ||
| </code> | </code> | ||
| - | 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 &win64 applications.((What is obviously available on 64-bit systems only.)) On 64-bit systems, you should generally register the assembly both for 32-bit (such as old versions of [[library_vb|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. | + | In the command above, 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 &win64 applications.((What is obviously available on 64-bit systems only.)) On 64-bit systems, you should generally register the assembly both for 32-bit (such as old versions of [[library_vb|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: | Typical registration commands for .NET 4.0 on 64-bit system would be: | ||
| Line 88: | Line 91: | ||
| You can use ''/comregistration'' command-line switch of WinSCP [[executables]] to list (and optionally unregister) all registered versions of the assembly (without having the assembly files). | You can use ''/comregistration'' command-line switch of WinSCP [[executables]] to list (and optionally unregister) all registered versions of the assembly (without having the assembly files). | ||
| - | ===== Deploying ===== | + | ===== [[deploying]] Deploying ===== |
| 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 [[#installing|can find the executable]]. | 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 [[#installing|can find the executable]]. | ||