Sunsetless.Ews.NETStandard 2.1.0

Sunsetless EWS for the .NET Standard port

Keep your async 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. This package is for applications built on the community .NET Standard port of the EWS Managed API, Microsoft.Exchange.WebServices.NETStandard 1.1.x, with its async API (await service.FindItems(...)). It keeps the port's namespaces, types, method signatures and assembly name. 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.

For applications on the original Microsoft package Microsoft.Exchange.WebServices 2.2 (synchronous API), use Sunsetless.Ews instead.

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

Install

Replace the port's package with this one and rebuild your application. Your code compiles unchanged.

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

Runs on .NET Framework 4.6.2 or later and on .NET 8, 9 and 10 (the package targets .NET Standard 2.0 and .NET Framework 4.6.2).

The assembly keeps the port's name, Microsoft.Exchange.WebServices.NETStandard.dll. Unlike the port's, it is strong-named (public key token 1b8c25c6fc94dcf1), so strong-named applications and components can reference it on .NET Framework. On .NET 8, 9 and 10, libraries compiled against the port use this file too; on .NET Framework, rebuild them against this package. When such a library brings the port's package along, the build keeps this package's file, which has the higher assembly version.

Differences from the port

• FileAttachment.Load(Stream) and FileAttachment.Load(string) wait for the content before they return. In the port they return before the content is written.
• ExchangeService.Timeout ends a call to Exchange Online that takes longer, with ServiceRequestException ("The operation has timed out").
• The 2.0.0 beta versions of the port (with CancellationToken parameters) are not covered.

.NET Framework: binding redirects

On .NET Framework 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.

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 source code of the .NET Standard port of the EWS Managed API (https://github.com/sherlock1982/ews-managed-api), Copyright (c) Microsoft Corporation and contributors, MIT License. Its license text is in licenses/ews-managed-api-license.txt in this package.