Dverse.Cli 0.1.0-ci.102

dverse

Declarative deployment + SDK for Microsoft Dataverse / Dynamics 365 plugins. dverse replaces spkl-style imperative registration with a Terraform-like plan/apply model, and replaces hand-written plugin boilerplate with source-generated code.

Dataverse online only. dverse authenticates via Microsoft Entra ID (Azure.Identity) and always registers plugins in the sandbox — there is no on-premises / IFD support and none is planned for v1.

You write only this, in a plain SDK-style csproj:

using Dverse;
using Dverse.Model;

public partial class AccountPlugins
{
    [Step(typeof(Account), Msg.Update, Stage.PreOperation,
        Filtering = new[] { Account.Cols.CreditLimit })]
    public void BlockCreditLimitDowngrade(IStepContext<Account> ctx)
    {
        if (ctx.Target.CreditLimit < ctx.PreImage.CreditLimit)
            throw ctx.Fail("Credit limits can't be lowered.");
    }
}

Then run dotnet build -t:Deploy. Everything else is generated or computed:

• the IPlugin entry class and the embedded context runtime (no base classes, no runtime DLL, no ILMerge),
• the pre-image registration — columns inferred from your code (ctx.PreImage.CreditLimit above ⇒ a pre-image with exactly creditlimit); escapes are compile errors, never a silent "all columns",
• the registration manifest, diffed field-by-field against the live environment.

A no-op deploy performs zero writes in ~5 read round trips. dverse plan shows exactly what would change (--json for machines, exit code 0 = clean / 2 = changes pending) — put it in CI and never let an environment drift again.

Feature overview

Getting started

• New project: docs/getting-started.md
• Solution layout & multi-assembly: docs/solution-layout.md
• Migrating from spkl: docs/migrating-from-spkl.md
• Runtime API contract: docs/dverse-context-api-spec.md
• Planned work: GitHub issues

The five-minute version

# 1. install the CLI (or run it from source: dotnet run --project src/Dverse.Cli --)
dotnet tool install --global Dverse.Cli --prerelease
dverse version   # the installed package version, e.g. 0.1.0-ci.89 (+ the commit it was built from)

# 2. in your plugin repo: describe your environments (no secrets — this file is committed)
cat > dataverse.yaml <<'EOF'
default: dev
environments:
  dev:
    url: https://yourorg.crm.dynamics.com
    solution: yoursolution
    prefix: your
EOF

# 3. sign in once (device code; later runs are silent)
dverse auth login
dverse whoami

# 4. declare the entities once in dataverse.yaml:
#      model:
#        entities: [account, contact]
#    plan/apply keep the model snapshot fresh automatically from then on

# 5. deploy (from the plugin project directory: builds, diffs, applies)
dverse apply
# ... or preview first / via MSBuild:
dverse plan
dotnet build -t:Deploy

Architecture in one paragraph

Plugins target net462 and reference exactly one package, Dverse.Sdk (attributes + source generators + MSBuild targets). The generators are pure: metadata comes exclusively from the committed dataverse.snapshot.json, so builds are reproducible and CI needs no Dataverse connection. The registration manifest is emitted as an inactive preprocessor block — it contributes zero IL, so a registration-only change (a rank, a filter column) never changes the assembly hash and never re-uploads the DLL. The dverse CLI talks raw Dataverse Web API (no Microsoft.PowerPlatform.Dataverse.Client dependency), reads the environment in a constant number of queries, canonicalizes both sides, and PATCHes only changed columns. Matching precedence for existing steps: explicit Id → Key → natural key (plugin type, message, entity, stage) when unique on both sides → name; ambiguity is a hard error, never a heuristic.

Repository layout

src/Dverse.Cli/              the dverse CLI (net9.0, packs as dotnet tool Dverse.Cli)
src/Dverse.Sdk/              attributes (netstandard2.0) — the package plugins reference
src/Dverse.Sdk.Generators/   Roslyn incremental generators + diagnostics (ships inside Dverse.Sdk)
src/Dverse.Sdk.Targets/      MSBuild props/targets (ship inside Dverse.Sdk)
tests/                    unit, generator, and live-environment integration tests
samples/TestPlugins/      end-to-end sample plugin project (project references, for development)
samples/pcf/CreditGauge/  sample PCF control (scaffolded with `dverse pcf init`, built output committed)
demos/NugetDemo/          standalone consumer demo — uses only the published NuGet packages
docs/                     getting started, spkl migration, API spec, backlog

Building

dotnet build && dotnet test

Integration tests run only when DVERSE_TEST_URL is set and create only prefixed, torn-down test components. CI publishes prerelease packages to NuGet on every push to main.