Retrieve Exchange Online Folder Information Using EWS Managed API 2.2 and PowerShell

Retrieve Exchange Online Folder Information Using EWS Managed API 2.2 and PowerShell

Summary

This TechNet Wiki is to demo a PowerShell script which retrieves Exchange Online folder information using EWS Managed API 2.2 and PowerShell. The reason to develop this PowerShell function is to meet client requirement.

Requirement

Show basic information like display name, total count, unread count, etc from the MsgFolder (Root).

References

• Download EWS Managed API
• How to: Communicate with EWS using EWS Managed API
• Get started with EWS Managed API client applications
• EWS Managed API reference

Solution

To meet the requirement, let us create a PowerShell function named Get-xInbox folder as illustrated below:

function Get-xFolder {
 
}

Most important is to include a comment-help for the function which helps others to understand the code. Take look at the below comment section

    <#
    .SYNOPSIS
        A PowerShell function to list exchange online folder information
    .DESCRIPTION
        A PowerShell function to list exchange online folder information. 
    Assume you have the assembly 'Microsoft.Exchange.WebServices.dll' in the correct location. 
    .EXAMPLE
        PS C:\> Get-xFolder -Identity user@tenant.onmicrosoft.com
        Retrieves 10 folder information from the given mailbox
    .EXAMPLE
        PS C:\> Get-xFolder -Identity user1@tenant.onmicrosoft.com -ItemCount 100 -Credential user@tenant.onmicrosoft.com 
        Retrieves top 100 folder information from the given mailbox. This use the ImpersonatedUserId class. 
    .EXAMPLE
        PS C:\> "user@tenant.onmicrosoft.com", "user1@tenant.onmicrosoft.com" | Get-xFolder 
        If you have permission the above snippet returns 10 folder information from the given mailboxes. 
    .NOTES
        @ChendrayanV
    http://chen.about-powershell.com
    #>

Define the parameter as you need. In our case, we created three parameters where only $Identity is mandatory. $ItemCount and $Credential are not. But, if $ItemCount is not used 10 folder's information will be listed.

param (
        [Parameter(Mandatory,ValueFromPipeline,ValueFromPipelineByPropertyName)]
        $Identity,
 
        [Parameter()]
        $ItemCount,
 
        [Parameter()]
        [System.Management.Automation.CredentialAttribute()]
        [pscredential]
        $Credential
    )

Begin Block

    # This block is used to provide optional one-time pre-processing for the function. 
    begin
 {
        Import-Module 'C:\Program Files\Microsoft\Exchange\Web Services\2.2\Microsoft.Exchange.WebServices.dll'
    }

Process Block

    # This block is used to provide record-by-record processing for the function
    process
 {
        $ExchangeService = [Microsoft.Exchange.WebServices.Data.ExchangeService]::new()
        if($PSBoundParameters.ContainsKey('Credential')) 
     {
            $ExchangeService.Credentials = [System.Net.NetworkCredential]::new($Credential.UserName,$Credential.Password)
        }
        else
     {
            $ExchangeService.UseDefaultCredentials = $true
        }
        $ExchangeService.ImpersonatedUserId = [Microsoft.Exchange.WebServices.Data.ImpersonatedUserId]::new([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress,$Identity)
        $ExchangeService.Url = "https://outlook.office365.com/EWS/Exchange.asmx"
        if($PSBoundParameters.ContainsKey('ItemCount')) {
            $View = [Microsoft.Exchange.WebServices.Data.FolderView]::new($ItemCount)
        }
        else {
            $View = [Microsoft.Exchange.WebServices.Data.FolderView]::new(10)
        }
        $View.Traversal = [Microsoft.Exchange.WebServices.Data.FolderTraversal]::Deep
        $Folder = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($ExchangeService,[Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::MsgFolderRoot)
        $Folder.FindFolders($View)
    }

End Block

    # This block is used to provide optional one-time post-processing for the function.
    end    {
        # No need to dispose the $ExchangeService - In EWS Managed API FindItems will do the object dispose job. You can add some code if required. 
    }

Usage

help Get-xFolder 

help Get-xFolder -Examples

help Get-xFolder -Parameter *

Video

View

Output

Full Code

function Get-xFolder {
    <#
    .SYNOPSIS
        A PowerShell function to list exchange online folder information
    .DESCRIPTION
        A PowerShell function to list exchange online folder information. 
        Assume you have the assembly 'Microsoft.Exchange.WebServices.dll' in the correct location. 
    .EXAMPLE
        PS C:\> Get-xFolder -Identity user@tenant.onmicrosoft.com
        Retrieves 10 folder information from the given mailbox
    .EXAMPLE
        PS C:\> Get-xFolder -Identity user1@tenant.onmicrosoft.com -ItemCount 100 -Credential user@tenant.onmicrosoft.com 
        Retrieves top 100 folder information from the given mailbox. This use the ImpersonatedUserId class. 
    .EXAMPLE
        PS C:\> "user@tenant.onmicrosoft.com", "user1@tenant.onmicrosoft.com" | Get-xFolder 
        If you have permission the above snippet returns 10 folder information from the given mailboxes. 
    .NOTES
        @ChendrayanV
        http://chen.about-powershell.com
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory,ValueFromPipeline,ValueFromPipelineByPropertyName)]
        $Identity,
 
        [Parameter()]
        $ItemCount,
 
        [Parameter()]
        [System.Management.Automation.CredentialAttribute()]
        [pscredential]
        $Credential
    )
    # This block is used to provide optional one-time pre-processing for the function. 
    begin
 {
        Import-Module 'C:\Program Files\Microsoft\Exchange\Web Services\2.2\Microsoft.Exchange.WebServices.dll'
    }
    # This block is used to provide record-by-record processing for the function
    process
 {
        $ExchangeService = [Microsoft.Exchange.WebServices.Data.ExchangeService]::new()
        if($PSBoundParameters.ContainsKey('Credential')) 
     {
            $ExchangeService.Credentials = [System.Net.NetworkCredential]::new($Credential.UserName,$Credential.Password)
        }
        else
     {
            $ExchangeService.UseDefaultCredentials = $true
        }
        $ExchangeService.ImpersonatedUserId = [Microsoft.Exchange.WebServices.Data.ImpersonatedUserId]::new([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress,$Identity)
        $ExchangeService.Url = "https://outlook.office365.com/EWS/Exchange.asmx"
        if($PSBoundParameters.ContainsKey('ItemCount')) {
            $View = [Microsoft.Exchange.WebServices.Data.FolderView]::new($ItemCount)
        }
        else {
            $View = [Microsoft.Exchange.WebServices.Data.FolderView]::new(10)
        }
        $View.Traversal = [Microsoft.Exchange.WebServices.Data.FolderTraversal]::Deep
        $Folder = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($ExchangeService,[Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::MsgFolderRoot)
        $Folder.FindFolders($View)
    }
    # This block is used to provide optional one-time post-processing for the function.
    end 
 {
        # No need to dispose the $ExchangeService - In EWS Managed API FindItems will do the object dispose job. You can add some code if required. 
    }
}