Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Installation Instructions for VS Code .NET MAUI Extension #2033

Merged
merged 12 commits into from
Jan 25, 2024
Merged

Update Installation Instructions for VS Code .NET MAUI Extension #2033

Changes from 9 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
f5db94a
Update installation instructions for Visual Studio Code.
Jan 9, 2024
7da8baa
Merge branch 'dotnet:main' into althompson-vscode-install
Jan 10, 2024
66e6192
specify preferred package manager
Jan 12, 2024
b29927c
Merge remote-tracking branch 'origin/main' into althompson-vscode-ins…
Jan 23, 2024
6603c45
update minimum versions of android dependencies
Jan 23, 2024
a12c40e
update android installation options
Jan 23, 2024
ae98439
fix link to Visual Studio tab
Jan 23, 2024
3a7ba6e
fix visual studio tab link
Jan 23, 2024
e9922a0
fix visual studio tab link
Jan 23, 2024
5529940
Addressed feedback
Jan 25, 2024
7b96329
Use dotnetcli instead of cmd
davidbritch Jan 25, 2024
7a43d38
Edit.
davidbritch Jan 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 34 additions & 51 deletions docs/get-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,52 +111,41 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must
> [!NOTE]
> The .NET MAUI extension requires the C# Dev Kit and prerelease C# extensions. You must sign into C# Dev Kit to use the .NET MAUI extension's functionality. See [this blog post](https://devblogs.microsoft.com/visualstudio/announcing-csharp-dev-kit-for-visual-studio-code/) for more information about C# Dev Kit and its family of extensions.

## Set up .NET, .NET MAUI, and target platforms
## Install .NET and .NET MAUI workloads

To develop with .NET MAUI in Visual Studio code, you need to have .NET, the .NET MAUI workload, and a valid target platform based on your development machine's operating system:
1. Install [.NET 8](/dotnet/core/install/windows).
1. On Windows, it is 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](./installation.md?tabs=vswin).
1. Install .NET MAUI workload
- Windows/MacOS: Run `dotnet workload install maui` in a terminal.
- Linux: Run `dotnet workload install maui-android` in a terminal.

## Set up Target Platforms

To debug a .NET MAUI app in Visual Studio code, you need to have a valid target platform based on your development machine's operating system:

| Your Operating System | Supported Target Platforms |
|---|---|
| Windows | Windows, Android |
| macOS | Android, iOS, macOS |
| Linux | Android |

### Windows
### iOS and MacOS

The recommended approach to setup your Windows machine for .NET MAUI development is through the Visual Studio installer. You can follow the instructions in the Visual Studio tab on this page to walk through installing the .NET MAUI workload. You can also use Visual Studio to manage different versions of Android, create emulators, update .NET and .NET MAUI, and more.
To debug to an iOS or MacOS target in Visual Studio Code, follow the steps below:

If you don't want to install Visual Studio, you can still get set up for .NET MAUI development by following these steps:

