Skip to content

04 Push Plugins and Custom APIs

Jump to bottom
RemyDuijkeren edited this page Jul 21, 2026 · 5 revisions

Push Plugins and Custom APIs

Flowline uses source-only NuGet package Flowline.Attributes to register Dataverse plugin steps and Custom APIs. Add it to your Plugins project:

<PackageReference Include="Flowline.Attributes" Version="1.0.0" PrivateAssets="all" />

PrivateAssets="all" keeps this as a development-time dependency. The attributes compile directly into your assembly — no extra DLL is shipped.

Run flowline push and Flowline inspects your compiled assembly, then creates or updates all registrations in Dataverse — no Plugin Registration Tool needed.

Plugin steps

Flowline registers exactly one plugin step per IPlugin class.

The message, stage, and processing mode come from the class name; the table and options come from attributes.

Any class that implements IPlugin — directly or through a base class — is eligible. Using your own PluginBase : IPlugin works fine; Flowline walks the full inheritance chain.

The pipeline

Stage keyword When it runs In transaction? Use for
Validation Before the transaction opens No Throwing to reject the operation cleanly
Pre Before the record is saved Yes Enriching or correcting incoming data
Post (sync) After the record is saved Yes Follow-up writes that must be atomic
Post + Async After the transaction closes No Notifications, external API calls, long-running work

Class naming convention

{DescriptiveName}{Stage keyword}{Message}[Async][Plugin]
Class name Message Stage Mode
SetNamePostCreatePlugin Create PostOperation Synchronous
RecalculateTotalsPreUpdatePlugin Update PreOperation Synchronous
OwnershipValidationDeletePlugin Delete PreValidation Synchronous
NotifyPostUpdateAsyncPlugin Update PostOperation Asynchronous

The {DescriptiveName} describes what the plugin does, it can have the table name but it doesn't need to. The table is declared on [Step].

For {Stage keyword} we use the shortened versions Pre, Post and Validation to match the Dataverse pipeline terminology (PreOperation, PostOperation, PreValidation) because it makes the class names more concise and readable, like SetNamePostCreatePlugin. To make it async you add the Async suffix, like the normal C# convention.

The {Message} is the Dataverse message, like Create, Update, Delete, Associate, Disassociate, AddToQueue, etc. The message is case-sensitive and must match the Dataverse message exactly. See also Available events.

Classes without [Step] are skipped for step registration. Classes with [Step] must follow the naming convention — Flowline fails fast when it cannot parse the stage and message or when invalid combinations are used.

Brownfield class names. If you can't rename an existing class, use [Handles] — see below.

[Step] — required

Specifies the table logical name. Without it, Flowline ignores the class.

[Step("account")]
public class SetNamePostCreatePlugin : IPlugin { ... }

The logical name is lowercase, found in the maker portal under Table → Properties → Name.

Registering on all tables: pass "none" explicitly:

[Step("none")]
public class GlobalPreCreatePlugin : IPlugin { ... }

Optional named properties:

Property Type Default Description
Order int 1 Execution order when multiple steps fire on the same event. Lower runs first.
RunAs string? null GUID of the systemuser to impersonate. null runs as the calling user.
Config string? null Passed to the plugin constructor as unsecureConfig.
Description string? null Description shown in the Plugin Registration Tool.
DeleteJobOnSuccess bool true Delete the AsyncOperation job record on success. Async steps only.
SecondaryTable string? null Secondary table for Associate / Disassociate steps. Pass "none" to match any secondary table.

[Filter] — optional, strongly recommended on Update steps

Limits the step to fire only when at least one of the listed columns is included in the operation. Without [Filter], an Update step fires on every update to the table. Flowline warns if you omit it on an Update step.

[Step("account")]
[Filter("name", "creditlimit")]
public class RecalculateTotalsPreUpdatePlugin : IPlugin { ... }

Use nameof with early-bound classes for compile-time safety:

[Filter(nameof(Account.name), nameof(Account.creditlimit))]

[Filter] only applies to Update steps. Using it on any other message is an error.

[PreImage] and [PostImage] — optional

Register snapshots of the record before and after the operation.

Availability by message and stage:

PreImage PostImage
Create Not available PostOperation only
Update Any stage PostOperation only
Delete Any stage Not available

Violations are errors — Flowline throws during flowline push.

Specify only the columns your plugin needs. Omitting columns fetches all of them, which negatively impacts performance.

