ppbp-dv-plugins

Official skill

No official Microsoft skill exists for this topic. Dataverse plug-in authoring (IPlugin, Custom APIs, PAC CLI plugin workflow) is not covered by any official skill in the dataverse:* or code-apps-preview:* namespaces.

Repository layout

This skill owns the following paths in the canonical repository layout (see ppbp-overview):

<repo-root>/
└── plugins/
    └── <plugin-name>/   # One subfolder per Dataverse Plugin project (scaffolded by pac plugin init)
        ├── <PluginName>.csproj
        ├── <PluginName>.snk
        ├── PluginBase.cs
        └── Models/      # Early-bound classes generated by pac modelbuilder build

Each plugin lives in its own subfolder. Never place .csproj files directly under plugins/.

Best practices

1. Target .NET Framework 4.6.2 for on-premises compatibility and net8.0 for isolated (sandbox) plug-ins on the cloud — choose at project creation, not after.
2. Always scaffold with pac plugin init — never create plugin projects by hand; it generates PluginBase.cs, the strong-name key (.snk), and the correct .csproj NuGet package configuration.
3. All plugin classes must extend PluginBase (generated by pac plugin init) and override ExecuteDataversePlugin — this base class standardises context resolution and exception wrapping. Never implement IPlugin.Execute directly in a pac-init project.
4. Use early-bound classes generated by pac modelbuilder build — never use late binding (entity["attribute"]); it bypasses compile-time safety and column security.
5. Retrieve only the columns you need in pre/post images and in explicit Retrieve calls — never use ColumnSet(true); it ignores column security and wastes bandwidth.
6. Use the service factory pattern: resolve IOrganizationService once per execution from serviceFactory.CreateOrganizationService(context.UserId) so the call runs under the triggering user's security context.
7. Register Custom APIs instead of custom messages for new extensibility points — Custom APIs are first-class, discoverable, and callable from Power Automate and client SDKs.
8. Always set FullyQualifiedWebApiName on Custom API request/response parameters — it controls how they appear in the Web API and Power Automate.
9. Throw InvalidPluginExecutionException (not generic exceptions) to surface user-facing errors; use OperationStatus.Failed only for business rule failures.
10. Register steps with the most restrictive image — use Pre-Image only when you need pre-update values; avoid Post-Image on synchronous steps (performance cost).
11. Increment AssemblyVersion and FileVersion in .csproj before every deployment — Dataverse uses the version to detect assembly changes; deploying without a version bump can silently skip the update or cause deployment conflicts.

PAC CLI workflow

1 — Scaffold the project

pac plugin init --outputDirectory <ProjectName> --author "<Author>"

Generates: PluginBase.cs, <ProjectName>.snk, <ProjectName>.csproj, sample plugin file.
After init: set <RootNamespace>, update NuGet metadata (Company, Description), leave <PluginId> empty until first deployment.

2 — Generate early-bound classes

pac modelbuilder build \
  --outdirectory <ProjectName>/Models \
  --namespace <Company>.<Product>.Models \
  --environment https://<org>.crm.dynamics.com/ \
  --emitfieldsclasses \
  --generateGlobalOptionSets \
  --entitynamesfilter "table1;table2;table3"

Do not add --generatesdkmessages — it floods the project with SDK message classes that are not needed.

3 — Increment version before every build

In .csproj, bump both fields:

<AssemblyVersion>1.0.1.0</AssemblyVersion>
<FileVersion>1.0.1.0</FileVersion>

Use Major.Minor.Patch.Build: Patch for bug fixes, Minor for new features, Major for breaking changes.

4 — Release build

dotnet clean && dotnet build -c Release

dotnet clean is mandatory — without it the NuGet package is not regenerated and the version bump is silently ignored.

Output: bin/Release/net462/<ProjectName>.dll and bin/Release/<ProjectName>.<Version>.nupkg.

5 — Deploy

First deployment — pac plugin push requires an existing plugin GUID. Register the assembly once via the Plugin Registration Tool, then store the returned GUID in .csproj:

