1.1.Introduction to developing for Exchange

Exchange Online offers three main possibilities to be accessed programmatically: Exchange Web Services API (EWS), a dedicated set of PowerShell cmdlets (called Exchange Online PowerShell), and, since the introduction of Microsoft Graph, the possibility to approach Exchange Online using REST APIs has been open. Because Graph is an ongoing project by Microsoft, the functionality it offers is not (yet) as complete as the possibilities given by EWS, but Graph is officially replacing EWS. The Exchange Online PowerShell is mainly used for configuration, monitoring, maintenance, and to manage Exchange from the command line.

EWS can be used in precisely the same way for Exchange Online and Exchange Onprem, the only difference is given by the disparities in functionality in the two systems (they are very similar in any way), and the login method. EWS can be used in different ways: As a managed API by any development language (making SOAP, Simple Object Access Protocol, calls under the hood), as a set of SOAP Web Services, and from PowerShell. Because SOAP has been replaced by REST in the enterprise and is, in fact, not used anymore, its programmatic use will be not discussed in this book.

1.2.Login in Exchange

As it happens with other servers from Office 365, it is necessary to log in to the system to be authenticated, before any program can start interacting with the data.

1.2.1.Login from a managed language (CSharp)

For the CSharp examples in this chapter, the values to log in to Exchange (email address, password, application ID, and tenant ID, depending on the authorization method) are saved in an external file called exCs.values.config that is used by the appSettings section in the App.Config Visual Studio Solution file. The App.Config file for the Visual Studio Solution contains the following section inside the <configuration> tag:

The first line points to an external file that contains the values to be used by the App.Config file; it has the following form:

Note: The exAppId and exTenantId values are only needed if using oAuth (se section about oAuth later in this chapter).

The values can be called by their name in the appSettings file, as follows:

1.2.2.Login from PowerShell

EWS can be used by PowerShell to reach programmatically the Exchange information. The Microsoft.Exchange.WebServices.dll needed to work with EWS must be installed locally.

To make the EWS DLLs available for PowerShell, they must be loaded at the beginning of the script with the following statement (which must be in one continuous line):

The values to log in to Exchange (email address, password, application ID, and tenant ID, depending on the authorization method) are saved in an external file called exPs.values.config (in XML format) that is loaded by PowerShell at runtime. The external config file is called at the beginning of the script, as follows:

And the file exPs.values.config contains the values to be used in the script; it has the following form:

Note: The exAppId and exTenantId values are only needed if using oAuth (se section about oAuth later in this chapter).

The values can be called by their name in the appSettings file, as follows:

If PowerShell is not allowing to run scripts, change the execution policy using the command:

1.2.3.Login with user credentials for EWS (Basic Authentication) and CSharp

Microsoft recommends not to use basic authentication (using username/password) anymore, although Exchange Online still accepts this type of authentication. Nevertheless, basic authentication can be a good option, to avoid extensive setup tasks and repetitive logins, for simple test or demonstration applications.

