Using Visual Studio Code for WinUI3 Development with C#

Visual Studio Code can be used to develop WinUI3 applications with C#, although the process requires additional configuration compared to using Visual Studio. Here's a complete guide to getting started with WinUI3 development in VS Code.

Prerequisites

Before starting, ensure your system meets the following requirements:

System Requirements

Enable Developer Mode

• Windows 10 version 1809 (build 17763) or newer
• .NET SDK (version 6.0 or newer)
• Windows SDK version 2004 (build 19041) or newer
• Visual Studio Code

Developer Mode is required to develop and run WinUI3 applications. To enable it:

1. Open **Settings** by pressing **Windows + I**

2. Select **System** from the left menu

3. Scroll down and click **For developers**

4. Enable the **Developer Mode** toggle

5. Click **Yes** on the confirmation dialog

Install Required Tools

Install .NET SDK

1. Visit https://dotnet.microsoft.com/download/dotnet

2. Download the installer for Windows (choose x64 for most systems)

3. Run the installer and follow the instructions

4. Verify installation by running `dotnet --version` in command prompt

Alternative using winget:

winget install Microsoft.DotNet.SDK.9

Install Visual Studio Code

1. Download installer from https://code.visualstudio.com/

2. Run the installer and follow the instructions

3. VS Code will be automatically added to PATH environment variable

Install Required VS Code Extensions

Open VS Code and install the following extensions via Extensions view (Ctrl+Shift+X):

1. **C# Dev Kit** - Main extension for C# development

- Provides Solution Explorer

- Test Explorer for unit testing

- IntelliCode for AI-powered code completion

2. **C#** - Will be installed automatically with C# Dev Kit

3. **.NET Install Tool** - Will be installed automatically with C# Dev Kit

Install Windows App SDK Runtime

Download and install the latest runtime from the Windows App SDK page. This runtime is required to run unpackaged WinUI3 applications.

Creating a WinUI3 Project

Step 1: Create Project Using .NET CLI

Although VS Code doesn't have template wizards like Visual Studio, you can create projects using dotnet CLI or use Visual Studio first:

1. Open Command Prompt or PowerShell

2. Navigate to the folder where you want to create the project

3. Run the command to create a WinUI3 project:

dotnet new install Microsoft.WindowsAppSDK.Templates
dotnet new winui -n YourProjectName

Alternatively, create a project using Visual Studio 2022 with the template "Blank App, Packaged (WinUI 3 in Desktop)", then open it in VS Code.

Step 2: Modify .csproj File

To run WinUI3 applications in VS Code, you need to add important properties to the `.csproj` file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <Platform>x64</Platform>
    <Platforms>x86;x64;arm64</Platforms>
    <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
    <WindowsPackageType>None</WindowsPackageType>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>
</Project>

**Explanation of Important Properties:**

Configuring VS Code

Step 3: Create launch.json File

• `Platform` with value `x64` - **Required for VS Code**
• `WindowsAppSDKSelfContained` with value `true` - Includes Windows App SDK in deployment package, allowing the application to run without separate SDK installation
• `WindowsPackageType` with value `None` - Creates unpackaged application (not using MSIX packaging)
• `Platforms` - Supports various architectures (optional, but useful if also using Visual Studio)

Create a `.vscode` folder in your project root, then create a `launch.json` file inside it:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch (WinUI3)",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/bin/x64/Debug/net8.0-windows10.0.19041.0/win10-x64/YourProjectName.exe",
      "args": [],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "console": "internalConsole"
    }
  ]
}

**Important Note:** Adjust the `program` path according to your project name and framework version used.

Step 4: Create tasks.json File

Create a `tasks.json` file in the `.vscode` folder:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
      "args": [
        "build",
        "${workspaceFolder}/YourProjectName.csproj",
        "/property:GenerateFullPaths=true",
        "/consoleloggerparameters:NoSummary"
      ],
      "problemMatcher": "$msCompile"
    },
    {
      "label": "publish",
      "command": "dotnet",
      "type": "process",
      "args": [
        "publish",
        "${workspaceFolder}/YourProjectName.csproj",
        "/property:GenerateFullPaths=true",
        "/consoleloggerparameters:NoSummary"
      ],
      "problemMatcher": "$msCompile"
    },
    {
      "label": "watch",
      "command": "dotnet",
      "type": "process",
      "args": [
        "watch",
        "run",
        "--project",
        "${workspaceFolder}/YourProjectName.csproj"
      ],
      "problemMatcher": "$msCompile"
    }
  ]
}

