Migrating Your VSTO Outlook Add-Ins Before April 2026

Why You Must Migrate Your VSTO Add-Ins Before April 2026

Microsoft has set a hard deadline. By April 2026, the new Outlook for Windows will become the default mail client for enterprise Microsoft 365 subscribers, and the classic Outlook that your VSTO and COM add-ins depend on will enter a deprecation path with no further feature investment. If your organisation relies on custom VSTO add-ins for critical business workflows, the clock is ticking.

This is not a speculative change or a distant roadmap item. New Outlook became the default for small and medium business customers in January 2025. Enterprise organisations were given an extended timeline, but April 2026 is the line in the sand. After that date, new installations will default to new Outlook, and Microsoft has been explicit that VSTO and COM add-in models will not be supported in the new client. Additionally, newer versions of Office and Outlook have shifted towards web-based models, further impacting VSTO compatibility and the ability to run traditional add-ins.

For every organisation running legacy add-ins in Outlook, Word, Excel, or PowerPoint, the question is no longer whether to migrate but how to migrate without disrupting the business processes that depend on those add-ins. VSTO and COM add-ins are typically developed using Microsoft Visual Studio, which has historically provided robust integration for Office development.

What Is Actually Changing

To understand the urgency, it helps to understand what Microsoft is doing and why.

Many organisations have deployed custom VSTO add-ins to extend Microsoft Office functionality. These VSTO solutions can include various project types, such as add-ins, document-level customizations, and application-level projects, depending on the business requirements and the capabilities of different Visual Studio versions.

The End of Classic Outlook

Classic Outlook for Windows, the desktop application that has been the backbone of enterprise email for over two decades, is being replaced by new Outlook. The new client is built on web technologies and shares its codebase with Outlook on the web. It is faster, more consistent across platforms, and significantly easier for Microsoft to maintain and update.

Critically, new Outlook does not support VSTO (Visual Studio Tools for Office) add-ins or COM (Component Object Model) add-ins. These technologies rely on deep integration with the Windows desktop application runtime, a runtime that does not exist in the new web-based client. In classic Outlook, the application loads VSTO assemblies directly into its process, allowing for rich integration and customisation—this capability is not available in the new web-based Outlook.

VSTO and COM: Why They Cannot Be Carried Forward

VSTO add-ins are .NET assemblies that run inside the Office application process. They have full access to the Office object model and the Windows operating system. This allows developers to perform a wide range of operations within the Office client, including accessing local resources and integrating with other applications. COM add-ins operate similarly, loading as native code within the Office process. Both technologies were designed for a world where Office was a desktop application running on Windows.

The new Outlook is fundamentally different. It runs in a web-based rendering engine. There is no .NET runtime to host VSTO assemblies. There is no COM infrastructure to load native add-in DLLs. Microsoft has stated explicitly that they will not port these technologies to the new platform. The statement from the Office product team is unambiguous: VSTO will not be updated for .NET Core or .NET 5+, and there are no plans to bring COM add-in support to new Outlook.

This is not a temporary gap that will be filled in a future update. It is an architectural decision that reflects the direction of the entire Microsoft 365 platform.

Primary Interop Assemblies and Compatibility

When working with VSTO add ins in Microsoft Office, ensuring compatibility across different Office versions is critical for both stability and user experience. At the heart of this compatibility are Primary Interop Assemblies (PIAs)—special libraries that allow .NET code to communicate directly with Office applications like Word, Excel, and Outlook. PIAs provide the type information needed for Visual Studio Tools for Office (VSTO) add ins to interact with the Office object model, enabling rich features and deep integration.

For example, if you’re building a VSTO add in for Office 2016, you must use the Office 2016 PIAs. Using mismatched versions can lead to subtle bugs, missing features, or even prevent your add in from loading. This is especially important for organisations supporting multiple Office versions, as each version of Microsoft Office requires its own set of PIAs to ensure full functionality.

To maximise compatibility and minimise support headaches, follow these best practices:

1. Match PIAs to Office Version: Always use the Primary Interop Assemblies that correspond to your target Office version. These can be installed via Visual Studio, downloaded from Microsoft, or included in your deployment package.

2. Target the Right .NET Framework: Make sure your VSTO add in is built against a .NET Framework version supported by your chosen Office version. This ensures your code can leverage all the features and APIs available.

3. Test Across Office Versions: Don’t assume compatibility—test your add in on every Office version your users run. This helps catch version-specific issues before they impact productivity.

