Rajeev Pentyala – Microsoft Power Platform

Lets say you have built a Power Apps business application or Service and you want to promote it to AppSource, In this article, I am going to provide a detailed walkthrough of generating an AppSource package.

What is an AppSource:

• Microsoft AppSource is an online store that contains thousands of business applications and services built by industry-leading software providers.
• You can use AppSource to find, try, buy, and deploy the business software and services that help you run your business.
• As an example, Creator Kit is a collection of Fluent UI controls, Templates for Power Apps makers and is available on AppSource.

AppSource package structure:

An AppSource package consists of the following files:

From the above list of required files, generating the ‘Package file'(i.e.,pdpkg.zip) using Package Deployer Tool is the major work.

What is a package file:

A Package Deployer package can consist of any or all of the following:

• One or more Dataverse solution files.
• Flat files or exported configuration data file from the Configuration Migration tool. For more information about the tool, see Move configuration data across instances and organizations with the Configuration Migration tool.
• Custom code that can run before, while, or after the package is deployed to the Dataverse instance.
• HTML content specific to the package that can display at the beginning and end of the deployment process. This content can be useful to provide a description of the solutions and files that are deployed in the package.

Now that we know what files are required for AppSource package, lets get started with the generation of Package Deployer package.

Steps to generate Package Deployer package:

As we know package deployer package contains one or more Dataverse solution files along with data files, In this article I will be focusing only on Dataverse solutions.

In this example, I am going to package two solutions ‘Solution 1’ and ‘Solution 2’.

• Following are those two solutions from my ‘DEV’ environment.

• From the Power Apps maker portal, download the two solutions and save it locally.

• Next, open the Visual Studio 2019 or later, or Visual Studio Code. I am using VS2022.
• Make sure you already installed Power Platform Tools extension to your Visual Studio.
• Create a new project and choose ‘Power Platform PD Package project’ template as shown below.

• In the project details pane, provide Project name. Click Next.

• Provide package related details as shown below. To know more about the properties refer the docs here.

• Click ‘Create’ to complete the project creation.
• You should see your ‘Solution Explorer’ looks as below

• As a first step, build the project and make sure it builds with no errors.

• Now we need to add our download Dataverse solutions to this project. For that, in Visual Studio, select switch to folder view.

• Add the two Dataverse solutions which we downloaded previously, under the PkgAssets folder.

• We can also update the HTML language specific files.
• In the Solution Explorer pane, expand PkgAssets > Content > en-us. You’ll find two folders called EndHTML and WelcomeHTML.
• These folders contain the HTML and associated files that enable you to display (to the user) information at the end and beginning of the package deployment process.
• Edit the files in the HTML folder of these folders to add information to display for your package.

Configure the package:

As the next step, we need to provide configuration information like Import order of your solutions and whether to install sample data as part of this package, etc.

We will be updating the ImportConfig.xml file.

• Open the ImportConfig.xml file and the structure looks as below.

• Under <solutions> tag, define your order of solution import to target.
• In my case, I want ‘Solution1_1_0_0_1_managed.zip’ to be imported first and then ‘Solution2_1_0_0_1_managed.zip’. So I added my solutions info to <solutions> tag as below.

  <solutions>    
    <configsolutionfile solutionpackagefilename="Solution1_1_0_0_1_managed.zip" />
    <configsolutionfile solutionpackagefilename="Solution2_1_0_0_1_managed.zip" />
  </solutions>

• You can also following properties
  • overwriteunmanagedcustomizations :  
    • Specify whether to overwrite any unmanaged customizations when importing a solution that already exists in the target.
    • This attribute is optional, and if you do not specify this attribute, by default the unmanaged customizations in the existing solution are maintained on the target.
  • publishworkflowsandactivateplugins:
    • Specify whether to publish workflows and activate plug-ins in the target after the solution is imported.
    • This attribute is optional, and if you do not specify not specify this attribute, by default the workflows are published and plug-ins are activated after the solution is imported on the target.
• With the above additional properties, your solution configurations looks below.

<solutions>  
     <configsolutionfile solutionpackagefilename="Solution1_1_0_0_1_managed.zip"  
overwriteunmanagedcustomizations="false"  
publishworkflowsandactivateplugins="true"/>  
     <configsolutionfile solutionpackagefilename="Solution2_1_0_0_1_managed.zip"  
overwriteunmanagedcustomizations="false"  
publishworkflowsandactivateplugins="true"/> 
</solutions>

There are other configurations related to sample data import, which I will cover in a separate article. Refer this to know more.

Add custom code:

You can add custom code that executes before, during, and after the package is imported into an environment. As an example, I need to enable “Power Apps component framework for canvas apps” before my solutions gets imported to target.

