This article is a tutorial that will present to you all the steps required to take in order to convert a traditional Windows app into the Windows 10 app packaging format (APPX). Appx is a special type of software package format used by the Windows developers to put together code and resources and, finally, to submit for publication the program in Windows Apps Store.
In fact, all the steps I will present here are the steps I have made to develop the blessTags application (Windows Store link - the only app able to manage 4 different SensorTags) and the blessTags Lite application (Windows Store link) – a free version of blessTags applications.
- A computer with Windows 10 Professional or Enterprise operating system (OS);
- A 64 bit (x64) processor with support for: (a) Hardware-assisted virtualization and (b) Second Level Address Translation (SLAT)
- Desktop App Converter tool;
- The base Windows image;
- Windows 10 SDK;
- An existing installer (a MSI file) of your application – in a following post, I will present how to generate a MSI file, from the LabWindows CVI environment, able to work as an UWP application.
- Update the windows. Desktop App Converter requires at least Windows 10 Anniversary Update to work - version 1607 (released on August 2, 2016; end of support: April 10, 2018; end of additional servicing: October 9, 2018).
- Install the Desktop App Converter tool itself, from the following link:
- Download the base Windows image. This package is used as a container and it is required in order to generate your AppX package. But, each type of Windows (each specific build like 17134, 16299, 15063 or 14393) needs to have a matching base Windows image for the Desktop App Converter to work correctly. As a result:
- First, find your Windows build version. Press Win + R keys together to launch the RUN dialog box and then type cmd and press Enter.
- From there, you can find the needed information – the build number: the number placed inside the red rectangle.
- From the following link download the base Windows image associated with your Windows build (this file is big, approximately 3.3 GB, be prepared to have enough free space on the HDD):
- Run Desktop App Converter as administrator (under administrative privileges): Press Win key → Desktop App Converter + click right → More → Run as administrator (see the figure from below).
- Bypass the standard Windows execution policies:
PS C:\Windows\system32> Set-ExecutionPolicy bypass
- Install the base Windows image, by executing the following command:
PS C:\Windows\system32> DesktopAppConverter.exe -Setup -BaseImage "D:\Windows_BaseImage_DAC_17134.wim" -Verbose
- A container is the equivalent of a virtual machine; a virtual machine of a specific type sustained by the fewest number of components from the Windows operating system. So, a container = a "little" virtual machine. Containers enable you to execute an application in an isolated environment. In order to build an APPX, you will need the windows feature “Container”. So, you have several options to install “Containers”:
- If in the process to install the base image, you will receive the following warning: “WARNING: DesktopAppConverter : warning 'W_ENABLING_FEATURE': Required feature 'Containers' is not enabled. Attempting to enable it now (this will require a restart)”. Respond with yes to restart the computer and the component will be installed automatically.
- You can manually install this feature (use one of the two options, depending on the version of your OS):
- Right-click on the Start button, choose Apps and Features, from the right Programs and features and, in the left panel, the option Turn Windows features on or off. Here tick the “Container” component.
- Right-click on the Start button, choose Programs and features and, in the left panel, the option Turn Windows features on or off. Here tick the “Container” component.
- In an elevated PowerShell session, with Administrator rights, please use the following command:
PS C:\Windows\system32> Enable
-WindowsOptionalFeature -Online -FeatureName containers –All
- The worst scenario is when you will receive the following error: “DesktopAppConverter : error 'E_FEATURE_NOT_AVAILABLE': Required Windows Feature 'Containers' is not available on your system”. This error means your system does not have the Container feature!!! To have the Container feature as a component of the Windows OS you need to run the Professional or Enterprise version of Windows 10. The previous message has warned you that this component is not available because your computer it runs an operating system that does not support it. So, upgrade or downgrade your OS in order to match the requirements: Windows 10 Professional or Enterprise versions.
- To perform the conversion process, you will need also the Windows 10 SDK installed on your system. Download the Windows 10 SDK from here https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk and install it.
Building the AppX
Right now, you have all components installed and set. You are ready now to create your first application AppX file.
I am going to present two ways to build an AppX file. Each approach tracks a different goal: (1) to submit your AppX to the Windows Store and (2) to test your app locally on your PC.
So, first, let us build an Appx for Windows Store submission:
- In the first step, put the file with the extension MSI (SensorTag_BLE.msi in my case) into the folder:d:\Temp\InstallerWork\Installer\
In order to have an error-free conversion, it is very important that your installer to be capable of silent/quiet installation - i.e. that it does not display one or more blocking user interface messages (e.g. to ask the user to press a couple of Next buttons). This requirement must be obeyed since in the conversion process you will not be able to interact with your application installer.
- Run Desktop App Converter (DAC) under administrative privileges.
- Inside the DAC environment run the command:
- The Destination parameter is the place where the AppX package will be placed, not where the app is installed.
- Note that the least-significant value of the Version (revision number) must be zero. For example, instead of the 126.96.36.199, you must use 188.8.131.52 as the version number.
- The parameters PackageName, Publisher and PackagePublisherDisplayName must be the same as the ones from your developer account: App Management → App Identity (see the information from the figure presented below).
- MakeAppx has the significance that, other than generating the folder that will contain all the files that need to be packaged, you want also to generate the AppX package. In our case, this parameter can be excluded – anyway, we will build the AppX manually.
- If the installer package (MSI file) ask the user to press a couple of Next buttons, it is possible that the installer still offers a silent installation mode, but it requires to be launched with a special parameter (like Setup.exe /s). If that is your case, please specify this information with an additional parameter provided to the Desktop App Converter called “InstallerArguments”. For example, the previous command would be completed with:
- Check if between the files used to build the AppX package (in this case all placed in the folder: d:\Temp\InstallerWork\Output\82971DobreaDan.BLESensorTags\PackageFiles\) you have an “uninstall.exe” file. If yes, delete this file. Uninstall.exe requires administrative privileges and Microsoft does not allow this for a UWP application.
The following steps are required only you deleted the Uninstall.exe files otherwise you already have the file 82971DobreaDan.BLESensorTags.appx required to be submitted to the Microsoft Store.
- Now delete the file: 82971DobreaDan.BLESensorTags.appx.
- Being in the folder d:\Temp\InstallerWork\Output\82971DobreaDan.BLESensorTags run the command (MakeAppx.exe - creates an application package from the individual files on the disk):
"c:\Program Files (x86)\Windows Kits\10\bin\10.0.17134.0\x64\makeappx.exe" pack /d d:\Temp\InstallerWork\Output\82971DobreaDan.BLESensorTags\PackageFiles /l /p BLESensorTags.appx
- And as a result finally, you have the file: BLESensorTags.appx.
Second, we will build the package required in order to install your app locally on your PC:
- Put the file with the extension MSI (SensorTag_BLE.msi file in my case) into the folder:
- Run Desktop App Converter (DAC) under administrative privileges.
- Inside the DAC, run the same command as it was presented previously (at the third step) but at the end add “-Sign”. The Sign parameter allows to automatically generate a certificate needed to properly sign the AppX package. Without this digital signature, the AppX package cannot be installed on a PC, which will not trust the application without an associated certificate.
- Enable Sideloading: you can install an Appx or an AppxBundle software package only if sideloading is enabled on your Windows 10 device. So, follow the steps: Settings → Update & Security → For Developers. In this point, set either “Sideload apps” or “Developer mode”.
- Now, manually install an AppX package without using the Microsoft Store. Just:
- double-click on the file 82971DobreaDan.BLESensorTags.appx or
- run the following cmdlet within PowerShell:
PS C:\Windows\system32> Add-AppxPackage -Path
- Pressing the Install button and the following error will appear:
The reason for this error is that an AppX package must be signed with a valid certificate in order to be installed and this certificate needs to be trusted by the computer. To solve this problem, you will need to add the certificate (generated automatically by the “Sign” parameter) in the Trusted Root Certification Authority of the computer.
- Double click on auto-generated.cer and choose Install certificate.
- On the new window, choose Local machine and then the option Place all certificates in the following store.
- By pressing the Browse button, make sure to choose Trusted Root Certification Authorities and complete the process.
- Tray again the steps 4 and 5. Now, after pressing the Install button, you will see a progress bar showing the installation status.
Other problems and solutions
Windows 10 updateWith a new Windows 10 update, your specific build (like 16299) will go to another superior build (e.g. 17134) But, each specific Windows build needs to have a matching base Windows image for the Desktop App Converter to work correctly. So, a new base Windows image must be installed. For this, follow the steps:
- Open Desktop App Converter (DAC) with Administrative rights.
- You need to clean up the old base Windows image, otherwise the tool won’t be able to install the new one. To do it, you perform the following command:
PS C:\Windows\system32> DesktopAppConverter -Cleanup "ExpandedImage" –Verbose
- Once the operation is completed, you are ready to install the new base Windows image. So, follow the step 3 from the Components installation sub-chapter.
After you install your application, several times (dozens or hundreds of installations) locally and from the store to test different scenarios, you may face different types of problems while using Windows Store such as:
- You can't update or install apps from Windows Store,
- Frequent Store apps crashing or freezing problems,
- Windows Store apps won't open or give error messages,
- Windows Store opens and suddenly closes etc.
- Press WIN+R keys together to launch RUN dialog box and then type wsreset and press Enter.
- It will immediately start the cache resetting process which may take a few moments. After clearing the cache, it'll launch Windows Store.
-= 👍👍👍 =-