Edit

Dependent Assembly plug-ins (preview)

  • Article
  • 6 minutes to read

[This topic is pre-release documentation and is subject to change.]

It is frequently valuable to include another assembly or a resource file within a plug-in. For example, you may want to use Newtonsoft.Json.dll or another assembly. You may want to access a list of localized strings.

Without dependent assemblies, all plug-ins are registered as individual .NET Framework assemblies. The only way to include another assembly is to combine it into one using ILMerge. While ILMerge worked for many, it was never supported by Dataverse and it didn't always work. ILMerge is no longer being maintained.

With dependent assemblies, rather than register an individual .NET assembly, you will upload a NuGet Package that contains your plug-in assembly AND any dependent assemblies. This NuGet package file is stored in a new table called PluginPackage. The contents of the NuGet package is stored in file storage rather than SQL.

Important

  • This is a preview feature.
  • Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.

This document previously described a process to include additional files with the plug-in package that would be available in the assembly run-time. This capability will not be supported. We cannot guarantee that the runtime will allow access to these files.

When you upload your NuGet package, any assemblies that contain classes that implement the IPlugin Interface will be registered in PluginAssembly table and associated with the PluginPackage. As you develop and maintain your project, you will continue to update the PluginPackage and changes to the related plugin assemblies will be managed on the server.

At runtime, Dataverse copies the contents of the NuGet package from the PluginPackage row and extracts it to the sandbox runtime. This way, any dependent assemblies needed for the plug-in are available.

You will still be able to register plug-in assemblies individually, but using PluginPackage will become the recommended approach. Even if your current plug-in project doesn't require access to a dependent assembly, if you start with a project configured to support dependent assemblies you will be able to add a dependent assembly later. There is no work planned to convert existing plug-in assembly projects to use PluginPackage.

Send feedback

If you have questions or issues with this feature you can contact technical support. If you have suggestions please post them on the Power Apps Ideas Forum site.

Limitations

The following limitations apply to dependent assembly plug-ins.

  • Workflow extensions, also known as workflow assemblies, workflow activities or custom workflow activities are not supported.
  • On-premises environments are not supported.
  • Unmanaged code is not supported. You can't include references to unmanaged resources.

Signing Assemblies

You are not required to sign plug-in assemblies used in plugin packages.

When registering individual plug-in assemblies without the dependent assemblies feature, signing is required because it provides a unique name for the assembly. But with plug-in assemblies within plug-in package, the assemblies are loaded on the sandbox server using a different mechanism, so signing is not necessary.

Note

If you sign your assemblies, be aware that signed assemblies cannot use resources contained in unsigned assemblies. If you sign your plug-in assemblies or any dependent assembly, all the assemblies that those assemblies depend on must be signed. If any signed assemblies depend on unsigned assemblies, you will get an error like the following: Could not load file or assembly '<AssemblyName>, Version=<Version>, Culture=neutral, PublicKeyToken=null' or one of its dependencies. A strongly-named assembly is required.

When you use the Microsoft Power Platform CLI (pac cli), the default settings will sign the assembly for you. You must opt out of signing by using the --skip-signing parameter. More information: Create a Visual Studio project.

Power Platform Tools will not sign your plug-in assembly for you.

Tooling options

You can use this feature with two tooling options:

Tools Overview
PAC CLI and Plug-in Registration tool (PRT) Microsoft Power Platform CLI is a simple, one-stop developer CLI that empowers developers and ISVs to perform various operations in Microsoft Power Platform related to environment lifecycle, authentication, and work with Microsoft Dataverse environments, solution packages, portals, code components, and more.

PRT is a Windows application you can use to manage registering plug-in assemblies and register plug-in step registrations.

See instructions below: Use PAC CLI and PRT
Use Power Platform Tools for Visual Studio Power Platform Tools for Visual Studio supports the rapid creation, debugging, and deployment of plug-ins. Other capabilities include development of custom workflow activities, web resources, integration technologies like Azure Service endpoints and webhooks, and more.

See instructions below: Use Power Platform Tools for Visual Studio

Use PAC CLI and PRT

Use PAC CLI to create a Visual Studio project and PRT to manage your packages and register steps.

Prerequisites

To use this feature with PAC CLI and PRT, you should use these tools and applications.

Tool/App Instructions
Microsoft Power Platform CLI You must have version 1.17 or higher.
The preferred installation method is using Visual Studio Code. See Power Platform Tools.

You can also download and install the Windows version here: https://aka.ms/PowerAppsCLI.
If you have already installed the Windows version, make sure you run pac install latest to get the latest version.

More information: What is Microsoft Power Platform CLI?
PRT You should use version 9.1.0.155 or higher.

