DEV Community: Ján

Moving from spkl to Pillaro: A Practical Migration Guide for Dataverse Plugins

Ján — Wed, 23 Sep 2026 17:38:47 +0000

Part 1/4 of the Modern Dataverse Plugin Development series.

A practical look at what Pillaro can replace in an existing spkl-based Dataverse plugin project, what changes during migration, and what Pillaro deliberately does not try to replace.

If you have been building Dataverse plugins for a while, there is a good chance you have come across spkl.

For years, spkl solved a very real problem: stop registering and deploying Dataverse plugins manually. Instead of clicking through the Plugin Registration Tool for every environment, developers could describe registration in code and configuration and deploy it repeatedly.

A lot of existing Dataverse solutions still use that model today.

The problem is that spkl is no longer actively evolving with the Dataverse development ecosystem. The main SparkleXrm repository has seen no meaningful spkl development for a long time, while unresolved issues around newer Microsoft tooling and authentication remain open. For example, an incompatibility with a newer Microsoft.CrmSdk.CoreTools version was reported in 2022 and remains open today.

That does not mean every existing spkl project suddenly needs to be rewritten.

If your project is stable, its dependencies are pinned, deployment works, and you are not actively changing the solution, migration may give you very little value.

But if you are maintaining an actively developed Dataverse codebase, upgrading dependencies, introducing automated testing, or trying to make deployment more predictable, you may eventually need a path forward.

That is the problem Pillaro is trying to solve.

Pillaro is listed in Microsoft Learn's Community Tools for Microsoft Dataverse catalog and is also published in Microsoft Marketplace. The Marketplace offer installs the Dataverse-side runtime layer, while the C# framework itself is consumed through NuGet.

These listings provide Microsoft ecosystem discovery and distribution paths, but Pillaro remains a community-maintained framework. Microsoft explicitly states that community tools are supported by their publishers rather than by Microsoft.

Microsoft Learn listing · Microsoft Marketplace

Pillaro is also listed in Microsoft Learn's Community Tools for Microsoft Dataverse catalog. It remains a community-maintained framework rather than a Microsoft-supported product, but its inclusion gives Dataverse developers another official documentation path to discover the project.

Community Tools for Microsoft Dataverse — Microsoft Learn

This is not "spkl vs Pillaro"

Pillaro is not a fork of spkl and it is not trying to recreate every spkl command.

spkl is primarily a deployment task runner around the standard Dataverse development model.

Pillaro is a plugin development framework with deployment and registration built into that model.

There is overlap, especially around plugin registration and deployment, but the scope is different.

The useful question therefore is not:

Which one is better?

It is:

If my project uses spkl today, which parts can Pillaro replace, what will change, and what will I need to handle differently?

That is what this article covers.

What spkl typically does in a Dataverse project

A typical spkl-based plugin project can use spkl for several responsibilities:

deploying plugin assemblies,
defining plugin step registration using [CrmPluginRegistration],
configuring registrations through spkl.json,
registering images and filtering attributes,
reverse-engineering an existing deployment using spkl instrument,
generating early-bound classes,
deploying web resources,
unpacking and packing Dataverse solutions.

That was one of spkl's strengths: a relatively small tool could cover a surprisingly large part of the Dynamics/Dataverse developer workflow.

But those responsibilities do not necessarily need to stay in one tool forever.

Microsoft's own tooling has evolved significantly since spkl was introduced. Today, operations such as solution management and model generation have first-party alternatives in the Power Platform CLI.

Pillaro therefore focuses on the part we believe belongs closest to the plugin code itself:

plugin structure, registration, deployment and testing.

What Pillaro can replace

1. Plugin assembly deployment

spkl: yes
Pillaro: yes

Both approaches can deploy a compiled plugin assembly into Dataverse.

The important difference is what happens around the assembly.

With spkl, deployment tooling discovers plugin registration metadata from your assembly and configuration.

With Pillaro, deployment is part of a framework where the registration declared by the plugin code is treated as the desired state of the environment.

2. Plugin step registration as code

spkl: yes
Pillaro: yes

With spkl you typically define registration using attributes such as:

[CrmPluginRegistration(
    MessageNameEnum.Update,
    "account",
    StageEnum.PostOperation,
    ExecutionModeEnum.Synchronous,
    "name,address1_city",
    "Account updated",
    1,
    IsolationModeEnum.Sandbox)]

