1.1One system, centred on Dataverse
what the organising sentence looks like on disk and in a query
The guide treats the platform as one system centred on Dataverse: apps, automation and deployment artifacts are metadata records stored there. That reads like a slogan until you see what it means on disk and in a query.
A model-driven app is not a program that reads a database. The app is itself a record in the database, describing which tables it shows, on which forms, under which site map. So is the site map. So is the JavaScript library the form loads, the registration that binds it to an event, the cloud flow that runs afterwards, and the security role that decides who sees any of it. A solution is a further record, and its members are references to those records — which is why the solution is the thing that moves between your environments.
The table indexes the rest of the guide. Each row's second column is a shape a chapter reads straight out of the platform or out of an unpacked export; the third column says where that reading is warranted.
| What it is to a maker | What it is to the platform | Where the guide reads it |
|---|---|---|
| A table and its columns | Metadata the platform stores, written by an export as Entities/<table>/Entity.xml | §2.1, §2.2 |
| A relationship between two tables | A file under Other/Relationships/, named for the referenced table, carrying a cascade setting per action | §2.3 |
| Who may see a row | Rows of role and systemuserroles, joined to the user and read with FetchXML | §2.5, §2.5.1 |
| A model-driven app | An app module, listed by pac model list and written by an export as AppModules/<name>/AppModule.xml | §4.1 |
| A form and a view | Rows of systemform and savedquery | §4.3, §4.4 |
| A script on a form | A row of webresource, plus a handler registration inside the form's own XML | §5.2, §5.2.1 |
| Code that runs on save | A row of sdkmessageprocessingstep, carrying the stage and the mode it is registered for | §6.1, §6.1.2 |
| A classic workflow and a cloud flow | Rows of the same table, workflow, told apart by a category column | §6.4, §6.5 |
| A value that differs per environment | A definition record that travels in the solution and a value record that does not | §9.3 |
| A solution | A record whose members are references to the records above, layered over the ones below it | §3.1, §3.3 |
Two consequences run through the whole guide. First, when you ask why something behaves the way it does, you are usually asking about a record: “why does this button not appear” resolves to a row and a column, and §4.6 follows one of those to its file. Second, deployment is the movement of records, which is why the guide's later half is about what a solution carries, what it leaves behind and what it overwrites.
Caution
“Metadata” here means the platform's own records, not a documentation layer over something else. When you change a form you change a record, and other users see it when you publish — which is why §3.3 is about layers rather than files.
1.2Tenancy, environments and what moves between them
the container the records live in, in brief
An environment is the container. It belongs to a tenant, sits in a geography, and holds a database together with the apps, flows and connections that go with it. This section gives you the shape; §3.5 tells you what to do with it.
An environment is created under a Microsoft Entra tenant and its resources are reachable only by users within that tenant. An environment is bound to a geographic location, and it can have zero or one Dataverse database.citedsource: Power Platform admin docs — environments overview › scope of an environment · artifacts-ch01.md
An app created in an environment is permitted to connect only to data sources deployed in that same environment, connections, gateways, flows and Dataverse databases included.citedsource: Power Platform admin docs — environments overview › what an app may connect to · artifacts-ch01.md
That boundary is why solutions exist. Work you do in an environment reaches another as an export and an import, and chapters 3 and 9 are the two halves of that trip: what the package is, and how you move it repeatedly without drift.
The admin centre's environment-types table lists Production, Default, Sandbox, Trial, Developer and Microsoft Dataverse for Teams. A developer environment is intended for use by its owner, and security groups cannot be assigned to one.citedsource: Power Platform admin docs — environments overview › the developer environment type · artifacts-ch01.md
The lab behind this guide's verified claims is three developer environments in one tenant, standing in for a development, test and production chain. §10.1 shows what that stand-in reaches and where it falls short, with the commands that produced it.
1.3A reader's map of the guide
what each chapter settles, and what it assumes of the ones before it
The chapters are ordered by dependency: the data model, then its packaging, then the apps built on it, then automation with the synchronous side first, then data movement, then lifecycle. Each chapter assumes what comes before it, and reads without what comes after.
| Chapter | What it settles |
|---|---|
| 2 · The Dataverse data model | Table types, column types and their run-time shapes, relationships and cascade behaviour, ownership, and how the security model resolves at read time |
| 3 · Solutions and environments | Publishers and prefixes, managed compared with unmanaged, the layer stack and its merge order, updates and upgrades, and the seam where deployment-time values are supplied |
| 4 · Model-driven app design | The app module and what it references, the site map, form and view types, business rules, the command bar, and what an export of an app carries |
| 5 · Client scripting | When to reach for script at all, how a library reaches a form, the formContext object, the asynchronous OnLoad event, the supported-API boundary, and Power Fx commanding |
| 6 · The synchronous question | The event execution pipeline and its stages, transaction participation and rollback, the bound on synchronous work, classic workflows, and where cloud flows sit |
| 7 · Power Automate patterns | The Dataverse trigger and its settings, error handling, retry policies, concurrency, service protection limits, child flows, and what a solution-aware flow does at import |
| 8 · Dataflows and data movement | Dataflows and their solution behaviour, the paths data takes out of Dataverse, alternate keys and upsert, and batching against the service protection counters |
| 9 · ALM and pipelines | A solution in source control, reading a diff, the deployment settings file, update compared with upgrade, and pipelines beside Azure DevOps |
| 10 · Appendix: the verified lab | The tenant, the plan and the environments the guide's verified claims were run against, and each artifact those claims name |
1.3.1Three ways in
You will land here from a search result more often than you will start at the front. Three orders hold together, one per job.
New to a team's estate? You want §2.1 to §2.5 for the data model, then chapter 3 whole, where environment strategy and solution layering are settled. Chapter 4's §4.8 and chapter 9's §9.1 then show what an estate looks like in source control.
Owning the automation? You start at chapter 6's decision ladder, §6.7, and read backwards into §6.1 and §6.3 for the reasoning behind it. Chapter 7 follows in order. §7.5 settles what the platform does with work that touches many rows, and §8.5 is its counterpart for work that belongs outside a flow.
Owning the deployments? Chapter 3, then chapter 9, then back to §7.7 and §9.3, which settle what an import does to a flow's state and owner, and how a value that differs per environment is supplied.
Those two sections are where a first deployment most often goes wrong: a flow that arrives switched off and owned by whoever imported it, and a value that was meant to differ per environment and did not.experientialbasis: the two sections a team is sent back to when a first deployment behaves differently from the environment it was built in
The chapter teams skip most and need most is chapter 3. Solution layering explains a class of “it works in dev” failures that looks, from the outside, like a platform defect.experientialbasis: the sections a reader is sent back to after a first deployment fails, in teams adopting solution-based ALM
1.4The platform's stated direction
three directions with a current document behind each
Predictions date faster than anything else in a reference work, so this section takes up three directions a current Microsoft document states outright: a deprecation, a stated preference, and a scheduled change of default. The citation log behind each one dates it.
The pac canvas reference marks pack and unpack deprecated and directs canvas source control to Power Platform Git Integration. Both commands are still listed, marked Preview, while pac canvas create is generally available.citedsource: Power Platform CLI reference — canvas command group › pack and unpack deprecated · artifacts-ch01.md
Microsoft's stated position is that new automation should be built as cloud flows instead of classic Dataverse workflows, and that existing background workflows should be reviewed for replacement. The same page's capability table gives synchronous, real-time execution as available to classic workflows and not to Power Automate.citedsource: Power Automate docs — replace classic workflows with Power Automate › the recommendation · artifacts-ch01.md
Those two sit together awkwardly. §6.4.2 settles what you do about it.
The pipelines documentation states that from February 2026 Microsoft would begin enabling managed environments for pipeline target environments not already enabled, and that environments used in pipelines other than the host and development environments must be managed environments. It encourages pipelines for core deployment and extension into other CI/CD tools where more is needed.citedsource: Power Platform ALM docs — pipelines › managed environments for pipeline targets · artifacts-ch01.md
Caution
The date in the claim above had passed when this chapter was written, and the sentence was still on the page in the future tense. A scheduled platform change needs confirming in the tenant it applies to; the document that announced it keeps its original tense forever. This guide's lab could not confirm this one, because the plan behind it withholds managed environment use rights (§10.1.1).
Guidance
Treat a deprecation notice as a schedule for the work, not as a reason to stop using the command today. pac canvas unpack still runs, so if you have canvas apps in source control you have time to move to Git integration deliberately.