|
| 1 | +--- |
| 2 | +title: V source code files for canvas apps (pa.yaml) |
| 3 | +description: Learn about how to view source code files for canvas apps. |
| 4 | +author: marcelbf |
| 5 | +ms.author: marcelbf |
| 6 | +ms.date: 11/1/2024 |
| 7 | +ms.topic: conceptual |
| 8 | +ms.reviewer: |
| 9 | +ms.subservice: canvas-maker |
| 10 | +ms.collection: get-started |
| 11 | +search.audienceType: |
| 12 | + - maker |
| 13 | + - developer |
| 14 | +ms.custom: |
| 15 | + - canvas |
| 16 | +--- |
| 17 | + |
| 18 | +# View source code files for canvas apps (preview) |
| 19 | + |
| 20 | +[!INCLUDE [preview-banner](~/../shared-content/shared/preview-includes/preview-banner.md)] |
| 21 | + |
| 22 | +You can use the source code for a canvas app to review changes made my makers in Power Apps Studio. The generated canvas app YAML code is read-only and shouldn't be modified. Any change in the file will be ignored and can be lost. |
| 23 | + |
| 24 | +Currently, we don't recommended that you modify **pa.yaml** files or create canvas apps using other text editors. However, more scenarios will be supported in the future. |
| 25 | + |
| 26 | +> [!NOTE] |
| 27 | +> - The YAML schema is in active development, the content may be incomplete. |
| 28 | +> - The current proposed static schema for ***.pa.yaml** files can be found, [here](https://raw.githubusercontent.com/microsoft/PowerApps-Tooling/refs/heads/master/schemas/pa-yaml/v3.0/pa.schema.yaml). |
| 29 | +
|
| 30 | + |
| 31 | +We use Power Fx and YAML as the languages for Power Apps source code. YAML is appreciated for its human-readable format and benefits from a wide array of existing editors, tools, and libraries for its manipulation. |
| 32 | + |
| 33 | +## Prerequisite |
| 34 | + |
| 35 | +To use this feature, you must create an [Early release cycle environment](/power-platform/admin/early-release). |
| 36 | + |
| 37 | +## Access source code files |
| 38 | + |
| 39 | +You have access to the source code files if you're using the [Dataverse Git Integration](/power-platform/alm/git-integration/overview), eliminating the need for **.msapp** files. |
| 40 | + |
| 41 | +The Power Apps Studio creates the source code for canvas apps, which is stored as *.pa.yaml files within the **.msapp** file. The **.msapp** file is a binary file that contains a collection of files, including the source code. |
| 42 | + |
| 43 | +> [!TIP] |
| 44 | +> To effectively use ALM, it's recommended to use solutions. [Canvas apps package](export-import-app-package.md) doesn't support ALM and should only be used for basic import and export capabilities when Dataverse isn't available. |
| 45 | +
|
| 46 | +You can also get the source code files either from the **.msapp** file or by using [Power Platform CLI](/power-platform/developer/cli/introduction). |
| 47 | + |
| 48 | +The ***.pa.yaml** files can be found in the **\Src** folder of the extracted **.msapp**. |
| 49 | + |
| 50 | +> [!Important] |
| 51 | +> Only files located in the **\Src** directory of the extracted **.msapp** are intended for use with source control. |
| 52 | +> The JSON files in the **.msapp** shouldn't be used as source code because those aren't stable between save and load cycles. |
| 53 | +
|
| 54 | +### Download and Extract the pa.yaml files using Power Platform CLI |
| 55 | + |
| 56 | +Connect to your environment using Power Platform CLI and then use the following commands: |
| 57 | + |
| 58 | +1. To list the canvas apps in your current environment, use the command: [pac canvas list](/power-platform/developer/cli/reference/canvas#pac-canvas-list). |
| 59 | +1. To extract the source code files, use the command: [pac canvas download](/power-platform/developer/cli/reference/canvas#pac-canvas-download) with the [parameter -d](/power-platform/developer/cli/reference/canvas#--extract-to-directory--d). |
| 60 | + |
| 61 | + |
| 62 | +### Extract source code files from a .msapp file |
| 63 | + |
| 64 | +To extract source code files from a [.msapp file](export-import-single-app.md#export-msapp-files-in-power-apps), you have two options: |
| 65 | + |
| 66 | +1. Manually unzip the **.msapp** file. |
| 67 | +1. Alternatively, you can use the following command: |
| 68 | + |
| 69 | +```powershell |
| 70 | + Expand-Archive -Path "C:\path\to\yourFile.msapp" -DestinationPath "C:\path\to\destination" |
| 71 | +``` |
| 72 | + |
| 73 | +## File structure for a .msapp file |
| 74 | + |
| 75 | +For older **.msapp** files without the \src folder, follow these steps to generate source code files: |
| 76 | + |
| 77 | +1. Import and resave and download the new **.msapp** in Power Apps Studio. |
| 78 | +1. After that, you can proceed to [extract the source code files](#extract-source-code-files-from-a-msapp-file). |
| 79 | + |
| 80 | +In the **\src** folder, find the following files and folders: |
| 81 | + |
| 82 | +- **App.pa.yaml**: Represents the App. |
| 83 | +- **[screen Name].pa.yaml**: One file for each screen, representing the screen. |
| 84 | +- **\Component**: A folder containing one file for each [component](create-component.md#create-an-example-component), represented as [component Name].pa.yaml. |
| 85 | + |
| 86 | +Only ***.pa.yaml** files within the **\src** folder can be used as source code. Any other file shouldn't be used as source code. |
| 87 | + |
| 88 | + |
| 89 | +## Power Fx YAML |
| 90 | + |
| 91 | +Microsoft Power Fx utilizes a grammar for expressions that is based on Excel and well-established. However, when using Power Apps and other hosts that rely on UI for formula binding, there's no standardized method for editing formula bindings as text. |
| 92 | + |
| 93 | +We choose [YAML](https://yaml.org/spec/1.2/spec.html) as the industry standard language for formula binding. YAML has a wide array of editors, tools, and libraries available for working with it. |
| 94 | + |
| 95 | +> [!NOTE] |
| 96 | +> Currently, we only support a limited subset of YAML. Only the constructs outlined in this article are supported. More information: [Power Fx YAML formula grammar](/power-platform/power-fx/yaml-formula-grammar). |
| 97 | +
|
| 98 | +## Power Apps YAML schema versions |
| 99 | + |
| 100 | +Currently there are three schema versions of Power Apps Source Code: |
| 101 | + |
| 102 | +|Format Name|File Extension|Description| |
| 103 | +|-----------|-----------|-------| |
| 104 | +| [Experimental](power-apps-yaml.md#experimental-format-fxyaml) | *.fx.yaml| Version used by the experimental [Power Apps Git version control](git-version-control.md) and [pac canvas unpack](/power-platform/developer/cli/reference/canvas#pac-canvas-unpack) - no longer in development.| |
| 105 | +| [Early Preview](power-apps-yaml.md#early-preview) | - | The version used by code view, copy code, and paste code. There's no version information in this schema, therefore it isn't suitable for version control. When [code view](code-view.md) is generally available (GA), it switches to the source code preview format.| |
| 106 | +| [Source Code](power-apps-yaml.md#source-code-payaml) | *.pa.yaml files | Includes enhancements and version details for source control and it is in active development. | |
| 107 | + |
| 108 | +>[!NOTE] |
| 109 | +> You can't copy YAML code from a pa.yaml file and paste it as code in Power Apps Studio. However, in the future, code view will utilize the source code format for this purpose. |
| 110 | +
|
| 111 | +## Experimental format (*.fx.yaml) |
| 112 | + |
| 113 | +This schema represents an experimental format employed by the Power Platform CLI to process and convert canvas apps into a source code format. However, this format is no longer being actively developed. |
| 114 | + |
| 115 | +You can't directly convert ***.fx.yaml** files to the new formats. To convert older apps, you need to package the canvas app as a **.msapp** file and import it into Power Apps Studio. |
| 116 | + |
| 117 | +## Early Preview |
| 118 | + |
| 119 | +This version is used by [Code view](code-view.md). Is designed to create apps within Power Apps Studio, letting you easily copy and paste controls. In this version, the source code is used in Power Apps Studio instead of being converted (like the experimental format). |
| 120 | + |
| 121 | +The Early Preview format is a preview feature and is temporary. In the future, both code view, copy code, and paste code are going to use the same source code version. |
| 122 | + |
| 123 | +Here are the changes made from the experimental format: |
| 124 | + |
| 125 | +1. **ZIndex Property Removal**: The ZIndex property is removed. Instead, a screen is now represented as an array of controls. The order of controls now determines their stacking order. Normal controls are ordered in ascending order, while responsive controls are ordered in descending order. |
| 126 | +1. **JSON Object Representation Replacement**: We no longer use the "As" syntax to define the control type. Instead, the left side of the control's name identifier remains unique. Only properties that differ from the default values are serialized. Two new properties are added to define the control type and default values: |
| 127 | + |
| 128 | +- **Control**: Represents the control type in YAML. |
| 129 | +- **Variant**: Identifies a variant of a control type, which might alter default property values, add or remove properties, or modify the behavior/layout of the control. |
| 130 | + |
| 131 | +These properties are used for instantiating controls and don't accept Power Fx expressions. |
| 132 | + |
| 133 | +## Source code (*.pa.yaml) |
| 134 | + |
| 135 | +> [!IMPORTANT] |
| 136 | +> |
| 137 | +> - The YAML source code for canvas apps is currently in preview and actively being developed. The content may be incomplete and subject to change. |
| 138 | +> - The **.pa.yaml** files are read-only and should only be used to review changes made in Power Apps Studio. These files are not used when an app is loading. |
| 139 | +> - External editing, merging, and conflict resolution isn't supported. |
| 140 | +
|
| 141 | +This schema is designed for source control purposes and allows the use of a single YAML file. It's an updated format compared to the previous code view. |
| 142 | + |
| 143 | +Updates from the previous format include: |
| 144 | + |
| 145 | +1. Grouping of Top-Level Node Elements: |
| 146 | + - The top-level keywords "App" and "Screens" are examples of how elements are now grouped in a top-level node. |
| 147 | +2. Control Version Specification: |
| 148 | + - You can now specify the version of a control using the Control Keyword followed by the **@** operator. If no version is specified, the most current version of the control is used. |
| 149 | +3. Simplified Variant Names: |
| 150 | + - Not all controls require a variant. For controls that do require a variant, the name is simplified and more user-friendly. |
| 151 | +4. Consistent ZIndex for All Controls: |
| 152 | + - All controls now use an ascending order to determine the ZIndex value, starting from 1. This behavior aligns with the [CSS 2 spec](https://drafts.csswg.org/css2/#z-index). |
| 153 | + |
| 154 | + |
| 155 | + |
| 156 | +## Schema updates |
| 157 | + |
| 158 | +|Change|Authoring version|Description| |
| 159 | +|---|---|---| |
| 160 | +|Initial Version|---|Initial version, support simple controls| |
| 161 | + |
| 162 | + |
0 commit comments