Pillaro keeps runtime task registration and deployment metadata separate. Deployment metadata is declared through Register(IPluginRegistration registration) using the fluent registration API:

public override void Register(IPluginRegistration registration)
{
    registration
        .OnUpdate<Account>("00000000-0000-0000-0000-000000000000")
        .PostOperation()
        .Synchronous()
        .WhenChanged(
            Account.Fields.Name,
            Account.Fields.Address1_City);
}

The step ID is part of the registration contract and is required. Filtering attributes are declared with WithFilteringAttributes(...), or its more readable alias WhenChanged(...), rather than being hidden in deployment configuration.

The exact syntax differs from spkl, but the important property is the same: the registration is explicit in source control and can travel through environments with the code.

3. Filtering attributes, images and execution order

spkl: yes
Pillaro: yes

Pillaro registration supports the registration metadata you normally need for Dataverse plugin steps, including:

message,
entity,
pipeline stage,
execution mode,
filtering attributes,
pre-images,
post-images,
execution order / rank.

This means the core plugin-registration responsibility that many teams originally adopted spkl for can move into Pillaro.

4. Removing registrations that no longer exist in code

This is where the approaches start to differ more substantially.

A common problem in Dataverse projects is registration drift.

A step existed six months ago. Someone removed or renamed it in code. The assembly gets redeployed — but the old registration remains in one environment.

Now DEV, TEST and PROD no longer contain the same plugin topology.

Pillaro deployment treats registration in code as authoritative.

If a plugin step was previously deployed by Pillaro and is no longer declared, the deployer can detect the difference and remove the obsolete registration.

The intended model is:

Code registration
       ↓
Desired state
       ↓
Compare with Dataverse
       ↓
Create / update / remove
       ↓
Environment matches code

For us, this was one of the main reasons to build the deployment model in the first place.

What Pillaro adds beyond the spkl workflow

Migration does not have to stop at replacing deployment scripts.

Pillaro also introduces a different way of structuring plugin behavior.

Explicit validation and execution

A recurring problem we saw in larger Dataverse implementations was plugin code where everything gradually accumulated inside Execute:

Execute
 ├─ get context
 ├─ check stage
 ├─ validate data
 ├─ load records
 ├─ apply business rules
 ├─ execute changes
 └─ handle errors

The code works.

Then it grows.

Pillaro uses an explicit task model where validation and execution are separate phases.

Conceptually:

Dataverse event
      ↓
Plugin Task
      ↓
Validate
      ↓
Execute

Validation can fail before the execution phase touches the business operation.

The goal is not abstraction for abstraction's sake. It is to make the execution flow obvious and make individual pieces easier to test.

Integration testing against real Dataverse

Pillaro also includes a separate testing package designed for integration tests against an actual Dataverse environment.

Tests:

prepare test data,
create or update records in Dataverse,
trigger the real deployed plugin,
verify the resulting data or exception,
clean up created test data.

For example:

[Fact]
public void CreateContact_WithoutPostalCode_ShouldFail()
{
    var contact = ContactRepository.GetNew(
        city: "Prague",
        postalCode: null);

    Assert.Throws<InvalidPluginExecutionException>(
        () => TestDataService.CreateTestEntity(contact));
}

This is intentionally not a mocked plugin execution.

Dataverse executes the deployed plugin and the test verifies the real outcome.

That gives teams another step beyond reproducible deployment:

reproducible verification of the deployed behavior.

What Pillaro does NOT replace

This part is important.

spkl does more than plugin deployment, and Pillaro intentionally does not reproduce every one of those features.

Capability	spkl	Pillaro	Recommended direction
Plugin assembly deployment	✅	✅	Pillaro
Plugin step registration as code	✅	✅	Pillaro
Filtering attributes	✅	✅	Pillaro
Pre/post images	✅	✅	Pillaro
Execution order / rank	✅	✅	Pillaro
Remove obsolete plugin steps	Not clearly documented	✅	Pillaro
Validation/execution task model	❌	✅	Pillaro
Integration testing against real Dataverse	❌	✅	Pillaro
Modern Custom API metadata registration	❌	✅ registration	Pillaro
Early-bound model generation	✅	❌ built-in	`pac modelbuilder`
Web resource deployment	✅	❌	Power Platform tooling / CI
Solution pack/unpack	✅	❌	PAC CLI
Reverse-engineer existing plugin registration	✅ `instrument`	❌	Manual inventory before migration

