Migrate SharePoint Add-ins to SharePoint Framework - FAQ

A few months ago, I published an article summarizing Microsoft’s announcement regarding the retirement of SharePoint Add-in and Azure Access Control Services (ACS). Since then, I’ve spoken to several customers who have had numerous questions about the retirement plan and how to proceed with the SharePoint Add-ins. In this article, I would like to take a few minutes to address some of the common questions that have been raised.

First, let’s recap what Microsoft has said.

SharePoint retirement plans summarized

In November of 2023, it was announced that the SharePoint Add-in model and Azure ACS would be retired in 2026. This decision followed the earlier announcement in 2023 that Microsoft plans to retire the SharePoint 2013 workflow engine in 2026.

Let’s review some key milestones related to this retirement plan.

• Starting in March of 2024, Microsoft will no longer accept new submissions of SharePoint Add-ins to the SharePoint store.
• In July 2024, customers will no longer be able to install SharePoint Add-ins from the store into their SharePoint tenants.
• In November 2024, all infrastructure and services related to SharePoint Add-ins will no longer be enabled for new Microsoft 365 tenants. The same applies to Azure ACS. It won’t be enabled for new Microsoft 365 tenants, but existing tenants will still have access to the SharePoint Add-in. All infrastructure and services supporting SharePoint Add-ins and Azure ACS will remain active and operational.
• Then, in April 2026, Microsoft will shut down all three services: SharePoint Add-ins, SharePoint 2013 workflow, and Azure ACS. This change will apply to all existing Microsoft 365 tenants.

For more information, you can refer to the article and video published in December of 2023: SharePoint Add-in model retirement + other services unpacked

Migrating SharePoint Add-ins to supported scenarios

While there is a migration story for almost every scenario you can think of, there are two scenarios where there is no migration path. We’ll lose the capabilities and functionality of these two scenarios.

SharePoint Add-in lifecycle events

The first blocker revolves around app deployment lifecycle events. In the SharePoint Add-in model, we can trigger an event and notify a remote endpoint or web service when an app is installed or about to be uninstalled. This is useful for implementing a first-run experience, such as provisioning necessary resources such as lists or libraries. However, this functionality does not exist in the SharePoint Framework (SPFx) or outside of the Add-in model and Microsoft currently has no plans to implement it.

For example, if you deploy a web part that requires certain lists to be present, you’ll need to check if those lists exist when the web part is added to the page. If the lists are missing, you can display a message instructing the user to provision the required lists. If the user has the necessary permissions, you can programmatically provision the lists.

Remote event receivers

Another feature we’ll lose is related to remote event receivers (RER’s). Remote event receivers are similar to webhooks but also support synchronous operations and cancelable events. Unfortunately, there is no alternative functionality outside of the SharePoint Add-in model, and Microsoft has no plans to create something similar.

For example, if you were using RER’s to control the addition of items to a list you can create a custom form using the SPFx list form customizers to control the data being submitted and added to the list. Just keep in mind that this is just one way to add items to a list. Other options include using PowerApps, the SharePoint REST API, and the Microsoft Graph. The form created with the SPFx will not block these other options, so make sure to consider that your form isn’t a fool-proof way to block data from being added to a list. Unfortunately, there’s easy no way to implement that without RER’s in modern SharePoint.

Porting SharePoint Add-ins to the SharePoint Framework (SPFx)

Let’s discuss the process of moving your SharePoint Add-ins to the SPFx, which is the natural progression for SharePoint Hosted Add-ins. It’s worth noting that if you’re working with a SharePoint Provider-Hosted Add-in, the process is a little more clear-cut. I haven’t seen many questions about migrating SharePoint Provider-Hosted Add-ins. But if you fall into that camp, please reach out to me with your scenarios & questions (drop a comment at the end of this article).

One important thing to remember is that SharePoint Add-ins can only run on classic pages and not on modern pages. However, SPFx components can run on both modern and classic pages.

What happens to SharePoint Add-ins after the retirement date?

A common question I hear developers ask is:

Most likely, your SharePoint Add-in won’t load on the page. Microsoft won’t delete or uninstall anything because doing so would also remove all associated data on the page. SharePoint doesn’t automatically delete data; Microsoft defaults to letting the user handle data cleanup so customers are responsible for possible data loss… Therefore, your SharePoint Add-in will still be present but won’t run or appear on the page. I want to make this point because this will be relevant in just a minute.

Migrating SharePoint Add-ins deployed to the SharePoint store

What if you have a SharePoint Add-in already deployed to the SharePoint store?

Unfortunately, it seems that you cannot replace your existing SharePoint Add-in package with an SPFx package and expect an automatic upgrade - there is no automatic upgrade process.

Instead, you’ll need to deploy your new SPFx solution as a completely new app. To do this, create a new SPFx project with news GUIDs for your solution and component (web part), and deploy it as a new app.

Can you reuse existing SharePoint Add-in project & component IDs?

Technically, you could create an SPFx project and copy the existing SharePoint Add-ins’ solution web part IDs (GUIDs) and deploy it as a new app. However, I don’t recommend this approach because I can’t see a benefit to doing so. As I said earlier, there’s no option for an automatic upgrade, there’s little if any value in doing this.

These are migration projects, not upgrades. Having two projects in your environment with the same GUID doesn’t seem like a good idea.

How to migrate existing deployed & in-use SharePoint Add-ins to SPFx solutions?

So, how can you migrate your existing installed or deployed solution to the new SPFx-based one?

One option is to use the Patterns & Practices (PnP) Transformation Framework to convert your classic pages to modern pages. Then, use the Microsoft Graph Pages API that’s currently in public preview to add the new SPFx web parts to the page.

Extract in-use SharePoint Add-in data to SPFx solutions?

The next question is how to extract data from your existing SharePoint Add-in that has been added to the page and apply it to the new SPFx solution: use the existing APIs available to developers.

Recall that SharePoint Add-ins only work on classic pages. Classic pages use the legacy web part framework and that includes a WebPartManager object. This WebPartManager serves as the conductor of the page, managing all the web part controls, functionality, events, and the data associated with each web part on the page.

Using the WebPartManager, you can retrieve the specific web part created as a SharePoint Add-in and extract the values of its public properties. Then, you can use the Microsoft Graph Pages API to add your new SPFx web part(s) to the page and migrate the data to those.

What happens after the end-of-life date to existing SharePoint Add-ins?

Let’s say you haven’t removed a SharePoint Add-in by the time we reach the SharePoint Add-in model end-of-life date of April 2026. What then?

Microsoft will not remove your SharePoint Add-ins from the pages. This tracks with the stance Microsoft has always taken with deactivating features and removing functionality - they never delete or remove data. That’s left for the customer to decide if they want to remove it and how it’s done.

So, while your SharePoint Add-in won’t load, it will still be on the page and its data will be accessible by the WebPartManager.

Conclusion

In this article, I wanted to share some of the most common questions I’m hearing from customers. I’m sure there are plenty of additional situations not covered here!

What about your situation? Do you have SharePoint Add-in migration questions?

Do you have a question that I haven’t covered here? Leave a comment below. If I don’t know the answer, I’ll work to get those answers for you and follow up!