Editar

Partilhar via

pac canvas

  • Artigo

Operating with Power Apps .msapp files

[This article is pre-release documentation and is subject to change.]

Important

  • The pack and unpack commands are in public preview.
  • Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
  • The create command is generally available.

Commands

Command Description
pac canvas create Generate a canvas app from a custom connector
pac canvas download Download canvas app as .msapp file
pac canvas list List canvas apps
pac canvas pack (Preview) Pack sources into an msapp file
pac canvas unpack (Preview) Extract an msapp file into sources
pac canvas validate (Preview) Validate the .pa.yaml source for an unzipped msapp file

pac canvas create

Generate a canvas app from a custom connector

This command will generate an .msapp canvas app based on the OpenAPI definition of an existing custom connector. The app will contain screens, control layout, and Power Fx code generated based on how the actions of the custom connector are defined, with a predefined look and feel. The app can be used to directly exercise the actions defined in the custom connector.

Makers can import the generated .msapp into Power Apps Studio to play the app, or to do edits and make further customizations. Import the generated app to Power Apps Studio by navigating to File > Open > Browse within Studio.

Examples

The following examples show the use of the pac canvas create command.

Create a canvas app based on an Open API Definition by display name

This example creates a canvas app (as a *.msapp file) based on an Open API Definition by using the display name of the connector.

pac canvas create --msapp HelloWorld.msapp --connector-display-name "My Custom Connector"

Create a canvas app based on an Open API Definition by id

This example creates a canvas app (as a *.msapp file) based on an Open API Definition by using the ID of the connector.

pac canvas create --msapp HelloWorld.msapp --connector-id 00000000-0000-0000-0000-000000000000

Either connector-display-name or connector-id are required.

Required Parameters for canvas create

--msapp

Path to .msapp file to be generated

Optional Parameters for canvas create

--connector-display-name

The display name of the Connector to generate the Power App from.

--connector-id

The ID of the Connector to generate the Power App from.

--environment

The target Environment ID or URL. The default value is the environment of your currently active Dataverse Auth Profile.

Remarks

Considerations and limitations:

  • The custom connector referenced with the connector-display-name or connector-id parameters must be part of a Solution.
  • After importing the app to Studio, there will be no association to the custom connector. The maker must manually add a reference to the custom connector from which the app was generated before the app can be played. See Add data connections to canvas apps for steps. Until this is done, you may see formula errors in the app which will resolve once the connector reference is added. The name of the custom connector you add to the app must match the display name of the custom connector referenced in the canvas create command.
  • The app will contain one screen for each POST and GET action that the connector defines.
    • Other verbs available in custom connectors are not supported.
  • The controls rendered on each action's screen are dynamically generated based on how the input and output types of each action are defined. Certain types of input and output defined in the custom connector are not supported by canvas create. The command will generate warnings in the console when these are encountered. Specific cases:
    • Arrays of objects and arrays of arrays are not supported as inputs
    • Controls are not generated for objects or nested arrays beyond a depth of 20
    • "File" and "binary format" types are not supported for input or output.

pac canvas download

Download canvas app as .msapp file

Required Parameters for canvas download

--name -n

Canvas app exact, partial name, or App ID

Optional Parameters for canvas download

--environment -env

Specifies the target Dataverse. The value may be a Guid or absolute https URL. When not specified, the active organization selected for the current auth profile will be used.

--extract-to-directory -d

Directory name to extract canvas app to

--file-name -f

File name (usually with .msapp extension). If not provided file is saved in current directory with 'appname'.msapp

--overwrite -o

Allow file overwrite

This parameter requires no value. It's a switch.

pac canvas list

List canvas apps

Optional Parameters for canvas list

--environment -env

Specifies the target Dataverse. The value may be a Guid or absolute https URL. When not specified, the active organization selected for the current auth profile will be used.

pac canvas pack

(Preview) Pack sources into an msapp file

Example

pac canvas pack --sources MyHelloWorldFiles --msapp HelloWorld.msapp

Required Parameters for canvas pack

--msapp

Path to .msapp file

--sources

Directory to sources to be packed

Remarks

Creates an .msapp file from the previously unpacked source files. The result can be opened in Power Apps Studio by navigating to File > Open > Browse.

After being unpacked, the source files can be edited and managed with external tools such as Visual Studio Code and GitHub.

pac canvas unpack

(Preview) Extract an msapp file into sources

Example

pac canvas unpack --msapp HelloWorld.msapp --sources MyHelloWorldFiles

pac canvas unpack --msapp HelloWorld.msapp

Unpacks to default HelloWorld_src directory.

Required Parameters for canvas unpack

--msapp

Path to .msapp file

Optional Parameters for canvas unpack

--sources

Directory to sources to be unpacked

Remarks

Unpacks the .msapp source file.

Download the .msapp file from Power Apps Studio by navigating to File > Save as > This computer.

If the sources parameter is not specified, a directory with the same name and location as the .msapp file is used with _src suffix.

Folder structure

Unpack and pack properties use the following folder structure:

  • \src - Control and component files. This contains the sources.
    • *.fx.yaml - The formulas extracted from the control.json file.

      Note

      This is the place to edit your formulas.

    • CanvasManifest.json - A manifest file that contains the information normally present in the header, properties, and publishInfo.
    • *.json - The raw control.json file.
    • \EditorState*.editorstate.json - Cached information for Power Apps Studio to use.
  • \DataSources - All the data sources used by the app.
  • \Connections - Connection instances saved with the app and used when reloading into Power Apps Studio.
  • \Assets - Media files embedded in the app.
  • \pkgs - A downloaded copy of external references, such as templates, API definition files, and component libraries. These are similar to NuGet/NPM references.
  • \other - All miscellaneous files needed to re-create the .msapp.
    • entropy.json - Volatile elements (like timestamps) are extracted to this file. This helps reduce noisy differences in other files while ensuring that we can still round-trip.
    • Holds other files from the msapp, such as what's in \references.

File format

The .fx.yaml files use a subset of YAML. Similar to Excel, all expressions should begin with an equal sign =. More information: Power Fx YAML Formula Grammar

Merging changes with Power Apps Studio

When merging changes that are made in two different Power Apps Studio sessions:

  • Ensure that all the control names are unique. For example, inserting a button in two different sessions can result in two Button1 controls. We recommend that you name the controls soon after you create them. The tool doesn't accept two controls with the same name.
  • For these files, merge them as you normally do:
    • \src*.fx.yaml
  • If there are conflicts or errors, you can delete these files:
    • \src\editorstate*.json - These files contain optional information in Power Apps Studio.
    • \other\entropy.json
  • For any conflicts in these files, it's ok to accept the latest version:
    • \checksum.json
  • If there are any merge conflicts under these paths, it isn't safe to merge. Let us know if this happens often; we'll work on restructuring the file format to avoid conflicts.
    • \Connections*
    • \DataSources*
    • \pkgs*
    • CanvasManifest.json

Open source

The canvas commands in Microsoft Power Platform CLI are open source. Discuss improvements, raise issues, and access the code from Power Apps language tooling repository.

pac canvas validate

(Preview) Validate the .pa.yaml source for an unzipped msapp file

Required Parameters for canvas validate

--directory -d

Path to the extracted msapp directory containing .pa.yaml files to validate

See also

Microsoft Power Platform CLI Command Groups
Microsoft Power Platform CLI overview