Lets see how to add the custom code to enable “Power Apps component framework for canvas apps”. For that, we need to edit the PackageImportExtension.cs file.

• From your Visual Studio, switch to Solution View and open the PackageImportExtension.cs file.

• In the ‘InitializeCustomExtension()’ function, add the following code.

        public override void InitializeCustomExtension()
        {
            // Enable PCF for canvas
            var query = new QueryExpression("organization");
            query.ColumnSet.AddColumns("iscustomcontrolsincanvasappsenabled");
            var result = CrmSvc.RetrieveMultiple(query);
            var environmentSettings = result.Entities[0];
            environmentSettings["iscustomcontrolsincanvasappsenabled"] = true;
            // Trigger update
            CrmSvc.Update(environmentSettings);
        }

• Build the solution and make sure its succeeded.
• Once the build succeeds, we need to publish the project, to generate the deployment package.
• Trigger dotnet publish (All lowercase) command either from command prompt or from ‘Package Manager Console’.
• dotnet publish generates ‘your_package_name.pdpkg.zip’ file. This is the package deployer file.

• Go to bin/Debug folder and you would find the ‘.pdpkg.zip’ file. In my scenario, my package file name is ‘AppSourceDemo.1.0.0.pdpkg’.

Test the package deployer file:

It’s highly recommended testing your package deployer file (.pdpkg.zip) before moving this to AppSource package. I will be using pac cli to test the package deployer file.

• Open the command prompt. Make sure you install pac cli ,if not installed already.
• As we are going deploy the generated .pdpkg.zip file to a test environment, first create a connection using pac auth create command.

• Next we are going to use pac package deploy command to deploy the package.
• If your package is properly generated, pac package deploy command execution should be succeeded as below.

Now we are ready with the package deployer package file (i.e.,AppSourceDemo.1.0.0.pdpkg). Lets proceed with other files configuration.

Create [Content_Types].xml file:

You can use the same ‘[Content_Types].xml’ file available under the generated AppSourceDemo.1.0.0.pdpkg file.

• Unzip the package deployer package file (i..e, AppSourceDemo.1.0.0.pdpkg).
• Copy and save a copy of the [Content_Types].xml.

• We will use this file in next steps.

Create an icon for your AppSource package:

• Create an icon file of size 32×32 to display along with the preferred solution name and description.
• Valid file formats are PNG and JPG.
• I named my logo as Logo32X32.png.

Create an HTML file for license terms:

• Create an HTML file containing your license terms. You can have an HTML file per language to display the license terms in the user selected language if your app supports multiple languages.
• These terms are specific to your application. You can search online for the samples.

• I named my file as TermsOfUse.html

Create Input.xml file:

Content in this file needs to be accurate. Any typo or mistake will cause your AppSource package failure during upload to AppSource.

• Create an Input.xml file that provides information about your package and the contents of the package.
• You can download the sample Input.xml from here.
• Following is Input.xml file, specific to our demo.
  • PackageFile : Should be the name of our pdpkg.zip file (i.e., AppSourceDemo.1.0.0.pdpkg).
  • SolutionAnchorName : Name of the Dataverse solution zip file in the package that is used for the display name and description of solution assets. I have given my Solution1_1_0_0_1_managed.zip which is one of my solution file.
• Logo and PackageTerm should be the file name

• Pro tip : Make sure you include file extension (i.e, .zip,.png,.html) in the Input.xml for PackageFile, SolutionAnchorName,Logo and PackageTerm properties any deviation will cause your package fail during certification.
• For other properties of Input.xml file, refer this link to know more.

Add the items to an AppSource package:

We’ve generated all the required files already. Following is the list.

• Package file (i.e., AppSourceDemo.1.0.0.pdpkg.zip)
• [Content_Types].xml
• Logo (i.e., logo32x32.png)
• Terms of Use (i.e., TermsOfUse.html)
• Input.xml

The final step is to add all the components into a single compressed (zip) file, which will be your app source package.

• Select the files and compress to a zip file.

• Rename the the zip file appropriately as per your app. Its recommend that you include your company name and app name. For example: Microsoft_SamplePackage.zip.
• I’ve renamed our AppSource package as Rajeev_DemoAppSource.zip.

Check the AppSource package using AppSource checker:

• You have an option to test the generated AppSource package file using AppSource checker
• You need to login with your Office365 credentials.
• Click on ‘Check your app’. Browse and upload the AppSource package which we generated in above section.

• Click on ‘Run Check’ to get the results.
• Our AppSource package is valid, as you can see below, ‘Issues present’ is ‘No issues’.

🙂