[Step("account")]
[Filter("name", "creditlimit")]
[PreImage("name", "creditlimit")]
[PostImage("name", "creditlimit")]
public class RecalculateTotalsPostUpdatePlugin : IPlugin
{
    public void Execute(IServiceProvider sp)
    {
        var ctx       = (IPluginExecutionContext)sp.GetService(typeof(IPluginExecutionContext));
        var preImage  = ctx.PreEntityImages["preimage"];
        var postImage = ctx.PostEntityImages["postimage"];
    }
}

Default aliases are "preimage" and "postimage". Override Alias when migrating from a step with a different alias:

[PreImage(Alias = "legacy_pre")]  // retrieve with: ctx.PreEntityImages["legacy_pre"]

One image per type, by design. [PreImage] and [PostImage] each allow at most one instance per class — this is intentional, not a Dataverse limitation (the platform itself allows multiple images of the same type on one step). Splitting one step's columns across several same-type images has no benefit over declaring them together on a single image, so Flowline doesn't expose the option. Flowline finds an existing image by (step, image type); renaming Alias or changing the column list updates the same record in place.

[Handles] — brownfield escape hatch

When a class name doesn't follow the naming convention, use [Handles] to declare message and stage explicitly:

[Step("account")]
[Handles(Message.Update, Stage.PreOperation)]
public class AccountPlugin : IPlugin { ... }

// Async
[Step("account")]
[Handles(Message.Create, Stage.PostOperationAsync)]
public class AccountPlugin : IPlugin { ... }

// Custom API message
[Step("account")]
[Handles("mynamespace_MyAction", Stage.PostOperation)]
public class AccountPlugin : IPlugin { ... }

[Handles] requires [Step] to be present.

Stacking [Handles] — last resort for brownfield migration

Caution

Stacking [Handles] goes against Flowline's intent. Flowline is designed around one class = one step — the class name carries the step's identity. Multi-step classes obscure that contract and make push output harder to read.

Hard limitation: all stacked handles share the same [Step], which sets the primary table. If any two steps fire on different primary tables, stacking cannot help — you need two separate classes regardless.

Use only when migrating from a tool where one class handled multiple steps and splitting right now is not feasible. Split into named subclasses as soon as the migration window allows.

// Valid — both steps fire on the same table ("account")
[Step("account")]
[Handles(Message.Create, Stage.PostOperation)]
[Handles(Message.Update, Stage.PostOperation)]
public class AccountPlugin : IPlugin { ... }

// Not possible via stacking — steps fire on different tables
// These must be separate classes with separate [Step] attributes
[Step("account")]
[Handles(Message.Create, Stage.PostOperation)]
[Step("contact")]                                 // ← compile error: duplicate attribute
[Handles(Message.Update, Stage.PostOperation)]
public class MultiTablePlugin : IPlugin { ... }

Each [Handles] produces one step. When two handles share the same message, all step names include the stage suffix to stay distinct:

  • MyNamespace.AccountPlugin: Update of account at PreOperation
  • MyNamespace.AccountPlugin: Update of account at PostOperation

[Filter], [PreImage], and [PostImage] are applied per-step based on message compatibility.

Flowline emits a warning once per class (on the first step) to flag the multi-step pattern.

Splitting changes step names. The next push deletes the old steps and creates new ones — plan for a maintenance window.

Associate / Disassociate

Use SecondaryTable on [Step] to scope the step to a specific secondary table:

// Fires when a contact is associated with any record type
[Step("contact", SecondaryTable = "none")]
public class ContactPreAssociatePlugin : IPlugin { ... }

// Fires only when a contact is associated with an account
[Step("contact", SecondaryTable = "account")]
public class ContactAccountPreAssociatePlugin : IPlugin { ... }

On Associate/Disassociate steps, pass "none" to match any secondary table.

Plugin Lifecycle

On every flowline push:

  • Plugin types — created for every public IPlugin or CodeActivity class; deleted when the class is removed.
  • Steps — created or updated for every class with [Step]; deleted when [Step] is removed or the class is deleted.

Steps created by Flowline are stamped with [flowline] in their description, visible in Plugin Registration Tool.

Step identity. Flowline finds an existing step by (message, table filter, stage, mode) on the owning plugin type — never by the generated display name. Renaming a class or otherwise changing the display text updates the same Dataverse row in place; it never deletes and recreates the step. Changing the message, table, stage, or mode itself is a different registration, so it does recreate the step — a PreValidation step runs at a genuinely different point in the pipeline than a PostOperation step, so this is a real behavior change, not just cosmetics.

Use --no-delete to suppress all deletions for a run. Use --dry-run to preview changes without applying them.

Custom APIs

