Differences
This shows you the differences between the selected revisions of the page.
| library_from_script 2013-09-23 | library_from_script 2022-06-16 (current) | ||
| Line 5: | Line 5: | ||
| Start by choosing a language. WinSCP .NET assembly can be used from any .NET language or any language that supports COM. | Start by choosing a language. WinSCP .NET assembly can be used from any .NET language or any language that supports COM. | ||
| - | If you do not have your own preferred language, use [[library_powershell|Windows PowerShell]]. | + | If you do not have your own preferred language, use [[library_powershell|PowerShell]]. |
| ===== Mapping Script Commands to .NET Assembly Calls ===== | ===== Mapping Script Commands to .NET Assembly Calls ===== | ||
| Line 12: | Line 12: | ||
| There are some conceptual differences though. These are discussed in following sections. | There are some conceptual differences though. These are discussed in following sections. | ||
| - | ==== [[mode]] Interactive/Batch Mode ==== | + | ==== [[mode]] Batch Mode ==== |
| - | Scripts run in an interactive mode by default (''[[scriptcommand_option|option batch off]]''). There's no equivalent for this in .NET assembly, which always runs in batch mode. It is near equivalent to ''option batch abort'' in scripting mode, what is a recommended setting, as used in most scripting examples. Read more about [[library_session#results|capturing errors]] in .NET assembly. Documentation for converting of individual scripting commands (such as ''get'' [[scriptcommand_get#net|command mapping]]) details mode mapping specifics for the respective operations. | + | Batch scripts (specified using ''/script'' or ''/command'' [[commandline#scripting|command-line switches]]) run in an ''[[scriptcommand_option#batch|option batch abort]]'' mode. |
| - | ==== [[default_config]] Default Configuration ==== | + | To emulate the ''option batch abort'' call a method ''[[library_operationresultbase|OperationResultBase]].Check'' for all ''Session'' methods that return an operation result (such as ''[[library_session_getfiles|GetFiles]]'', ''[[library_session_putfiles|PutFiles]]'', and ''[[library_session_synchronizedirectories|SynchronizeDirectories]]'').· |
| - | Scripting mode by default [[scripting#configuration|shares configuration]] with graphical mode. On the contrary the .NET assembly is by default isolated from graphical mode configuration (equivalent to using ''/ini=nul'' [[commandline|command-line parameter]] in scripting mode). | + | |
| - | It means that you cannot use [[session_configuration#site|sites/stored sessions]], when opening session with .NET assembly. You need to configure all your site settings directly in your code (using ''[[library_sessionoptions|SessionOptions]]'' class). | + | If you are using ''option batch continue'' mode, handle ''[[library_session_queryreceived|Session.QueryReceived]]'' event and call ''[[ library_queryreceivedeventargs#continue|QueryReceivedEventArgs.Continue]]'' in the handler. //For an example, see [[library_example_recursive_download_custom_error_handling|*]].// |
| + | |||
| + | Read more about [[library_session#results|capturing errors]] in .NET assembly. Documentation for converting an individual scripting commands (such as ''get'' [[scriptcommand_get#net|command mapping]]) details more mapping specifics for the respective operations. | ||
| + | |||
| + | ==== [[default_config]] Default Configuration ==== | ||
| + | Scripting mode by default [[scripting#configuration|shares configuration]] with graphical mode. On the contrary the .NET assembly is isolated from graphical mode configuration (equivalent to using ''[[commandline#configuration|/ini=nul]]'' command-line parameter in scripting mode). | ||
| - | It also means that with .NET assembly, you always start with default [[transfer_settings|transfer settings]], default [[ui_pref_resume|resume/endurance settings]], etc.· | + | It means that you cannot use [[session_configuration#site|stored sites]], when opening session with .NET assembly. You need to configure all your site settings directly in your code (using ''[[library_sessionoptions|SessionOptions]]'' class). |
| - | Alternatively, you can force the .NET assembly to share configuration with graphical/scripting mode, by setting ''[[library_session|Session.DefaultConfiguration]]'' to ''false''; (''$False'' in PowerShell). Though this is not recommended practise. | + | It also means that with .NET assembly, you always start with default [[transfer_settings|transfer settings]], default [[ui_pref_resume|resume/endurance settings]], etc. |
| ==== [[paths]] Relative/Absolute Paths ==== | ==== [[paths]] Relative/Absolute Paths ==== | ||
| Line 28: | Line 32: | ||
| In the scripting you can use paths relative to current working directory in parameters to script commands. | In the scripting you can use paths relative to current working directory in parameters to script commands. | ||
| - | In the .NET assembly, you need to always use absolute paths. | + | In the .NET assembly, you need to always use absolute paths or paths relative to //initial// working directory (for remote paths the //initial// directory is typically a home directory). |
| For example following script snippet: | For example following script snippet: | ||
| Line 48: | Line 52: | ||
| <code winscp> | <code winscp> | ||
| - | # Automatically abort script on errors | ||
| - | option batch abort | ||
| - | # Disable overwrite confirmations that conflict with the previous | ||
| - | option confirm off | ||
| # Connect | # Connect | ||
| - | open sftp://user:password@example.com -hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | open sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..." |
| # Change remote directory | # Change remote directory | ||
| cd /home/user | cd /home/user | ||
| Line 67: | Line 67: | ||
| maps to following [[library_powershell|PowerShell]] code: | maps to following [[library_powershell|PowerShell]] code: | ||
| - | |||
| - | &beta (* .dll *) | ||
| <code powershell> | <code powershell> | ||
| Line 74: | Line 72: | ||
| { | { | ||
| # Load WinSCP .NET assembly | # Load WinSCP .NET assembly | ||
| - | # Use "winscp.dll" for the releases before the latest beta version. | + | Add-Type -Path "WinSCPnet.dll" |
| - | [Reflection.Assembly]::LoadFrom("WinSCPnet.dll") | Out-Null | + | |
| # Setup session options | # Setup session options | ||
| - | $sessionOptions = New-Object WinSCP.SessionOptions | + | $sessionOptions = New-Object WinSCP.SessionOptions -Property @{ |
| - | ···$sessionOptions.Protocol = [WinSCP.Protocol]::Sftp | + | ········Protocol = [WinSCP.Protocol]::Sftp |
| - | $sessionOptions.HostName = "example.com" | + | ·······HostName = "example.com" |
| - | $sessionOptions.UserName = "user" | + | ·······UserName = "user" |
| - | $sessionOptions.Password = "password" | + | ·······Password = "password" |
| - | $sessionOptions.SshHostKeyFingerprint = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | ·······SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| + | } | ||
| $session = New-Object WinSCP.Session | $session = New-Object WinSCP.Session | ||
| Line 98: | Line 96: | ||
| # Download file to the local directory d:\ | # Download file to the local directory d:\ | ||
| # Note use of absolute path | # Note use of absolute path | ||
| - | $transferResult = $session.GetFiles("/home/user/examplefile.txt", "d:\", $False, $transferOptions) | + | $transferResult = |
| + | ···········$session.GetFiles("/home/user/examplefile.txt", "d:\", $False, $transferOptions) | ||
| - | # Throw on any error to emulate "option batch abort" | + | # Throw on any error to emulate the default "option batch abort" |
| $transferResult.Check() | $transferResult.Check() | ||
| } | } | ||
| Line 111: | Line 110: | ||
| exit 0 | exit 0 | ||
| } | } | ||
| - | catch [Exception] | + | catch |
| { | { | ||
| - | Write-Host $_.Exception.Message | + | Write-Host "Error: $($_.Exception.Message)" |
| exit 1 | exit 1 | ||
| } | } | ||
| </code> | </code> | ||