4. Consider Late Binding or Reflection: If your add in must support multiple Office versions, using late binding or reflection in your code can help you avoid hard dependencies on specific PIAs, increasing flexibility and reducing maintenance.

Beyond PIAs, every VSTO add in also depends on the VSTO runtime—a component that enables .NET code to run inside the Office application. Without the VSTO runtime, your add in simply won’t load. To ensure a smooth installation experience for your users, you have several options:

• Bundled Installation: The VSTO runtime is often included with Visual Studio or the Office developer tools, but you can also package it with your add in installer to guarantee it’s present.

• Standalone Download: Microsoft provides the VSTO runtime as a separate download, allowing IT teams to install it on client machines as part of their standard Office deployment.

• Automatic Deployment: Many organisations choose to deploy the VSTO runtime alongside their add in, ensuring that all prerequisites are met with a single installation process.

By carefully managing your use of PIAs and the VSTO runtime, you can deliver VSTO add ins that are robust, compatible, and easy to install—no matter which version of Microsoft Office your users rely on. This attention to detail not only reduces support calls but also ensures your add in delivers its full range of features and functionality across every office application and version your business depends on.

The Modern Web Add-In Model

The replacement is the Office Web Add-In model (sometimes called Office JS add-ins or simply modern add-ins). These add-ins are built using standard web technologies: HTML, CSS, and JavaScript. The add-in is rendered as a webpage within the Office application, providing users with a familiar web-based interface. They run in a sandboxed browser context within the Office application and interact with Office through the office.js API.

The web add-in model works across all Office platforms: Windows (classic and new), Mac, web, and mobile. This cross-platform capability is one of the primary reasons Microsoft is pushing the transition. A single add-in built to the web model works everywhere, whereas VSTO add-ins only work on Windows desktop.

The Migration Timeline

Understanding the timeline is essential for planning a migration that does not disrupt your business.

January 2025. New Outlook became the default for new Microsoft 365 Business (SMB) subscriptions. SMB users opening Outlook for the first time on a new machine see new Outlook unless their administrator has configured a policy override.

Throughout 2025. Microsoft is progressively expanding the new Outlook rollout. Feature parity with classic Outlook continues to improve, and the toggle to switch back to classic Outlook remains available but is positioned as a temporary measure.

April 2026. New Outlook becomes the default for enterprise Microsoft 365 subscribers. This is the point at which most large organisations will feel the impact. New deployments and device refreshes will default to new Outlook. Existing classic Outlook installations will not be forcibly removed, but they will receive no new features and limited security updates.

Beyond April 2026. Microsoft has not published an end-of-support date for classic Outlook, but the trajectory is clear. Classic Outlook will receive security patches for a period after April 2026, but it is entering end-of-life. Organisations that have not migrated their add-ins will be running on a platform with a finite remaining lifespan.

The practical implication is this: if your organisation has custom VSTO or COM add-ins that are critical to business operations, you need to have a working web add-in replacement deployed before April 2026. Given that a typical migration project takes three to nine months depending on complexity, the window for starting that project is closing rapidly. Organisations must decide on their migration approach and timeline as soon as possible to avoid last-minute disruptions.

Key Architectural Differences Between VSTO and Web Add-Ins

Migration is not a straightforward port. The architectural differences between VSTO and web add-ins are significant, and understanding them is essential for planning a realistic migration project. The ability to access certain features and system resources differs significantly between VSTO and web add-ins, which can impact the functionality available in your solution.

Execution Model

VSTO add-ins run as .NET assemblies inside the Office process with full access to the Office object model, the Windows API, and any .NET library. For instance, a VSTO add-in can interact directly with a Microsoft Word document to automate formatting tasks or with OneNote to enhance note-taking by integrating local data sources. Web add-ins run in a sandboxed browser context and interact with Office exclusively through the office.js API. They cannot access the file system or run arbitrary .NET code.

Office API Surface

VSTO provides access to the complete Office object model via COM interop. Web add-ins use office.js, which provides a curated but increasingly comprehensive API. While office.js covers the most common scenarios, it does not replicate the full breadth of the COM object model. Some operations that were straightforward in VSTO may require server-side workarounds.

UI and Data Access

VSTO add-ins use Windows Forms or WPF for custom task panes, ribbon tabs, and form regions. Web add-ins render task panes as web pages using HTML/CSS, typically styled with the Fluent UI React component library. Both VSTO and web add-ins can insert various types of content—such as images, diagrams, or data visualizations—directly into Office documents, making it easy to enhance documents with multimedia and interactive elements.

