Differences
This shows you the differences between the selected revisions of the page.
| library_from_script 2013-05-07 | 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 [[wp>Windows PowerShell]]. PowerShell is scripting language built on top of .NET framework. It comes with Windows 7 and newer and can be installed into Windows XP and Vista. PowerShell scripts can be directly executed, they do not need to be compiled first. See [[library#powershell|example PowerShell script that uses WinSCP .NET assembly]]. | + | 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 recommended setting, as used in most scripting examples. Read mode 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 session 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''. 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 38: | Line 42: | ||
| </code> | </code> | ||
| - | needs to be converted to following call: | + | needs to be converted to following call in [[library_powershell|PowerShell]]: |
| <code powershell> | <code powershell> | ||
| 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 66: | Line 66: | ||
| </code> | </code> | ||
| - | maps to following PowerShell code: | + | maps to following [[library_powershell|PowerShell]] code: |
| <code powershell> | <code powershell> | ||
| Line 72: | Line 72: | ||
| { | { | ||
| # Load WinSCP .NET assembly | # Load WinSCP .NET assembly | ||
| - | [Reflection.Assembly]::LoadFrom("WinSCP.dll") | Out-Null | + | Add-Type -Path "WinSCPnet.dll" |
| # 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 95: | 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 108: | Line 110: | ||
| exit 0 | exit 0 | ||
| } | } | ||
| - | catch [Exception] | + | catch |
| { | { | ||
| - | Write-Host $_.Exception.Message | + | Write-Host "Error: $($_.Exception.Message)" |
| exit 1 | exit 1 | ||
| } | } | ||
| </code> | </code> | ||