<PluginId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</PluginId>

Subsequent deployments — read the GUID from .csproj and push:

PLUGIN_ID=$(dotnet msbuild <ProjectName>.csproj -getProperty:PluginId -nologo)
pac plugin push --pluginId "$PLUGIN_ID" --pluginFile ./bin/Release/net462/<ProjectName>.dll

Never use --solution-name — it creates a solution dependency and breaks across environment boundaries.

Common issue: dotnet clean and version bumps

Skipping dotnet clean before a release build silently deploys the old assembly even when .csproj has been updated with a new version number — the NuGet package is not regenerated. Always run dotnet clean && dotnet build -c Release.

Common issue: First deployment requires the Plugin Registration Tool

pac plugin push --pluginId requires a GUID that only exists after the assembly has been registered at least once. There is no CLI-only path for the initial registration — the Plugin Registration Tool (available via NuGet: Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool) must be used once to create the record and obtain the GUID, which is then stored in <PluginId> in .csproj for all subsequent deployments.

Anti-patterns (DO NOT DO)

Anti-pattern	Correct approach
Storing state in instance fields — Dataverse reuses plug-in instances across calls; instance fields accumulate state from previous executions.	Declare all working variables inside ExecuteDataversePlugin().
Calling the organisation service in PreValidation — The transaction has not started; service calls create a nested transaction and can cause deadlocks.	Move data access to PreOperation or PostOperation.
Missing plug-in registration update after schema changes — If a step uses an explicit image with a fixed column set, new columns are silently excluded.	Update the image's attribute list in the Plugin Registration Tool after every schema change that affects step images.
Unbound Custom API used for record-scoped operations (or bound for global operations) — Choosing the wrong type breaks the Web API path.	Unbound for global operations, bound for record-scoped operations.
Catching all exceptions silently — Swallows failures in asynchronous steps where no UI feedback exists.	Log to the Dataverse trace log (ITracingService) and re-throw, or throw InvalidPluginExecutionException.
Deploying with --solution-name — Creates a solution dependency, is slower, and breaks across environment boundaries.	Store the plugin GUID in <PluginId> in .csproj and use pac plugin push --pluginId ... --pluginFile ....
Skipping dotnet clean before a release build — The NuGet package is not regenerated; a version bump in .csproj is silently ignored.	Always run dotnet clean && dotnet build -c Release.
Resolving security roles by display name across Business Units — Every BU has its own copy of each role with the same display name; querying by name returns all copies with no deterministic result.	Query by ParentRootRoleId (the root role's GUID) filtered to the target BU — see example below.

Security role resolution — Wrong vs Correct:

	Wrong	Correct
Query filter	name == "My Role"	parentrootroleid == rootRoleId AND businessunitid == targetBuId

// Wrong — returns every BU's copy of the role
var wrong = service.RetrieveMultiple(new QueryExpression("role")
{
    ColumnSet = new ColumnSet("roleid"),
    Criteria = { Conditions = { new ConditionExpression("name", ConditionOperator.Equal, roleName) } }
});

// Correct — returns exactly the BU-specific instance
var correct = service.RetrieveMultiple(new QueryExpression("role")
{
    ColumnSet = new ColumnSet("roleid"),
    Criteria =
    {
        Conditions =
        {
            new ConditionExpression("parentrootroleid", ConditionOperator.Equal, rootRoleId),
            new ConditionExpression("businessunitid",   ConditionOperator.Equal, targetBuId)
        }
    }
});
var roleId = correct.Entities.Single().Id;

Skill boundaries

This skill covers Dataverse plug-ins and Custom APIs only. It does not cover:

• Dataverse schema design (tables, columns, relationships) → ppbp-dv-metadata
• Solution lifecycle and deployment pipelines → ppbp-alm
• Power Automate cloud flows → out of scope for this plugin
• Code App or Generative Page development → ppbp-code-apps / ppbp-generative-pages