For data access, VSTO can connect directly to local databases, the file system, and on-premises services. Web add-ins access data through web APIs over HTTPS, which means on-premises systems must be exposed through a secure API layer. Add-ins can also create and display charts within Excel or PowerPoint, enabling users to visualize data more effectively and make documents more engaging.

Authentication and Deployment

VSTO typically relies on Windows integrated authentication (Kerberos/NTLM). Web add-ins use OAuth 2.0 through Microsoft Identity Platform (Entra ID), with SSO available via the getAccessToken API.

VSTO deploys via MSI, ClickOnce, or Group Policy, requiring redeployment for updates. Web add-ins deploy through the Microsoft 365 Admin Center. Updates to the add-in’s functionality only require updating the hosted web application, with no changes needed on end-user machines.

Planning Your Migration: A Step-by-Step Checklist

A well-planned migration minimises disruption and delivers a modern add-in that is more maintainable, more secure, and works across all Office platforms. Here is a structured approach. Using project templates in Microsoft Visual Studio can streamline the creation of new Office add-ins, providing a pre-configured starting point for your development.

When planning your migration, consider using templates as useful resources for organising, planning, and documenting each stage of the process.

1. Inventory Your Add-Ins

Create a comprehensive inventory of every VSTO and COM add-in deployed in your organisation. For each add-in, document:

• The Office application it extends (Outlook, Word, Excel, PowerPoint).

• The business process it supports.

• The number of users who depend on it.

• The criticality to business operations (critical, important, or nice-to-have).

• The specific Office APIs and Windows APIs it uses.

• Any integrations with backend systems (databases, file shares, on-premises services).

• Who developed and maintains it (internal team, vendor, or contractor).

2. Assess office.js API Coverage

For each add-in, map the VSTO/COM APIs it uses to their office.js equivalents. Identify any gaps where a VSTO capability does not have a direct office.js replacement.

Common areas where gaps may exist include:

• Outlook form regions: Not available in web add-ins. The replacement is a task pane or contextual inline display using the on-message-read or on-message-compose events.

• Low-level document manipulation: VSTO provides access to the full Open XML structure. office.js provides a higher-level API. For complex document manipulation, consider using the Open XML SDK on the server side, invoked by the add-in through a web API.

• Document level customizations: Certain editions of VSTO support document level customizations, allowing deep integration with specific Office documents. office.js does not have a direct equivalent for these customizations, so alternative approaches may be needed.

• Windows API calls: Any add-in that calls Windows APIs directly (file system, registry, COM automation of other applications) will require architectural changes. These operations must move to a backend service.

3. Design the Target Architecture

Based on the API assessment, design the architecture for each web add-in:

• Frontend: HTML/CSS/JavaScript running in the Office task pane. Use Fluent UI React for consistent Office styling. Consider TypeScript for maintainability.

• Backend: A web API hosted in Azure (App Service, Azure Functions) or another cloud provider. This backend handles business logic that cannot run in the browser sandbox, including database access, file processing, and integration with on-premises systems.

• Authentication: Implement SSO using the office.js getAccessToken API and Microsoft Identity Platform. For backend API calls, use the on-behalf-of flow to exchange the Office SSO token for tokens scoped to your backend.

• Data layer: Replace direct database connections with RESTful or GraphQL API calls to your backend service.

4. Plan the Manifest

Web add-ins are defined by a manifest that describes the add-in’s entry points, permissions, and hosting details. The manifest also includes a description field, which details the add-in’s functionality and permissions, helping users and administrators understand what the add-in does. Microsoft is transitioning to a unified manifest format (JSON-based) that supports both add-in and Copilot agent scenarios. For new development, use the unified manifest unless you have a specific reason to use the legacy XML manifest.

5. Build a Proof of Concept

Before committing to a full migration, build a proof of concept that demonstrates the most critical functionality of each add-in in the web model. Focus on the areas identified as highest risk in the API assessment. This proof of concept validates your architectural decisions and surfaces any unexpected limitations early.

6. Develop and Test

Develop the web add-in following Microsoft’s best practices:

• Use the Yeoman generator for Office Add-ins (yo office) to scaffold the project.

• Test across all target platforms: new Outlook, classic Outlook, Outlook on the web, and Outlook mobile if required.

• Implement error handling for scenarios where office.js APIs behave differently across platforms.

• Use the Office Add-in Debugger extension in Visual Studio Code for development and debugging.

7. Plan Deployment and Rollout

• Sideload for development and internal testing.

• Use Centralised Deployment through the Microsoft 365 Admin Center for organisational rollout.