A note on Custom APIs: spkl can register a plugin step against a legacy custom action message, for example through [CrmPluginRegistration("dev1_TestAction", ...)]. That is not the same capability as managing modern customapi / customapirequestparameter metadata. Pillaro's MainOperation() registration addresses the modern Custom API scenario.

There is also no Pillaro equivalent of spkl instrument. If an existing environment contains registrations that are not accurately documented in source control, migration starts with a manual inventory of the deployed state. That limitation is important: Pillaro treats code as the desired state, but it does not automatically reconstruct that code from an unknown Dataverse environment.

This distinction is intentional.

We do not think a modern plugin framework needs to own solution unpacking or model generation when Microsoft already provides dedicated tooling for those jobs.

The migration therefore looks less like:

spkl → Pillaro

and more like:

                 ┌─ plugin architecture
                 ├─ plugin registration
spkl project ────┼─ plugin deployment     → Pillaro
                 ├─ plugin testing
                 │
                 ├─ model generation      → PAC CLI
                 ├─ solution management   → PAC CLI
                 └─ web resources         → existing CI / Power Platform tooling

What about spkl maintenance and compatibility?

This is one of the practical reasons we started looking for a different long-term foundation.

As of September 2026, spkl is not under active feature development.

The SparkleXrm repository still exists and existing projects can continue using it, but the Dataverse platform and Microsoft tooling around it have continued to evolve.

There are unresolved compatibility issues in the repository. One concrete example is issue #461, where upgrading Microsoft.CrmSdk.CoreTools broke spkl early-bound generation. In practice, that means teams cannot assume that newer Microsoft package versions can be adopted independently of spkl; package pinning or workarounds may be required.

The maintenance gap shows up elsewhere as well. Issue #490, opened in July 2025, requests Device Code authentication support for spkl. Issue #491, opened in August 2026, reports get-webresources silently doing nothing and explicitly asks about maintaining the project.

These are not arguments that every existing spkl installation is broken. They are evidence that the tool is no longer keeping pace with the current Dataverse tooling stack in the way an actively maintained dependency normally would.

For a stable legacy project, that may not matter.

For an actively maintained codebase that needs current SDK/tooling packages, modern authentication, or ongoing fixes, it matters a lot more.

What does migration actually look like?

The good news is that moving away from spkl does not necessarily mean rewriting all of your business logic on day one.

We see migration as two separate steps.

Step 1 — Replace registration and deployment

Start by moving the operational responsibility:

spkl attributes / configuration
           ↓
Pillaro registration
           ↓
Pillaro deployment

The first goal is simply to make sure the same plugin assembly and the same logical steps are registered correctly.

At this stage, avoid unnecessary business-logic changes.

A migration is much easier to verify when deployment and architecture are not being rewritten at the same time.

Step 2 — Adopt the task model incrementally

Once deployment is stable, plugin implementations can be moved toward Pillaro tasks.

For example, an existing plugin might contain:

public void Execute(IServiceProvider serviceProvider)
{
    var context = GetContext(serviceProvider);

    if (!context.InputParameters.Contains("Target"))
        return;

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

    if (!target.Contains("name"))
        throw new InvalidPluginExecutionException("Name is required.");

    // business logic
}

The responsibility can gradually become:

UpdateAccountTask

Validate
 └─ verify required business conditions

Execute
 └─ perform the business operation

You do not need to refactor every plugin in the same pull request.

For a large solution, incremental migration is usually safer.

When migration probably makes sense

Consider moving away from spkl when several of these are true:

the project is still under active development,
you need to upgrade Dataverse or Microsoft SDK dependencies,
existing spkl dependencies are blocking those upgrades,
plugin registration differs between environments,
developers still need Plugin Registration Tool to understand deployed state,
you want automated cleanup of obsolete registrations,
plugin classes are becoming hard to reason about,
you want integration tests that exercise deployed plugins in Dataverse,
you are standardising CI/CD for multiple Dataverse projects.

In that situation, keeping an unmaintained deployment layer alive can become more expensive than replacing it.

When you should probably stay on spkl

There is no value in migrating simply because a newer tool exists.

If you have:

a mature solution,
pinned dependencies,
reliable deployments,
very little ongoing plugin development,
no registration drift,
and no need for newer tooling,

then leaving the project alone can be the right engineering decision.

Migration itself has a cost and creates risk.

