dataverse-plugins

name: "dataverse-plugins" description: 'Build Microsoft Dataverse server-side extensions in C# (.NET) -- plugins implementing IPlugin and custom workflow activities -- and register them via SdkMessageProcessingStep so an agent can add transactional business logic that runs inside the Dataverse event pipeline. Covers the execution context, pipeline stages, registration metadata, and pro-code-vs-low-code boundaries.' metadata: author: "AgentX" version: "1.0.0" created: "2026-05-30" compatibility: surfaces: ["low-code-builder", "agent-x", "engineer"] platforms: ["power-platform", "dataverse", "dotnet", "csharp"]

Dataverse Plugins (Server-Side .NET)

Purpose: emit C# plugins / custom workflow activities and their registration so logic runs inside the Dataverse transaction -- the pro-code escape hatch when Power Automate / business rules cannot enforce a rule reliably.

When to Use (and When Not To)

Use a plugin when you need synchronous, transactional, low-latency server enforcement:

• Cross-record validation that MUST block a save
• Derived/calculated values that must be set in the same transaction
• Integration that must commit-or-rollback with the record

Prefer low-code first: business rules (form logic), calculated/rollup columns, and Power Automate flows (async, no compile/deploy). A plugin adds a C# build, signing, and deployment pipeline -- only pay that cost when the low-code options cannot meet the requirement.

The Event Pipeline

A plugin registers against a message + table + stage. Dataverse runs it when that message fires.

Mode: Synchronous (blocks the call, can throw to roll back) or Asynchronous (background, cannot block the user).

IPlugin

public sealed class ValidateIssue : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
        var service = factory.CreateOrganizationService(context.UserId);
        var tracing = (ITracingService)serviceProvider.GetService(typeof(ITracingService));

        if (context.InputParameters.TryGetValue("Target", out var t) && t is Entity target)
        {
            if (target.GetAttributeValue<string>("agx_name") is null or "")
            {
                throw new InvalidPluginExecutionException("Issue name is required.");  // rolls back
            }
            tracing.Trace("ValidateIssue passed for {0}", target.Id);
        }
    }
}

Contract:

• Plugin classes MUST be stateless (one instance serves many requests) -- never use instance fields for per-request data.
• Throw InvalidPluginExecutionException to surface a user-facing error and roll back a sync step.
• Read context.Depth and guard against infinite loops (your Update firing your own step again).
• Use ITracingService for diagnostics -- it surfaces in the plugin trace log.

Registration (SdkMessageProcessingStep)

Steps are metadata, registered with the Plugin Registration Tool or pac plugin, and travel in a solution:

src/
  PluginAssemblies/<AssemblyName>/      # signed .dll + assembly metadata
  SdkMessageProcessingSteps/<step>.xml  # message=Create/Update, table, stage, mode, filtering attributes

Set filtering attributes on Update steps so the plugin only fires when relevant columns change -- not on every save.

Custom Workflow Activities

For reusable steps invoked from Power Automate (legacy classic workflows / some flows), implement CodeActivity with InArgument/OutArgument. Same assembly, registered as a workflow activity rather than a step.

Anti-Patterns

• Long-running or external HTTP calls in a synchronous step -- blocks the user and risks the 2-minute timeout; use async or a flow.
• No filtering attributes on Update -- the plugin runs on every column change, hurting throughput.
• Instance state on the plugin class -- cross-request data corruption.
• Re-implementing in C# what a business rule or flow already does -- unjustified pro-code cost.
• Ignoring Depth -- self-triggering recursion.

Verify

dotnet build -c Release          # assembly must compile and be signed
pac plugin push ...              # register against a dev environment, exercise the message

Related

• power-automate-flow-json -- async no-code alternative
• dataverse-schema -- the tables/columns plugins read and write
• solution-anatomy -- PluginAssemblies + step packaging