What is the Plugin Registration Tool?
The Plugin Registration Tool (PRT) is the official Microsoft utility for registering and managing plugins, custom workflow activities, virtual table data providers, webhooks, and service endpoints in Dynamics 365 and Dataverse environments.
Unlike deploying code to traditional web servers, Dynamics 365 plugins must be registered through PRT to inform the platform about your custom assemblies and define the exact conditions under which they should execute. plugin registration fundamentals.
Installation and setup
The Plugin Registration Tool is distributed as part of the Power Platform development tools package.
Installation methods:
- Power Platform CLI: Run pac tool prt to download and launch PRT
- Direct download: Download development tools from Microsoft and extract PluginRegistration.exe
- Via XrmToolBox: Access PRT as a plugin within XrmToolBox for integrated workflow
Connecting to your environment
Click "Create New Connection" and provide your Dynamics 365 environment URL and credentials. The tool supports Office 365, OAuth, and on-premises Active Directory authentication.
Registering a plugin assembly
Before you can register individual plugin steps, you must first register the compiled assembly (DLL file) containing your plugin code.
Registration process:
- Click "Register" > "Register New Assembly"
- Browse to your compiled plugin DLL
- Select isolation mode (sandbox is recommended for cloud environments)
- Choose storage location (database for cloud, disk for on-premises)
- Review the detected plugin classes and click "Register Selected Plugins"
đź’ˇ Best practice:
Always use Sandbox isolation mode for plugins unless you have specific requirements for full trust. Sandboxed plugins provide better security isolation and are required for Dynamics 365 Online environments.
Updating existing assemblies
When you modify plugin code, you must update the registered assembly. Right-click the assembly in PRT and select "Update". Choose your new DLL and all existing step registrations will automatically use the updated code.
Registering plugin steps
A plugin step defines when and how your plugin executes. Each step specifies the message, entity, execution stage, and execution mode for your plugin. the event execution pipeline.
Step configuration parameters
- Message: The operation that triggers the plugin (create, update, delete, retrieve, associate, etc.)
- Primary entity: The entity the plugin monitors (leave blank for all entities)
- Event pipeline stage: When the plugin runs (PreValidation, PreOperation, PostOperation)
- Execution mode: Synchronous (blocks user action) or asynchronous (runs in background)
- Filtering attributes: For update messages, specify which field changes trigger the plugin
- User context: Execute as the calling user or a specific system user
⚠️ Critical decision:
Choose execution stage carefully. PreOperation runs before database transaction commit (can modify data before save). PostOperation runs after commit (data is already saved). PreValidation runs before security checks.
Filtering attributes for performance
For Update message plugins, always specify filtering attributes to limit executions. Without filters, your plugin runs on every field update, causing unnecessary processing and performance degradation.
Step images: Capturing data snapshots
Step images allow your plugin to access record data as it existed before (PreImage) or after (PostImage) the operation. entity images documentation.
Image configuration
- PreImage: Captures record state before the operation (available in PreOperation and PostOperation stages)
- PostImage: Captures record state after the operation (only available in PostOperation stage)
- Image alias: Name you'll use in code to access the image (e.g., "PreImage", "PostImage")
- Attributes: Specify which fields to include (reduces payload size and improves performance)
Webhooks: HTTP callbacks for external integration
Webhooks enable Dynamics 365 to call external HTTP endpoints when specific events occur, allowing integration with external systems without custom plugin code. webhook capabilities.
Registering a webhook
- Click "Register" > "Register New Webhook"
- Provide webhook name and endpoint URL (must be HTTPS)
- Select authentication type (HttpHeader, WebhookKey, HttpQueryString)
- Register step on the webhook similar to plugin step registration
Custom workflow activities
Custom workflow activities extend Power Automate workflows with .NET code. They appear as activities in the workflow designer after registration.
Registration steps
- Develop workflow activity inheriting from CodeActivity
- Register assembly same as plugin assembly
- Activity appears in workflow designer under custom activities
- Configure input/output parameters through workflow designer
Plugin profiler: Debugging in action
The Plugin Profiler captures plugin execution context from your live environment and creates a local profile that you can replay in Visual Studio for debugging.
Profiling workflow
- Select the plugin step to profile in PRT
- Click "Start Profiling" and choose profiling mode (Exception or Persist to Entity)
- Perform the operation in Dynamics 365 that triggers the plugin
- Return to PRT and click "Debug" to download the execution profile
- Open your plugin project in Visual Studio and attach the profile
- Set breakpoints and step through code with captured context
đź’ˇ Profiler tip:
Use "Exception Only" mode in production to minimize performance impact. Use "Persist to Entity" in development for capturing all executions. Remember to stop profiling when done.
Service endpoints for Azure integration
Service endpoints enable posting Dynamics 365 event data to Azure Service Bus queues, topics, or Event Hubs for downstream processing.
Configuring service endpoints
- Register service endpoint with Azure connection string
- Specify message format (JSON, XML, binary)
- Register step on service endpoint (similar to plugin steps)
- Messages are automatically posted to Azure when step executes
Best practices for plugin registration
Security and governance
- Use solution-aware development to package plugins properly
- Limit production environment access to authorized personnel
- Document all registered plugins and their business purpose
- Implement change management processes for plugin updates
Performance considerations
- Always specify filtering attributes for update message plugins
- Use asynchronous mode when real-time execution isn't required
- Only include necessary attributes in step images
- Monitor plugin trace logs for execution time analysis
Development workflow
- Use development environments for initial plugin testing
- Implement proper versioning for assembly updates
- Enable tracing during development, exception-only in production
- Clean up unused plugin registrations to reduce complexity
Troubleshooting common issues
Sandbox worker process timeouts
Sandboxed plugins have a 2-minute execution limit. Design plugins to complete quickly and offload long-running operations to async processes.
Isolation mode conflicts
Sandbox and None isolation modes cannot coexist in the same assembly. Separate sandbox plugins from full-trust plugins into different assemblies.
Missing dependencies
Plugin assemblies must be self-contained. Use ILMerge or embed dependencies as resources. Only SDK assemblies are available in the sandbox.
Conclusion
The Plugin Registration Tool is fundamental to Dynamics 365 customization, serving as the bridge between your custom .NET code and the platform's event framework. Mastering PRT is essential for any Dynamics 365 developer building enterprise solutions.
Understanding registration concepts—assemblies, steps, images, and execution pipeline stages—enables you to build robust, performant plugins that integrate seamlessly with the platform. Combined with debugging capabilities like the Plugin Profiler, PRT provides everything needed for professional plugin development and maintenance.