The goal should be to remove a real problem, not to modernise code for appearance's sake.

A practical migration checklist

Before migrating an existing spkl project:

[ ] Inventory all plugin assemblies.
[ ] Export or document all current plugin steps.
[ ] Document filtering attributes.
[ ] Document pre/post images.
[ ] Document execution order.
[ ] Identify configuration values.
[ ] Identify every spkl command currently used in CI/CD.
[ ] Separate plugin-related spkl usage from solution/web-resource tooling.
[ ] Recreate plugin registration in Pillaro.
[ ] Deploy into a non-production Dataverse environment.
[ ] Compare deployed registration with the original environment.
[ ] Add integration tests for critical plugin flows.
[ ] Remove the old spkl deployment only after the new deployment is verified.
[ ] Migrate solution/model-generation responsibilities to PAC CLI where appropriate.

The important part is that spkl removal itself should not be the objective.

The objective is a codebase where:

plugin behavior is understandable,
registration is reproducible,
environments do not silently drift,
deployment works with the modern toolchain,
and critical behavior can be verified automatically.

What comes next

This article focused specifically on teams already using spkl.

The next articles in this series will look at different decisions:

Plain SDK vs a plugin framework — when adding a framework actually pays for itself.
Pillaro and XrmFramework — two actively maintained but very different approaches to structuring Dataverse development.
The Dataverse plugin tooling landscape in 2026 — where the SDK, PAC CLI, deployment tools and frameworks fit together.

If you are currently maintaining a spkl-based project and there is a migration scenario we have not covered here, open an issue or discussion in the Pillaro Dataverse Plugin Framework repository.

We would rather document the migration gap than pretend it does not exist.

Sources

Disclosure: I maintain Pillaro. This article is written for teams evaluating a path away from spkl, not to claim that every existing spkl project should migrate.

Why Dataverse Plug-in Steps Drift — and Why Stable IDs Fix It

Ján — Thu, 10 Sep 2026 13:23:27 +0000

If you have worked on a Dataverse project with more than one developer and more than one environment, you have probably seen this:

A plug-in fires twice. Or three times.

An autonumber skips values.

A validation message appears twice in the same dialog.

You open the Plugin Registration Tool, expand the assembly, and find two steps registered on the same message, the same table, the same stage — one of them created three weeks ago by someone who no longer remembers doing it.

The usual reaction is to delete the extra step and move on.

But the duplicate is not the problem.

It is a symptom of where the registration lives.

Where registration actually lives

A plug-in step is a row in Dataverse.

SdkMessageProcessingStep stores information such as:

message
table
execution stage
execution mode
filtering attributes
execution order
unsecure configuration

Secure configuration is stored separately in SdkMessageProcessingStepSecureConfig, and plug-in images are separate records as well.

None of that is part of the compiled plug-in assembly.

The assembly contains the code.

Dataverse contains the metadata that decides when and how that code executes.

This separation is where drift starts.

Your C# lives in Git, gets code-reviewed, has a history, and is expected to be consistent across environments.

Registration metadata, on the other hand, can become environment state — modified through tools or transported through solutions — and it can diverge from what developers believe should be registered.

Without a single source of truth connecting the two, code and registration drift apart.

How the duplicate actually appears

The mechanics are worth being precise about, because they explain why the problem is so persistent.

When you register a new step through the Plugin Registration Tool, Dataverse creates a new SdkMessageProcessingStep record with its own ID.

If another logically equivalent step is registered separately, it is still a different Dataverse record.

Both are valid.

Both can fire.

Now add multiple environments:

development
test
UAT
production

And multiple ways of getting plug-ins there:

manual registration
solution transport
deployment scripts
different developers doing different things over time

A step may be transported as a solution component while another version of what developers consider the same logical step was created manually.

If those records have different identities, Dataverse does not consider them duplicates.

They are simply two different registered steps with similar configuration.

That distinction is important.

The real problem is identity

The common explanation is that deployment tools should update existing steps instead of creating new ones.

That is only part of the problem.

Dataverse can update an existing component when it knows which component it is updating.

But two registrations with different IDs remain two different registrations, even if they share the same:

message
table
stage
plug-in type
execution mode
filtering attributes

From the platform's perspective, they are still two separate records.

Without a stable identity for the intended step, deployment tooling has no reliable way to say:

This is the step that should already exist.

And that is why duplicate registrations keep coming back.

