Use .NET libraries in PowerShell Scripts.

Requirements: Any .NET Edition

PowerShell provides the option to use .NET libraries within a script. Products such as IPWorks, IPWorks SSH, Cloud Storage, and others, provide .NET class libraries that can be consumed not only from C# or VB.NET, but also directly from PowerShell scripts.

This article will walk you through each step of using the IPWorks .NET library in PowerShell to create a script that connects to an IMAP server using OAuth:

Contents

• Loading the Assembly
• Creating an Instance of the Component
• Setting Properties
• Calling Methods
• Handling Events
• Full Example

Loading the Assembly

First, identify the correct build of the /n software library for your runtime. Choosing the correct assembly build is essential. The following table shows the target needed depending on the version of PowerShell that you will be using.

The below example shows how a script would load the .NET 6.0 target for to be used by a PowerShell.

$assemblyPath = ".\Documents\IPWorks 2024 .NET Edition\lib\net6.0\nsoftware.IPWorks.dll" Add-Type -Path $assemblyPath

Creating an Instance of the Component

Once the correct assembly has been chosen, you can then create instances of the component. This is done differently depending on the version of PowerShell that you are using. It is important to save them so that they can be used later.

$oauth = New-Object nsoftware.IPWorks.OAuth $imap = New-Object nsoftware.IPWorks.IMAP

In PowerShell 7+, the shorter constructor syntax is also supported:

$oauth = [nsoftware.IPWorks.OAuth]::new() $imap = [nsoftware.IPWorks.IMAP]::new()

Setting Properties

Once the component had been initialized, the properties are assigned just like native PowerShell object properties. You can also use the enumerated types for properties that support enums like SSLStartMode in the below example.

$imap.MailServer = "outlook.office365.com" $imap.User = "example@email.com" $imap.SSLStartMode = [nsoftware.IPWorks.IMAPSSLStartModes]::sslImplicit $imap.MailPort = 993

Calling Methods

Once the components have been configured using the properties, you can call methods like you normally would.

# Connect and disconnect $imap.Connect() # ... perform operations ... $imap.Disconnect()

Handling Events

In components that expose events (e.g. PITrail, Log, etc.) these can be hooked using Register-ObjectEvent. See below for an example of capturing the IMAP PITrail event that outputs any messages sent to or from the server.

$piTrailEvent = Register-ObjectEvent -InputObject $imap -EventName OnPITrail -Action { Write-Host ">> PITrail:" $EventArgs.Message }

Later when you are done with the events, you can un-register the event using the Unregister-Event like below.

Unregister-Event -SourceIdentifier $piTrailEvent.Name

Full Example

Below is a complete example that will have the IMAP component connect to the Office365 IMAP server using OAuth for authentication.

# Demonstrates using a custom .NET class (properties, methods, events) in PowerShell
# --- Load the DLL --- $assemblyPath = ".\IPWorks 2024 .NET Edition\lib\net6.0\nsoftware.IPWorks.dll" Add-Type -Path $assemblyPath
# --- Create an instance of the class --- $oauth = New-Object nsoftware.IPWorks.OAuth $imap = New-Object nsoftware.IPWorks.IMAP
# --- OAuth --- $oauth.ClientId = "" $oauth.ClientSecret = "" $oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize" $oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token" $oauth.AuthorizationScope = "https://outlook.office.com/IMAP.AccessAsUser.All offline_access"
$authorization = $oauth.GetAuthorization()
# --- IMAP --- $piTrailEvent = Register-ObjectEvent -InputObject $imap -EventName OnPITrail -Action { Write-Host ">> PITrail:" $EventArgs.Message }
$imap.MailServer = "outlook.office365.com" $imap.User = "example@email.com" $imap.SSLStartMode = [nsoftware.IPWorks.IMAPSSLStartModes]::sslImplicit $imap.MailPort = 993
$imap.AuthMechanism = [nsoftware.IPWorks.IMAPAuthMechanisms]::amXOAUTH2 $imap.Config("AuthorizationIdentity=$authorization")
$imap.Connect() # ... your IMAP commands go here ... $imap.Disconnect()
Unregister-Event -SourceIdentifier $piTrailEvent.Name