Application running as UWP app

e-pity as UWP app


E-pity is a personal income tax application that both individuals and businesses can use to complete their tax forms. The application was written many years ago by using Adobe AIR; it’s a multi-platform application available as a Windows Installer, iOS/Android app, Linux application, and even a web app. Having so many platforms covered by the current version, it didn’t make sense for the customer to write a separate Universal Windows Platform (UWP) app just to put it in the Windows Store, so the decision to use the Desktop Bridge was a natural one, with the goal of making its reach even broader.

Core team

  • Adam Mielcarski – CEO, e-file
  • Michał Hoffman – Developer, e-file
  • Bartek Kuligowski – Developer, e-file
  • Bartek Indycki – Developer, e-file
  • Jakub Gemel – Developer, e-file
  • Bartek Wierzbinski – Developer, e-file
  • Matteo Pagani – Windows AppConsult Engineer, Microsoft
  • Tomasz Wiśniewski – Technical Evangelist, Microsoft

Working team


Customer profile

E-file is a software company and solution provider based in Poznan, Poland. The e-file team consists of experts with more than 10 years of experience in producing high quality applications, professional web services, and marketing solutions. They specialize in e-government and e-documents. Their applications are written mostly in Adobe AIR, but they also have .NET components.

Their main application is called e-pity, and it’s one of the most popular personal income tax applications in Poland with over 15,000,000 declarations filled to date. To give you a better perception of the reach of the app, on a single day (April 28, 2016), the application was used to file over 90,000 tax declarations, which means 62 declarations per minute and more than 1 declaration per second.

The application is also being used by professional accountants to fill out tax declarations both for individual customers and companies that are using their services.

Problem statement

As mentioned in the overview, the e-pity application is written in Adobe AIR and is available on multiple platforms. In such a situation, reaching a new platform can be difficult because if the platform does not support the runtime, there needs to be a very good business or technical reason to rewrite the application from scratch with a new technology. Because e-pity is always looking to reach new customers, in addition to having an .exe Windows Installer, they saw a great opportunity to have the app be available in the Windows Store as well. Thanks to the Desktop Bridge, bringing this Adobe AIR application to the Store was very easy and required just minor modifications to accommodate some technical and Store policy requirements.

Solution, steps, and delivery

Using Desktop Bridge as a starting point for this conversion was very easy and made the whole process quicker and more intuitive. In addition, the team learned a lot that they could apply to future conversions of other products.

At this point I would like to express a big thank you to Matteo Pagani from the Windows AppConsult team whose knowledge, experience, and willingness to help with Desktop Bridge was outstanding!

Step 1: Setting up the Desktop App Converter

The first requirement when doing such a conversion with the Desktop Bridge is to set up the computer correctly. There are multiple ways to convert a desktop application, but the best one for e-file was by using the tool provided by Microsoft called the Desktop App Converter (DAC), which could convert the classic installer that the customer already had.

The system requirements can be found at Package an app using the Desktop App Converter.

To set up the Desktop App Converter:

  1. Download the Desktop App Converter app from the Windows Store.
  2. Based on your Windows build version (which you can check by opening the Start menu and typing winver), download an appropriate .wim file from the Microsoft Store.
  3. Run the Desktop App Converter as an administrator on your computer.
  4. In the prompt that appears, run this command: Set-ExecutionPolicy bypass
  5. Set up the Desktop App Converter by running this command: DesktopAppConverter.exe -Setup -BaseImage .\BaseImage-1XXXX.wim -Verbose


TIP – Don’t put the .wim file in a folder that contains other files, such as .iso or .exe files or any other installation files, because it will get copied to your C:\ drive.

Step 2: Conversion

After setting up the DAC, we decided to do an initial conversion to see how it reacts to the current installer that is generated by Inno Setup. To run the conversion, we used the following command:

