Getting started with Sunsetless EWS
From the package swap to the first call on Microsoft Graph. Your EWS code does not change.
Check that it fits your application
Pick the package for your EWS library. Both run on .NET Framework and on .NET 8, 9 and 10.
Your code uses Install from NuGet.org Microsoft.Exchange.WebServicesMicrosoft's EWS Managed APISunsetless.EwsMicrosoft.Exchange.WebServices.NETStandardThe community port with the async APISunsetless.Ews.NETStandardMicrosoft.Exchange.WebServices.dllLoaded in a PowerShell script, see EWS scripts in PowerShellSunsetless.EwsTo see whether every call your code makes is covered, run your usage report through the usage checker, which also sets apart the Microsoft and vendor apps in the report, or look up single operations in the compatibility table.
Swap the package
Replace the Microsoft package with ours from NuGet.org and rebuild. Your code compiles unchanged.
dotnet remove package Microsoft.Exchange.WebServices dotnet add package Sunsetless.EwsOn the .NET Standard port, swap that package instead. Your
awaitcalls stay as they are.dotnet remove package Microsoft.Exchange.WebServices.NETStandard dotnet add package Sunsetless.Ews.NETStandardOn .NET Framework 4.6.2 and newer the package's dependencies need assembly binding redirects. Set
<AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>in the application's project and the build writes them to the application's.exe.config. A web application reads them fromweb.config, which the build does not change: add the redirects there by hand. A missing redirect shows asCould not load file or assembly 'System.Memory, ...'.A project that targets .NET Framework 3.5 to 4.6.1 gets a
Microsoft.Exchange.WebServices.dllwithout dependencies and needs no redirects. Calls to Exchange Online then need .NET Framework 4.7.2 or newer on the computer. An application built for .NET Framework 3.5 must also run on the .NET Framework 4 runtime: put<supportedRuntime version="v4.0" />first in the<startup>section of its.exe.config.Grant Graph permissions
Register an app in Microsoft Entra ID, or use the one you have, and grant it the Microsoft Graph application permissions your code needs:
Mail.ReadWrite,Mail.Sendmail, mail folders, search folders, conversations, sync and notifications Calendars.ReadWritecalendars, meetings, availability and delegates Contacts.ReadWrite(orContacts.Readto only read)contacts, contact pictures, contact folders, FindPeople in a contact folder Tasks.ReadWrite.Alltasks MailboxSettings.ReadWriteout-of-office settings, inbox rules, categories and working hours User.Read.All,Group.Read.AllResolveNames, ExpandDL, FindPeople in the directory, user photos ProfilePhoto.ReadWrite.AllSetUserPhoto Place.Read.Allroom lists Seven more permissions are optional. Without them the rest works, and the operations that need them return a clear error that names the permission:
MailboxFolder.Read.Allfolders of every kind in folder listings; calendars created through EWS before the switch; Notes and Journal; a person's contacts in hidden folders for FindPeople MailboxFolder.ReadWrite.Allrenaming, moving, copying and deleting calendars created through EWS MailboxItem.Read.Allcontact groups, a task's companies and contacts, non-mail items in Deleted Items and Recoverable Items MailboxItem.ImportExport.Allwhat Graph has no call of its own for, such as ArchiveItem, moving and copying contacts, tasks and calendar items, meetings saved with SendToNone, posts and contact groups MailboxItem.ReadWrite.Alldeleting contacts and contact groups in a single call, and purging a contact group from Recoverable Items MailboxConfigItem.ReadWriteuser configuration objects of every name and the retention policy tags, through a Microsoft Graph API still in preview Mail-Advanced.ReadWrite.Allchanging the subject, body, recipients or extended properties of received and sent messages, which Microsoft Graph requires from 31 December 2026 Domain.Read.AllAutodiscover GetDomainSettings Set the configuration
Nothing changes in your code. Set these environment variables for the process:
SUNSETLESS_TENANT_ID=<your Entra tenant ID> SUNSETLESS_CLIENT_ID=<the application (client) ID of the app registration> SUNSETLESS_CLIENT_SECRET=<a client secret of the app registration> SUNSETLESS_LICENSE_KEY=<your trial or license key>Microsoft recommends a certificate for production: leave
SUNSETLESS_CLIENT_SECRETout and setSUNSETLESS_CERT_THUMBPRINT(a certificate in the Windows certificate store), orSUNSETLESS_CERT_PATHandSUNSETLESS_CERT_PASSWORD(a .pfx file).One process that works for several tenants, such as a hosted product, configures each
ExchangeServicein code instead, withSunsetlessEws.Configure(service, options).Calls to Exchange Server keep using EWS. If your application still calls an Exchange Server URL after its mailboxes moved to Exchange Online, set
SUNSETLESS_BRIDGE_ALL_HOSTS=trueand every host goes to Microsoft Graph.No key yet? Get a free trial key for your tenant. The README in the package lists the optional settings and the configuration in code.
Limit mailbox access
Scope the app to the mailboxes it uses with RBAC for Applications in Exchange Online. That decision is made in your tenant; the library does not make it for you.
Test with your own mailboxes
Run your normal workflows against a test mailbox. Pay attention to the areas the compatibility table marks with differences, such as notifications, tasks and delegates.
Runnable samples for .NET 8, .NET Framework 4.8 and .NET Framework 3.5, for a process that serves several tenants and for a component that ships the library, are in the samples repository on GitHub. Report anything that behaves differently from EWS in its issue tracker.