Project Centennial – Convert Classic Windows Apps to a Universal Windows App (UWP) using Desktop App Converter

Windows 8 introduced a new type of Windows application in 2011: the Metro style application. Since then, it has been renamed a couple of times from Metro Style apps to Windows Store apps and now it goes by the name of Universal Windows Applications or Windows Store applications. Nevertheless, the essence of these applications has remained unchanged: these apps run in a sandbox with a restricted set of permissions, they are available as packages that by design support full uninstall, and they undergo a standard review process before being included in the centralized Windows Store (an app store for Windows). Up until now, none of this was available to classic desktop applications that existed before Windows 8, making these classic apps second-class citizens.

With Project Centennial, this might change.

This article is published from the DNC Magazine for Developers and Architects. Download this magazine from here [Zip PDF] or Subscribe to this magazine for FREE and download all previous and current editions

Bringing Applications from Other Platforms to Windows

At the Build conference in 2015, Microsoft announced four Universal Windows Platform bridges, with the goal of simplifying the conversion of existing applications from other platforms into Universal Windows applications, to distribute them through the Windows Store. Microsoft used this infographic (Src: bit.ly/uwp-bridge) to depict the goal of this project.

Image 1: The four Universal Windows Platform bridges. Src: bit.ly/uwp-bridge

Each of these four bridges has a similar project, dedicated to developing the said feature:

• Project Westminster’s goal was to bring existing web applications into the Windows Store.
• Project Centennial was all about packaging existing .NET and Win32 desktop applications in such a way so as to include them in the Windows Store.
• Project Astoria was aimed at making it easier to port existing Java and C++ applications for Android, to Universal Windows platform.
• Project Islandwood was developed to make it easier to port existing Objective-C applications to Universal Windows platform.

Microsoft officially canceled project Astoria in February 2016. The other three projects are now all publicly available, albeit in different stages of development:

• Project Westminster’s new name is Hosted web apps. It became a part of Windows SDK with the release of Windows 10 in July 2015. Several published Windows Store applications are already taking advantage of it.
• In August 2015, Microsoft open sourced project Islandwood as Bridge for iOS and released it on GitHub. It is still in active development, with a new preview released almost every week.
• At Build conference 2016, project Centennial finally made it into the preview, as well: Desktop App Converter is now available for download.

Project Centennial – The Bridge to Windows Desktop

Windows desktop applications converted to Universal Windows platform (UWP) get full application identity, just like any other Universal Windows application. Eventually, you can publish them in the Windows Store, with standard application licensing options and full auto-update support. UWP application identity also gives them access to a much larger subset of UWP APIs than an ordinary desktop application. They can create live tiles, register background tasks with any trigger type, create app services, etc.

The conversion process does not make them real universal applications though. They can only run on the desktop device family because they are still using legacy APIs that are only available in the desktop version of Windows 10. Hence, the automatic application conversion is supposed to be only the first step in the process of making them true universal applications that can run on any device type.

To make this transition process easier, an application package with a converted desktop application can include two separate executables: the original desktop one, and a separate Universal Windows component. Although they are running in two different processes, they can activate each other at the user interface level and communicate bi-directionally using app services (APIs similar to web services that a UWP application can expose). This process should allow a gradual migration of application functionalities from the legacy desktop process to the new UWP process.

Image 2: Communication between the desktop and the UWP process

Once the migration is complete, the application will, of course, be able to run on all Windows device families. However, even with a desktop executable still in the package, support for non-desktop device families can be declared in the application manifest. When installed on those devices, the application will only run the UWP component of the package. With proper design, such an application can still be fully functional on all devices. It can choose to support only a reduced feature set in comparison to Windows desktop on all the other devices.

A New Way to Distribute Desktop Applications

Desktop App Converter will convert an existing game or desktop application (Win32, Windows Forms, or WPF-based) into a Universal Windows application package (*.appx). Until these packages are allowed into Windows Store, sideloading will be the only way to install them. In Windows 10, Microsoft removed all licensing restrictions for sideloading, making it available to all users. They only need to enable sideloading in Windows settings.

