Skip to main content

Unpackaged Win32 Apps

Unpackaged apps use the classic Win32 application paradigm instead of the modern Windows packaged app system. This means they can be distributed as exe's with full system access, but have some limitations when it comes to using the latest Windows APIs.

In order to have full access to modern Windows APIs, build a packaged app and distribute it using MSIX. The documentation on other pages follows the packaged app approach. If, for any reason, you cannot use MSIX or packaged apps, then follow the below guide to build an unpackaged app.

info

Unpackaged Ionic Windows apps use WPF instead of the Windows App SDK. This is due to one or more limitations in the Windows App SDK and WebView2 for unpackaged apps (one such issue).

This may impact compatibility with other Ionic Windows plugins that depend on the Windows App SDK.

We hope this limitation is resolved by Microsoft in the coming months and we can move back to using the Windows App SDK for unpackaged apps.

Required Configuration#

To use the unpackaged app template for Ionic Windows, set the following configuration option in capacitor.config.ts before running the add command:

import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {    // ...}
// Add this:(config as any).windows = {    unpackaged: true}
export default config;
note

If you've already added a windows platform without this flag you will need to delete it and recreate it using the above command.

Starting Template#

npx cap add @ionic-enterprise/capacitor-windows

Installer - Microsoft Visual Studio Installer Projects 2022#

There are many tools for building installer projects for your Windows app. One option is the Microsoft Visual Studio Installer Projects 2022 extension for VS 2022.

To install this extension, open VS 2022 and from the Extensions menu choose Manage Extensions -> Search -> Microsoft Visual Studio Installer Projects 2022. Install it and then restart VS 2022.

Next, right-click on your solution and go to Add -> New Project. Find the Setup project and add it, giving it a useful name like 'Setup' or 'Installer':

New setup project

Configure the Setup Project#

Next, we need to configure the setup project.

First, we can set some values for the setup project that match our organization and app information:

Setup project config

Additionally, make sure to set the TargetPlatform to x64.

Prerequisites#

On install, we need to make sure the setup project installs any necessary runtime libraries, in this case .NET 5 and Edge WebView.

Right click on the project properties and then click the Prerequisites button:

Setup project properties

Then, choose a matching .NET Desktop runtime for your project (likely 5.x):

.NET Desktop Runtime

Next, find and check the Edge WebView Runtime entry:

Setup project prereqs

Add Project Outputs#

Close the properties window and tight click on the Installer project and go to View -> Filesystem. Then, double click on Application Folder in the right pane:

Setup installer application folder

Then, right click in the main content area and go to Add -> Project Output, and select the following Project Output options. These will be:

  • Content Files
  • ContentFilesProjectOutputGroup
  • Localized resources
  • Primary output
  • Publish items
  • ReferenceCopyLocalPathsOutputGroup

These ensure the appropriate files and dependencies are copied to the install output directory:

Setup installer application folder

Build the Installer#

To build the installer, right click on the installer project and choose build. Find the installer by right-clicking on the Installer project and going to Open Folder in File Explorer, then find the installer in bin/Debug/x64 or bin/Release/x64. This installer can be distributed to users. See Advanced Topics below for code signing and other topics that are out of scope of this document.

Advanced Topics#

For more advanced topics, such as code signing, see the official extension documentation.