• Plan a parallel running period where both the legacy VSTO add-in and the new web add-in are available. This allows users to transition gradually and provides a fallback if issues are discovered.

• Communicate the migration to end users with training materials and a clear timeline for removing the legacy add-in. Include step-by-step instructions for users to install add ins: instruct them to click the add ins button on the appropriate ribbon tab (often found on the home tab), navigate to the store tab, browse available add-ins, and click continue to complete the installation. These options may appear on different ribbon tabs depending on the Office application.

8. Decommission Legacy Add-Ins

Once the web add-in is validated in production and users have transitioned, decommission the VSTO/COM add-in. Remove it from deployment systems, archive the source code, and update your documentation.

What About Word, Excel, and PowerPoint?

While Outlook is driving the most immediate urgency due to the new Outlook timeline, the same architectural shift applies to Word, Excel, and PowerPoint. Microsoft’s investment is in the web add-in model across all Office applications. VSTO and COM add-ins in these applications will continue to work in the desktop versions for now, but the direction is clear: the web add-in model is the future.

Organisations that are migrating Outlook add-ins should consider migrating Word, Excel, and PowerPoint add-ins at the same time. In particular, migration planning should include excel outlook add-ins and other apps that enhance productivity across these platforms. Excel add ins play a key role in extending spreadsheet functionality, so ensuring these tools are migrated is essential for maintaining business processes. Many apps, including free add in options, are available to support business needs in the new web add-in model. Web add-ins can enhance powerpoint presentations and word document workflows by enabling new features and integrations, such as embedding data visualizations or automating content creation. The web add-in model also allows for seamless interaction with office documents across platforms, supporting integration and interactivity within Word, Excel, and PowerPoint. The architectural patterns are the same, and a coordinated migration avoids having to run parallel add-in infrastructure for an extended period.

The Cost of Waiting

Delaying migration creates compounding risk:

Reduced migration window. Every month of delay shortens the available development and testing time before the April 2026 deadline. Complex add-ins with deep backend integrations require months of development and testing. Starting late means cutting corners or missing the deadline.

Talent availability. As the deadline approaches, demand for developers with VSTO to web add-in migration experience will increase. Engaging a specialist consultancy now ensures availability and competitive pricing. Organizations should also ensure the right user accounts are in place for managing new add-in deployments.

Parallel running risk. A shorter migration timeline compresses or eliminates the parallel running period, increasing the risk of disruption when the legacy add-in is removed.

Technical debt. Every enhancement or bug fix applied to a VSTO add-in between now and migration is work that will be duplicated in the web add-in. Freezing VSTO development and focusing resources on the migration avoids this waste. Some free tools and resources are available to assist with migration, helping to reduce costs.

How McKenna Consultants Can Help

McKenna Consultants has been developing custom Microsoft Office add-ins for over a decade. Our team has deep expertise in both the legacy VSTO/COM model and the modern web add-in architecture, which makes us uniquely positioned to plan and execute migrations.

We specialise in custom Outlook add-in development for UK businesses, and we have guided multiple clients through the transition from VSTO to web add-ins. Our approach covers the full migration lifecycle:

• Assessment and planning: We audit your existing add-ins, map API dependencies, identify risks, and produce a detailed migration plan with realistic timelines.

• Architecture design: We design the target web add-in architecture, including backend services, authentication flows, and integration with your existing systems.

• Development and testing: We build the web add-in, test across all Office platforms, and ensure feature parity with the legacy add-in.

• Deployment and transition: We manage the rollout through centralised deployment, support the parallel running period, and help decommission the legacy add-in.

If your organisation has VSTO or COM add-ins and you have not yet started planning the migration, the time to act is now. Contact McKenna Consultants to discuss your migration requirements and timeline.

The new Outlook add-in migration 2026 deadline is not a theoretical future event. It is a concrete timeline backed by Microsoft’s strategic decision to unify Office around the web platform. VSTO and COM add-ins have served organisations well for two decades, but their architectural model is incompatible with where Office is going.

Migration from VSTO to web add-ins is achievable. The office.js API surface is mature, the development tooling is strong, and the resulting add-ins are more portable, more secure, and easier to deploy than their legacy predecessors. But it requires planning, development time, and testing across platforms.

With fewer than twelve months until the enterprise deadline, the window for a well-planned migration is closing. Organisations that start now will have time to build a proper proof of concept, run a parallel deployment period, and transition users smoothly. Those that wait risk a rushed migration, disrupted workflows, and the uncomfortable position of depending on a platform that Microsoft has stopped investing in.