Build your first app

In this tutorial, you'll learn how to create and run your first .NET Multi-platform App UI (.NET MAUI) app.

Important

The documentation for .NET Multi-platform App UI (.NET MAUI) is under construction.

Visual Studio for Mac support will arrive in a future release.

Prerequisites

  • The latest preview of Visual Studio 2022, with the required workloads. For more information, see Installation.

Get started with Visual Studio 2022 (Preview)

In this tutorial, you'll create your first .NET MAUI app in Visual Studio 2022, and run it on an Android emulator:

  1. Launch Visual Studio 2022, and in the start window click Create a new project to create a new project:

    New solution.

  2. In the Create a new project window, select MAUI in the Project type drop-down, select the .NET MAUI App (Preview) template, and click the Next button:

    Choose a template.

  3. In the Configure your new project window, name your project, choose a suitable location for it, and click the Create button:

    Configure the project.

  4. Wait for the project to be created, and its dependencies to be restored:

    Restored dependencies.

  5. In the Visual Studio toolbar, press the Android Emulator button to start the download of the Android SDK and emulator:

    Android emulator button.

    Note

    To work around current issues in Preview 5:

    • If the Android Emulator button does not appear, restart Visual Studio and reload the solution.
    • If Visual Studio builds the app and attempts to deploy it to Windows, restart Visual Studio a second time and reload the solution.
  6. In the Android SDK License Acceptance window, press the Accept button:

    Android SDK License Acceptance window.

  7. In the User Account Control dialog, press the Yes button:

    User Account Control dialog.

    Wait for Visual Studio to download the Android SDK and Android Emulator.

  8. In the Visual Studio toolbar, press the Android Emulator button to build the app:

    Android emulator button.

  9. In the User Account Control dialog, press the Yes button:

    User Account Control dialog.

  10. In the New Device window, press the Create button:

    New Android Device window.

  11. In the License Acceptance window, press the Accept button:

    License Acceptance window.

    Wait for Visual Studio to download, unzip, and create an Android emulator.

  12. Close the Android Device Manager window:

    Android Device Manager window.

  13. In the Visual Studio toolbar, press the Pixel 2 - API 28 (Android 9.0 - API 28) button to build and run the app:

    Pixel 2 API 28 emulator button.

    Visual Studio will start the Android emulator, build the app, and deploy the app to the emulator.

  14. In the running app in the Android emulator, press the CLICK ME button several times and observe that the count of the number of button clicks is incremented.

    App running in the Android emulator.

Build and debug iOS apps

If, while connecting Visual Studio to your Mac through Xamarin Mac Agent (XMA), you are prompted to install a different version of the SDK, you can ignore the prompt since it refers to a legacy version of XMA.

Note

Visual Studio 2022 can only currently deploy .NET MAUI iOS apps to the iOS simulator, and not to physical devices.

Prerequisites

  • The latest preview of Visual Studio 2022, with the required workloads. For more information, see Installation.
  • A configured Android emulator.

Get started with .NET command-line interface

In this tutorial, you'll create and run your first .NET MAUI app using the .NET command-line interface (CLI):

  1. In the .NET CLI, create a new .NET MAUI app:

    dotnet new maui -n HelloMauiPreview
    
  2. In the .NET CLI, change directory to the newly created project:

    cd HelloMauiPreview
    
  3. In the .NET CLI, change directory to the single project and restore its dependencies:

    cd HelloMauiPreview
    dotnet restore
    
  4. In the .NET CLI, build and launch the app on your chosen platform:

    dotnet build -t:Run -f net6.0-android
    dotnet build -t:Run -f net6.0-ios
    dotnet build -t:Run -f net6.0-maccatalyst
    

    Note

    These commands will launch the app on the default platform device, if one can be found. On Android, it's recommended to start an emulator before building and launching your app.

Select an iOS simulator

It's possible to specify which simulator is launched and used for net6.0-ios by specifying the _DeviceName MSBuild property:

dotnet build -t:Run -f net6.0-ios -p:_DeviceName=:v2:udid=<UDID>

You can retrieve a list of possible unique device id (UDID) values by executing the simctl list command:

/Applications/Xcode.app/Contents/Developer/usr/bin/simctl list

The default iOS simulator will be launched if you don't specify a UDID.