DesktopAppConverter.exe -Installer D:\epity\epity.exe -InstallerArguments "/SILENT" -Destination D:\epity\final -PackageName "epity" -Publisher "CN=efile" -Version 1.0.0.0 -MakeAppx -Sign -Verbose


  • -Installer points to the installer that you want to use.

  • -InstallerArguments is where you must specify the parameter that triggers the unattended setup procedure because DAC can only work with silent installers.

  • -Destination is where the DAC should produce the output of the command.

  • -PackageName and -Publisher are parameters that are injected in the AppManifest.xml file. Because this was just the initial conversion, we didn’t use the real identity of the app at this time (we will talk about this later).

  • -MakeAppx creates an .appx file that is the installation format of a Windows Store application.

  • -Sign generates a certificate that you can install on your computer to test the generated package. When the final package is submitted to the Store, it is automatically signed by a trusted certificate during the process, so there is no need to do it later when you’re ready to publish your application.

  • -Verbose gives you better information while the conversion is happening.


Application converting


Step 3: Initial testing

This step is not required by the technology itself, but we decided to launch the app after the successful conversion and to identify any places or issues that needed to be addressed, changed, or modified within the app.

As mentioned in the previous step, the DAC command has a parameter -Sign that signs the package. It also generates the certificate that needs to be installed on the computer before installing the app.

  1. In the output folder of your DAC command, you will find an auto-generated file. Double-click it and then select Install Certificate.


    Install certificate


  2. On the wizard Welcome page, select Local Machine.

    Install certificate - local machine


  3. Select Place all certificates in the following store, select Browse, and then select Trusted Root Certification Authorities.

    Install certificate - store


After completing these steps, you will be able to install the app from the .appx file and launch it from the Start menu.

Our testing revealed the following areas that we needed to modify:

  • The installer asked the user to accept a license, and now with silent install there is no such step (which is required for legal reasons).
  • The installer created registry entries for file associations.
  • The installer created reminders with Task Scheduler in Windows.
  • The icons generated by DAC were not scaled properly and needed to be regenerated.
  • The application had a built-in auto-update functionality.
  • An option exists to install the .NET Framework within the application.

All other tests about running the app, how it launches other apps, where it stores user files, etc. were successful, so there was no need for doing any other modifications.

Step 4: Fixing and enhancing the app

Following is what was needed to be done to fix the issues in Step 3:

  • “The installer asked the user to accept a license” – This part was moved from the installer to the first launch of the application, so that the application could continue to be compliant from a legal point of view.
  • “The installer created registry entries for file associations” – This part was removed from the installer generated by Inno Setup, and we used UWP enhancements to register proper file associations within the AppManifest.xml file.

     <Extensions>
       <uap3:Extension Category="windows.fileTypeAssociation">
         <uap3:FileTypeAssociation Name="epity" Parameters="&quot;%1&quot;">
           <uap:SupportedFileTypes>
             <uap:FileType>.epity</uap:FileType>
           </uap:SupportedFileTypes>
         </uap3:FileTypeAssociation>
       </uap3:Extension>
       <uap3:Extension Category="windows.protocol">
         <uap3:Protocol Name="epity" Parameters="&quot;%1&quot;">
           <uap:DisplayName>epity</uap:DisplayName>
         </uap3:Protocol>
       </uap3:Extension>
     </Extensions>
    


  • “The installer created reminders with Task Scheduler in Windows” – The Task Scheduler creation was also moved from the installer to the first app launch.
  • “The icons generated by DAC were not scaled properly and needed to be regenerated” – We will discuss app icons regeneration later in the document, because it needs to be done after the DAC generates a package with the previous changes.
  • “The application had a built-in auto-update functionality” – The auto-update functionality has been turned off and removed from the menu because application updates need to go through the Windows Store certification process. In fact, an app distributed through the Store can’t auto-update itself; the update must be delivered by the Store.
  • “An option exists to install the .NET Framework within the application” – The .NET Framework download links have been removed because Windows Store with the Desktop Bridge apps work on Windows 10 Anniversary Update and later, which means that they have .NET installed, so there is no need to provide a link for installation.

After these steps were finished and all the issues fixed (except the icons), we ran the DAC command again to generate a new set of files.