A Custom API is a custom endpoint invoked explicitly by name — from Power Automate, a canvas app, a web resource, or another plugin.

Add [CustomApi] to an IPlugin class to register it as a Custom API.

Class naming

Flowline strips the Api, CustomApi, or Plugin suffix and prefixes the result with the solution's publisher prefix:

Class name Unique name
GetAccountRiskApi av_GetAccountRisk
SendNotificationCustomApi av_SendNotification
ApproveOrderPlugin av_ApproveOrder

[CustomApi] — required

Without arguments, registers a global API — not tied to any table:

[CustomApi]
public class SendNotificationApi : IPlugin { ... }

Pass a table logical name for entity binding:

[CustomApi("salesorder")]
public class ApproveOrderApi : IPlugin
{
    public void Execute(IServiceProvider sp)
    {
        var ctx     = (IPluginExecutionContext)sp.GetService(typeof(IPluginExecutionContext));
        var orderId = ((EntityReference)ctx.InputParameters["Target"]).Id;
    }
}

Optional named properties:

Property Type Default Description
IsFunction bool false true = Function (HTTP GET). false = Action (HTTP POST).
IsPrivate bool false Hides the API from the OData catalog.
AllowedStepType AllowedStepType None Whether third parties can register plugin steps on this API.
DisplayName string? class name split Shown in solution explorer.
Description string? null Shown in solution explorer.
ExecutePrivilege string? null Privilege required to call this API.
UniqueName string? class name derived Overrides the unique name. Complete name, publisher prefix included (e.g. "dev1_MyCustomApi"). See Class naming.

[Input] and [Output]

Declare Custom API parameters on the class:

[CustomApi]
[Input("accountId",      FieldType.EntityReference, Table = "account")]
[Input("includeHistory", FieldType.Boolean, IsOptional = true)]
[Output("riskScore",     FieldType.Integer)]
[Output("riskLabel",     FieldType.String)]
public class GetAccountRiskApi : IPlugin
{
    public void Execute(IServiceProvider sp)
    {
        var ctx = (IPluginExecutionContext)sp.GetService(typeof(IPluginExecutionContext));

        var accountId   = (EntityReference)ctx.InputParameters["accountId"];
        var withHistory = ctx.InputParameters.Contains("includeHistory")
                          && (bool)ctx.InputParameters["includeHistory"];

        ctx.OutputParameters["riskScore"] = ComputeScore(accountId, withHistory);
        ctx.OutputParameters["riskLabel"] = "High";
    }
}

Always check Contains before reading an optional input.

[Input] properties:

Property Type Default Notes
Name string — Key in context.InputParameters. Convention: camelCase.
Type FieldType — See type table below.
IsOptional bool false Check Contains("name") before reading when true.
Table string? null Required when type is EntityReference or Entity.
DisplayName string? name split Shown in solution explorer.
Description string? null

[Output] has the same properties except IsOptional.

Supported field types

C# type in Execute FieldType
bool Boolean
DateTime DateTime
decimal Decimal
Entity Entity
EntityCollection EntityCollection
EntityReference EntityReference
float / double Float
int Integer
Money Money
OptionSetValue Picklist
string String
string[] StringArray
Guid Guid

Custom API Lifecycle

