Skip to main content

C# Plugin Architecture — IPlugin, IPluginExecutionContext, and Service Provider

1. Conceptual Foundation​

The Microsoft Dataverse Event Framework is a highly optimized, event-driven execution engine that allows developers to intercept and extend the platform's core data operations. At the heart of this extensibility model is the C# plugin architecture. A plugin is a custom business logic handler, compiled as a .NET Framework 4.6.2 class library, that integrates directly into the Dataverse message processing pipeline.

The Dataverse Event Framework and Message Pipeline​

Every action in Dataverse—whether a standard Create, Update, Delete, or a custom action/API—is processed as a message. When a client application invokes an operation, the request is translated into an OrganizationRequest and sent to the organization web service. The Event Framework processes this request through a execution pipeline consisting of distinct stages:

  1. Pre-Validation (Stage 10): Executes before database transactions start and before security privilege checks occur. It is primarily used for validation logic that does not require database locks.
  2. Pre-Operation (Stage 20): Executes within the database transaction, immediately before the core database operation. This stage is ideal for modifying the attributes of the target record before they are committed.
  3. Main-Operation (Stage 30): Reserved for internal platform execution, such as writing the record to the SQL database. Custom APIs and virtual table data providers also execute in this stage.
  4. Post-Operation (Stage 40): Executes within the database transaction, immediately after the core database operation. This stage is used to perform secondary actions, such as creating related records, modifying output parameters, or triggering asynchronous integrations.

The IPlugin Interface​

To integrate with this pipeline, a class must implement the Microsoft.Xrm.Sdk.IPlugin interface. This interface defines a single method:

void Execute(IServiceProvider serviceProvider);

The Execute method is the entry point for the plugin. It accepts a single parameter, IServiceProvider, which acts as a service locator. Rather than using dependency injection containers, Dataverse uses the Service Provider pattern to dynamically resolve runtime dependencies.

Resolving Services from the Service Provider​

The IServiceProvider is used to resolve the essential execution context and platform services required by the plugin:

  • IPluginExecutionContext: Provides access to the contextual data of the current operation, including the message name, target entity, pipeline stage, and user identities.
  • ITracingService: Enables writing diagnostic messages to the Plug-in Trace Log. This is the primary debugging mechanism for sandboxed plugins.
  • IOrganizationServiceFactory: A factory interface used to instantiate an IOrganizationService instance. This service allows the plugin to perform CRUD operations and execute messages back against Dataverse.
  • IServiceEndpointNotificationService: Used in asynchronous plugins to post the execution context to Azure Service Bus or Event Hubs.

The Execution Context: Properties and Collections​

The IPluginExecutionContext exposes several critical collections and properties that define the state of the operation:

InputParameters​

A ParameterCollection containing the parameters of the request message that triggered the plugin. For example, in a Create or Update message, the InputParameters collection contains a Target key, which holds the Entity being processed. In a Delete message, the Target key holds an EntityReference.

OutputParameters​

A ParameterCollection containing the results of the core operation. This collection is only populated and accessible in the Post-Operation (Stage 40) stage. For example, in a Create message, the OutputParameters collection contains an id key representing the GUID of the newly created record.

PreEntityImages and PostEntityImages​

These collections contain snapshots of the primary record's attributes before and after the core database operation.

  • PreEntityImages are available in Pre-Operation and Post-Operation stages. They represent the state of the record in the database before the transaction began.
  • PostEntityImages are available only in the Post-Operation stage. They represent the state of the record in the database after the core operation completed but before the transaction is committed.
  • Performance Benefit: Using entity images is a critical performance best practice. It avoids the need to execute a separate Retrieve request against the database to compare old and new values, saving database round-trips and reducing transaction lock times.

SharedVariables​

A ParameterCollection that allows plugins to pass data downstream to other plugins executing in the same pipeline. For example, a plugin running in the Pre-Validation stage can calculate a value and store it in SharedVariables. A subsequent plugin running in the Post-Operation stage can retrieve this value, provided they share the same parent execution context.

Depth​

An integer representing the current depth of execution in the call stack. Every time a plugin or workflow executes a message request that triggers another plugin or workflow, the Depth property increments. Dataverse uses this property for infinite loop prevention. If the depth exceeds the platform limit (default is 8) within a one-hour window, the platform aborts execution and rolls back the transaction.

CorrelationId​

A unique Guid assigned to the initial request. It remains constant across all nested plugin and workflow executions, allowing developers to trace the entire execution chain in the telemetry logs.

UserId vs. InitiatingUserId​

  • UserId: The GUID of the system user account under whose security context the plugin is currently executing. This is determined by the "Run in User's Context" setting on the registered step (either the Calling User or an impersonated user).
  • InitiatingUserId: The GUID of the system user who actually performed the action in the client application (e.g., clicked the button or saved the form) that triggered the pipeline.

Statelessness and Thread Safety​

Dataverse instantiates a plugin class once and then caches that instance in memory for subsequent executions to maximize performance. Because the platform caches plugin instances, the class constructor is not called for every execution.

This caching mechanism introduces strict architectural constraints:

  1. Plugins must be stateless. You must never store execution-specific data in class member fields or properties. All state information must be accessed exclusively via the IPluginExecutionContext passed into the Execute method.
  2. Thread Safety is mandatory. Multiple system threads can execute the same cached plugin instance concurrently. Any write operations to class-level fields will cause race conditions, data corruption, and memory leaks.
  3. Allowed Class Members: The only acceptable class-level members are read-only constants, static read-only fields initialized at compile-time, or configuration data passed into the constructor during initialization.

Constructor Signatures and Configuration Data​

When registering a plugin step, you can optionally provide Unsecure and Secure configuration data. This data is passed as string parameters to the plugin's constructor. The platform supports three constructor signatures:

// Default constructor called when no configuration is provided
public MyPlugin() {}