Use these instructions to install the latest version: Dataverse development tools.
Visual Studio We require Visual Studio 2019 or newer.

Create a Visual Studio project

Use the PAC CLI pac plugin init command to create a Visual Studio project that will streamline your development process with dependent assemblies.

  1. Create a folder for your plug-in project. The name of this folder will determine the name of the Visual Studio .NET Framework Class library project for your plug-in.

  2. Open a PowerShell terminal window in Visual Studio Code to navigate to the folder and run the command pac plugin init. For plug-in packages we recommend that you use the --skip-signing parameter so that your plug-in assemblies are not signed.

    Example:

    PS E:\projects\mypluginproject> pac plugin init --skip-signing

Note

It is no longer required to sign the assemblies when using dependent assemblies. If you sign your assembly, all dependent assemblies must also be signed. More information: Signing Assemblies

The pac plugin init command has a number of optional parameters. You must use the --skip-signing parameter if you do not want to sign your plug-in assembly.

You will find a Visual Studio .NET Framework class library project created based on the name of the folder it was created in.

Depending on your Visual Studio solution configuration, when you open the Visual Studio project in Visual Studio and build it, you will find a NuGet package generated for the project in the bin\Debug or bin\Release folder. Each time you build your project, this NuGet package will be updated. This is the file you will upload using the Plug-in Registration tool.

Add a dependent assembly using NuGet

You can add a NuGet Package to your Visual Studio project as you normally do. After you build the project, you should find the assembly in the NuGet package.

You can use NuGet Package Explorer to examine the NuGet package.

Add a dependent assembly without using NuGet

If you have an assembly that is not distributed as a NuGet package, you can add it to your project as you normally do. In Solution Explorer, right-click Dependencies and choose Add Assembly Reference.... Select the assembly you want to add.

Use the Plug-in Registration tool

You can use the Plug-in Registration tool (PRT) to perform the following tasks:

  1. View list of available plugin packages.
  2. Register a NuGet package as a plugin package.
  3. Update a plugin package.
  4. Delete plugin packages.

View list of available plugin packages

PRT has a new Display by Package view to list any plug-in packages previously imported:

View a list of plug-in packages using the plug-in registration tool.

Register a NuGet package as a plugin package

PRT has a new command to select a NuGet package to import/register as a plug-in package.

Command to register a plug-in package using the plug-in registration tool.

This will open a dialog to select the plug-in package.

You have the option to select an existing solution or create a new one.

Dialog to import a new plug-in package.

From the Display by Package view, you can select the assembly and register steps.

Showing a newly uploaded plug-in package in the Display by Package view.

The assembly is also available within the Display by Assembly view.

Showing the pluginpackage assembly in the Display by Assembly view.

Update a plugin package

While viewing the list of plugin packages using the Display by Package view, select the plugin package and click the Update command.

Showing the Update command while a plugin package is selected.

This opens a dialog to allow you to select the NuGet Package with changes.

The update Plugin Package dialog.

Important

If your update removes any plug-in assemblies, or types which are used in plug-in step registrations, the update will be rejected. You must manually remove any step registrations that use plug-in assemblies or plugin types that you want to remove with your update.

The version of the plug-in package or plug-in assembly is not a factor in any upgrade behaviors. You can update the versions of these items as you need.

Delete plugin packages

While viewing the list of plugin packages using the Display by Package view, select the plugin package and click the Unregister command.

Showing the Unregister command while a plugin package is selected.

Important

Unregistering a package will delete the package, all assemblies within it, all plug-ins within the assembly, and any plug-in step registrations for the plug-ins.

Use Power Platform Tools for Visual Studio

Use Power Platform Tools for Visual Studio create a Visual Studio project, manage your packages and register steps.

Prerequisites

To use this feature with Power Platform Tools for Visual Studio, you must have Visual Studio 2019 and install Power Platform Tools for Visual Studio.

See the following topics related to installing and using Power Platform Tools for Visual Studio to work with plug-ins.

You will generally use the same process to create and manage plug-ins using Power Platform Tools for Visual Studio, however signing the assemblies is no longer required. More information: Signing Assemblies.

Enable Plugin Packages for Power Platform Tools

Power Platform Tools for Visual Studio provides several configuration options as described in Power Platform Tools options.

  1. In Visual Studio, go to Tools > Options and search for Power Platform tools.

  2. Select Use nuget package for deploying Plugins to Dataverse.

    Select Use nuget package for deploying Plugins to Dataverse.

Note

When this option is selected, all your plug-in projects will be deployed with Plug-in packages.