Flowline treats the DLL as the source of truth for Custom APIs, the same as for steps.

  • Created when a class with [CustomApi] has no matching unique name in Dataverse.
  • Updated when mutable fields change (DisplayName, Description, IsPrivate, ExecutePrivilege).
  • Deleted and recreated when an immutable field changes (binding type, IsFunction, AllowedStepType, or a parameter's type or optionality). Flowline warns before doing this.
  • Deleted when the class or [CustomApi] is removed — provided the live record's implementation is a plugin type this push owns. A Custom API that points at a plugin type from another project, or at nothing at all, is left alone. See What push deletes, with several projects.

The --no-delete flag suppresses deletions the same way it does for steps.

Why one class per step

Each plugin class registers exactly one step. This constraint pays dividends:

Unambiguous attributes. [Filter], [PreImage], and [PostImage] always belong to exactly one step — the one the class registers. No need to associate them with a particular step in a multi-step registration.

Focused Execute bodies. Without the rule, Execute needs branching logic to handle different messages. With it, every Execute does one thing — Dataverse guarantees which step fired because only one is registered.

Self-describing logs. When a plugin throws, Dataverse logs the class name. SetNamePostCreatePlugin tells you exactly what happened; AccountPlugin does not.

Shared logic via base classes. The rule does not mean duplicating code. Put shared logic in a base class and declare one leaf class per step:

public abstract class AccountSavePlugin : IPlugin
{
    public void Execute(IServiceProvider sp) { /* shared logic */ }
}

[Step("account")]
public class AccountPreCreatePlugin : AccountSavePlugin { }

[Step("account")]
public class AccountPreUpdatePlugin : AccountSavePlugin { }

// Same pattern for multiple entities:
[Step("contact")]
public class ContactPreCreatePlugin : AccountSavePlugin { }

One assembly for everything

Flowline supports IPlugin classes, CodeActivity workflow activities, and [CustomApi] classes all in the same assembly. One Plugins project, one build output (a classic .dll or a NuGet .nupkg package — see PluginPackageMode), one flowline push. That's the default and it's the right shape for most solutions — but it is a default, not a limit; see More than one plugin project.

CodeActivity classes need the classic .dll path — Dataverse's Dependent Assemblies feature only auto-creates plugin records for IPlugin classes, not workflow activities. If a .nupkg build contains a CodeActivity class, push rejects it before uploading and names the offending type; move workflow activities to a separate project built as a .dll (or force PluginPackageMode: Dll for that project).

Other tools run a separate sync pass per type — each pass deletes registrations it doesn't recognise, causing the passes to destroy each other's work. Flowline reads all types in a single pass and registers everything together.

This also means:

  • No separate early-bound types project — generated classes live directly in Plugins/.
  • No ILMerge — external references are resolved normally by the build.
  • Fewer projects, less cognitive overhead, simpler pipeline.

Microsoft's best practices recommend consolidating plug-ins and custom workflow activities into a single assembly.

More than one plugin project

A solution can hold several plugin projects, and one flowline push registers all of them. Each gets its own assembly, plugin types, steps, and Custom APIs under the same Dataverse solution.

You don't configure this. push reads the solution file, takes every .csproj it references, and reflects each one's build output for IPlugin or CodeActivity types. Whatever has them is a plugin project. Whatever doesn't — a shared library, your web resources project — is skipped. Run with --verbose to see what was skipped and why.

That also means the folder and project names are yours. Plugins/<SolutionName>.Plugins.csproj is what clone scaffolds, not what push requires. A custom <AssemblyName>, a build output with no publish/ subfolder, a project called Contoso.Sales.Plugins in a folder called Sales — all fine, as long as the solution file references it.

Renaming an existing project changes the assembly's identity as far as Dataverse is concerned — it registers as a new assembly, and the old one and its steps stay behind as orphans. push reports them; --force delete-orphans clears them. Steps and Custom APIs re-derive from your source attributes, so nothing is lost.

When to split. Two reasons come up in practice: separating business areas that change on different cadences, and the CodeActivity case above — workflow activities need the classic .dll path, so a solution using .nupkg packaging can put them in their own project rather than giving up packaging everywhere.

What push deletes, with several projects

push removes registrations that no longer have source behind them. Assemblies and steps and Custom APIs follow different rules, because the underlying records aren't shaped the same way.

Assemblies and steps. A step belongs to its plugin type, and a plugin type belongs to one assembly, so "which project owns this" always has an answer. Anything in the solution that no discovered project produces is an orphan — reported on every push, deleted only with --force delete-orphans. push accounts for every project it discovered, so a sibling's assembly is never mistaken for an orphan.

Custom APIs are different. A Custom API points at a plugin type as its implementation, rather than belonging to one. It can exist with no implementation at all, and there's no way to ask Dataverse for "the Custom APIs of this assembly" — only for everything under your publisher prefix, which spans every project and every repo that shares that prefix. So push deletes a Custom API only when it can prove the API is its own:

The API's implementation What push does
A plugin type this push owns, and source no longer declares the API Deleted
A plugin type this push doesn't own Never deleted, with or without --force. --verbose says why it was left
Nothing — no plugin type set Left alone; deleted only with --force delete-orphans

The last row is deliberate: a Custom API with no implementation may be a contract someone is about to implement, not a leftover. And a Custom API is a public API surface — other people's code calls it — so the bar to delete one is higher than for a step.

The practical consequence: push the whole solution, not a subset. All the projects a solution contains are discovered and pushed together, which is what keeps the orphan set correct. Something genuinely abandoned — an assembly no project produces any more — is still flagged and still cleaned up under the existing rules.

One failure stops the run. If a project fails to push, the error names it, lists which assemblies already reached the org, and lists which were not attempted. Nothing is skipped quietly. Fix the named project and push again — the ones that already landed are idempotent.

Clone this wiki locally