From accepting the migration to actually doing it
If you already know your VSTO Outlook add-in is on borrowed time, the new Outlook does not run it and the deadlines are real, then the question is no longer whether to migrate but how. This is the playbook for that. Migrating a VSTO Outlook add-in to an Office.js web add-in is less a port and more a structured rebuild, because the two share no code and no runtime. But it is a well-trodden path, and done in the right order it carries low risk and zero downtime. This guide walks the six steps from inventory to cutover, including the Exchange Web Services to Microsoft Graph work that teams underestimate, and the side-by-side technique that lets you switch users over gradually instead of all at once.
Key Takeaways
It is a rebuild, not a port
VSTO and Office.js share no code or runtime. You reproduce the behaviour in a new technology, so start by mapping features, not copying code.
Assess against supported scenarios first
Microsoft maintains a table of which Outlook scenarios web add-ins support. Map every feature to it before committing, to flag gaps early.
EWS must become Microsoft Graph
Exchange Web Services stops accepting add-in connections on 1 October 2026, so mailbox data access moves to Graph. This is often the most underestimated piece.
Sandbox limits force some redesign
Anything the VSTO add-in did on the local machine cannot run in the sandboxed web add-in and must move to a backend or a new design.
Run both in parallel during the move
Equivalent-add-in markup or Group Policy lets the VSTO add-in and the web add-in coexist on classic Outlook with no duplicate buttons.
Cut over gradually, then retire VSTO
Pilot the web add-in, run a parallel period to confirm parity, then flip preference and remove the VSTO add-in.
Step 1: Inventory and assess every feature
Before writing any code, list everything the VSTO add-in does and map each feature to Microsoft's supported-scenarios table for Outlook web add-ins. This tells you which features port cleanly, which need a different approach, and which depend on capabilities the sandboxed web model does not have, such as local file access. The assessment is what makes the rest of the migration predictable.
The most expensive migration mistake is starting to build before you know what does not translate. So the first step is a full inventory of the add-in's features, including the quiet ones nobody documented, and a frank assessment of each against what Outlook web add-ins can do.
Microsoft maintains a table of key Outlook scenarios and their support status in web add-ins, and it is updated as the API closes gaps. Walk your feature list against it. Most mail-reading, compose, and ribbon-command scenarios are fully supported. The ones to flag are anything that touched the local machine, drove another desktop application through automation, or relied on deep COM access, because those do not have a direct web equivalent.
Come out of this step with three buckets: features that port directly, features that need a redesigned approach (usually moving work to a backend), and features that need a product conversation because the web model genuinely does them differently. That triage drives the scope, the timeline, and the cost, and it prevents the nasty surprise of discovering a blocker halfway through the build.
Step 2: Design the new architecture
The destination is an Office.js web add-in: HTML, CSS, and JavaScript or TypeScript that Outlook loads in a sandboxed task pane, almost always paired with a backend service you host. The backend matters more here than people expect, because it is where the things the sandbox cannot do move to.
A useful way to think about it: the add-in is the part that runs inside Outlook and touches the mail item and the UI, and the backend is the part that does everything the sandbox forbids, talking to your databases, calling other systems, holding secrets, and doing heavy processing. Where the VSTO add-in read a local file or reached another desktop app, the web version routes that through the backend or rethinks it.
This is also where you decide your authentication model, single sign-on through Office.js with calls to Microsoft Graph, and your hosting. Getting the architecture right up front is what keeps the build from turning into a series of dead ends when a feature you assumed would be simple turns out to need a server.
Step 3: Rebuild the UI as a task pane and commands
VSTO add-ins typically used Windows forms and custom panes. The web add-in replaces those with a task pane, which is your main interface, and ribbon commands, which are the buttons that launch actions. Rebuilding the UI is usually the most straightforward part of the migration, because it is ordinary web development once the architecture is set.
The piece that needs care is event-based activation. Many VSTO Outlook add-ins did something on send, such as stamping a disclaimer, checking recipients, or enforcing a compliance rule. Web add-ins support on-send and other event-based activation, but the handler must be fast and idempotent, because it sits directly in the user's send action. A slow or double-firing on-send handler is the quickest way to make users resent the new add-in, so this is where to spend testing effort.
Throughout, you work in the Office.js proxy-and-sync model, queuing reads and writes and flushing them with context.sync, and batching to keep things fast. If your team is new to that model, our field guide to Office.js covers the pattern and the traps.
Step 4: Replace Exchange Web Services with Microsoft Graph
If your VSTO add-in read or wrote mailbox data through Exchange Web Services, that access must move to Microsoft Graph, because EWS stops accepting connections from add-ins on 1 October 2026. The add-in gets an identity token via single sign-on, exchanges it for an access token, and calls Graph for mail, calendar, and contacts. This is frequently the most underestimated part of the migration.
This is the workstream teams forget to budget for, and it can be as large as the UI rebuild. Many older Outlook add-ins used Exchange Web Services to reach mailbox data beyond what was available in the add-in itself. EWS is being switched off for add-ins on 1 October 2026, so the migration is not done until that data access is moving through Microsoft Graph instead.
Practically, you set up single sign-on so the add-in gets an identity token for the signed-in user, exchange that token for an access token with the right Graph scopes, and call Graph for the mail, calendar, contact, and file operations the add-in needs. It means learning a second API surface alongside Office.js, which is exactly why it surprises teams that scoped only for the UI rebuild.
Treat this as its own track with its own testing, especially around permissions and consent, because Graph scopes and admin consent are where these integrations most often stumble in the field. Build it on Graph from the start rather than porting EWS calls, since porting to a dying API just creates a second migration later.
Step 5: Run the VSTO and web add-ins side by side
You do not have to flip everyone at once, and you should not. On classic Outlook you can have the VSTO add-in and the new web add-in installed together, and control which one is active so users never see duplicate buttons or get conflicting behaviour on the same mail item.
The mechanism is the equivalent-add-in markup in the web add-in's manifest, where you name the legacy add-in by its ProgId and mark it as equivalent, or a Group Policy setting that achieves the same thing centrally without touching the manifest. With that in place, you can roll the web add-in out to a pilot group, keep the VSTO add-in active for everyone else, and shift preference as confidence grows.
During this period a shared code library can help if parts of your logic can be expressed once and used by both, reducing duplicated work while the two run together. The goal of this step is a safety net: real users on the new add-in, the old one ready to fall back to, and no window where both fight over the same email.
<!-- In the web add-in manifest: mark the VSTO add-in as equivalent -->
<VersionOverrides>
<!-- ... -->
<EquivalentAddins>
<EquivalentAddin>
<ProgId>ContosoOutlookAddin</ProgId>
<Type>COM</Type> <!-- "COM" covers both COM and VSTO -->
</EquivalentAddin>
</EquivalentAddins>
</VersionOverrides>Migrations go wrong when they start late and the parallel-running period gets squeezed out. If your organisation is moving to new Outlook and you have a VSTO add-in that has to come with it, the assessment in step one is the cheapest, highest-leverage thing you can do now. We run these migrations end to end. See how on our page.Office Add-in development services
Step 6: Cut over and retire the VSTO add-in
With the web add-in piloted and a parallel period behind you confirming it matches the old behaviour, you flip preference so the web add-in becomes the active one for everyone, then retire the VSTO add-in. Because users were already running the new add-in alongside the old one, this is an anticlimax rather than an event, which is exactly what you want.
Plan the retirement deliberately. Uninstall the VSTO add-in through whatever deployment mechanism installed it, confirm the web add-in is the equivalent everywhere, and communicate the change so support knows what users will see. Keep the rollback option, leaving the VSTO add-in available for a short grace period, until you are confident.
Running both is only ever a transition state, not a destination, because a COM or VSTO add-in and a web add-in operating on the same surface can interfere. The point of the parallel period is a clean, low-risk cutover with a net underneath, after which you collapse to a single web add-in that also happens to now work on Mac, the web, and mobile.
What goes wrong, and what needs a rethink?
Two categories of trouble. First, the timeline. A migration typically runs three to nine months, and the single biggest risk is starting too late, which compresses or eliminates the parallel-running period and forces shortcuts precisely when reliability matters most. Every month of delay also shortens testing time before your organisation's switch to new Outlook.
Second, the scenarios that genuinely do not map. Anything the VSTO add-in did on the local machine, reading local files, driving another desktop application, deep COM operations, cannot run in the sandboxed web add-in. Those features need a redesign: move the work to a backend service, use a different integration pattern, or in rare cases keep a small desktop component for that one job. This is why the step-one assessment matters so much, because discovering a non-mappable feature in month four is far more expensive than flagging it in week one. For the strategic context behind all of this, see our overview of VSTO add-ins in 2026.
What maps directly vs what needs a rethink
| VSTO capability | Web add-in equivalent | Effort |
|---|---|---|
| Read / compose mail item | Office.js mailbox APIs | Direct |
| Ribbon buttons and panes | Add-in commands + task pane | Direct |
| On-send / event handling | Event-based activation | Moderate (must be fast, idempotent) |
| Mailbox data via EWS | Microsoft Graph + SSO | Significant (its own workstream) |
| Local file / machine access | Backend service or redesign | Significant (no direct equivalent) |
| COM automation of other apps | Redesign or backend | Case by case |
Frequently asked questions
Can I port my VSTO code directly to a web add-in?
No. VSTO (C#/.NET) and Office.js (JavaScript/TypeScript) share no code or runtime, so a migration is a rebuild. You reproduce the add-in's behaviour in the new technology, which is why the process starts with mapping features rather than copying code.
Do I have to replace EWS during the migration?
If your add-in used Exchange Web Services for mailbox data, yes. EWS stops accepting connections from add-ins on 1 October 2026, so that access moves to Microsoft Graph with single sign-on. It is often the most underestimated part of the work.
Can users keep using the old add-in while I migrate?
Yes, on classic Outlook. Using equivalent-add-in markup or a Group Policy setting, the VSTO add-in and the new web add-in can coexist with no duplicate buttons, so you can pilot the web add-in and shift users over gradually rather than all at once.
What if a feature has no web add-in equivalent?
Features that touched the local machine, like reading local files or automating other desktop apps, cannot run in the sandboxed web model. They are redesigned, usually by moving the work to a backend service. The step-one assessment flags these before you build.
How long does a VSTO Outlook migration take?
Typically three to nine months depending on complexity and how much EWS-to-Graph work is involved. Starting before your organisation switches to new Outlook leaves room for a parallel-running period, which is what keeps the cutover low risk.
Will the web add-in do everything my VSTO add-in did?
For most scenarios, yes, and the gap keeps narrowing as Microsoft adds APIs. The exceptions are deep local-machine operations, which move to a backend or a redesign. Mapping your features against Microsoft's supported-scenarios list early tells you exactly where you stand.
A rebuild done in the right order is a non-event
Migrating a VSTO Outlook add-in to the web sounds daunting and is not, provided you do it in order: assess every feature against what web add-ins support, design an architecture where the backend absorbs what the sandbox cannot do, rebuild the UI and event handlers, move mailbox data from EWS to Microsoft Graph, run both add-ins side by side with a safety net, then cut over and retire the old one. The risk lives almost entirely in starting late and skipping the parallel period. If your add-in needs to make the move and you would rather hand it to a team that has done it before, tell us what the add-in does and we will start with the assessment. Reach out through our contact page whenever you are ready.