| name | canvas-app-yaml |
| description | Author Microsoft Power Apps canvas app source as unpacked *.fx.yaml + CanvasManifest.json so an agent can generate Power Fx screens that pac canvas pack and pac solution pack will accept. Covers the Src/ YAML control tree, Power Fx formula syntax, App OnStart, screens, data sources, components, and the round-trip with pac canvas unpack/pack. |
| metadata | {"author":"AgentX","version":"1.0.0","created":"2026-05-30"} |
| compatibility | {"surfaces":["low-code-builder","agent-x","engineer"],"platforms":["power-platform","power-apps","canvas-apps","power-fx"]} |
Power Apps Canvas App YAML
Purpose: emit canvas app source that round-trips through pac canvas unpack / pac canvas pack and packs into a solution under CanvasApps/.
When to Use
- Generating a canvas app (forms, galleries, screens over Dataverse or other data) from a PRD-LOWCODE
- Editing screen logic or controls in an existing unpacked app
- Reviewing Power Fx before packaging
On-Disk Layout (after pac canvas unpack)
CanvasApps/
<prefix>_<appname>_<DocumentUri>/
CanvasManifest.json # app metadata, dependencies, data sources, app-level Power Fx
Src/
App.fx.yaml # App.OnStart, App.Formulas, named formulas
<ScreenName>.fx.yaml # one file per screen, control tree + Power Fx
Component/ # reusable canvas components
Assets/ # images, media
Connections/ # data source connection metadata
DataSources/ # *.json per data source (table, connector)
pac canvas pack --sources ./Src --msapp build/app.msapp rebuilds the .msapp, which pac solution pack then embeds.
The Src YAML Control Tree
Each screen is a YAML tree. Indentation defines nesting. Each control has Control: and a properties block. Power Fx expressions are prefixed with =.
Screens:
HomeScreen:
Properties:
Fill: =RGBA(248, 249, 250, 1)
Children:
- TitleLabel:
Control: Label@2.5.1
Properties:
Text: ="Issues"
Size: =24
FontWeight: =FontWeight.Semibold
- IssueGallery:
Control: Gallery@2.15.0
Variant: galleryVertical
Properties:
Items: =SortByColumns(Filter(Issues, Status.Value = "Open"), "agx_duedate")
OnSelect: =Set(varSelected, ThisItem)
Children:
- TitleRow:
Control: Label@2.5.1
Properties:
Text: =ThisItem.agx_name
Rules:
Control: <Name>@<version> -- the version must match a control the target environment ships. Use current GA versions; do not invent.
- Property values are Power Fx, always
=-prefixed.
Children: is an ordered list; z-order follows list order.
Power Fx Essentials
| Need | Pattern |
|---|
| App state | Set(varName, value) (global), UpdateContext({x: 1}) (screen-scoped) |
| Named formula (preferred over OnStart) | In App.Formulas: varTheme = RGBA(...); |
| Filter a table | Filter(Issues, Status.Value = "Open") |
| Sort | SortByColumns(source, "col", SortOrder.Ascending) |
| Lookup single row | LookUp(Issues, agx_issueid = varId) |
| Patch (create/update) | Patch(Issues, Defaults(Issues), {agx_name: txtTitle.Text}) |
| Navigate | Navigate(DetailScreen, ScreenTransition.Cover) |
| Choice column value | ThisItem.Status.Value (display), bind via the choice record |
Prefer named formulas (App.Formulas) and delegable queries (Filter/Sort on Dataverse columns) over OnStart + ClearCollect of whole tables, which breaks past 2000 rows.
CanvasManifest.json (key fields)
{
"FormatVersion": "0.24",
"Properties": { "Id": "<guid>", "Name": "<prefix>_<appname>" },
"PublishInfo": { "AppName": "Issue Tracker" },
"AppPreviewFlagsMap": { "delegationforalltabularsources": true },
"DataSources": [ { "Name": "Issues", "Type": "NativeCDSDataSourceInfo" } ]
}
Solution Integration
- The app folder name embeds a
DocumentUri GUID -- keep it stable across regenerations.
- Add a
RootComponent type="300" (Canvas App) entry to Solution.xml.
- Data sources that point at Dataverse tables create implicit dependencies; ensure those tables are in the same solution or referenced.
Anti-Patterns
- Inventing
Control@version numbers -- packing fails or the control renders blank.
ClearCollect(coll, Filter(BigTable, ...)) of large tables in OnStart -- delegation warning + truncation at 2000 rows.
- Hardcoding environment-specific GUIDs in formulas -- use connection references and environment variables.
- Editing the
.msapp binary directly -- always edit Src/*.fx.yaml and re-pack.
Verify
pac canvas pack --sources ./Src --msapp build/app.msapp
Related