Removing a Plugin and Its Steps from Managed Downstream Environments

Overview

When a plug-in and its associated steps have already been deployed to downstream managed environments (QA, UAT, Production), they cannot be removed by simply deleting the steps and plug-in from the development environment and redeploying the solution.

If the steps and plug-in are removed directly, managed solution deployment may fail in downstream environments because Dataverse still maintains references to the existing plug-in assembly and plug-in types.

To properly remove a plug-in from managed environments, a new major assembly version must be created. Dataverse will treat the updated assembly as a new assembly, allowing all existing step registrations (Event Handlers) to be migrated to the new assembly version. Once all steps are migrated, the old assembly can be safely removed from the solution and unregistered.

---

Steps to Remove a Plugin and Its Steps

1. Update the Assembly Version

Open the plug-in project in Visual Studio.

Update the assembly version in AssemblyInfo.cs by incrementing the major or minor version number.

Example:

[assembly: AssemblyVersion("1.1.0.*")]
[assembly: AssemblyFileVersion("1.1.0.0")]

Remove the plug-in class(es) that need to be retired and rebuild the solution.

---

2. Open Plug-in Registration Tool (PRT)

Open XrmToolBox and launch the Plug-in Registration Tool (PRT).

Connect to the Development environment.

---

3. Register the New Assembly Version

Register the updated DLL using:

Register New Assembly

This will create a new assembly version in Dataverse.

---

4. Migrate Existing Steps

Locate the steps under the old assembly.

For each step:

1. Open the step.

2. Update the Event Handler property.

3. Select the corresponding plug-in type from the newly registered assembly version.

---

5. Repeat for All Steps

Repeat the migration process for all existing steps until every step points to the new assembly version.

---

6. Verify Step Migration

Confirm that:

• All steps are registered under the new assembly version.

• No active steps remain under the old assembly.

---

7. Add the New Assembly to the Solution

Add the newly registered assembly and its associated steps to the desired solution.

---

8. Remove the Old Assembly from the Solution

Remove only the old assembly from the solution.

Do not remove the new assembly.

---

9. Unregister the Old Assembly

In the Plug-in Registration Tool:

1. Right-click the old assembly.

2. Select Unregister.

This removes the obsolete assembly registration from the Development environment.

---

10. Validate Solution Components

Verify the solution contains:

• New assembly version

• All required plug-in types

• All migrated steps

Ensure no references exist to the old assembly.

---

11. Export and Deploy

1. Export the solution.

2. Create a Pull Request (if applicable).

3. Deploy the solution to downstream environments (QA/UAT/Production).

The managed solution upgrade will remove the old assembly and associated plug-in components while preserving the migrated step registrations.

---

Summary

Update Assembly Version
        ↓
Register New Assembly
        ↓
Migrate All Steps
        ↓
Verify Migration
        ↓
Add New Assembly to Solution
        ↓
Remove Old Assembly from Solution
        ↓
Unregister Old Assembly
        ↓
Export Solution
        ↓
Deploy to QA/UAT/Production

Following this process ensures plug-ins and steps can be safely removed from managed downstream environments without causing solution import or plug-in registration conflicts.