From f5db94adf059634f69b929bff2b5069ca442f51e Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Mon, 8 Jan 2024 16:02:49 -0800 Subject: [PATCH 01/10] Update installation instructions for Visual Studio Code. --- docs/get-started/installation.md | 78 +++++++++++++------------------- 1 file changed, 31 insertions(+), 47 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 80d94ebef..9b5aa9c85 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -111,9 +111,17 @@ 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](#tab/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 | |---|---| @@ -121,42 +129,24 @@ To develop with .NET MAUI in Visual Studio code, you need to have .NET, the .NET | 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="" -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="" -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). + * Install via Visual Studio (Windows only). + * Install via Android Studio. + * Install via package manager. + * Install via the [Android website](https://developer.android.com/about/versions/13/setup-sdk). ## Troubleshooting @@ -166,23 +156,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 "" -p:JavaSdkDirectory "" -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 ""` installs or updates Android dependencies to the specified path (Note: You must use an absolute path without a tilde "~"). - * `-p:JavaSdkDirectory ""` 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 ""` : installs or updates Android dependencies to the specified path (Note: Must use an absolute path). + * Windows: the suggested AndroidSdkPath is `%LOCALAPPDATA%/Android/Sdk`. + * MacOS: the suggested AndroidSdkPath is `$HOME/Library/Android/sdk`. +* `JavaSdkDirectory ""` : 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 From 66e61920cd38787f81afda52f61b9940e2ed6ae8 Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Fri, 12 Jan 2024 13:52:13 -0800 Subject: [PATCH 02/10] specify preferred package manager --- docs/get-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 9b5aa9c85..617b60a34 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -145,7 +145,7 @@ To debug to an Android target in Visual Studio Code, follow the steps below: * **(Recommended)** Create a new .NET MAUI project (`dotnet new maui`) and use the [InstallAndroidDependencies target](#using-installandroiddependencies). * Install via Visual Studio (Windows only). * Install via Android Studio. - * Install via package manager. + * Install via your preferred package manager (Linux). * Install via the [Android website](https://developer.android.com/about/versions/13/setup-sdk). ## Troubleshooting From 6603c45bba6c403d85735b6292325b17526083ee Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Tue, 23 Jan 2024 10:18:55 -0800 Subject: [PATCH 03/10] update minimum versions of android dependencies --- docs/get-started/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 617b60a34..9d86abda5 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -177,11 +177,11 @@ If you try to create a new project and the file explorer keeps popping up in an * 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 From a12c40e27cd6c6d14e8273300fa45894bfaba596 Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Tue, 23 Jan 2024 10:20:16 -0800 Subject: [PATCH 04/10] update android installation options --- docs/get-started/installation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 9d86abda5..908833a7b 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -145,8 +145,7 @@ To debug to an Android target in Visual Studio Code, follow the steps below: * **(Recommended)** Create a new .NET MAUI project (`dotnet new maui`) and use the [InstallAndroidDependencies target](#using-installandroiddependencies). * Install via Visual Studio (Windows only). * Install via Android Studio. - * Install via your preferred package manager (Linux). - * Install via the [Android website](https://developer.android.com/about/versions/13/setup-sdk). + * Install via your preferred package manager on Linux. ## Troubleshooting From ae984390d5ed89e9eea756c7a422a17238fc1e7a Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Tue, 23 Jan 2024 11:22:15 -0800 Subject: [PATCH 05/10] fix link to Visual Studio tab --- docs/get-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 908833a7b..6e60dc8c0 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -114,7 +114,7 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must ## Install .NET and .NET MAUI workloads 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](#tab/vswin). + 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](#visual-studio). 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. From 3a7ba6e8ba13dcbe14ee0539512882d704e30e87 Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Tue, 23 Jan 2024 11:47:26 -0800 Subject: [PATCH 06/10] fix visual studio tab link --- docs/get-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 6e60dc8c0..65b30273b 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -114,7 +114,7 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must ## Install .NET and .NET MAUI workloads 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](#visual-studio). + 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#visual-studio). 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. From e9922a036f1f5fbaf072c5b6a998ea1b79159f13 Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Tue, 23 Jan 2024 11:57:27 -0800 Subject: [PATCH 07/10] fix visual studio tab link --- docs/get-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index 65b30273b..d5fb65e9b 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -114,7 +114,7 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must ## Install .NET and .NET MAUI workloads 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#visual-studio). + 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. From 5529940fb797ebfe95f01138a940ebce21980ba4 Mon Sep 17 00:00:00 2001 From: Alex Thompson Date: Wed, 24 Jan 2024 16:36:45 -0800 Subject: [PATCH 08/10] Addressed feedback --- docs/get-started/installation.md | 46 +++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index d5fb65e9b..e05e3ab45 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -114,14 +114,24 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must ## Install .NET and .NET MAUI workloads 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. + 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](./installation.md?tabs=vswin). +1. Install the .NET MAUI workload: -## Set up Target Platforms + On Windows and macOS, run the following command in a terminal: -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: + ```cmd + dotnet workload install maui + ``` + + On Linux, run the following command in a terminal: + + ```cmd + 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 for your development machine's operating system: | Your Operating System | Supported Target Platforms | |---|---| @@ -129,20 +139,20 @@ To debug a .NET MAUI app in Visual Studio code, you need to have a valid target | macOS | Android, iOS, macOS | | Linux | Android | -### iOS and MacOS +### iOS and macOS -To debug to an iOS or MacOS target in Visual Studio Code, follow the steps below: +To debug to an iOS or macOS target in Visual Studio Code: 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. ### Android -To debug to an Android target in Visual Studio Code, follow the steps below: +To debug to an Android target in Visual Studio Code: 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). +1. 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](#using-the-installandroiddependencies-target). * Install via Visual Studio (Windows only). * Install via Android Studio. * Install via your preferred package manager on Linux. @@ -155,17 +165,21 @@ 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`. -#### Using "InstallAndroidDependencies" +#### Using the "InstallAndroidDependencies" target .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: -> `dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory "" -p:JavaSdkDirectory "" -p:AcceptAndroidSDKLicenses=True` +```cmd +dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory "" -p:JavaSdkDirectory "" -p:AcceptAndroidSDKLicenses=True +``` + +In the command above: -* `AndroidSdkDirectory ""` : installs or updates Android dependencies to the specified path (Note: Must use an absolute path). +* `AndroidSdkDirectory ""`: 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 ""` : installs Java to the specified path (Note: Must be an absolute path). -* `AcceptAndroidSDKLicenses=True` : accepts the necessary Android licenses for development. +* `JavaSdkDirectory ""`: 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 was not found From 7b96329efdc3d36f338e3b5976a23ad795cc3700 Mon Sep 17 00:00:00 2001 From: David Britch Date: Thu, 25 Jan 2024 11:33:37 +0000 Subject: [PATCH 09/10] Use dotnetcli instead of cmd --- docs/get-started/installation.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index e05e3ab45..bf246245e 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -114,18 +114,20 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must ## Install .NET and .NET MAUI workloads 1. Install [.NET 8](/dotnet/core/install/windows). + 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](./installation.md?tabs=vswin). + 1. Install the .NET MAUI workload: On Windows and macOS, run the following command in a terminal: - ```cmd + ```dotnetcli dotnet workload install maui ``` On Linux, run the following command in a terminal: - ```cmd + ```dotnetcli dotnet workload install maui-android ``` @@ -165,11 +167,11 @@ 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`. -#### Using the "InstallAndroidDependencies" target +#### Using the InstallAndroidDependencies target .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: -```cmd +```dotnetcli dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory "" -p:JavaSdkDirectory "" -p:AcceptAndroidSDKLicenses=True ``` From 7a43d382992b9ab13dcd0c895f12c3343c0f35fa Mon Sep 17 00:00:00 2001 From: David Britch Date: Thu, 25 Jan 2024 11:43:22 +0000 Subject: [PATCH 10/10] Edit. --- docs/get-started/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index bf246245e..d5d86dee1 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -117,7 +117,7 @@ To install Visual Studio 2022 for Mac behind a firewall, certain endpoints must 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](./installation.md?tabs=vswin). -1. Install the .NET MAUI workload: +1. Install the .NET MAUI workload. On Windows and macOS, run the following command in a terminal: