Sunsetless.Ews 2.1.0

Sunsetless EWS

Keep your EWS Managed API code and run it on Microsoft Graph.

Microsoft is retiring Exchange Web Services (EWS) in Exchange Online. From October 10, 2026, a tenant that keeps EWS on (EWSEnabled set to True) has to list the apps allowed to use it in EWSAllowedAppIDs. In the other tenants Microsoft switches EWS off in waves, each announced in the Message Center 7 days ahead. On April 1, 2027 EWS is retired. Sunsetless EWS is a source-compatible build of the EWS Managed API 2.2 (namespace Microsoft.Exchange.WebServices.Data, the same types and methods). Inside your application it translates calls to Exchange Online into Microsoft Graph calls. Calls to on-premises Exchange keep using EWS, so hybrid setups keep working.

Sunsetless is independent: not affiliated with, endorsed by or sponsored by Microsoft.

Install

Replace the Microsoft package with this one and rebuild your application. Your code compiles unchanged.

dotnet remove package Microsoft.Exchange.WebServices
dotnet add package Sunsetless.Ews

Projects can target .NET Framework 3.5 or newer, or .NET 8, 9 and 10. Routing to Microsoft Graph needs .NET Framework 4.7.2 or newer on the computer; for applications built for .NET Framework 3.5 to 4.6.1, see below. The assemblies are strong-named (public key token 1b8c25c6fc94dcf1), so strong-named applications and components can reference them on .NET Framework too.

If Microsoft.Exchange.WebServices stays in the build, referenced directly or through another package, the build uses this package's Microsoft.Exchange.WebServices.dll and shows warning SUNSETLESS001. A library compiled against Microsoft's package then loads this file on .NET 8, 9 and 10. On .NET Framework it fails with FileLoadException, because it asks for Microsoft's signed assembly.

.NET Framework: binding redirects

On .NET Framework 4.6.2 and newer the package's dependencies (System.Text.Json, Microsoft.Identity.Client) need assembly binding redirects in the application's config file. Set <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects> in the application's project and the build writes them to YourApp.exe.config. A web application reads them from web.config, which the build does not change: add the redirects there by hand.

A missing redirect shows as Could not load file or assembly 'System.Memory, ...'. The located assembly's manifest definition does not match the assembly reference.

.NET Framework 3.5 to 4.6.1

Projects that target .NET Framework 3.5, 4.0, 4.5, 4.6 or 4.6.1 get a Microsoft.Exchange.WebServices.dll without dependencies, so they need no binding redirects. It is the only file the package adds to the application, also with packages.config. The part that talks to Microsoft Graph is inside it, with its own private copies of System.Text.Json and Microsoft.Identity.Client, so the application can use any version of those libraries itself. That part loads the first time a request goes to Microsoft Graph. Requests that stay on EWS, such as those to Exchange Server, never load it.

It needs:

• .NET Framework 4.7.2 or newer installed on the computer. Applications built for .NET Framework 4.0 to 4.6.1 run on it unchanged.
• The .NET Framework 4 runtime. An application built for .NET Framework 3.5 runs on the .NET Framework 2.0 runtime unless its config file asks for version 4 first:

<configuration>
  <startup>
    <supportedRuntime version="v4.0" />
    <supportedRuntime version="v2.0.50727" />
  </startup>
</configuration>

Without these, requests to Microsoft Graph fail with a ServiceLocalException that names what is missing. Requests that stay on EWS keep working, and Autodiscover goes to Exchange.

Microsoft Graph and Microsoft Entra ID accept only TLS 1.2 or newer, which applications built for .NET Framework 4.5 or older do not offer by default. The library's own connections to them ask for TLS 1.2 themselves. ServicePointManager.SecurityProtocol and the application's other connections stay as they are.

Configure

Nothing changes in your code. The library calls Microsoft Graph as an app registration in your Microsoft Entra tenant, so it needs that app's ID and a way to sign in as it. Set four environment variables for the process:

Certificate instead of a client secret

Microsoft recommends a certificate for production. Leave SUNSETLESS_CLIENT_SECRET out and set one of these:

Optional settings

Configuration in code

Instead of environment variables, before the first ExchangeService call:

Sunsetless.Ews.SunsetlessEws.Configure(new Sunsetless.Ews.Core.SunsetlessEwsOptions
{
    TenantId = "...",
    ClientId = "...",
    ClientSecret = "...",   // or CertificateThumbprint, or CertificatePath and CertificatePassword
    LicenseKey = "...",
});

Exchange Server URL, mailboxes in Exchange Online

By default only calls to Exchange Online go to Microsoft Graph, and calls to any other host stay on EWS. When the mailboxes have moved to Exchange Online but the application still calls an Exchange Server URL, such as https://mail.contoso.com/EWS/Exchange.asmx, set SUNSETLESS_BRIDGE_ALL_HOSTS=true (or BridgeAllHosts = true in the options). Calls to every host then go to Microsoft Graph, and the application's configuration stays as it is.

The library signs in as the app registration, so the user name and password the code sets for Exchange Server are not used. Name the mailbox with ImpersonatedUserId or SUNSETLESS_DEFAULT_MAILBOX. Autodiscover is unaffected: it is answered from Microsoft Graph for Exchange Online mailboxes and goes to Exchange for the rest.

Many tenants in one process

A service that works for several Microsoft 365 tenants, such as a hosted product with many customers, configures each ExchangeService with the values of its tenant. The call replaces the process-wide configuration for that service only:

var service = new ExchangeService(ExchangeVersion.Exchange2013_SP1) { Url = new Uri("https://outlook.office365.com/EWS/Exchange.asmx") };
Sunsetless.Ews.SunsetlessEws.Configure(service, new Sunsetless.Ews.Core.SunsetlessEwsOptions
{
    TenantId = customer.TenantId,
    ClientId = "...",
    CertificateThumbprint = "...",
});

Services with the same options share one Microsoft Graph sign-in and token cache, so creating a service per request is fine. Changing the options object afterwards does not affect a configured service. Without LicenseKey the options use the process-wide key or SUNSETLESS_LICENSE_KEY; an ISV key is not tied to a tenant, so one key serves every customer.

Inside a component

A component or SDK that ships this package inside it, for other developers to build on, supplies its own license key in its code:

Sunsetless.Ews.SunsetlessEws.UseComponentLicense("...");

The call routes nothing by itself: until the application configures a tenant, every ExchangeService keeps using EWS, and the application needs no key of its own. A key issued for a component works only when the assembly that makes the call has the strong-name public key token the key names, so make the call from the component's own assembly, not through reflection. The same key in SUNSETLESS_LICENSE_KEY or LicenseKey is refused. When the application sets a key of its own, that key is checked first.

Permissions

The app registration needs Microsoft Graph application permissions for what your code does:

Without the last seven the rest works; the library then lists only mail folders under the root and under mail folders and only the calendars Graph lists under Calendar, reads tasks from To Do alone, shows no contact groups, reports deleted calendar items, contacts and tasks as DeletedEvent, serves only CategoryList and WorkHours as user configurations, and answers the Notes and Journal folders, the calendar writes listed for MailboxFolder.ReadWrite.All, other user configurations, GetUserRetentionPolicyTags, the operations listed for MailboxItem.ImportExport.All and, once Microsoft Graph enforces it, the message changes listed for Mail-Advanced.ReadWrite.All with an error that names the missing permission.

Autodiscover (AutodiscoverUrl, GetUserSettings, GetDomainSettings) is answered from Microsoft Graph, because Exchange Online refuses app-only tokens there. The answer needs User.Read.All and MailboxSettings.Read; without them Autodiscover goes to Exchange. SUNSETLESS_AUTODISCOVER=passthrough sends it to Exchange instead.

The library calls Microsoft Graph with the app's own permissions, not with the rights of the user it impersonates, and an item or folder ID opens the mailbox it belongs to. Limit the mailboxes the app can open with RBAC for Applications in Exchange Online. An application that takes item IDs, folder IDs or mailbox addresses from its users should also set SUNSETLESS_DENY_CROSS_MAILBOX_ACCESS=true.

License

Sunsetless EWS is commercial software. You get a license key at https://sunsetless.com/pricing, or a free trial key for testing at https://sunsetless.com/trial. Without a valid key the package does not call Microsoft Graph, and calls fail with ErrorInvalidLicense. The key is checked offline, and the package sends no telemetry. The terms are at https://sunsetless.com/terms.

What is covered

The supported operations, what was verified against live Exchange Online, and the known differences between EWS and Graph are listed at https://sunsetless.com/compatibility. To check an application, open its EWS usage report in the checker at https://sunsetless.com/coverage-check. The report stays in your browser. Without the report, the free tool ews-scan (https://github.com/sunset-less/ews-scan) lists the EWS operations in the compiled application: dotnet tool install --global Sunsetless.EwsScan.

This version has no preview operations. Operations added in later versions before they are verified against live Exchange Online will be off by default and listed on the compatibility page; SUNSETLESS_PREVIEW_FEATURES=true will switch them on.

Support

contact@sunsetless.com

Third-party code

Built on the EWS Managed API source code, Copyright (c) Microsoft Corporation, MIT License. Its license text is in licenses/ews-managed-api-license.txt in this package.

For .NET Framework 3.5 to 4.6.1, Microsoft.Exchange.WebServices.dll also contains System.Text.Json, Microsoft.Identity.Client and their dependencies (MIT License). Their notices are in licenses/third-party-notices.txt.