1. Install [.NET 8](/dotnet/core/install/windows).
1. After .NET has finished installing, run `dotnet workload install maui` in a terminal.
1. If you'd like to debug Android in Visual Studio Code, you also have to:
1. Install [Microsoft OpenJDK 11](/java/openjdk/download#openjdk-11).
1. Install the Android SDK. You can acquire the correct versions of the Android SDK and build tools by creating a new .NET MAUI project (`dotnet new maui`) and running the following command in your terminal:
`dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory="<ANDROID SDK DIRECTORY>" -p:AcceptAndroidSDKLicenses=True`
On Windows, the suggested Android SDK directory value is `%LOCALAPPDATA%/Android/Sdk`.
1. Install the [latest stable Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12).
1. Run `xcode-select --install` in a terminal to acquire the Xcode command line tools.

> [!NOTE]
> See the [Troubleshooting > Android Setup](#android-setup) section for more information on setting up the Android SDK.
### Android

### macOS
To debug to an Android target in Visual Studio Code, follow the steps below:

1. Install [.NET 8](/dotnet/core/install/macOS).
1. Install the [latest stable Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12).
1. After Xcode has finished installing, run `xcode-select --install` in a terminal to acquire the Xcode command line tools.
1. Run `dotnet workload install maui` in a terminal.
1. If you'd like to debug to Android in Visual Studio Code, you also have to:
1. Install [Microsoft OpenJDK 11](/java/openjdk/download#openjdk-11).
1. Install the Android SDK. You can acquire the correct versions of the Android SDK and build tools by creating a new .NET MAUI project (`dotnet new maui`) and running the following command in your terminal:
`dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory="<ANDROID SDK DIRECTORY>" -p:AcceptAndroidSDKLicenses=True`
On macOS, the suggested Android SDK directory value is `$HOME/Library/Android/sdk`.

### Linux

1. Install [.NET 8](/dotnet/core/install/linux).
1. After .NET has installed, run `dotnet workload install maui-android` in a terminal.
1. If you'd like to debug to Android in Visual Studio Code, you also have to:
1. Install [Microsoft OpenJDK 11](/java/openjdk/download#openjdk-11).
1. Install the Android SDK from your preferred package manager, or from the [Android website](https://developer.android.com/about/versions/13/setup-sdk).
1. Install [Microsoft OpenJDK 11](/java/openjdk/download#openjdk-11).
1. Install the Android SDK via one of the following options:
* **(Recommended)** Create a new .NET MAUI project (`dotnet new maui`) and use the [InstallAndroidDependencies target](#using-installandroiddependencies).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **(Recommended)** Create a new .NET MAUI project (`dotnet new maui`) and use the [InstallAndroidDependencies target](#using-installandroiddependencies).
* **(Recommended)** Create a new .NET MAUI project (`dotnet new maui`) and use the [InstallAndroidDependencies target](#using-the-installandroiddependencies-target).

* Install via Visual Studio (Windows only).
* Install via Android Studio.
* Install via your preferred package manager on Linux.

## Troubleshooting

Expand All @@ -166,23 +155,17 @@ You might face issues when setting up the .NET MAUI extension for Visual Studio

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`.

### Android setup

There are multiple ways you can set up and manage Android SDKs on your machine:

* (Recommended) Use the [`dotnet build -t:InstallAndroidDependencies` target](#using-installandroiddependencies).
* Install via Visual Studio (Windows only).
* Install via Android Studio.
* Use the [Android Command Line Tools](https://developer.android.com/studio#command-tools).
#### Using "InstallAndroidDependencies"

No matter which way you install Android, you can develop .NET MAUI apps in Visual Studio Code. If the following troubleshooting steps don't solve your issue, please [Report a Problem](https://github.com/microsoft/vscode-dotnettools/issues).
.NET 8 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:

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

* .NET 8 has a build target that helps set up your Android environment for you. You can add or remove the following properties to `dotnet build -t:InstallAndroidDependencies -f:net8.0-android` to configure your machine:
* `-p:AndroidSdkDirectory "<PATH>"` installs or updates Android dependencies to the specified path (Note: You must use an absolute path without a tilde "~").
* `-p:JavaSdkDirectory "<PATH>"` installs Java to the specified path (Note: You must use an absolute path without a tilde "~").
* `-p:AcceptAndroidSDKLicenses=True` accepts the necessary Android licenses for development.
* `AndroidSdkDirectory "<AndroidSdkPath>"` : installs or updates Android dependencies to the specified path (Note: Must use an absolute path).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `AndroidSdkDirectory "<AndroidSdkPath>"` : installs or updates Android dependencies to the specified path (Note: Must use an absolute path).
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 path (Note: Must be an absolute path).
* `AcceptAndroidSDKLicenses=True` : accepts the necessary Android licenses for development.

#### There's an error that the Android SDK or Java SDK was not found

Expand All @@ -193,11 +176,11 @@ No matter which way you install Android, you can develop .NET MAUI apps in Visua
* 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 >= 32.0.0
* cmdline-tools == 7.0
* platforms;android-33*
* build-tools >= 34.0.0
* cmdline-tools == 11.0
* platforms;android-34*
* .NET 7: platform-tools = 33.0.2
* .NET 8: platform-tools = 34.0.1
* .NET 8: platform-tools = 34.0.5

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

Expand Down
Loading