The Plug-in Registration Tool — a deep dive

The Plug-in Registration Tool (PRT) has been the workbench for Dataverse plug-in development for over a decade. It registers compiled .NET assemblies into a Dataverse environment, wires them to table events, defines step parameters and pre/post images, and exposes secure configuration. Despite modern alternatives (Power Platform Build Tools, solution-based registration), PRT remains the everyday tool for plug-in developers.

Where PRT comes from

Part of the Dataverse SDK; downloadable as a Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool NuGet package. Run-anywhere desktop tool, connects to a Dataverse environment.

Core registration units.

• Assembly — the compiled .DLL containing plug-in classes.
• Plug-in class — a C# class implementing IPlugin.
• Step — a registration tying a class to a table event with execution parameters.
• Pre-image / Post-image — captured snapshots of the row before/after the operation.
• Service endpoint — registration of an Azure Service Bus or Event Grid endpoint as a step target.

Workflow.

1. Build the plug-in DLL in Visual Studio.
2. Connect PRT to the Dataverse environment.
3. Register Assembly — pick the DLL; PRT inspects classes; registers as an assembly record.
4. Register Step — pick a class, table, event (Create/Update/Delete), stage (Pre/Post), execution mode (Sync/Async), filtering attributes (only fire on these column changes).
5. Register Image if needed — capture snapshot of specified attributes.
6. Test — trigger the event; verify the plug-in fired.

Step parameters.

• Message — Create, Update, Delete, Retrieve, RetrieveMultiple, Associate, Disassociate, custom action.
• Primary table — the table the event fires against.
• Stage — Pre-validation, Pre-operation, Post-operation.
• Execution mode — Synchronous (in transaction) or Asynchronous (background queue).
• Filtering attributes — limits firing to changes in specified columns.
• Run in user's context / specific user — security context for the plug-in.
• Deployment — Server (Dataverse), Offline (mobile offline), or Both.

Stages explained.

• Pre-validation — fires before the platform validates the operation; can be on any rollback. Used for very early gates (license checks, custom auth).
• Pre-operation — fires after validation but before the DB commit. Most common for mutation logic on the operation's record.
• Post-operation — fires after commit. Most common for cascading side effects.

Sync vs async.

• Sync — runs inline with the user's operation; failures roll back the operation. Maximum 2 seconds before the platform considers it slow.
• Async — runs in the system job queue; out-of-band from the user.

For validation, sync. For external integrations and side effects, async.

Pre-image and post-image.

• A plug-in's IExecutionContext.PreEntityImages / PostEntityImages give snapshots of the row.
• Required for Update steps that need to compare before/after.
• Each image has a name (typically PreImage, PostImage); the plug-in code references by name.
• Image attributes specify which columns are included — capturing only what you need.

Secure / unsecure configuration.

• Unsecure — string passed to the plug-in via IPluginExecutionContext; visible in PRT.
• Secure — encrypted; visible to the plug-in at runtime but not in the registration UI.

Use secure for API keys, credentials, sensitive parameters. Use unsecure for non-sensitive tuning (modes, flags).

Solution-aware registration

Modern practice:

1. Create a solution.
2. Add the plug-in assembly to the solution.
3. Add the steps and images to the solution.
4. Export/import the solution to promote across environments.

PRT supports this by tagging registrations with solution membership. Promotion happens through solution import in each environment, not through re-registering with PRT in each.

Modern alternatives.

• Power Platform Build Tools (Azure DevOps task / GitHub Action) — automate registration as part of CI/CD pipeline. Reduces manual PRT clicking.
• Solutions via packagedeployer — package the assembly with metadata; promote together.
• CLI commands — pac plugin push from the Power Platform CLI.

For mature teams, PRT is the dev-time tool; promotion is automated.

Common pitfalls.

• Forgot to add the step to a solution. Step exists in dev but doesn't promote; downstream environment lacks it.
• Wrong stage chosen. Pre-validation for logic that should be post-operation; cascading effects don't happen.
• Sync plug-in slow. Drags user-facing operations; flip to async if validation isn't blocking-critical.
• Image not registered or name mismatch. Plug-in code refers to "PreImage" but registration created "preimage"; case-sensitive failure.
• Secure configuration leaked. Connection strings in unsecure config; visible to anyone with admin access; rotate immediately.
• Plug-in chains causing recursion. A plug-in updating its own table triggers itself; infinite loop; protect with depth checks (IExecutionContext.Depth > 1 is a common guard).

Operational discipline

PRT is the daily tool for plug-in developers but should never be the production deployment tool. Build/test with PRT; promote via solutions. The line between "registered in dev" and "registered in prod" should be the solution import pipeline, not someone clicking PRT in prod.