Image 3: Sideloading enabled in Windows Settings

A packaged desktop application gets its own application manifest for defining its capabilities and declarations. Since the desktop process will be running outside the sandbox even after the conversion, the capability restrictions will only apply to the UWP part of the package.

Although the desktop part of the package will keep using Win32 and .NET APIs in full trust mode, its environment will still be much more isolated than that of a standard non-converted desktop application. All its file system and registry access will be virtualized in a manner similar to App-V. Without any modifications to the application source code, the actual file system and registry will remain untouched. Any changes will automatically be written to the package local storage as if the UWP file and settings APIs were used.

This approach makes uninstalling the application a breeze. By only deleting the package local storage folder and the installation directory itself, all traces of the application will be completely removed without the risk of leaving behind large nodes of registry settings. The solution is not perfect, though, and some features will require additional intervention to keep them working. For example, desktop applications register supported file extension by adding entries to registry during installation or from a running application. Due to registry virtualization, this will not work anymore. Instead, a File Type Association declaration will need to be added to the application manifest to achieve the same result.

It is not so easy to resolve every compatibility issue. The limitations of the virtualized environment, in which the packaged desktop applications are running, will break some of them after the conversion. The following are the most notable restrictions:

• There is no kernel mode available; therefore, drivers and Windows services will not work.
• No in-process (shell) extensions can be registered
• No modifications to the application installation directory or the local machine registry hive are allowed.
• Due to isolation, the application cannot share any of its files with other applications using the AppData folder.

Code changes can circumvent some of these restrictions, e.g. files can be shared between multiple applications from the same publisher by using a common publisher cache folder. Others will require a larger redesign of the application to keep it working, or even make it impossible. Such applications will remain restricted to desktop devices and have to keep their current distribution model.

Using the Application Converter

To use Desktop App Converter your computer must fulfill the following requirements:

• It must be running a 64-bit version of Windows 10 Enterprise or Pro edition with Anniversary Update preview installed, i.e. build 14342 or newer.
• It must support hardware-assisted virtualization and second-level address translation (SLAT) and have both enabled.

The tool consists of two downloads: the converter itself and a Windows 10 base image, matching the Windows build you are currently using. You also need to have Windows 10 SDK installed, as the converter uses MakeAppx.exe from the SDK to build the final package.

To set up the converter, unblock and unzip its archive, navigate to its folder, and run the following PowerShell commands as administrator:

Set-ExecutionPolicy bypass
.\DesktopAppConverter.ps1 -Setup -BaseImage .\BaseImage-14342.wim -Verbose

The second one requires the new Containers Windows feature. The script will enable it and automatically reboot the computer, if necessary. The setup process will take a significant amount of time. Once it completes, you will be ready to run the converter on a desktop application of your choice with the following command:

.\DesktopAppConverter.ps1 -Installer "<MyAppSetup.exe>" -InstallerArguments "<SetupArguments>" -Destination "<DestinationFolder>" -PackageName <PackageName> -Publisher "CN=<PublisherName>" -Version <Version> -MakeAppx -Verbose

You need to replace the placeholders as follows:

• <MyAppSetup.exe> is the full path to your application setup. Usually, it will be an executable or a Windows installer package, but a batch script will work as well. The only requirement is that the setup can fully execute silently without any user interaction.
• <SetupArguments> includes any arguments that need to be passed to your application setup for it to run completely silently.
• <DestinationFolder> is a folder on your machine where you want to output the generated package and its contents.
• <PackageName> is the name that you want to use for your application package (without the .appx extension).
• <PublisherName> is the publisher name that you want to use in your package. You will need a code-signing certificate with a matching common name.
• <Version> is a four-part version number (e.g. 1.0.0.0) that you want your package to use.