We could now focus on generating a better set of icons because the original ones were extracted by the application’s icon, resulting in a set of images with a low resolution.

There are multiple ways to achieve this goal:

  • You can generate the icons manually from your favorite application. We chose to use a free Visual Studio extension UWP Tile Generator. This plug-in takes the best quality graphic that you provide and generates all of the Windows Store required sizes and scales of images.
  • If you have already installed Visual Studio 2017 on your machine, this feature is built in to the product inside the visual manifest editor of UWP projects.

To generate new icons:

  1. After generating the images, go to your DAC output directory, where you will find a folder called PackageFiles\Assets in which all of the images auto-generated by DAC are stored.

  2. Delete all of these images and copy your newly generated images from the Visual Studio extension.

  3. Regenerate all the resource files, which contain a reference to the assets images. As such, you need to delete all of the files with the .pri extension inside the PackageFiles folder.

    IMPORTANT – The name of the images generated by the UWP Tile Generator may be different from the convention used by DAC while generating images. Because of that, you need to modify the AppManifest.xml file found in the PackageFiles folder before generating the final package. These nodes need to be modified:

         <Logo>Assets\FILENAME.png</Logo>
    
         <uap:VisualElements DisplayName="epity" Description="epity" BackgroundColor="transparent" Square150x150Logo="Assets\ FILENAME.png" Square44x44Logo="Assets\ FILENAME.png">
    
         <uap:DefaultTile Wide310x150Logo="Assets\FILENAME.png" Square310x310Logo="Assets\ FILENAME.png" Square71x71Logo="Assets\FILENAME.png">
    
  4. After making this change, we regenerated the assets by running this command…

    makepri createconfig /cf D:\epity\final\epity\PackageFiles\priconfig.xml /dq en-US

    …and then this one:

    makepri new /pr D:\epity\final\epity\PackageFiles /cf D:\epity\final\epity\PackageFiles\priconfig.xml

These steps are described in the official documentation Package an app manually (Desktop Bridge).

Step 5: Generating and preparing the package for submission

In this step, the final package for submission was prepared.

  1. To publish an application to the Windows Store, you need to have a developer account, which can be set up at the Windows Dev Center.

  2. After setting up the account, we went to the Dashboard and created a new app and reserved a name for it.

  3. Next we went to the App management -> App identity section.

    App identity


  4. From here we found all the necessary information to insert into the AppManifest.xml file.

    App identity details


  5. We modified the AppManifest.xml file corresponding to the values found in the developer dashboard.

      <Identity Name="[Package/Identity/Name]" ProcessorArchitecture="x86" Publisher="[Package/Identity/Publisher]" Version="8.0.22.0" />
    
      <Properties>
        <DisplayName>[Reserved Application Name]</DisplayName>
        <PublisherDisplayName>[Package/Properties/PublisherDisplayName]</PublisherDisplayName>
        <Logo>Assets\NewStoreLogo.png</Logo>
      </Properties>
    


  6. Now we were ready to regenerate the .appx file with the changes included by running this command:

    makeappx pack -d " D:\epity\final\epity\PackageFiles" -p " D:\epity\final\epity\YourApp.appx" -l


    OPTIONAL – We wanted to test the package so that the new package had to be signed with a developer certificate, so we could install it and test it. We ran this command:

    signtool.exe sign /a /v /fd SHA256 /f " D:\epity\final\epity\auto-makgenerated.pfx" /p "123456" "D:\epity\final\epity\epity.appx"

  7. After testing the application and confirming that everything worked and looked as we wanted, we were able to submit the app to the Windows Store.

Conclusion

Converting the application by using the Desktop Bridge was an easy and very streamlined process. With this conversion, the application, which was already cross-platform, gained a new audience—Windows Store users.

Working with the Windows Store team, we were also able to put the application in the Store Spotlight for the relevant tax period in Poland, which made it more visible to users and increased the number of downloads.


e-pity on the Windows Store Spotlight


This process proved that doing such a conversion can be beneficial for the company and their products, so e-file is planning on releasing their other products in the Windows Store.

Additional resources