The function (ConnectBA) in the following recipe uses the email address and password of one user to get authorized in Exchange. The AutodiscoverUrl method determines the best endpoint for a given user (the endpoint that is closest to the user's Mailbox server); this method can be called using only the username parameter, but Exchange Online rejects the request as unsafe. Therefore, the RedirectionUrlValidationCallback routine, which is considered valid if it uses HTTPS, must be used in conjunction with the authentication call. Instantiating the ExchangeService with an empty constructor will create an instance that is bound to the latest known version of Exchange. The TraceEnabled and TraceFlag properties can be activated to get information from Exchange about the login process (for debugging purposes), and the Url method of the service instance gives back the address used by Exchange Online.

        static ExchangeService ConnectBA(string userEmail, string userPW)
        {
            ExchangeService exService = new ExchangeService
            {
                Credentials = new WebCredentials(userEmail, userPW)
            };

            //exService.TraceEnabled = true;
            //exService.TraceFlags = TraceFlags.All;

            exService.AutodiscoverUrl(userEmail, RedirectionUrlValidationCallback);
            //Console.WriteLine(exService.Url);

            return exService;
        }

        static bool RedirectionUrlValidationCallback(string redirectionUrl)
        {
            bool validationResult = false;

            Uri redirectionUri = new Uri(redirectionUrl);
            if (redirectionUri.Scheme == "https")
            {
                validationResult = true;
            }

            return validationResult;
        }

The authorization method can be called from any other routine as follows:

        static void Main(string[] args)
        {
            ExchangeService myExService = ConnectBA(
                                ConfigurationManager.AppSettings["exUserName"],
                                ConfigurationManager.AppSettings["exUserPw"]);

            CallEWSTest(myExService);
        }

1.2.4.Login with oAuth for EWS and CSharp

Although the fact that oAuth relies on a third-party authentication provider, that the standard is more difficult to implement than basic authentication, and that oAuth requires another layer of integration (the application will need both, the authentication provider and the Exchange server), Microsoft recommends using oAuth instead of basic authentication because of the advantage in security.

Since Office 365 uses Azure Active Directory (AAD) as authentication provider, any application that wants to use Office Exchange EWS oAuth authentication must have an application ID issued by AAD. The following steps indicate how to register one application as a public client with Azure Active Directory.

1 - Using a browser, navigate to the main administration page of Office 365 (https://admin.microsoft.com or through https://portal.office.com), log in with an administrator account, and open the Azure Active Directory Admin Center.

2 - Click on Azure Active Directory in the menu on the left side, and then on App registrations (Manage section). Use the New registration button.

3 - Assign a name to the registration, select Accounts in this organizational directory only in the Supported account types section, and select the Public client/native (mobile & desktop) option in the Redirect Uri section. Write the value urn:ietf:wg:oauth:2.0:oob on the textbox at the side of the Redirect Uri section. Use the Register button to save the registration.

4 - The registration is complete. Copy the values given in Application (client) ID and Directory (tenant) ID to use it in the source code of the application to be developed.

Note: If you are using the App.config file described in the initial section of this chapter, copy the Application (client) ID value to the exAppId parameter, and the Directory (tenant) ID value to the exTenantId parameter.

The Visual Studio solution to use the authentication from oAuth (a console applications in this chapter) requires a using directive to Microsoft.Identity.Client.

The function ConnectOA in the following recipe uses the Azure AD registration client and tenant ID to get authorized in Exchange.

        static async System.Threading.Tasks.Task<ExchangeService> ConnectOA(
                                                            string AppId, string TenId)
        {
            ExchangeService exService = new ExchangeService();

            PublicClientApplicationOptions pcaOptions = new PublicClientApplicationOptions
            {
                ClientId = AppId,
                TenantId = TenId
            };

            IPublicClientApplication pcaBuilder = PublicClientApplicationBuilder
                .CreateWithApplicationOptions(pcaOptions).Build();

            string[] exScope = new string[] {
                            "https://outlook.office.com/EWS.AccessAsUser.All" };

            AuthenticationResult authToken = await
                              pcaBuilder.AcquireTokenInteractive(exScope).ExecuteAsync();

            exService.Url = new Uri("https://outlook.office365.com/EWS/Exchange.asmx");
            exService.Credentials = new OAuthCredentials(authToken.AccessToken);

            return await System.Threading.Tasks.Task.FromResult(exService);
        }

The first time that the application runs, a standard login window will appear requiring the account data of the user that made the registration. After login, the window will ask for permissions (Access your mailboxes, Maintain access to data you have given it access to and View your basic profile). Subsequently, the application will ask only for the user login, not for the permissions.

Because the connection routine is asynchronous, use the following code to call it.

        static void Main(string[] args)
        {
            ExchangeService myExService = ConnectOA(
                                ConfigurationManager.AppSettings["exAppId"],
                                ConfigurationManager.AppSettings["exTenantId"]).
                                                            GetAwaiter().GetResult();

            CallEWSTest(myExService);
        }

1.2.5.Login for EWS with PowerShell and Basic Authentication

The ConnectPsEwsBA routine in the next recipe takes care of login in Exchange using Basic Authentication with PowerShell.

Function ConnectPsEwsBA()
{
	$ExService = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService
	$ExService.Credentials = New-Object Microsoft.Exchange.WebServices.Data.WebCredentials(`
		$configFile.appsettings.exUserName, $configFile.appsettings.exUserPw)
	$ExService.Url = new-object Uri("https://outlook.office365.com/EWS/Exchange.asmx");
	#$ExService.TraceEnabled = $true
	#$ExService.TraceFlags = [Microsoft.Exchange.WebServices.Data.TraceFlags]::All
	$ExService.AutodiscoverUrl($configFile.appsettings.exUserName, {$true})

	return $ExService
}

See section 1.2.2. to get details about login with PowerShell. The TraceEnabled and TraceFlag properties can be activated at any moment to get information regarding the internal working of Exchange when logging in.

To call the function, use code similar to the next example.

##==> EWS Basic Authorization
Add-Type -Path "C:\Program Files\Microsoft\Exchange\Web Services\2.2\Microsoft.Exchange.WebServices.dll"
$ExService = ConnectPsEwsBA

CallEWSTest $ExService  #Calling any function

1.2.6.Login for EWS with PowerShell and oAuth

Using oAuth from PowerShell is not a trivial or easy endeavor. But because Basic Authentication is being closed for Exchange, it will be obligatory to use in some years.

For this book, we use the GenericOauthEWS.ps1 login routine developed by Glen Scales (glenscales@yahoo.com, https://gsexdev.blogspot.com/), that can be downloaded from his GitHub repository https://github.com/gscales/Powershell-Scripts/blob/master/GenericOauthEWS.ps1. The module is fully described in the article https://gsexdev.blogspot.com/2018/08/dependency-free-generic-ews-oauth.html.

To use the module, first, load it in the script and then call the Connect-Exchange method. Use the return value to get any access to the required information.

##==> EWS oAuth Authorization
Import-Module .\GenericOauthEWS.ps1 -Force
#Test-EWSConnection -MailboxName $configFile.appsettings.exUserName
$ExService = Connect-Exchange `
				$configFile.appsettings.exUserName "" $configFile.appsettings.exAppId

CallEWSTest $ExService  #Calling any function

The module has a Test-EWSConnection method that can be used to check the connection with Exchange and get some information about the account.

1.2.7.Login using the Exchange Online PowerShell

To work with Exchange Online PowerShell, use Windows PowerShell on the local computer to create a remote PowerShell session with Exchange Online, providing the Office 365 credentials, the required connection settings, and then import the Exchange Online cmdlets into the local Windows PowerShell session.

The following function automates the complete process.

Function ConnectPsOnlBA() 
{
	[SecureString]$securePW = ConvertTo-SecureString -String `
				$configFile.appsettings.exUserPw -AsPlainText -Force
	$myCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList `
				$configFile.appsettings.exUserName, $securePW
	$mySession = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri `
				https://outlook.office365.com/powershell-liveid/ -Authentication Basic `
				-AllowRedirection -Credential $myCredentials
	Import-PSSession $mySession -AllowClobber
}

To use the remote session, utilize the function as follows.

##==> Exchange Online PowerShell Basic Authorization
ConnectPsOnlBA

Get-Mailbox  #Calling any cmdlet

$currentSession = Get-PSSession
Remove-PSSession -Session $currentSession

The remote session is killed at the end of the code for security concerns.

1.3.Programming Exchange with EWS and CSharp

To work with EWS in Visual Studio, the development computer must have the Microsoft.Exchange.WebServices and Microsoft.Exchange.WebServices.Auth DLLs installed.