Skip to content

Latest commit

 

History

History
212 lines (136 loc) · 13.6 KB

installation.md

File metadata and controls

212 lines (136 loc) · 13.6 KB
Raw
title description ms.date monikerRange
Install Visual Studio 2022 and Visual Studio Code to develop cross-platform apps using .NET MAUI
Learn how to install Visual Studio 2022 and Visual Studio Code with the .NET MAUI extension to develop native, cross-platform apps using .NET MAUI.
11/12/2024
>=net-maui-9.0

Installation

Developing native, cross-platform .NET Multi-platform App UI (.NET MAUI) apps requires Visual Studio 2022 17.12 or greater, or the latest Visual Studio Code with the .NET MAUI extension.

Visual Studio

To start developing native, cross-platform .NET MAUI apps on Windows, install Visual Studio 2022 17.12 or greater by following the installation steps.

Prerequisites

  • Visual Studio 2022 17.12 or greater. For information about supported operating systems, hardware, supported languages, and additional requirements and guidance, see Visual Studio 2022 System Requirements.

To build, sign, and deploy .NET MAUI apps for iOS, you'll also need:

Alternatively, to deploy debug builds of your app directly from Windows to your iOS device with hot restart, you'll need:

Installation

  1. To create .NET MAUI apps, you'll need the latest version of Visual Studio 2022:

  2. Either install Visual Studio, or modify your existing installation, and install the .NET Multi-platform App UI development workload with its default optional installation options:

    :::image type="content" source="media/installation/vs/vs-workloads.png" alt-text="Visual Studio workloads for .NET MAUI.":::

Visual Studio Code

To start developing native, cross-platform .NET MAUI apps on Windows, macOS, or Linux, install the latest Visual Studio Code by following the installation steps.

Prerequisites

To build, sign, and deploy .NET MAUI apps for iOS, you'll need:

Installation

  1. To create .NET MAUI apps you'll need to install the latest Visual Studio Code.

  2. In Visual Studio Code, in the Extensions tab, search for ".NET MAUI" and install the .NET MAUI extension. The .NET MAUI extension automatically installs the C# Dev Kit and C# extensions, which are required for the .NET MAUI extension to run.

    :::image type="content" source="media/installation/vscode/maui-extension-preview.png" alt-text="Screenshot of the Visual Studio Code extension pane showing the .NET MAUI extension":::

Note

The .NET MAUI extension requires the C# Dev Kit and C# extensions. You must #to C# Dev Kit to use the .NET MAUI extension's functionality. For more information, see this blog post to learn more about C# Dev Kit and its family of extensions.

Install .NET and .NET MAUI workloads

  1. Install .NET 9.

    On Windows, it's recommended to use the Visual Studio installer to manage .NET and the .NET MAUI workload installations. Instructions on using the Visual Studio installer can be found here.

    On Linux, install using the scripted installation instructions.

  2. Install the .NET MAUI workload.

    On Windows, unless installed through the Visual Studio installer, run the following command in a terminal:

    dotnet workload install maui

    On macOS, run the following command in a terminal:

     sudo dotnet workload install maui

    On Linux, run the following command in a terminal:

    dotnet workload install maui-android

Set up target platforms

