powershellwinscp-netadd-type

PowerShell: Unable to find type when using PS 5 classes


I'm using classes in PS with WinSCP PowerShell Assembly. In one of the methods I'm using various types from WinSCP.

This works fine as long as I already have the assembly added - however, because of the way PowerShell reads the script when using classes (I assume?), an error is thrown before the assembly could be loaded.

In fact, even if I put a Write-Host at the top, it will not load.

Is there any way of forcing something to run before the rest of the file is parsed?

Transfer() {
    $this.Logger = [Logger]::new()
    try {

        Add-Type -Path $this.Paths.WinSCP            
        $ConnectionType = $this.FtpSettings.Protocol.ToString()
        $SessionOptions = New-Object WinSCP.SessionOptions -Property @{
            Protocol = [WinSCP.Protocol]::$ConnectionType
            HostName = $this.FtpSettings.Server
            UserName = $this.FtpSettings.Username
            Password = $this.FtpSettings.Password
        }

Results in an error like this:

Protocol = [WinSCP.Protocol]::$ConnectionType
Unable to find type [WinSCP.Protocol].

But it doesn't matter where I load the assembly. Even if I put the Add-Type cmdlet on the topmost line with a direct path to WinSCPnet.dll, it won't load - it detects the missing types before running anything, it seems.


Solution

  • As you've discovered, PowerShell refuses to run scripts that contain class definitions that reference then-unavailable (not-yet-loaded) types - the script-parsing stage fails.

    The proper solution is to create a script module (*.psm1) whose associated manifest (*.psd1) declares the assembly containing the referenced types a prerequisite, via the RequiredAssemblies key.

    See alternative solution at the bottom if using modules is not an option.

    Here's a simplified walk-through:

    Create test module tm as follows:

    Create file ./tm/tm.psm1 with your class definition; e.g.:

        class Foo {
          # As a simple example, return the full name of the WinSCP type.
          [string] Bar() {
            return [WinSCP.Protocol].FullName
          }
        }
    

    Note: In the real world, modules are usually placed in one of the standard locations defined in $env:PSMODULEPATH, so that the module can be referenced by name only, without needing to specify a (relative) path.

    Use the module:

    PS> using module ./tm; [Foo]::new().Bar()
    WinSCP.Protocol
    

    The using module statement imports the module and - unlike Import-Module - also makes the class defined in the module available to the current session.

    Since importing the module implicitly loaded the WinSCP assembly thanks to the RequiredAssemblies key in the module manifest, instantiating class Foo, which references the assembly's types, succeeded.


    If you need to determine the path to the dependent assembly dynamically in order to load it or even to ad-hoc-compile one (in which case use of a RequiredAssemblies manifest entry isn't an option), you should be able to use the approach recommended in Justin Grote's helpful answer - i.e., to use a ScriptsToProcess manifest entry that points to a *.ps1 script that calls Add-Type to dynamically load dependent assemblies before the script module (*.psm1) is loaded - but this doesn't actually work as of PowerShell 7.3.4 (the version current as of this writing): while the definition of the class in the *.psm1 file relying on the dependent assembly's types succeeds, the caller doesn't see the class until a script with a using module ./tm statement is executed a second time:

    # Create module folder (remove a preexisting ./tm folder if this fails).
    $null = New-Item -Type Directory -ErrorAction Stop ./tm
    
    # Create a helper script that loads the dependent
    # assembly.
    # In this simple example, the assembly is created dynamically,
    # with a type [demo.FooHelper]
    @'
    Add-Type @"
    namespace demo {
      public class FooHelper {
      }
    }
    "@
    '@ > ./tm/loadAssemblies.ps1
    
    # Create the root script module.
    # Note how the [Foo] class definition references the
    # [demo.FooHelper] type created in the loadAssemblies.ps1 script.
    @'
    class Foo {
      # Simply return the full name of the dependent type.
      [string] Bar() {
        return [demo.FooHelper].FullName
      }
    }
    '@ > ./tm/tm.psm1
    
    # Create the manifest file, designating loadAssemblies.ps1
    # as the script to run (in the caller's scope) before the
    # root module is parsed.
    New-ModuleManifest ./tm/tm.psd1 -RootModule tm.psm1 -ScriptsToProcess loadAssemblies.ps1
    
    # Up to at least PowerShell 7.3.4
    # !! First attempt FAILS:
    PS> using module ./tm; [Foo]::new().Bar()
    InvalidOperation: Unable to find type [Foo]
    
    # Second attempt: OK
    PS> using module ./tm; [Foo]::new().Bar()
    demo.FooHelper
    

    The problem is a known one, as it turns out, and dates back to 2017 - see GitHub issue #2962


    If your use case doesn't allow the use of modules:

    # Adjust this path as needed.
    Add-Type -LiteralPath C:\path\to\WinSCPnet.dll
    
    # By placing the class definition in a string that is invoked at *runtime*
    # via Invoke-Expression, *after* the WinSCP assembly has been loaded, the
    # class definition succeeds.
    Invoke-Expression @'
    class Foo {
      # Simply return the full name of the WinSCP type.
      [string] Bar() {
        return [WinSCP.Protocol].FullName
      }
    }
    '@
    
    [Foo]::new().Bar()
    

    This approach is demonstrated in Takophiliac's helpful answer.


    As for the variant problem of not being able to use custom PowerShell classes defined in a script or loaded via using module in the same script's param(...) block, see this answer.


    [1] It's not a concern in this case, but generally, given that Invoke-Expression can invoke any command stored in a string, applying it to strings not fully under your control can result in the execution of malicious commands - see this answer for more information. This caveat applies to other language analogously, such as to Bash's built-in eval command.