Things that partially help

There are several approaches that reduce the problem.

Solution-based transport

Add plug-in steps as solution components and move them with the solution.

This works and is the platform-native approach.

But it does not prevent duplicates that already exist in development, and the registration itself is still not particularly convenient to review next to the C# implementation.

The code says what the plug-in does.

The environment still says when it runs.

Configuration-driven deployment

You can describe registrations in deployment configuration and synchronize environments from there.

This improves repeatability and auditability, but the registration still lives somewhere separate from the code it governs.

Attribute-based or declarative deployment tools

Tools such as spkl and XrmFramework have used a declarative approach for years.

The registration is described in source control and deployment tooling synchronizes Dataverse accordingly.

This is the right shape of solution.

And the principle behind it matters more than the specific tool.

The fix is a stable identity declared in code

If a logical plug-in step has a stable identity that lives in source control, deployment can stop being:

Register another step.

and become:

Make the environment match this declaration.

Repeated deployments can then find the registration created previously and update it instead of creating another copy.

That single change has consequences that go far beyond duplicate plug-in steps.

Registration becomes reviewable

Imagine changing a plug-in from:

PreOperation

to:

PostOperation

or adding another filtering attribute.

That can completely change the behavior of the solution.

Yet in many Dataverse projects, that change happens through the Plugin Registration Tool and never appears in a pull request.

When registration metadata lives with the code, the trigger becomes part of the review.

The reviewer no longer sees only:

public void Execute(...)
{
    // business logic
}

They also see when that code is supposed to execute.

That is a much more complete review.

Environments become comparable

A very common Dataverse question is:

Is production registered the same way as test?

Without deterministic deployment, answering that often means opening two environments and comparing registrations manually.

With declarative registration, the intended state already exists in the repository.

Deployment tooling can compare the environment against that state and report the difference.

You are no longer comparing environment A with environment B.

You are comparing both environments with the same source of truth.

Rollback becomes reproducible

When registration is source-controlled, rollback stops being:

Does anyone remember what this step looked like before?

Instead:

revert the declaration
deploy again
restore the previous registration

Code and execution metadata move together.

That is what deterministic deployment should mean.

What this looks like in practice

In the Pillaro Dataverse Plugin Framework, the framework I maintain, plug-in registration metadata is declared directly in the plug-in class.

For example:

public override void Register(IPluginRegistration registration)
{
    registration
        .OnUpdate<Contact>("5056ef4c-0e08-f111-8407-000d3ab261ac")
        .PreOperation()
        .Synchronous()
        .Rank(1)
        .WhenChanged(
            c => c.FirstName,
            c => c.LastName);
}

The explicit identifier represents the identity of the logical Dataverse step.

The same approach is used for plug-in images.

Deployment reads these declarations and builds the desired registration state.

It can then:

update existing steps
create missing steps
synchronize filtering attributes
synchronize images
synchronize execution order
synchronize registration metadata
remove registrations that are no longer declared

The same source of truth is used for local development and automated deployment.

A developer can run the deployment locally while implementing the plug-in.

The same deployment process can run from Azure DevOps.

There is no need to manually recreate registrations in each environment.

The Plugin Registration Tool still has a place

None of this means the Plugin Registration Tool is a bad tool.

It is extremely useful for:

inspecting registrations
troubleshooting
understanding an unfamiliar environment
checking execution configuration

But there is an important distinction:

It is a good place to inspect what is registered.

It is a poor place to decide what should be registered.

That decision belongs in source control.

The part worth taking away

Duplicate plug-in steps are usually treated as an annoying deployment issue.

But the duplicate itself is only the visible symptom.

The deeper problem is that the intended identity and configuration of the step are not part of the same source-controlled definition as the code.

Once registration becomes declarative and each logical step has a stable identity, deployment becomes deterministic.

And once deployment becomes deterministic:

developers stop recreating registrations manually
environments stop drifting
registration changes become reviewable
repeated deployments become predictable
rollback becomes reproducible

If your team is deleting duplicate plug-in steps by hand every few weeks, deleting them is not the fix.

Move the declaration into the repository.

Which tool you use matters much less than making that move.

The Pillaro Dataverse Plugin Framework is open source under Apache-2.0 and free for commercial use, including client projects.

If you prefer another implementation of the same idea, also take a look at spkl and XrmFramework.

The important part is not the framework.

The important part is making plug-in registration deterministic.