Add a dependent assembly using NuGet with Power Platform Tools

You can add a NuGet Package to your Visual Studio project as you normally do. After you build the project, you should find the assembly in the NuGet package. The nuget package will be in the bin\outputPackages folder

You can use NuGet Package Explorer to examine the NuGet package.

Add a dependent assembly without using NuGet with Power Platform Tools

If you have an assembly that is not distributed as a NuGet package, you can add it to your project as you normally do. In Solution Explorer, right-click Dependencies and choose Add Assembly Reference.... Select the assembly you want to add.

Deploy Plugin Packages for Power Platform Tools

To deploy your plug-in package, in Solution Explorer right-click the plug-in project and select Deploy from the context menu.

foo

When you deploy for the first time, you should see a message in the output window that informs you that the plug-in package was created:

6/22/2022 3:03:17 PM : registration of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, 
at E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful. 
ID allotted was 06a20e15-77f2-ec11-bb3c-000d3a892245.

Each time you deploy after that, you will see a message in the output window that informs you that the plug-in package was updated.

6/22/2022 3:20:14 PM : update of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, at
E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful.

Important

If your update removes any plug-in assemblies, or types which are used in plug-in step registrations, the update will be rejected. You must manually remove any step registrations that use plug-in assemblies or plugin types that you want to remove with your update.

The version of the plug-in package or plug-in assembly is not a factor in any upgrade behaviors. You can update the versions of these items as you need.

View Plugin Packages with Power Platform Tools

Within the Power Platform Explorer, you can view available plug-in packages.

Within the Power Platform Explorer, you can view available plug-in packages

Delete a Plugin Package with Power Platform Tools

Within the Power Platform Explorer, select a plug-in package and select Delete from the context menu.

Select a plug-in package and select Delete from the context menu

Important

Deleting a package will delete the package, all assemblies within it, all plug-ins within the assembly, and any plug-in step registrations for the plug-ins.

Create a Plugin Package with Power Platform Tools

Note

As mentioned in Deploy Plugin Packages for Power Platform Tools, you will not typically have to create a plug-in package in the usual flow of creating a plug-in. It will be created automatically the first time you deploy the plug-in while the Use nuget package for deploying Plugins to Dataverse option is set in Visual Studio. However, you can create a new plug-in package from a Nuget package using the steps below.

  1. Within the Power Platform Explorer, select Plug-in Packages and select Create from the context menu.

    Within the Power Platform Explorer, select Plug-in Packages and select Create from the context menu.

  2. This will open the Import new Plugin package dialog.

    The **Import new Plugin package dialog

    Select the NuGet package and choose which solution it should be added to, or create a new solution.

Update a Plugin Package with Power Platform Tools

Note

As mentioned in Deploy Plugin Packages for Power Platform Tools, you will not typically have to update a plug-in package in the usual flow of creating a plug-in. It will be updated automatically each time you deploy the plug-in while the Use nuget package for deploying Plugins to Dataverse option is set in Visual Studio. However, you can update a new plug-in package from a Nuget package using the steps below.

Within the Power Platform Explorer, select a plug-in package and select Update from the context menu.

Select a plug-in package and select Update from the context menu

This will open an dialog to allow you to select a nuget package to update the plug-in package.

Design notes

The Visual Studio project created using pac plugin init leverages Visual Studio capabilities that enable generating NuGet Packages. This method uses the SDK-style project format. Power Platform Tools for Visual Studio uses the Non-SDK-style project format.

You are not required to use these tools to generate a NuGet package with your plug-ins. You can use whatever capabilities you choose to generate a NuGet package, but you must use the tooling available to upload the package to Dataverse.

More information:

FAQ

Q: Can I continue to use ILMerge?

A: We have never supported ILMerge. This dependent assemblies feature provides a solution we can support with the same functionality and more. But nothing else has changed. If ILMerge works for you, you can continue to use it. We recommend using dependent assemblies because we can support this solution.

Known issues

The following are known issues that should be resolved before dependent assemblies for plug-ins becomes generally available.

Plug-in profiler

You cannot use Plug-in Profiler to debug plug-ins that are part of a plug-in package. More information: Use Plug-in profiler

Solution containing plugin package cannot include any steps using the plug-in

When you prepare a solution that contains a plugin package, do not include any plug-in step registrations that use an assembly included in the plug-in package.

The export of the solution will succeed, but you will not be able to import the solution. To test plug-ins that use a dependent assembly in a different environment, you must manually register the steps.

Custom API cannot use dependent assembly plug-ins

The custom API will not work after being imported as part of a solution.

See also

Use plug-ins to extend business processes
PAC CLI pac plugin init