To debug a .NET MAUI app in Visual Studio Code, you need to have a valid target platform relative to your development machine's operating system. Including invalid target platforms will prevent your project from building. You can manage target platforms in your app's project file (.csproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net9.0-android;net9.0-ios;net9.0-maccatalyst</TargetFrameworks>
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0</TargetFrameworks>
Your Operating System Supported Target Platforms
Windows Windows, Android
macOS Android, iOS, macOS
Linux Android

iOS and macOS

To debug to an iOS or macOS target in Visual Studio Code:

  1. Install the version of Xcode that's required by the version of .NET MAUI that you're using. For information, see Release versions. The latest stable Xcode release can be downloaded from the Apple App Store.
  2. Run xcode-select --install in a terminal to acquire the Xcode command line tools.
  3. Open Xcode, and ensure you accept any license agreements.

Android

To debug to an Android target in Visual Studio Code:

  1. Install Microsoft OpenJDK 17.
  2. Install the Android SDK via one of the following approaches:
    • (Recommended) Create a new .NET MAUI project (dotnet new maui) and use the InstallAndroidDependencies target.
    • Install via Visual Studio (Windows only).
    • Install via Android Studio.
    • Install via your preferred package manager on Linux.

Troubleshooting

You might face issues when setting up the .NET MAUI extension for Visual Studio Code. To see details on errors related to the extension, navigate to the Output window (CTRL/CMD + Shift + u ) and select .NET MAUI in the dropdown. See the below sections to help address your issue. If you're still facing issues after following the troubleshooting steps, please report an issue.

Project creation

If you try to create a new project and the file explorer keeps popping up in an infinite loop, you may not be selecting an empty folder. Check that there are no hidden files or folders, create a new folder, or create your .NET MAUI app from the command line using dotnet new maui.

Using the InstallAndroidDependencies target

.NET 9 has a build target that helps set up your Android environment for you. Run the following command in a terminal to configure your machine and set up your Android environment:

dotnet build -t:InstallAndroidDependencies -f:net9.0-android -p:AndroidSdkDirectory="<AndroidSdkPath>" -p:JavaSdkDirectory="<JavaSdkPath>" -p:AcceptAndroidSDKLicenses=True

In the command above:

  • AndroidSdkDirectory="<AndroidSdkPath>": installs or updates Android dependencies to the specified absolute path.
    • Windows: the suggested AndroidSdkPath is %LOCALAPPDATA%/Android/Sdk.
    • macOS: the suggested AndroidSdkPath is $HOME/Library/Android/sdk.
  • JavaSdkDirectory="<JavaSdkPath>": installs Java to the specified absolute path.
  • AcceptAndroidSDKLicenses=True: accepts the required Android licenses for development.

There's an error that the Android SDK or Java SDK wasn't found

  • Open the command palette (Ctrl/Cmd + Shift + P) and search for the .NET MAUI: Configure Android command. Select both "Set Android SDK path" and "Set Android JDK path" and validate that they point to installations of each.
    • The Android SDK folder should have sub-folders such as build-tools, cmdline-tools, and platform-tools.
    • The Java OpenJDK folder should have sub-folders such as bin, lib, and more.
    • On Windows, if you install via Visual Studio, the Java SDK will be in C:\Program Files\Microsoft\ and Android SDK will be in C:\Program Files (x86)\Android\android-sdk.
  • Set the JAVA_HOME environment variable to a valid Java OpenJDK path.
  • Set the ANDROID_HOME environment variable to your Android SDK path.
  • Check your minimum versions of installed Android dependencies:
    • build-tools >= 34.0.0
    • cmdline-tools == 11.0
    • platforms;android-34*
    • .NET 9: platform-tools = 34.0.5

There's an error that Android licenses aren't accepted

In an elevated command prompt or terminal, navigate to your Android SDK's cmdline-tools/latest/bin/ folder and run sdkmanager --licenses then follow the CLI prompts.

My Android dependencies aren't loading in the Solution Explorer, but my app builds fine

This is a known issue if you install to %APPDATA% on Windows and will be fixed in a future release.

iOS/Xcode Setup

  • If you get an error that Xcode isn't found, run xcode-select --install in a terminal, then check that xcode-select -p points to your Xcode installation.
  • If you're still facing issues, open Xcode itself to make sure it loads correctly. Once Xcode is open, navigate to Xcode > Settings > Locations and check that the Command Line Tools field is pointing to the correct Xcode.
  • There's a known issue that sometimes you have to build your iOS/macOS app twice for it to deploy. This will be fixed in an upcoming release.

Debugging issues

  • Debugging can fail to start for multiple reasons. If there isn't a clear error in the Output window, first double check that you're using the C# run configuration in Visual Studio Code.
  • If you're using an older version of .NET, the C# debugger isn't supported for .NET MAUI apps. You can use the legacy .NET MAUI debug configuration by unchecking the extension setting MAUI > Configuration > Experimental > Use VSDbg.
  • You can try a command line build from the terminal to see if the error is with your code or the .NET MAUI extension. For example, you could run dotnet build -f:net9.0-android to see if your Android build succeeds outside of Visual Studio Code. If this build succeeds, please Report an Issue

Known limitations

  • Currently, you can't switch the target framework for IntelliSense (it will show syntax highlighting for only the first target framework listed in your .csproj file). This capability is in progress. To get syntax highlighting for other targets (e.g. Android instead of iOS) you can reorder the target frameworks in your project file.
  • .NET Hot Reload is currently in preview in the C# Dev Kit.

Please give us your feedback on other features you'd like to see as we continue building this new experience!

Provide feedback

Please read the C# Dev Kit FAQs and check existing Known Issues before filing a new issue or suggestion. You can file suggestions and issues from inside Visual Studio Code through through the Help > Report Issue dialog. Ensure you select “An extension” then the .NET MAUI extension in the drop-down.

:::image type="content" source="media/installation/vscode/report-issue.png" alt-text="Picture of the report issue dialog in Visual Studio Code":::

Next steps

To learn how to create and run your first .NET MAUI app in Visual Studio 2022 on Windows, or Visual Studio Code, click the button below.

[!div class="nextstepaction"] Build your first app