The converter will use the downloaded Windows base image to create an isolated Windows environment and run the existing setup for the desktop application inside it. It will capture any changes to the registry and file system during the installation procedure, and include them in the generated application package:

• The application files that were copied to the installation directory.
• Any global linked libraries that the application depends on.
• A local registry hive containing all the registry changes.

For some applications, the converter might not be able to detect the installation path or the application executable to run. In this case, the conversion process will fail, and you will need to specify additional arguments for DesktopAppConverter.ps1:

-AppInstallPath "<InstallationFolderPath>" -AppExecutable "<ExecutablePath>"

Replace the placeholders as follows:

• InstallationFolderPath> is the absolute path of the folder containing the application files after the silent install is completed.
• <ExecutablePath> is the absolute path of the application executable that needs to be launched.

Before you can install the generated application package, you will need to sign it. All the required tools are included in Windows 10 SDK. If you do not have them in the path, you can find them all in C:\Program Files (x86)\Windows Kits\10\bin\x64 folder. Invoke them in the following order:

MakeCert.exe -r -h 0 -n "CN=<PublisherName>" -eku 1.3.6.1.5.5.7.3.3 -pe -sv <cert.pvk> <cert.cer>
pvk2pfx.exe -pvk <cert.pvk> -spc <cert.cer> -pfx <cert.pfx>
signtool.exe sign -f <cert.pfx> -fd SHA256 -v "<GeneratedPackage>"

Placeholder values are as follows:

• <PublisherName> must match the publisher name, which you used when generating the package.
• <cert.pvk> is the filename for the generated certificate private key
• <cert.cer> is the filename for the generated certificate public key.
• <cert.pfx> is the filename for the generated certificate PKCS #12 file.
• <GeneratedPackage> is the full path of the application package file generated by the converter.

Before installing the package, you need to set up trust for the certificate you signed it with. If it was a self-signed certificate, created with the command above, just double-click the generated <cert.cer> file and import it as a trusted root certification authority.

Assuming that you have unlocked your copy of Windows 10 with Anniversary Update for sideloading, you can now install the generated and signed application package:

Add-AppxPackage "<GeneratedPackage>"

Again, replace <GeneratedPackage> with the full path to the now signed generated application package. In the final release of Windows 10 Anniversary Update, it should be possible to install the .appx packages with a double click, without invoking any PowerShell cmdlets.

Additional tooling for packaging desktop applications was already announced and is expected to be available before the final version of project Centennial:

• WiX and InstallShield (and maybe other setup tools vendors) will support the direct generation of AppX packages for desktop applications without the conversion process.
• A special project template will be available for Visual Studio, which will support the creation of AppX packages from the desktop and UWP components in the same solution. It will even support debugging of both package components.

Conclusion:

Currently, the focus of project Centennial is on Line of business applications (LOB) for the enterprise. In this environment, sideloading will be the standard method for installing the application packages. Nevertheless, Windows Store support for packaged desktop applications is planned and might even be available at the same time as the final version of Windows 10 Anniversary Update is released.

There have already been announcements that more of the existing Win32 APIs will be available for UWP apps (i.e. in .NET Core). The final goal is to include everything, except the platform specific parts (registry APIs, Windows Forms, and WPF, etc.).

If all this comes true, we can look forward to a new migration path to UWP for existing desktop applications that does not include a full rewrite.

This article has been editorially reviewed by Suprotim Agarwal.

C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.

We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).

Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.

Click here to Explore the Table of Contents or Download Sample Chapters!

Author

Damir Arh has many years of experience with software development and maintenance; from complex enterprise software projects to modern consumer-oriented mobile applications. Although he has worked with a wide spectrum of different languages, his favorite language remains C#. In his drive towards better development processes, he is a proponent of Test-driven development, Continuous Integration, and Continuous Deployment. He shares his knowledge by speaking at local user groups and conferences, blogging, and writing articles. He is an awarded Microsoft MVP for .NET since 2012.