Get Started on Visual Studio 2022

This getting started will guide you through the creation of an Uno Platform App using C# and .NET, based in the WinUI 3 XAML.

Tip

This guide covers development on Windows using Visual Studio. If you want to use another environment or IDE, see our general getting started.

Important

To use Xamarin (as opposed to .NET 7 Mobile) with Visual Studio 2019, follow this guide.

Prerequisites

To create Uno Platform applications you will need Visual Studio 2022 17.4 or later:

  1. ASP.NET and web development workload installed (for WebAssembly development)

    Visual Studio Installer - ASP.NET and web development workload

  2. .NET Multi-platform App UI development workload installed (for iOS, Android, Mac Catalyst development).

    Visual Studio Installer - .NET Multi-platform App UI development workload

  3. .NET desktop development workload installed (for Gtk, Wpf, and Linux Framebuffer development)

    Visual Studio Installer - .NET desktop development workload

Important

To build Xamarin-based projects in Visual Studio 2022, in Visual Studio's installer Individual components tab, search for Xamarin and select Xamarin and Xamarin Remoted Simulator. See this section on migrating Xamarin projects to .NET 6.

Note

For information about connecting Visual Studio to a Mac build host to build iOS apps, see Pairing to a Mac for Xamarin.iOS development.

Finalize your environment

  1. Open a command-line prompt, Windows Terminal if you have it installed, or else Command Prompt or Windows Powershell from the Start menu.

  2. a. Install the tool by running the following command from the command prompt:

    dotnet tool install -g uno.check

    b. To update the tool, if you already have an existing one:

    dotnet tool update -g uno.check

  3. Run the tool from the command prompt with the following command:

    uno-check

  4. Follow the instructions indicated by the tool

Note

When using a Visual Studio Preview version, you will need to run uno-check --pre.

You can find additional information about uno-check here.

Install the Solution Templates

  1. Launch Visual Studio 2022, then click Continue without code. Click Extensions -> Manage Extensions from the Menu Bar.

    Visual Studio - "Extensions" drop-down selecting "Manage Extensions"

  2. In the Extension Manager expand the Online node and search for Uno, install the Uno Platform extension or download it from the Visual Studio Marketplace, then restart Visual Studio.

    Extension Manager - Uno Platform extension

Create an application

To create an Uno Platform app:

  1. Create a new C# solution using the Uno Platform App template, from Visual Studio's Start Page, then click the Next button

    Visual Studio - Get started - Selecting create a new project option Visual Studio - Create a new project - Selecting Uno Platform App option

  2. Configure your new project by providing a project name and a location, then click the Create button

    Visual Studio - Configure project name and location

  3. Choose the base template to build your application

    Visual Studio - Configure your new project

  4. You can optionally choose to customize your app based on the sections on the left side:

    • Framework allows to choose which TargetFramework your app will use. .NET 7.0 is a commonly appropriate choice.
    • Platforms provides a list of platforms your application will support. You still can add additional platforms later.
    • Presentation gives a choice about using MVVM (e.g. MVVM Toolkit) or Uno Platform's MVUX and Feeds
    • Projects gives the ability to add a Server project for APIs and hosting for the WebAssembly project
    • Testing provides Unit Testing and UI Testing projects
    • Features provides support for WebAssembly PWA and optional VS Code support files
    • Extensions allows to choose for additional Uno.Extensions to kickstart your app faster
    • Application sets the App ID for relevant platforms, used when publishing on various app stores.
    • Theme gives the ability to change between Fluent and Material

  5. Click the create button

  6. Wait for the projects to be created, and their dependencies to be restored

  7. A banner at the top of the editor may ask to reload projects, click Reload projects: Visual Studio - A banner indicating to reload projects

  8. To debug the Windows head:

    • Right-click on the MyApp.Windows project, select Set as startup project
    • Select the Debug|x86 configuration
    • Press the MyApp.Windows button to deploy the app
    • If you've not enabled Developer Mode, the Settings app should open to the appropriate page. Turn on Developer Mode and accept the disclaimer.

  9. To run the WebAssembly (Wasm) head:

    • Right click on the MyApp.Wasm project, select Set as startup project
    • Press the MyApp.Wasm button to deploy the app

  10. To run the ASP.NET Hosted WebAssembly (Server) head:

    • Right click on the MyApp.Server project, select Set as startup project
    • Press the MyApp.Server button to deploy the app

  11. To debug for iOS:

    • Right click on the MyApp.Mobile project, select Set as startup project

    • In the "Debug toolbar" drop-down, select framework net7.0-ios:

      Visual Studio - "Debug toolbar" drop-down selecting the "net7.0-ios" framework

    • Select an active device

  12. To debug the Android platform:

    • Right click on the MyApp.Mobile project, select Set as startup project
    • In the Debug toolbar drop down, select framework net7.0-android
    • Select an active device in the "Device" sub-menu

You're all set! You can now head to our tutorials on how to work on your Uno Platform app.

Note

Debugging either the macOS and macCatalyst targets is not supported from Visual Studio on Windows.

Troubleshooting Installation Issues

You may encounter installation and/or post-installation Visual Studio issues for which workarounds exist. Please see Common Issues we have documented.

Getting Help

If you continue experiencing issues with Uno Platform, please visit our GitHub Discussions or Discord - #uno-platform channel where our engineering team and community will be able to help you.

Further reading