Alternatively, you can create these files automatically by opening Command Palette (Ctrl+Shift+P) and typing ".NET: Generate Assets for Build and Debug".

Running the Application

Using VS Code Debugger

1. Open the project in VS Code

2. Press F5 or select "Run > Start Debugging"

3. The application will be built and run

Using .NET CLI

You can also use command line for build and run:

# Build project
dotnet build

# Run application
dotnet run

# Watch mode (hot reload)
dotnet watch

# Publish application
dotnet publish

Tips and Important Notes

Application Size

Enabling `WindowsAppSDKSelfContained` will increase the deployment package size by about 200 MB because it includes all Windows App SDK libraries. If you want to reduce size, set this property to `false`, but users will need to install Windows App SDK runtime separately.

Hot Reload

Use the `dotnet watch` command to enable hot reload, allowing you to see changes in real-time without restarting the application.

Debugging

Make sure your breakpoints are set before starting debugging. If breakpoints are grayed out, the application is not running in debug mode.

Limitations

Some Visual Studio features like XAML Designer and Live Visual Tree are not available in VS Code. For visual UI design, you need to manually edit XAML or use Visual Studio as a complement.

Packaged vs Unpackaged

The above configuration uses the unpackaged model (`WindowsPackageType=None`). If you want to create a packaged app with MSIX, remove the `WindowsPackageType` property and follow the MSIX packaging guide.

Troubleshooting

Application Doesn't Run with `dotnet run`

Ensure the `WindowsAppSDKSelfContained` property is set to `true` and `Platform` is set to `x64`.

Build Errors

Make sure all NuGet packages are restored by running:

dotnet restore

Program Path Not Found in launch.json

Check the output folder after build and adjust the path in `launch.json` to the actual location of the `.exe` file.

Conclusion

By following this guide, you can now develop WinUI3 applications using Visual Studio Code and take advantage of VS Code's flexibility for your development workflow. While it requires additional configuration compared to Visual Studio, this approach provides greater flexibility and control over your development environment.

References

• [Official WinUI3 Documentation](https://learn.microsoft.com/en-us/windows/apps/winui/winui3/)
• [.NET SDK Guide](https://learn.microsoft.com/en-us/dotnet/core/install/windows)
• [Windows App SDK Samples](https://github.com/microsoft/WindowsAppSDK-Samples)
• [Visual Studio Code Documentation](https://code.visualstudio.com/docs)

This guide provides a solid foundation for starting WinUI3 development with VS Code. With the right configuration, you can enjoy VS Code's productivity while building modern Windows applications with WinUI3.

Frequently Asked Questions

Can I use VS Code instead of Visual Studio for WinUI3?

Yes, you can use VS Code for WinUI3 development with C#, though it requires additional configuration compared to Visual Studio. You'll need to set up launch.json and tasks.json manually.

What are the limitations of using VS Code for WinUI3?

VS Code doesn't have XAML Designer or Live Visual Tree, so you'll need to manually edit XAML files. For visual UI design, you may want to use Visual Studio as a complement.

Why do I need WindowsAppSDKSelfContained?

This property includes Windows App SDK libraries in your deployment package, allowing the application to run without requiring users to install Windows App SDK runtime separately. It increases app size by about 200MB.

What is the difference between packaged and unpackaged WinUI3 apps?

Packaged apps use MSIX format with full Windows Store integration and capabilities. Unpackaged apps (WindowsPackageType=None) run directly without MSIX packaging, which is simpler but has fewer Windows integration features.

How do I enable hot reload in VS Code for WinUI3?

Use the `dotnet watch` command to enable hot reload, allowing you to see changes in real-time without restarting the application. Configure this in tasks.json for convenience.

Can I debug WinUI3 apps in VS Code?

Yes, you can debug WinUI3 apps in VS Code by configuring launch.json with the correct program path and build task. Set breakpoints before starting debugging for them to be active.