Visual Studio project

Host Platform Support (Platform support)

macOS

Windows

Linux

x86‑64

arm64

x86

x86‑64

arm64

x86

x86‑64

arm

arm64

●

Briefcase supports creating a full Visual Studio project for a Windows App. This project can then be used to build the stub app binary with the briefcase build command, or directly from Visual Studio.

Building the Visual Studio project requires that you install Visual Studio 2022 or later. Visual Studio 2022 Community Edition can be downloaded for free from Microsoft. You can also use the Professional or Enterprise versions if you have them.

Briefcase will auto-detect the location of your Visual Studio installation, provided one of the following three things are true:

  1. You install Visual Studio in the standard location in your Program Files folder.

  2. MSBuild.exe is on your path.

  3. You define the environment variable MSBUILD that points at the location of your MSBuild.exe executable.

When you install Visual Studio, there are many optional components. You should ensure that you have installed the following:

  • .NET Desktop Development - All default packages

  • Desktop Development with C++ - All default packages - C++/CLI support for v143 build tools

Packaging format

Briefcase supports two packaging formats for a Windows app:

  1. As an MSI installer (the default output of briefcase package windows VisualStudio, or by using briefcase package windows VisualStudio -p msi); or

  2. As a ZIP file containing all files needed to run the app (by using briefcase package windows VisualStudio -p zip).

Briefcase uses the WiX Toolset to build an MSI installer for a Windows App. WiX, in turn, requires that .NET Framework 3.5 is enabled. To ensure .NET Framework 3.5 is enabled:

  1. Open the Windows Control Panel

  2. Traverse to Programs -> Programs and Features

  3. Select “Turn Windows features On or Off”

  4. Ensure that “.NET framework 3.5 (includes .NET 2.0 and 3.0)” is selected.

Icon format

Windows apps installers use multi-format .ico icons; these icons should contain images in the following sizes:

  • 16px

  • 32px

  • 48px

  • 64px

  • 256px

Windows Apps do not support splash screens or installer images.

Additional options

The following options can be provided at the command line when packaging Windows apps.

--file-digest <digest>

The digest algorithm to use for code signing files in the project. Defaults to sha256.

--use-local-machine-stores

By default, the certificate for code signing is assumed to be in the Current User’s certificate stores. Use this flag to indicate the certificate is in the Local Machine’s certificate stores.

--cert-store <store>

The internal Windows name for the certificate store containing the certificate for code signing. Defaults to My.

Common Stores:

Personal

My

Intermediate Certification Authorities

CA

Third-Party Root Certification Authorities

AuthRoot

Trusted People

TrustedPeople

Trusted Publishers

TrustedPublisher

Trusted Root Certification Authorities

Root

--timestamp-url <url>

The URL of the Timestamp Authority server to timestamp the code signing. Defaults to http://timestamp.digicert.com.

--timestamp-digest <url>

The digest algorithm to request the Timestamp Authority server uses for the timestamp for code signing. Defaults to sha256.

Application configuration

The following options can be added to the tool.briefcase.app.<appname>.windows section of your pyproject.toml file.

system_installer

Controls whether the app will be installed as a per-user or per-machine app. Per-machine apps are “system” apps, and require admin permissions to run the installer; however, they are installed once and shared between all users on a computer.

If true the installer will attempt to install the app as a per-machine app, available to all users. If false, the installer will install as a per-user app. If undefined the installer will ask the user for their preference.

use_full_install_path

Controls whether the app will be installed using a path which includes both the application name and the company or developer’s name. If true (the default), the app will be installed to Program Files\<Author Name>\<Project Name>. If false, it will be installed to Program Files\<Project Name>. Using the full path makes sense for larger companies with multiple applications, but less so for a solo developer.

version_triple

Python and Briefcase allow any valid PEP440 version number as a version specifier. However, MSI installers require a strict integer triple version number. Many PEP440-compliant version numbers, such as “1.2”, “1.2.3b3”, and “1.2.3.4”, are invalid for MSI installers.

Briefcase will attempt to convert your version into a valid MSI value by extracting the first three parts of the main series version number (excluding pre, post and dev version indicators), padding with zeros if necessary:

  • 1.2 becomes 1.2.0

  • 1.2b4 becomes 1.2.0

  • 1.2.3b3 becomes 1.2.3

  • 1.2.3.4 becomes 1.2.3.

However, if you need to override this default value, you can define version_triple in your app settings. If provided, this value will be used in the MSI configuration file instead of the auto-generated value.

Platform quirks

Use caution with --update-support

Care should be taken when using the --update-support option to the update, build or run commands. Support packages in Windows apps are overlaid with app content, so it isn’t possible to remove all old support files before installing new ones.

Briefcase will unpack the new support package without cleaning up existing support package content. This should work; however, ensure a reproducible release artefacts, it is advisable to perform a clean app build before release.

Packaging with --adhoc-sign

Using the --adhoc-sign option on Windows results in no signing being performed on the packaged app. This will result in your application being flagged as coming from an unverified publisher. This may limit who can (or is willing to) install your app.