Functions/New-ExchangeOnlineConnection.ps1
|
<#
.SYNOPSIS This class manages a connection to Exchange Online. .DESCRIPTION This class manages a connection to Exchange Online. It also performs mapping to several Exchange Online cmdlets and caching of the cmdlet outputs. #> class ExchangeOnlineConnection { ########### # Members # ########### # This tracks if the connection is currently open. [Bool]$IsConnectionOpen = $false # This stores the username used to logon. [String]$Username = $null # This stores the cached list of users. [PSObject[]]$CachedUsers = $null ########### # Methods # ########### # This is the constructor for the connection, which begins as a closed connection. ExchangeOnlineConnection() {} # This is the constructor for the connection, using a username and password to logon. ExchangeOnlineConnection([String]$username, [SecureString]$password) { $this.Open($username, $password) | Out-Null } # This is the constructor for the connection, using an MSPComplete Endpoint to logon. ExchangeOnlineConnection($endpoint) { $this.Open($endpoint) | Out-Null } # This method opens the connection using a username and password. # It returns whether a connection has been opened. [Bool]Open([String]$username, [SecureString]$password) { Write-Information "Opening a connection to Exchange Online" if (!$this.IsConnectionOpen) { $this.Username = $username $this.IsConnectionOpen = Connect-ExchangeOnlineAdminAccount -Username $username -Password $password return $this.IsConnectionOpen } else { Write-Warning "The connection to Exchange Online is already open." return $true } } # This method opens the connection using an MSPComplete Endpoint. # It returns whether a connection has been opened. [Bool]Open($endpoint) { Write-Information "Opening a connection to Exchange Online" if (!$this.IsConnectionOpen) { $this.Username = $endpoint.Credential.Username $this.IsConnectionOpen = Connect-ExchangeOnlineAdminAccount -Endpoint $endpoint return $this.IsConnectionOpen } else { Write-Warning "The connection to Exchange Online is already open." return $true } } # This method closes the connection. # It returns whether the connection has been closed. [Bool]Close() { Write-Information "Closing the connection to Exchange Online" if ($this.IsConnectionOpen) { $this.IsConnectionOpen = $false return Disconnect-ExchangeOnline } else { Write-Warning "The connection to Exchange Online has already been closed." return $true } } # This method retrieves the full list of users, and saves it to the cache. # If the testing environment switch is set, it retrieves the list of users in the test # environment instead. [PSObject[]]Get_User() { # Check if the testing environment switch is set if ((Get-BT_RunbookEnvironment).IsTestEnvironment) { $this.CachedUsers = Get-Office365TestEnvironmentAvailableUsers -Domain (Get-EmailAddressDomain $this.Username) -ExchangeOnline } else { $this.CachedUsers = Get-User -ResultSize unlimited } return $this.CachedUsers } } <# .SYNOPSIS This function establishes a new connection with Exchange Online. .DESCRIPTION This function establishes a new connection with Exchange Online. It returns an object which can be used to manage the connection. #> function New-ExchangeOnlineConnection { [CmdletBinding(DefaultParameterSetName="none")] [OutputType([ExchangeOnlineConnection])] param ( # The username of the Exchange Online admin account. [Parameter(Mandatory=$true, ParameterSetName="credential")] [string]$username, # The password of the Exchange Online admin account. [Parameter(Mandatory=$true, ParameterSetName="credential")] [SecureString]$password, # The MSPComplete Endpoint for the Exchange Online admin credentials. [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)] $endpoint ) # Construct the class and return it if ($PSCmdlet.ParameterSetName -eq "none") { return [ExchangeOnlineConnection]::new() } elseif ($PSCmdlet.ParameterSetName -eq "credential") { return [ExchangeOnlineConnection]::new($username, $password) } else { return [ExchangeOnlineConnection]::new($endpoint) } } |