Edit

Transform sandbox solutions to the SharePoint Add-in model

  • Article

Transforming your sandbox solutions to the SharePoint Add-in model involves analyzing your existing extensions, designing and developing your new SharePoint Add-ins, and then testing and deploying your add-in in your production environment.

Note

Code-based sandbox solutions were deprecated in 2014, and SharePoint Online has started the process to completely remove this capability. Code-based sandbox solutions are also deprecated in SharePoint 2013 and in SharePoint 2016.

Code-based sandbox solutions in SharePoint

Sandbox solutions are customization packages that can be used to deploy customizations to SharePoint on the site collection level. If a sandbox solution contains code, it has been executed in a special isolated process with a limited set of APIs to access SharePoint services and content.

There are two types of Sandbox solutions:

  • Code-based sandbox solutions, which contain a custom assembly in the package.
  • Declarative sandbox solutions, which only contain XML-based configurations and related assets.

Declarative (XML-based) sandbox solutions can be further divided into the following types based on their use cases:

  • Site template – Generated by using the “Save site as a template” functionality from existing sites.
  • Design package – Generated by using Design Manager from the publishing site.
  • Custom sandbox solutions - Created in Visual Studio, for example, for branding assets, and do not contain assemblies.

Code-based sandbox solutions can be further divided into the following types based on their use cases:

  • Declarative sandbox solution with empty assembly
  • Sandbox solution containing InfoPath form with code
  • Code-based sandbox solutions with customizations such as web parts, event receivers, and/or feature receivers
  • Sandbox solutions with custom workflow action

When you plan to move away from sandbox solutions, you should evaluate the functional and business requirements of a specific solution and determine the future design direction based on that.

Planning the transformation process

When you transform your sandbox solutions to the SharePoint Add-in model, you want to ensure that the impact on your users is minimal. Carefully analyze your current sandbox solutions, and then design your new SharePoint Add-in to meet the needs of your organization. We recommend the following process to ensure a successful transformation.

Readiness

Learn about:

Solution assessment

Analyze the functional and business requirements by:

  • Identifying deployed sandbox solutions in your current environment for which you can use either of the following tools provided as open source by the SharePoint PnP team:

  • Reviewing requirements with your users. Consider asking your users to demonstrate how they use the existing sandbox solutions to perform their daily work.

  • Identifying, documenting, and designing new functionality to include in the new SharePoint Add-in. Consider reviewing your list of new feature requests from your users for additional ideas.

  • Identifying unused features, and agreeing with your users to omit this functionality from the new SharePoint Add-in.

  • For each solution, determining whether to replace it with a SharePoint Add-in or implement it either by using out-of-the-box capabilities or an alternative solution.

Solution planning

Design the new application by using the SharePoint Add-in model based on:

  • The requirements gathered in the Solution assessment step.

  • Your analysis of the existing code. During your code analysis, consider identifying portions of the code that can be dropped (for example, the code is no longer being used, or the requirements have changed).

Develop and test the SharePoint Add-in model version of your application

This is usually the most time-consuming step in the transformation process.

Deploy your new add-in

Ensure that your deployment is stable, and send appropriate communication to your users.

Replacing sandbox solution customizations

Following are typical customizations that are included in the sandbox solutions and potential transformation options. We are looking at adding more information for each of the customization types so you can have real-world examples about the transformation options.

Customization Transformation options
Declarative solution with empty assembly

You can control assembly creation from Visual Studio solution project properties. For more information, see Remove the assembly reference from your Sandbox solution created in Visual Studio.



Important: When you use the SharePoint Sandbox Solution scanner, the scan output lists which solutions have an empty assembly, and the tool creates updated sandbox solution packages for you in which the assembly is dropped. You can then simply replace the existing sandbox solution with the updated one.
InfoPath form with code

If you have published an InfoPath form from the InfoPath client that contains code, it’s actually published to SharePoint as a sandbox solution. This means that the form code is actually executed by the sandbox engine in SharePoint.

Moving away from the code-based InfoPath forms is dependent on the actual business use case. There are multiple options from generating custom UI as add-ins or utilizing other form techniques.

For more information, see Fix InfoPath in sandbox solutions.
Web part

Web parts are typically converted either to add-in parts or they are implemented with fully client-side technologies by using the JavaScript embed pattern.

For more information, see:

Visual web part

Visual web parts are transformed in similar ways as normal web parts. User controls used in visual web parts must be replaced because in sandbox solution cases, it's included inside of the assembly.
Event receiver

Event receivers can in many cases be replaced with the remote event receiver implementation. Remote event receivers do, however, need to hosted on some platform, typically on specific provider-hosted add-ins.

For more information, see:

Feature receiver

Feature receivers are typically replaced with a remote API based operation, such as using CSOM or REST for applying the needed customization or configuration at the site level. If a needed API is missing from the remote APIs (CSOM/REST), report this gap by using SharePoint UserVoice.

Feature receivers are used, for example, to set a custom master page or theme to a site when they are activated. These kinds of operations can be easily replaced with remote code-based solutions or by using PnP PowerShell, which provides easy commands for controlling site configuration.
Custom workflow action

The typical code migration path for these kinds of customizations is to use SharePoint workflows or alternative solutions such as Microsoft Flow or third-party solutions.

Removing sandbox code from your site

When you deactivate your existing sandbox solution from sites, any assets or files deployed by using declarative options will not be removed. If you have used sandbox solutions to introduce new code-based web parts, those functionalities will be disabled from the sites. This means that the pages are still rendering normally, so there's no direct end user impact when the solution is deactivated, except removal of the code-based functionalities such as web parts.

Removing support for code-based sandbox solutions

Support of code-based sandbox solutions will be removed from SharePoint Online by disabling code-based operations that execute from sandbox-solution-based code. This means that your sandbox solutions are not explicitly deactivated from the solution store, but any code-based operation will no longer be performed. Sandbox solutions will remain in activated status in the solution gallery. Features deployed by using sandbox solutions will not get deactivated automatically, which means that possible code associated to feature deactivation or uninstall handlers won't be run.

All declarative definitions in the sandbox solution will continue working after this change is applied in SharePoint Online.

In this section

See also