// Constructor called when only unsecure configuration is provided
public MyPlugin(string unsecure) {}

// Constructor called when both unsecure and secure configurations are provided
public MyPlugin(string unsecure, string secure) {}
  • Unsecure Configuration: Stored in the SdkMessageProcessingStep table. It is visible to all users and is exported with solutions. It is ideal for non-sensitive settings like threshold values, business rules, or feature flags.
  • Secure Configuration: Stored in a separate, secure table (SdkMessageProcessingStepSecureConfig) that only system administrators have privileges to read. It is not exported with solutions. It is mandatory for sensitive data such as API keys, connection strings, or credentials.

2. Architecture & Decision Matrix​

When designing enterprise extensions in Microsoft Power Platform, developers must choose the correct extensibility point. The table below compares the four primary implementation approaches:

Feature / DimensionDataverse Plugins (C#)Power Automate Cloud FlowsAzure Functions (Webhooks)Power Apps Component Framework (PCF)
ComplexityHigh (Requires C# expertise, SDK knowledge, and ALM pipelines)Low to Medium (Low-code drag-and-drop designer)Medium to High (Requires Azure development and hosting setup)High (Requires TypeScript, React, and web development skills)
ScalabilityHigh (Runs directly on Dataverse web servers, optimized for database operations)Medium (Subject to API request limits and throttling)Extremely High (Serverless scaling, ideal for heavy processing)Client-side (Scales with the user's device performance)
Execution ContextFull access to database transactions, pre/post images, and pipeline stagesAsynchronous execution, no direct access to database transactionsAsynchronous execution, triggered via webhooks, no transaction accessClient-side execution, runs within the context of the model-driven or canvas app
Offline SupportSupported in Dynamics 365 Mobile Client (Offline sync)No offline supportNo offline supportSupported within the host app's offline capabilities
LicensingIncluded in standard Power Apps/Dataverse licensesSubject to Power Platform request limits; may require premium licensesRequires Azure subscription and consumption/hosting costsIncluded in standard Power Apps licenses
PL-400 Exam RelevanceCritical (Core focus of the exam; must know lifecycle, context, and code)High (Focus on integration, triggers, and expressions)Medium (Focus on registration, authentication, and webhooks)High (Focus on control lifecycle, manifest, and deployment)

Decision Flowchart for Extensibility​

Is the business logic synchronous and critical to database integrity?
 ├── YES: Must the logic execute within the database transaction (e.g., validation, auto-mutation)?
 │     ├── YES: Implement a Dataverse Plugin (C#).
 │     └── NO: Can it run asynchronously?
 │           └── YES: Implement an Asynchronous Plugin or Power Automate Flow.
 └── NO: Is the logic a long-running process (> 2 minutes) or does it require external libraries?
       ├── YES: Offload to an Azure Function triggered via a Dataverse Webhook or Service Bus.
       └── NO: Is it a user interface enhancement?
             ├── YES: Implement a Power Apps Component Framework (PCF) control.
             └── NO: Implement a Power Automate Cloud Flow.

3. Step-by-Step Implementation Guide​

This guide outlines the exact steps to set up, write, sign, register, and package a custom C# plugin using the Power Platform CLI and the Plug-in Registration Tool.

Step 1: Initialize the Project using Power Platform CLI​

Open a PowerShell terminal, navigate to your development directory, and execute the following commands to initialize a new plugin project:

# Create a directory for the plugin project
mkdir EnterprisePlugins
cd EnterprisePlugins

# Initialize the plugin project (this generates the PluginBase.cs and a sample class)
pac plugin init --author "Contoso Architecture Group" --skip-signing

Note: We use --skip-signing initially because we will configure a strong-name key file manually in Visual Studio to ensure strict security compliance.

Step 2: Configure the Visual Studio Project and NuGet Packages​

  1. Open the generated .csproj file in Visual Studio.
  2. Right-click the project in Solution Explorer and select Manage NuGet Packages.
  3. Install the latest stable version of the following package:
    • Microsoft.CrmSdk.CoreAssemblies (Targeting .NET Framework 4.6.2)
  4. Ensure that the target framework of the project is explicitly set to .NET Framework 4.6.2.

Step 3: Configure Assembly Signing​

All assemblies registered in Dataverse must be digitally signed with a strong name key.

  1. In Visual Studio, right-click the project and select Properties.
  2. Navigate to the Signing tab.
  3. Check the Sign the assembly checkbox.
  4. In the Choose a strong name key file dropdown, select <New...&gt.
  5. Enter EnterprisePluginsKey as the key file name.
  6. Uncheck Protect my key file with a password (to facilitate automated CI/CD build pipelines).
  7. Click OK. This generates an EnterprisePluginsKey.snk file in your project directory.

Step 4: Implement the Plugin Logic​

Rename the default class file to AccountCreditValidationPlugin.cs and implement the IPlugin interface. (The complete, production-grade code is provided in Section 4).

Step 5: Build the Assembly​

  1. In Visual Studio, set the active solution configuration to Release.
  2. Select Build > Build Solution (or press Ctrl+Shift+B).
  3. Verify that the build succeeds and generates EnterprisePlugins.dll in the bin/Release folder.

Step 6: Connect to Dataverse using the Plug-in Registration Tool (PRT)​

  1. Launch the Plug-in Registration Tool by executing the following PAC CLI command in your terminal: 
    pac tool prt
  2. Click + Create New Connection.
  3. Select Office 365 as the deployment type.
  4. Check Display list of available organizations and Show Advanced.
  5. Enter your environment credentials and click Login.
  6. Select your target development environment from the list and click Login.

Step 7: Register the Assembly​

  1. In the PRT, click Register > Register New Assembly (or press Ctrl+A).
  2. In the dialog, click the ellipsis (...) button and browse to the built assembly: bin/Release/EnterprisePlugins.dll.
  3. Ensure the Isolation Mode is set to Sandbox (mandatory for cloud deployments).
  4. Ensure the Location is set to Database (stores the assembly directly in the Dataverse database).
  5. Click Register Selected Plug-ins.

Step 8: Register the Plugin Step​

  1. In the PRT assembly tree, locate and expand your registered assembly EnterprisePlugins.dll.
  2. Right-click the plugin type EnterprisePlugins.AccountCreditValidationPlugin and select Register New Step (or press Ctrl+T).
  3. Configure the step with the following exact parameters:
    • Message: Update
    • Primary Entity: account
    • Filtering Attributes: Click the ellipsis and select only creditlimit (prevents the plugin from running on updates to other columns).
    • Event Pipeline Stage of Execution: PreOperation (Stage 20)
    • Execution Mode: Synchronous
    • Execution Order: 1
    • Run in User's Context: Calling User
  4. In the Unsecure Configuration text box, enter the following JSON configuration: 
    {
      "MaxCreditLimitThreshold": 1000000.00,
      "AuditTaskSubject": "High Credit Limit Approval Required"
    }
  5. Click Register New Step.

Step 9: Register the Pre-Entity Image​

  1. In the PRT, right-click the newly created step EnterprisePlugins.AccountCreditValidationPlugin: Update of account and select Register New Image (or press Ctrl+I).
  2. Configure the image with the following parameters:
    • Image Type: Pre Image
    • Entity Alias: PreImage (This exact string must match the key used in the C# code).
    • Parameters: Check the creditlimit and name attributes (only include columns required by the business logic).
  3. Click Register Image.

Step 10: Add the Components to a Solution​

To ensure proper Application Lifecycle Management (ALM), the registered assembly and steps must be packaged into a Dataverse solution.

  1. Navigate to the Power Apps Maker Portal (make.powerapps.com).
  2. Select your target environment.
  3. In the left navigation pane, click Solutions and open your unmanaged development solution.
  4. Click Add existing > Developer > Plug-in assembly.
  5. Select EnterprisePlugins from the list and click Add. This automatically pulls in the assembly and all associated steps and images.

4. Complete Code Reference​

The following is a complete, production-grade, compilable C# plugin implementation. It demonstrates best practices for statelessness, configuration parsing, parameter extraction, image access, service resolution, and robust error handling.

AccountCreditValidationPlugin.cs​

//===================================================================================
// Microsoft Power Platform Developer Training
// Technical Objective: C# Plugin Architecture
// Description: Production-grade plugin that validates account credit limit updates.
//              Demonstrates:
//              - Unsecure configuration parsing via constructor.
//              - Safe extraction of InputParameters (Target Entity).
//              - Safe extraction of PreEntityImages.
//              - Resolution of ITracingService and IOrganizationService.
//              - Mutation of InputParameters (Pre-Operation attribute injection).
//              - Creation of related records (Audit Task).
//              - SharedVariables usage for downstream pipeline communication.
//===================================================================================

using System;
using System.Globalization;
using System.Runtime.Serialization;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

namespace EnterprisePlugins
{
    /// <summary>
    /// Represents a plugin registered on the Pre-Operation stage of the Account Update message.
    /// Validates credit limit changes and enforces enterprise compliance rules.
    /// </summary>
    public sealed class AccountCreditValidationPlugin : IPlugin
    {
        private readonly decimal _maxCreditLimitThreshold = 500000.00m; // Default fallback
        private readonly string _auditTaskSubject = "Credit Limit Change Review"; // Default fallback
        private readonly bool _isConfigValid;

        /// <summary>
        /// Initializes a new instance of the <see cref="AccountCreditValidationPlugin"/> class.
        /// Parses unsecure configuration passed from the step registration.
        /// </summary>
        /// <param name="unsecureConfig">The unsecure configuration string (JSON expected).</param>
        public AccountCreditValidationPlugin(string unsecureConfig)
        {
            // Since the plugin instance is cached, constructor logic runs once upon instantiation.
            if (string.IsNullOrWhiteSpace(unsecureConfig))
            {
                _isConfigValid = false;
                return;
            }

            try
            {
                // Simple, robust JSON parsing without external dependencies (to comply with sandbox limits)
                var config = SimpleJsonParser.Parse(unsecureConfig);
                if (config != null)
                {
                    if (config.ContainsKey("MaxCreditLimitThreshold") && 
                        decimal.TryParse(config["MaxCreditLimitThreshold"], NumberStyles.Any, CultureInfo.InvariantCulture, out decimal threshold))
                    {
                        _maxCreditLimitThreshold = threshold;
                    }

                    if (config.ContainsKey("AuditTaskSubject") && !string.IsNullOrWhiteSpace(config["AuditTaskSubject"]))
                    {
                        _auditTaskSubject = config["AuditTaskSubject"];
                    }

                    _isConfigValid = true;
                }
            }
            catch
            {
                // Fallback to defaults if parsing fails; do not throw in constructor to prevent registration lock
                _isConfigValid = false;
            }
        }

        /// <summary>
        /// Executes the plugin logic.
        /// </summary>
        /// <param name="serviceProvider">The service provider locator.</param>
        public void Execute(IServiceProvider serviceProvider)
        {
            if (serviceProvider == null)
            {
                throw new ArgumentNullException(nameof(serviceProvider));
            }

            // 1. Resolve the Tracing Service
            ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
            if (tracingService == null)
            {
                throw new InvalidPluginExecutionException("Failed to resolve Tracing Service.");
            }

            tracingService.Trace("AccountCreditValidationPlugin: Execution started.");

            try
            {
                // 2. Resolve the Plugin Execution Context
                IPluginExecutionContext context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
                if (context == null)
                {
                    throw new InvalidPluginExecutionException("Failed to resolve Plugin Execution Context.");
                }

                // Verify execution context parameters to prevent incorrect registration errors
                if (context.MessageName.ToLower(CultureInfo.InvariantCulture) != "update" || 
                    context.PrimaryEntityName.ToLower(CultureInfo.InvariantCulture) != "account")
                {
                    tracingService.Trace("Invalid registration. Plugin only supports Update of Account. Current Message: {0}, Entity: {1}", context.MessageName, context.PrimaryEntityName);
                    return;
                }

                tracingService.Trace("Correlation ID: {0}, Depth: {1}, User ID: {2}", context.CorrelationId, context.Depth, context.UserId);

                // Prevent infinite loops by checking execution depth
                if (context.Depth > 2)
                {
                    tracingService.Trace("Execution depth limit reached. Aborting execution to prevent infinite loop.");
                    return;
                }

                // 3. Extract the Target Entity from InputParameters
                if (!context.InputParameters.Contains("Target") || !(context.InputParameters["Target"] is Entity))
                {
                    tracingService.Trace("Target entity is missing or invalid in InputParameters.");
                    return;
                }

                Entity targetEntity = (Entity)context.InputParameters["Target"];

                // 4. Extract the Pre-Entity Image
                Entity preImageEntity = null;
                if (context.PreEntityImages.Contains("PreImage") && context.PreEntityImages["PreImage"] is Entity)
                {
                    preImageEntity = context.PreEntityImages["PreImage"];
                }
                else
                {
                    // Pre-images are mandatory for this business logic to compare old vs new values
                    throw new InvalidPluginExecutionException(
                        OperationStatus.Failed,
                        -2147220891, // Custom ISV error code
                        "Pre-Entity Image 'PreImage' is missing. Please register a Pre-Image containing 'creditlimit' and 'name' attributes.");
                }

                // 5. Execute Business Logic: Validate Credit Limit Changes
                if (targetEntity.Contains("creditlimit"))
                {
                    Money newCreditLimitMoney = targetEntity.GetAttributeValue<Money>("creditlimit");
                    Money oldCreditLimitMoney = preImageEntity.GetAttributeValue<Money>("creditlimit");

                    decimal newCreditLimit = newCreditLimitMoney?.Value ?? 0m;
                    decimal oldCreditLimit = oldCreditLimitMoney?.Value ?? 0m;

                    tracingService.Trace("Credit Limit Change Detected. Old: {0}, New: {1}", oldCreditLimit, newCreditLimit);

                    // Rule A: Enforce maximum threshold limit
                    if (newCreditLimit > _maxCreditLimitThreshold)
                    {
                        tracingService.Trace("Validation Failed: New credit limit {0} exceeds maximum threshold {1}.", newCreditLimit, _maxCreditLimitThreshold);
                        
                        throw new InvalidPluginExecutionException(
                            OperationStatus.Failed,
                            -2147220891,
                            string.Format(CultureInfo.InvariantCulture, "The requested credit limit of {0:C} exceeds the maximum allowed threshold of {1:C} for standard accounts.", newCreditLimit, _maxCreditLimitThreshold));
                    }

                    // Rule B: If credit limit is increased by more than 50%, flag for audit and mutate description
                    if (oldCreditLimit > 0 && (newCreditLimit - oldCreditLimit) / oldCreditLimit > 0.50m)
                    {
                        tracingService.Trace("Significant credit limit increase detected (>50%). Mutating target description and queuing audit task.");

                        // Mutate the Target Entity in Pre-Operation (Stage 20)
                        // This ensures the description change is saved to the database in the same transaction without a separate Update call.
                        string accountName = preImageEntity.GetAttributeValue<string>("name") ?? "Account";
                        targetEntity["description"] = string.Format(
                            CultureInfo.InvariantCulture,
                            "Credit limit increased significantly from {0:C} to {1:C} on {2} UTC. Pending audit review.",
                            oldCreditLimit,
                            newCreditLimit,
                            DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture));

                        // 6. Resolve the Organization Service Factory and Service
                        IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
                        if (serviceFactory == null)
                        {
                            throw new InvalidPluginExecutionException("Failed to resolve Organization Service Factory.");
                        }

                        // Create the service in the context of the calling user
                        IOrganizationService orgService = serviceFactory.CreateOrganizationService(context.UserId);

                        // Create an Audit Task record
                        Entity auditTask = new Entity("task");
                        auditTask["subject"] = _auditTaskSubject;
                        auditTask["description"] = string.Format(
                            CultureInfo.InvariantCulture,
                            "Please review the credit limit increase for account '{0}'. Old Limit: {1:C}, New Limit: {2:C}.",
                            accountName,
                            oldCreditLimit,
                            newCreditLimit);
                        
                        // Set the regarding object to the account being updated
                        auditTask["regardingobjectid"] = new EntityReference("account", targetEntity.Id);
                        
                        // Set due date to 2 days from now
                        auditTask["scheduledend"] = DateTime.UtcNow.AddDays(2);

                        // Execute the create operation within the current transaction
                        Guid taskId = orgService.Create(auditTask);
                        tracingService.Trace("Audit Task successfully created. Task ID: {0}", taskId);

                        // 7. Write to SharedVariables to communicate with downstream plugins
                        context.SharedVariables["IsSignificantCreditIncrease"] = true;
                        context.SharedVariables["AuditTaskId"] = taskId.ToString();
                    }
                }

                tracingService.Trace("AccountCreditValidationPlugin: Execution completed successfully.");
            }
            catch (FaultException<OrganizationServiceFault> ex)
            {
                tracingService.Trace("OrganizationServiceFault encountered: {0}", ex.ToString());
                throw new InvalidPluginExecutionException(OperationStatus.Failed, ex.Detail.ErrorCode, "Database operation failed: " + ex.Message, ex);
            }
            catch (InvalidPluginExecutionException)
            {
                // Re-throw platform exceptions directly to preserve custom error messages and codes
                throw;
            }
            catch (Exception ex)
            {
                tracingService.Trace("Unexpected exception encountered: {0}", ex.ToString());
                // Wrap unexpected exceptions in InvalidPluginExecutionException to prevent generic ISV unexpected errors
                throw new InvalidPluginExecutionException(OperationStatus.Failed, -2147220956, "An unexpected error occurred in the credit validation plugin: " + ex.Message, ex);
            }
        }
    }

    /// <summary>
    /// A lightweight, zero-dependency JSON parser designed to run safely within the Dataverse Sandbox isolation mode.
    /// </summary>
    internal static class SimpleJsonParser
    {
        public static System.Collections.Generic.Dictionary<string, string> Parse(string json)
        {
            var result = new System.Collections.Generic.Dictionary<string, string>();
            if (string.IsNullOrWhiteSpace(json)) return result;

            // Clean up JSON string
            json = json.Trim().TrimStart('{').TrimEnd('}');
            string[] pairs = json.Split(',');

            foreach (var pair in pairs)
            {
                string[] parts = pair.Split(':');
                if (parts.Length == 2)
                {
                    string key = parts[0].Trim().Trim('"');
                    string val = parts[1].Trim().Trim('"');
                    result[key] = val;
                }
            }

            return result;
        }
    }
}

5. Configuration & Environment Setup​

Unsecure and Secure Configuration Schema​

When registering the plugin step, configurations should be structured as valid JSON. This allows the plugin to parse settings dynamically without hardcoding values.

Unsecure Configuration (Stored in Solution Metadata)​

{
  "MaxCreditLimitThreshold": 1500000.00,
  "AuditTaskSubject": "Compliance Audit: Credit Limit Threshold Exceeded"
}

Secure Configuration (Stored securely in target environment, not exported)​

{
  "ExternalAuditApiUrl": "https://api.contoso.com/v1/audit",
  "ExternalAuditApiKey": "prod-sec-key-99281-xXyZ"
}

Retrieving Environment Variables inside a Plugin​

Dataverse Environment Variables are stored in two tables:

  1. environmentvariabledefinition: Stores the schema and default value.
  2. environmentvariablevalue: Stores the environment-specific value override.

To retrieve an environment variable value within a plugin, use the following optimized query pattern:

public static string GetEnvironmentVariable(IOrganizationService service, ITracingService tracing, string schemaName)
{
    if (service == null) throw new ArgumentNullException(nameof(service));
    if (string.IsNullOrWhiteSpace(schemaName)) throw new ArgumentException("Schema name cannot be empty.", nameof(schemaName));

    tracing.Trace("Retrieving Environment Variable: {0}", schemaName);

    string query = @"
        <fetch version='1.0' mapping='logical' no-lock='true'>
            <entity name='environmentvariablevalue'>
                <attribute name='value' />
                <link-entity name='environmentvariabledefinition' from='environmentvariabledefinitionid' to='environmentvariabledefinitionid' link-type='inner'>
                    <filter type='and'>
                        <condition attribute='schemaname' operator='eq' value='{0}' />
                    </filter>
                </link-entity>
            </entity>
        </fetch>";

    EntityCollection results = service.RetrieveMultiple(new FetchExpression(string.Format(CultureInfo.InvariantCulture, query, schemaName)));

    if (results.Entities.Count > 0)
    {
        string val = results.Entities[0].GetAttributeValue<string>("value");
        tracing.Trace("Environment Variable retrieved from Value Override table.");
        return val;
    }

    // Fallback to Default Value in Definition table if no override exists
    string fallbackQuery = @"
        <fetch version='1.0' mapping='logical' no-lock='true'>
            <entity name='environmentvariabledefinition'>
                <attribute name='defaultvalue' />
                <filter type='and'>
                    <condition attribute='schemaname' operator='eq' value='{0}' />
                </filter>
            </entity>
        </fetch>";

    EntityCollection fallbackResults = service.RetrieveMultiple(new FetchExpression(string.Format(CultureInfo.InvariantCulture, fallbackQuery, schemaName)));

    if (fallbackResults.Entities.Count > 0)
    {
        string val = fallbackResults.Entities[0].GetAttributeValue<string>("defaultvalue");
        tracing.Trace("Environment Variable retrieved from Default Value table.");
        return val;
    }

    tracing.Trace("Environment Variable '{0}' not found.", schemaName);
    return null;
}

6. Security & Permission Matrix​

To execute custom plugins and access platform resources, the following security roles, privileges, and permissions must be configured:

PrincipalPermission / PrivilegeScopeReason
Deployment AdministratorprvCreatePluginAssembly
prvWritePluginAssembly		GlobalRequired to register, update, or delete plugin assemblies in on-premises deployments.
System AdministratorFull Customization PrivilegesGlobalRequired to register assemblies, steps, and images in cloud-based Dataverse environments.
Plugin Execution User (Calling User)prvReadAccount
prvWriteAccount		User / Business Unit / Parent / GlobalThe user triggering the update must have read/write privileges on the target record.
Plugin Execution User (Calling User)prvCreateTaskUser / Business Unit / Parent / GlobalRequired for the plugin to successfully create the audit task record on behalf of the user.
Impersonated User (if configured)prvActOnBehalfOfAnotherUserGlobalRequired if the plugin step is configured to run in the context of a specific user (impersonation).
Managed Identity (Azure Integration)Key Vault Secrets UserAzure ResourceRequired if the plugin uses Power Platform Managed Identity to retrieve secrets from Azure Key Vault.

7. Pipeline Execution Internals​

Understanding the internal mechanics of the Dataverse execution pipeline is critical for writing high-performance, bug-free plugins.

Client Request (e.g., Update Account)
  │
  ├──► Stage 10: Pre-Validation (Outside Transaction)
  │      ├── Security checks have NOT run yet.
  │      └── Ideal for basic validation. Throwing exception here avoids rollback overhead.
  │
  ├──► Database Transaction Starts
  │      │
  │      ├──► Stage 20: Pre-Operation (Inside Transaction)
  │      │      ├── Security checks have passed.
  │      │      ├── Target entity attributes can be mutated directly.
  │      │      └── Database locks are acquired. Keep execution extremely fast.
  │      │
  │      ├──► Stage 30: Main-Operation (Inside Transaction)
  │      │      └── Core platform writes data to SQL Server.
  │      │
  │      └──► Stage 40: Post-Operation (Inside Transaction)
  │             ├── Core database write is complete.
  │             ├── OutputParameters are populated.
  │             ├── Ideal for creating related records (e.g., Tasks, Audits).
  │             └── Synchronous steps run inside the transaction.
  │
  ├──► Database Transaction Commits
  │
  └──► Asynchronous Post-Operation Steps (Outside Transaction)
         └── Executed by the Async Service queue.

Transaction Boundaries and Rollback Behavior​

Synchronous plugins registered in stages 20 and 40 execute inside the database transaction.

  • If any synchronous plugin in the pipeline throws an exception, the platform aborts the entire operation.
  • All database changes made during the transaction—including the core operation and any database writes performed by the plugin (e.g., creating the audit task)—are rolled back.
  • Exception: Tracing logs written to the PluginTraceLog table are not rolled back. They persist even if the transaction fails, allowing developers to diagnose the failure.

Sandbox Isolation Mode and Callout Restrictions​

All custom plugins in Dataverse execute within an isolated, partial-trust security boundary called the Sandbox. The sandbox enforces strict security restrictions:

  1. No Local File System Access: Plugins cannot read or write files to the server's local disk.
  2. No Registry Access: Plugins cannot read or write registry keys.
  3. No GAC Access: Plugins cannot load assemblies from the Global Assembly Cache.
  4. Network Restrictions:
    • Plugins can only communicate over the network using HTTP/HTTPS (ports 80 and 443).
    • All other protocols (e.g., TCP, SMTP, FTP) are blocked.
    • IP addresses are blocked; you must resolve external endpoints using DNS names.
  5. Execution Timeout: There is a hard 2-minute (120 seconds) limit for the entire message operation to complete. If a plugin exceeds this limit, the sandbox process is terminated, throwing a TimeoutException and rolling back the transaction.

8. Error Handling & Retry Patterns​

Failure Modes and Remediation​

Error CodeException / Failure ModeRoot CauseCorrect Remediation
-2147204723Sandbox Worker process crashedStack overflow, unhandled thread exception, or memory limit exceeded.Wrap all code in try-catch blocks. Avoid spawning background threads. Ensure the plugin is stateless.
-2146893812ISV code reduced the open transaction countThe plugin caught a database exception from an IOrganizationService call and swallowed it, attempting to continue execution.Never swallow database exceptions. If an organization service call fails, you must throw an InvalidPluginExecutionException to abort the transaction.
-2147220911There is no active transactionA plugin ignored an error from a service call and attempted to perform subsequent database operations after the transaction was already marked for rollback.Immediately halt execution and throw an InvalidPluginExecutionException upon encountering any database fault.
-2147220970Message size exceeded when sending contextThe execution context payload exceeded the sandbox limit of 116.85 MB.Optimize step registration. Do not register plugins on messages containing massive binary attachments (e.g., annotation or activitymimeattachment).

Robust Error Handling Wrapper Pattern​

Always wrap your plugin execution in a standardized try-catch block to ensure that all exceptions are converted to InvalidPluginExecutionException with appropriate error codes.

try
{
    // Core plugin logic here
}
catch (FaultException<OrganizationServiceFault> ex)
{
    tracingService.Trace("Dataverse Database Fault: {0} (Code: {1})", ex.Message, ex.Detail.ErrorCode);
    // Throwing this ensures the transaction rolls back and displays a clean error to the user
    throw new InvalidPluginExecutionException(OperationStatus.Failed, ex.Detail.ErrorCode, "A database error occurred: " + ex.Message, ex);
}
catch (InvalidPluginExecutionException)
{
    // Re-throw direct platform exceptions to preserve custom messages
    throw;
}
catch (Exception ex)
{
    tracingService.Trace("Unhandled Exception: {0}", ex.ToString());
    // Wrap generic exceptions to prevent generic "Unexpected error from ISV" messages
    throw new InvalidPluginExecutionException(OperationStatus.Failed, -2147220956, "An unexpected error occurred in the business logic: " + ex.Message, ex);
}

Asynchronous Retry Pattern with Exponential Back-off​

When making external HTTP calls from within a sandboxed plugin, network glitches can cause transient failures. Use the following retry pattern with exponential back-off to handle transient errors gracefully:

using System.Net.Http;
using System.Threading;

public static string CallExternalApiWithRetry(string url, string payload, ITracingService tracing)
{
    int maxRetries = 3;
    int delayMilliseconds = 1000; // Start with 1 second delay

    using (var client = new HttpClient())
    {
        // Set aggressive timeout to prevent blocking the plugin thread
        client.Timeout = TimeSpan.FromSeconds(15);
        
        // Best Practice: Disable KeepAlive to prevent socket exhaustion in sandbox
        client.DefaultRequestHeaders.ConnectionClose = true;

        for (int i = 0; i < maxRetries; i++)
        {
            try
            {
                tracing.Trace("HTTP Call Attempt {0} to {1}", i + 1, url);
                var content = new StringContent(payload, Encoding.UTF8, "application/json");
                var response = client.PostAsync(url, content).GetAwaiter().GetResult();

                if (response.IsSuccessStatusCode)
                {
                    return response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
                }

                tracing.Trace("HTTP Status Code Failure: {0}", response.StatusCode);
            }
            catch (Exception ex)
            {
                tracing.Trace("HTTP Exception on attempt {0}: {1}", i + 1, ex.Message);
            }

            if (i < maxRetries - 1)
            {
                tracing.Trace("Waiting {0}ms before retry...", delayMilliseconds);
                Thread.Sleep(delayMilliseconds);
                delayMilliseconds *= 2; // Exponential back-off
            }
        }
    }

    throw new InvalidPluginExecutionException("External API call failed after maximum retries.");
}

9. Performance Optimisation & Limits​

To maintain platform stability and high throughput, plugins must adhere to strict performance limits.

Platform Limits​

  • Execution Timeout: Hard 2-minute limit per execution.
  • Trace Log Limit: The ITracingService can write a maximum of 10 KB of text per execution. If the trace exceeds 10 KB, older trace lines are truncated.
  • Payload Size Limit: The maximum payload size for sending context to the sandbox is 116.85 MB.
  • Memory Limit: Sandbox worker processes have a memory threshold. If a plugin leaks memory and causes the process to exceed the threshold, the worker process is killed instantly.

Optimization Strategies​

  1. Enforce Filtering Attributes: Never register an Update step without specifying filtering attributes. If no filtering attributes are set, the plugin will execute on every column update, causing severe performance degradation and infinite loops.
  2. Minimize Column Selection in Images: When registering Pre/Post Entity Images, select only the specific columns required by your logic. Selecting "All Columns" increases serialization overhead and database read times.
  3. Avoid Database Queries via Images: Use Pre-Entity Images to obtain the prior state of a record instead of executing a Retrieve request. This saves a database round-trip and reduces transaction lock times.
  4. Keep Plugins Stateless: Do not instantiate heavy objects or maintain state in class-level variables. Use local variables within the Execute method.
  5. Set Aggressive Timeouts for External Calls: The default timeout for .NET HttpClient is 100 seconds. This is too close to the 2-minute sandbox limit. Always set external call timeouts to 10-15 seconds to fail fast and release threads.
  6. Use No-Lock Queries: When querying data within a plugin using QueryExpression or FetchExpression, always set NoLock = true to prevent SQL blocking and deadlocks.

10. ALM & Deployment Checklist​

Moving plugins across environments (Development -> Test -> Production) must be fully automated using solutions and CI/CD pipelines.

Deployment Checklist​

  1. Build Configuration: Ensure the assembly is compiled in Release mode before exporting the solution.
  2. Assembly Signing: Verify the assembly is signed with a valid strong name key (.snk).
  3. Sandbox Isolation: Confirm the assembly is registered in Sandbox isolation mode.
  4. Solution Packaging: Ensure the plugin assembly, steps, and images are added to the unmanaged solution.
  5. Environment Variables: Do not hardcode environment-specific values. Use Dataverse Environment Variables and package them in the solution.
  6. Secure Configurations: Remember that secure configurations are not exported with solutions. You must manually apply secure configurations in the target environment or use a deployment script/API call during the release pipeline.

CI/CD Pipeline YAML Snippet (Azure DevOps)​

The following YAML snippet demonstrates how to automate the build, packaging, and deployment of Dataverse solutions containing plugins using the Power Platform Build Tools:

trigger:
- main

pool:
  vmImage: 'windows-latest'

variables:
  solutionName: 'EnterpriseBusinessLogic'
  devConnection: 'DataverseDevConnection'
  targetConnection: 'DataverseTestConnection'

steps:
- task: NuGetToolInstaller@1
  displayName: 'Install NuGet Tool'

- task: NuGetCommand@2
  displayName: 'Restore NuGet Packages'
  inputs:
    restoreSolution: '**/*.sln'

- task: MSBuild@1
  displayName: 'Build Plugin Assembly (Release)'
  inputs:
    solution: '**/*.csproj'
    configuration: 'Release'

# Tool Installer required for Power Platform Build Tools
- task: PowerPlatformToolInstaller@2
  displayName: 'Install Power Platform Build Tools'

# Export the unmanaged solution from Development
- task: PowerPlatformExportSolution@2
  displayName: 'Export Unmanaged Solution'
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: '$(devConnection)'
    SolutionName: '$(solutionName)'
    SolutionOutputFile: '$(Build.ArtifactStagingDirectory)/$(solutionName)_unmanaged.zip'
    AsyncOperation: true

# Pack the solution as Managed for downstream environments
- task: PowerPlatformPackSolution@2
  displayName: 'Pack Managed Solution'
  inputs:
    SolutionSourceFolder: '$(Build.SourcesDirectory)/src/$(solutionName)'
    SolutionOutputFile: '$(Build.ArtifactStagingDirectory)/$(solutionName)_managed.zip'
    Type: 'Managed'

# Publish the artifacts
- task: PublishBuildArtifacts@1
  displayName: 'Publish Solution Artifacts'
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)'
    ArtifactName: 'drop'

# Import the managed solution into the Test environment
- task: PowerPlatformImportSolution@2
  displayName: 'Import Solution to Test'
  inputs:
    authenticationType: 'PowerPlatformSPN'
    PowerPlatformSPN: '$(targetConnection)'
    SolutionInputFile: '$(Build.ArtifactStagingDirectory)/$(solutionName)_managed.zip'
    AsyncOperation: true
    PublishWorkflows: true

11. Common Pitfalls & Troubleshooting Guide​

1. Storing State in Class Member Variables​

  • Symptom: Intermittent bugs where data from one user's execution leaks into another user's execution.
  • Root Cause: The plugin class is cached and reused. Class-level fields are shared across concurrent threads.
  • Diagnostic Steps: Check if the class contains any non-static, non-readonly fields.
  • Fix: Move all execution-specific variables inside the Execute method.

2. Missing Filtering Attributes on Update Step​

  • Symptom: Severe performance degradation; database locks; plugin executes infinitely until depth limit is reached.
  • Root Cause: The plugin is registered on Update of account without filtering attributes. The plugin itself updates an account attribute, which triggers the plugin again.
  • Diagnostic Steps: Check the step registration in the PRT. Verify if "Filtering Attributes" is set to "All Attributes".
  • Fix: Explicitly select only the attributes that should trigger the business logic.

3. Swallowing Database Exceptions​

  • Symptom: SQL timeout errors or "ISV code reduced the open transaction count" exceptions.
  • Root Cause: Wrapping an IOrganizationService call in a try-catch block and swallowing the exception, allowing the plugin to continue.
  • Diagnostic Steps: Search the code for empty catch blocks or blocks that only log the error but do not re-throw.
  • Fix: Always throw an InvalidPluginExecutionException when a database operation fails.

4. Modifying Target Entity in Post-Operation Stage​

  • Symptom: Infinite loop error (Depth limit exceeded) or changes not being saved.
  • Root Cause: Attempting to modify attributes of InputParameters["Target"] in the Post-Operation stage. In Stage 40, the database write has already occurred; modifying the target has no effect unless you call service.Update(), which triggers a new update event and causes an infinite loop.
  • Diagnostic Steps: Check the registered stage. If it is PostOperation (Stage 40), check if the code modifies the Target entity directly.
  • Fix: Move attribute mutation logic to the PreOperation stage (Stage 20), where changes to the Target are automatically saved without a separate database call.

5. Casting InputParameters["Target"] Incorrectly​

  • Symptom: NullReferenceException or InvalidCastException during execution.
  • Root Cause: Assuming Target is always an Entity. On a Delete message, Target is an EntityReference. On an Associate message, Target is not present.
  • Diagnostic Steps: Check the message type and verify the cast logic.
  • Fix: Always validate the type of Target before casting: 
    if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is Entity) { ... }

6. Using Early-Bound Types in InputParameters Assignment​

  • Symptom: SerializationException when the platform attempts to serialize the execution context.
  • Root Cause: Assigning an early-bound entity class directly back to InputParameters["Target"].
  • Diagnostic Steps: Look for code like context.InputParameters["Target"] = new Account() { ... }.
  • Fix: Convert the early-bound entity to a late-bound Entity using .ToEntity<Entity>() before assigning it back to the collection.

7. Socket Exhaustion in Sandbox​

  • Symptom: Intermittent network connection failures when calling external APIs.
  • Root Cause: Re-instantiating HttpClient or WebClient on every execution without closing connections, leading to socket exhaustion within the sandbox container.
  • Diagnostic Steps: Check if HttpClient is instantiated without setting ConnectionClose = true.
  • Fix: Explicitly set ConnectionClose = true on the request headers to ensure sockets are released immediately.

8. Executing in the Context of a Disabled User​

  • Symptom: System.ServiceModel.FaultException: The user with SystemUserId = ... is disabled.
  • Root Cause: The plugin step is configured to run in the context of a specific user (impersonation), and that user's account has been disabled or their license removed.
  • Diagnostic Steps: Query the sdkmessageprocessingstep table to find steps where impersonatinguserid matches the disabled user ID.
  • Fix: Update the step registration in the PRT to run as the "Calling User" or a valid, active integration user.

9. Missing Pre-Image Registration​

  • Symptom: KeyNotFoundException: The given key was not present in the dictionary when accessing PreEntityImages.
  • Root Cause: The C# code attempts to access a pre-image alias that was not registered in the PRT.
  • Diagnostic Steps: Check if context.PreEntityImages.Contains("PreImage") returns false.
  • Fix: Open the PRT, right-click the step, and register the Pre-Image with the exact alias used in the code.

10. Exceeding the Trace Log Size Limit​

  • Symptom: Traces are truncated, and critical debug information at the end of the execution is missing.
  • Root Cause: Writing excessive debug logs to ITracingService, exceeding the 10 KB limit.
  • Diagnostic Steps: Check the length of the MessageBlock in the PluginTraceLog table.
  • Fix: Implement conditional tracing or limit logging to critical execution milestones and exception details.

12. Exam Focus: Key Facts & Edge Cases​

The following high-yield facts are critical for passing the PL-400 exam:

  • Assembly Target: Plugins must target .NET Framework 4.6.2. Targeting .NET Core, .NET Standard, or newer .NET versions will cause registration failures.
  • Sandbox Isolation: All custom plugins registered in Dataverse cloud environments must run in Sandbox isolation mode.
  • Stage Numbers: Memorize the exact stage numbers:
    • Pre-Validation = 10
    • Pre-Operation = 20
    • Main-Operation = 30 (Internal use only)
    • Post-Operation = 40
  • Transaction Boundaries: Stages 20 and 40 run inside the database transaction. Stage 10 runs outside the transaction (unless triggered from within an existing transaction chain).
  • Target Parameter Types:
    • Create message: Target is an Entity.
    • Update message: Target is an Entity containing only the changed attributes.
    • Delete message: Target is an EntityReference.
  • Entity Image Availability:
    • Pre-Image is not available on Create (the record does not exist yet).
    • Post-Image is not available on Delete (the record no longer exists).
    • Both are available on Update.
  • Impersonation IDs:
    • context.UserId represents the security context of the step execution (can be impersonated).
    • context.InitiatingUserId represents the actual user who triggered the action (always the real user).
  • Infinite Loop Prevention: The platform aborts execution if context.Depth exceeds 8 within a 1-hour window.
  • Shared Variables Scope: SharedVariables are only shared between plugins registered on the same message and executing in the same execution chain (e.g., passing data from Pre-Operation to Post-Operation of the same Create request).
  • Secure vs. Unsecure Configs: Unsecure configurations are exported with solutions; secure configurations are not exported. Secure configurations require System Administrator privileges to read.