Edit

Share via


Build your first app

Choose your platform

In this tutorial, you'll learn how to create and run your first .NET Multi-platform App UI (.NET MAUI) app in Visual Studio 2022 on Windows or Visual Studio Code on Windows, macOS, or Linux. This will help to ensure that your development environment is correctly set up.

Prerequisites

  • Visual Studio 2022 17.12 or greater, with the .NET Multi-platform App UI workload installed. For more information, see Installation.

Create an app

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

Developing .NET MAUI apps for iOS on Windows requires a Mac build host. If you don't specifically need to target iOS and don't have a Mac, consider getting started with Android or Windows instead.

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

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

  1. Launch Visual Studio 2022. 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 All project types drop-down, select the .NET MAUI App 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 Next button:

    Configure the project.

  4. In the Additional information window, choose the version of .NET that you'd like to target and click the Create button:

    Additional information.

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

    Restored dependencies.

  1. In the Visual Studio toolbar, use the Debug Target drop-down to select Android Emulators and then the Android Emulator entry:

    Select the Android Emulator debugging target for .NET MAUI.

  2. In the Visual Studio toolbar, press the Android Emulator button:

    Android emulator button.

    Visual Studio will start the process of installing the default Android SDK and Android Emulator.

  3. In the Android SDK - License Agreement window, press the Accept button:

    First Android SDK License Agreement window.

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

    Android SDK license user account control dialog.

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

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

    Android Device Manager user account control dialog.

  6. In the Android SDK Platform is missing dialog, press the Install button:

    Android SDK platform is missing dialog.

  7. In the Android SDK - License Agreement window, press the Accept button:

    Second Android SDK License Agreement window.

    Wait for Visual Studio to install the Android SDK components.

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

    New Android Device window.

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

  9. Close the Android Device Manager window:

    Android Device Manager window.

  10. In the Visual Studio toolbar, press the Pixel 7 - API 35 (Android 15.0 - API 35) button:

    Pixel 7 API 35 emulator button.

  11. In the Android SDK - License Agreement window, press the Accept button:

    Third Android SDK License Agreement window.

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

    Android SDK license user account control dialog.

    Wait for Visual Studio to install to download the Android SDK.

  13. In the Visual Studio toolbar, press the Pixel 7 - API 35 (Android 15.0 - API 35) button to build and run the app:

    Pixel 5 API 35 emulator button.

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

    Warning

    Hardware acceleration must be enabled to maximize Android emulator performance. Failure to do this will result in the emulator running very slowly. For more information, see How to enable hardware acceleration with Android emulators (Hyper-V & AEHD).

  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.

Troubleshooting

If your app fails to compile, review Troubleshooting known issues, which may have a solution to your problem. If the problem is related to the Android emulator, see Android emulator troubleshooting.

  1. In the Visual Studio toolbar, press the Windows Machine button to build and run the app:

    Run .NET MAUI app in Visual Studio button.

  2. In the running app, press the Click me button several times and observe that the count of the number of button clicks is incremented:

    .NET MAUI app running on Windows.

Troubleshooting

If your app fails to compile, review Troubleshooting known issues, which may have a solution to your problem.

  1. In Visual Studio, pair the IDE to a Mac Build host. For more information, see Pair to Mac for iOS development.

  2. In the Visual Studio toolbar, use the Debug Target drop-down to select iOS Simulators and then a specific iOS simulator:

    Visual Studio iOS simulators debug targets.

  3. In the Visual Studio toolbar, press the Start button for your chosen iOS simulator to build and run your app:

    Visual Studio iOS simulator debug target choice.

    Visual Studio will build the app, start the remote iOS Simulator for Windows, and deploy the app to the remote simulator. For more information about the remote iOS Simulator for Windows, see Remote iOS Simulator for Windows.

  4. In the running app, press the Click me button several times and observe that the count of the number of button clicks is incremented.

    .NET MAUI app running in iOS Simulator on a Mac.

Troubleshooting

If your app fails to compile, review Troubleshooting known issues, which may have a solution to your problem.

.NET MAUI apps that target Mac Catalyst can only be launched and debugged using Visual Studio Code.

Next steps

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

To learn the fundamentals of building an app with .NET MAUI, see Create a .NET MAUI app. Alternatively, for a full .NET MAUI training course, see Build mobile and desktop apps with .NET MAUI.