The VSTO Migration Countdown: Your 60-Day Implementation Guide for April 2026
The April 2026 VSTO migration deadline is no longer a future concern. For enterprise development teams that have not yet completed their transition to web add-ins, the window is now measured in weeks. If your organisation is still running Visual Studio Tools for Office (VSTO) add-ins in production, or COM add-ins, this is the guide you need — not the rationale for migrating, but the execution plan for doing it now.
Microsoft’s position is unambiguous: VSTO, COM, and VBA-based Office extensions are no longer the supported extensibility model. The Office Add-ins platform — built on Office.js, web standards, and the Microsoft 365 ecosystem — is where all future investment is directed. Organisations that miss the VSTO migration deadline face add-ins that break, features that stop working, and the prospect of emergency migration under the worst possible conditions.
At McKenna Consultants, we have guided enterprise clients through VSTO-to-web-add-in migrations and understand what separates teams that complete on time from those that do not. This guide gives you the week-by-week implementation checklist to get there.
Week 1: Triage, Decisions, and Architecture Selection
The first week is the most consequential. Teams that spend it in analysis paralysis or committee-driven debate will not make the deadline. Teams that make clear, documented decisions — even imperfect ones — will.
The Add-In Inventory Decision: Migrate, Retire, or Rebuild
Begin with a complete audit of every VSTO add-in your organisation runs. For each add-in, make one of three decisions:
Migrate: The add-in provides active business value, its functionality maps reasonably well to the Office.js API surface, and the migration effort is within your capacity. This is the default path.
Retire: The add-in is no longer actively used, duplicates functionality available in Microsoft 365 natively, or exists purely for legacy compliance with a process that has changed. Do not migrate what you do not need.
Rebuild: The add-in relies on capabilities that Office.js does not replicate (deep COM interop, raw binary file manipulation, OS-level access) and the business requirement still exists. These require a redesign, not a port. If you have add-ins in this category, escalate them immediately — they are your highest risk items.
A prioritisation matrix helps structure this decision:
| Criterion | Weight | Questions to Ask |
|---|---|---|
| Business criticality | High | What breaks if this add-in is unavailable after April? |
| User adoption | Medium | How many users rely on it daily vs occasionally? |
| API coverage | High | Does Office.js cover the core functionality? |
| Codebase complexity | Medium | How much VSTO-specific code vs business logic? |
| Authentication dependencies | High | Does it use Windows identity or legacy auth? |
Architecture Selection: Which Add-In Surface?
The second decision is which Office add-in surface each migrated add-in should use. Web add-ins support three primary surfaces, and selecting the wrong one creates rework.
| Surface | Best For | Office.js Entry Point |
|---|---|---|
| Task pane | Persistent UI panels alongside documents; workflow tools, data entry, search | Office.onReady() with task pane manifest |
| Content add-in | Embedding interactive content inside documents (charts, dashboards, forms) | Office.onReady() with content manifest |
| Function commands | Ribbon buttons that execute single actions without a visible UI | Office.actions.associate() |
| Event-based add-in | Background execution triggered by document events (e.g., email compose, send) | Event handlers in manifest |
Most VSTO add-ins that present a side panel or toolbox map naturally to task pane add-ins. VSTO add-ins that add ribbon buttons with simple actions map to function commands, or to task pane add-ins launched from ribbon buttons if they require user input.
Weeks 2–3: Office.js API Equivalents for Common VSTO Patterns
The most time-consuming part of any migration is mapping VSTO code to its Office.js equivalent. Below are the patterns your team will encounter most frequently.
Document and Workbook Access
In VSTO, you accessed the active document via the Globals class:
// VSTO
var doc = Globals.ThisAddIn.Application.ActiveDocument;
var selection = doc.ActiveWindow.Selection;
selection.Text = "Hello from VSTO";
In Office.js, all document interactions are asynchronous and run in a context.sync() batch:
// Office.js (Word)
await Word.run(async (context) => {
const range = context.document.getSelection();
range.insertText("Hello from Office.js", Word.InsertLocation.replace);
await context.sync();
});
This asynchronous model is the single most significant conceptual shift for VSTO developers. Every Office.js operation that reads or writes document content must go through the request-response pattern — you load properties, sync, then read the returned values.
Excel Range Operations
| VSTO Pattern | Office.js Equivalent |
|---|---|
worksheet.Range["A1"].Value2 = data | range.values = [[data]] |
worksheet.Cells[row, col] | worksheet.getCell(row, col) |
chart.SetSourceData(range) | chart.setData(range) |
worksheet.UsedRange | worksheet.getUsedRange() |
Range.AutoFit() | range.format.autofitColumns() |
Ribbon Customisation
VSTO ribbon customisation used XML and a code-behind file. Web add-ins define their ribbon contributions in the add-in manifest (or the new unified manifest for Microsoft 365). The declarative approach in the manifest replaces the ribbon designer.
For complex ribbon scenarios, the RibbonX patterns translate to unified manifest extensions.ribbons declarations. Custom task pane visibility toggling — a common VSTO pattern — becomes a command that launches or focuses the task pane via Office.addin.showAsTaskpane().
Custom Task Pane vs Task Pane Add-In
A frequently misunderstood migration challenge: VSTO’s CustomTaskPane is not the same as a web add-in task pane. VSTO custom task panes could be docked anywhere in the Office window and host Windows Forms or WPF controls. Web add-in task panes render in a fixed side panel using a web view. If your VSTO add-in relies on floating, dockable, or resizable task pane positioning, you need to redesign the UX — the web add-in model does not support arbitrary docking.
Week 3: Authentication Migration — Windows Identity to Microsoft Entra ID
Authentication is where migrations most commonly stall. VSTO add-ins frequently relied on Windows Integrated Authentication, NTLM, Kerberos, or the Active Directory user context available via WindowsIdentity.GetCurrent(). None of these mechanisms are available to web add-ins running in a sandboxed browser process.
The replacement is Microsoft Entra ID (formerly Azure Active Directory) with OAuth 2.0, using either:
-
Single Sign-On (SSO) via Office.js — the preferred approach.
OfficeRuntime.auth.getAccessToken()returns a bootstrap token that your web add-in exchanges server-side for a Microsoft Graph access token. The user signs in once via Microsoft 365; your add-in inherits that session silently. -
MSAL.js in the task pane — a fallback for scenarios where SSO is not available (older Office versions, unsupported platforms). The user authenticates in a pop-up dialog managed by MSAL.
The SSO flow requires:
- An Azure App Registration with the
openid,profile, andoffline_accessscopes - The add-in’s web app URL registered as a redirect URI
- The App ID URI in the format
api://{domain}/{clientId} - In the manifest:
<WebApplicationInfo>(legacy manifest) or the equivalent in the unified manifest
For add-ins that call back-end APIs protected by Windows authentication, the migration typically involves standing up a service endpoint that accepts Entra ID tokens and bridges to the legacy backend — rather than expecting the browser-hosted add-in to perform Windows auth directly.
If your organisation uses on-premises Exchange or SharePoint without Entra ID Connect, this authentication migration is your longest dependency. Start it in Week 1, not Week 3.
Week 4: Testing Strategy — Parallel Deployment
The safest migration strategy for enterprise teams is parallel deployment: running your VSTO add-in and its web add-in replacement simultaneously for a controlled group of users, before cutting over entirely. This reduces the risk of service disruption if the web add-in has gaps or defects in production scenarios your development environment did not surface.
Setting Up Parallel Deployment
VSTO and web add-ins use entirely different deployment mechanisms and do not conflict at the registry level. This means you can deploy a web add-in to your pilot group while VSTO add-ins remain installed for the broader organisation.
Web add-ins are deployed via:
- Microsoft 365 Admin Centre (Integrated Apps) — recommended for enterprise deployment
- SharePoint App Catalog — for organisations without Microsoft 365 Admin access
- Centralised Deployment (legacy mechanism, still supported)
- Sideloading — for development and piloting
For parallel deployment:
- Package your web add-in and deploy it to a security group via the Microsoft 365 Admin Centre
- Keep the VSTO add-in installed via Group Policy or Intune for the broader population
- Your pilot group will see both the VSTO add-in and the web add-in available — communicate clearly which to use
- Define a feedback mechanism (Teams channel, shared document, bug tracker) for pilot users to report issues
- Run the parallel phase for a minimum of two weeks under normal workload conditions
What to Test in Parallel Phase
| Test Category | What to Validate |
|---|---|
| Core workflows | Every documented user workflow completes correctly in the web add-in |
| Document compatibility | Output documents from the web add-in open correctly in VSTO and vice versa |
| Authentication | SSO works on first launch; re-auth prompts appear correctly when tokens expire |
| Performance | Task pane loads within acceptable time; operations are not perceptibly slower |
| Offline behaviour | Behaviour when network is unavailable matches user expectations |
| Edge cases | Large documents, complex formatting, concurrent multi-user scenarios |
Week 5: Manifest, Deployment, and Admin Centre Configuration
Choosing a Manifest Format
Microsoft supports two manifest formats as of early 2026:
- Add-in only manifest (XML, legacy): The established format, supported across all Office versions. Choose this if you need broad compatibility including Office 2019 and Office 2021 perpetual licences.
- Unified manifest (JSON, Microsoft 365 Apps only): The new format that positions your add-in for Copilot extensibility and deeper Microsoft 365 integration. Choose this if your organisation runs Microsoft 365 Apps for Enterprise and you anticipate integrating with Copilot agents.
For most enterprise migrations executing under deadline pressure, the add-in only manifest is the pragmatic choice — it is the established format with the widest tooling support and documentation.
Microsoft 365 Admin Centre Deployment
- Navigate to Microsoft 365 Admin Centre > Settings > Integrated Apps
- Select Upload custom apps and provide your manifest file or AppSource link
- Assign to specific users, groups, or the entire organisation
- Set deployment status to Available for pilot, then Mandatory for full rollout
Mandatory deployment (formerly “Fixed”) pushes the add-in to every assigned user’s Office ribbon without requiring them to install it. This is the mechanism that replaces Group Policy-based VSTO deployment.
For organisations using Intune for device management, you can configure add-in assignment via Intune’s Microsoft 365 Apps policy, targeting based on Azure AD security groups.
Week 6: Decommission VSTO and Final Cutover
With your web add-in in production for your pilot group and validated, Week 6 is the cutover and decommission phase.
VSTO Removal
VSTO add-ins are installed via one of three mechanisms:
- ClickOnce deployment (per-user, from a network share or URL)
- Windows Installer (MSI)
- Group Policy for managed deployment
Remove them using the corresponding mechanism:
- ClickOnce: Remove the deployment from the network share; Office will stop updating and prompt users to remove it
- MSI: Deploy a removal script via Intune or SCCM
- Group Policy: Remove the GPO entry that installs the add-in; it will be removed on next Group Policy refresh
Communicate the removal to users in advance. Include a clear message that the web add-in is the replacement and where to find it.
The 60-Day Checklist at a Glance
| Week | Key Actions |
|---|---|
| Week 1 | Audit all VSTO add-ins; decide migrate/retire/rebuild; select add-in surfaces |
| Week 1 | Create Azure App Registrations for Entra ID authentication |
| Week 2 | Map VSTO APIs to Office.js equivalents; begin development sprint |
| Week 3 | Implement SSO authentication via OfficeRuntime.auth; test auth flows |
| Week 3 | Develop Office.js manifest; sideload and test in development environment |
| Week 4 | Deploy web add-in to pilot security group via Admin Centre |
| Week 4 | Begin parallel deployment phase; collect pilot feedback |
| Week 5 | Resolve pilot issues; validate all test categories pass |
| Week 5 | Configure organisation-wide deployment as Mandatory |
| Week 6 | Remove VSTO add-ins via Intune/GPO |
| Week 6 | Confirm all users have migrated; decommission VSTO deployment infrastructure |
| Week 6 | Document new add-in for IT and end users |
The Dual Migration Challenge: EWS and VSTO Together
Teams building Outlook add-ins face a second, overlapping migration that compounds the complexity: Microsoft’s deprecation of Exchange Web Services (EWS). If your current Outlook VSTO add-in calls EWS endpoints for mail, calendar, or contact operations, you face two concurrent migration tracks — VSTO to web add-in, and EWS to Microsoft Graph.
Microsoft has confirmed that EWS blocking enforcement begins in phases through 2026, with the October 2026 date applying to the majority of Microsoft 365 commercial tenants. Frontline and kiosk licences see EWS calls blocked earlier.
The good news is that the VSTO-to-web-add-in migration and the EWS-to-Graph migration are architecturally complementary. Web add-ins authenticate via Entra ID, and Microsoft Graph uses the same OAuth 2.0 tokens. The SSO flow you implement for your add-in’s general authentication is the same flow that provides Graph API access. You are not building two authentication systems — you are building one modern one.
The EWS-to-Graph API mapping, migration strategies, and the AppID AllowList mechanism for organisations that cannot complete by October are covered in depth in our forthcoming article on the EWS to Microsoft Graph migration. If you are managing both migrations simultaneously, we recommend reading that guide alongside this one and planning them as a single integrated project rather than two sequential workstreams.
Common Mistakes That Cause Migrations to Fail
Having worked through enterprise VSTO migrations with clients, these are the patterns we see most often derail teams executing under deadline pressure:
Underestimating the async programming model shift. VSTO developers working in C# with synchronous COM interop consistently underestimate how different the async Office.js model is. Allocate explicit training time for your development team before writing production code.
Leaving authentication to the end. Authentication dependencies — particularly on legacy identity infrastructure — are the most common source of missed deadlines. Treat auth as Week 1 work, not Week 4.
Migrating before retiring. Teams that migrate every add-in without first retiring unused ones extend their timeline unnecessarily. Retire aggressively.
Skipping the parallel deployment phase. Teams that cut over directly from VSTO to web add-in without a piloting period are exposed to production incidents that a parallel phase would have caught. The two-week cost of parallel deployment is less than the cost of a post-cutover incident.
Treating the manifest as an afterthought. The add-in manifest is not boilerplate — it controls add-in discovery, surface availability, command placement, and SSO configuration. Errors in the manifest are the most common cause of add-in deployment failures in the Admin Centre.
How McKenna Consultants Can Accelerate Your Migration
McKenna Consultants is a UK-based Office add-in development consultancy with a track record of delivering complex add-in projects for enterprise clients. We have migrated VSTO add-ins to the web add-in platform for enterprise organisations, and our experience with the Office.js API surface, authentication architecture, and Microsoft 365 deployment mechanisms means we can compress the timeline that an internal team executing this for the first time would require.
If your organisation is facing the VSTO migration deadline April 2026 with incomplete or not-yet-started migration work, we can provide:
- Migration assessment: A structured audit of your VSTO add-ins with migrate/retire/rebuild recommendations and an honest effort estimate
- Architecture design: Surface selection, manifest design, and authentication architecture for your specific environment
- Development delivery: Full development of your web add-in replacements, including Office.js implementation and SSO integration
- Deployment support: Admin Centre configuration, pilot deployment management, and cutover coordination
- Dual-migration planning: Integrated planning for teams facing both the VSTO and EWS migrations simultaneously
Whether you need a team to take full ownership of the migration or expert guidance to support your internal developers, we can structure an engagement to fit your situation.
The VSTO to web add-in migration checklist 2026 is achievable in 60 days for organisations with focused intent and the right expertise. The teams that will not make the April deadline are the ones that start in March.
Contact McKenna Consultants today to discuss your VSTO migration requirements. Our Office add-in development consultancy UK team is ready to help you meet the deadline.
