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

Jump to bottom

Audit MSBuild error messages for VS and XA specific instructions #8413

Closed
jpobst opened this issue Oct 10, 2023 · 2 comments
Closed

Audit MSBuild error messages for VS and XA specific instructions #8413

jpobst opened this issue Oct 10, 2023 · 2 comments
Assignees
@dellis1972 @jonathanpeppers
Labels
Area: App+Library Build Issues when building Library projects or Application projects. Area: Documentation Issues with documentation. enhancement Proposed change to current functionality.
Milestone
.NET 9

Comments

@jpobst
Copy link
Contributor

jpobst commented Oct 10, 2023 •
edited
Loading

As we transition from Xamarin.Android to .NET and add additional support for tooling like dotnet CLI and VSCode we should audit our warning/error messages to ensure they aren't VS-exclusive.

In many cases we can probably make the message generic enough. In other cases where there is a benefit to giving tooling-specific instructions we can provide an aka.ms link to more detailed instructions.

Some examples that should be fixed:
@jpobst jpobst added Area: App+Library Build Issues when building Library projects or Application projects. Area: Documentation Issues with documentation. labels Oct 10, 2023
@jpobst jpobst added this to the .NET 9 Planning milestone Oct 10, 2023
@microsoft-github-policy-service microsoft-github-policy-service bot added the needs-triage Issues that need to be assigned. label Oct 10, 2023
@jpobst jpobst added enhancement Proposed change to current functionality. and removed needs-triage Issues that need to be assigned. labels Oct 10, 2023
@BretJohnson
Copy link
Member

See this Twitter/X thread for an example of a user who could really benefit from a better message here: https://twitter.com/seansparkman/status/1713998489745543536?s=20

Here's the scenario:

  • User (Sean) installs .NET8 MAUI on his Mac, trying to use it
  • He builds from the CLI
  • He sees the error Could not find android.jar for API level 34. This means the Android SDK platform for API level 34 is not installed. Either install it in the Android SDK Manager (Tools > Open Android SDK Manager...), or change the Xamarin.Android project to target an API version that is installed..
  • He's confused about what to do. He currently has VS Mac installed, but knows it's going away. VS Code doesn't have an Android SDK Manager. He seems to think that installing the right Android workload from the CLI will fix this somehow (a reasonable assumption, though a wrong one here). He struggles for a good while.
  • The fact that the branding is wrong (e.g. saying Xamarin.Android project instead of .NET Android project) makes it worse.

Probably our updated error text, at least when running on Mac, should include a link to the doc that talks about how to install Android dependencies, with VS Code. This doc: Install Visual Studio 2022 to develop cross-platform apps using .NET MAUI - .NET MAUI | Microsoft Learn

@dellis1972 dellis1972 mentioned this issue Nov 9, 2023
Merged
jonpryor pushed a commit that referenced this issue Dec 6, 2023
@dellis1972
[Xamarin.Android.Build.Tasks] Update XA5207 for VSCode (#8494)
6fa67be 
Context: #8413
Context: #8522

The [XA5207][0] error message contained IDE-specific instructions:

	# Visual Studio
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed.
	  Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change your Xamarin.Android project
	  to target an API version that is installed.

	# Visual Studio for Mac
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed.
	  Either install it in the Android SDK Manager (Tools > Open Android SDK Manager...), or change your Xamarin.Android project
	  to target an API version that is installed.

[Visual Studio for Mac is now deprecated][1]:

> Visual Studio for Mac is scheduled for retirement by August 31, 2024

Visual Studio Code is now supported, via [C# Dev Kit][2] and the
[.NET MAUI][3] extensions.  ([Announcement][4].)

These changes mean that our error messages are obsolete (building on
macOS) or misleading (building within VSCode on Windows).

Update the XA5207 error generation logic to take these changes into
consideration.  Visual Studio (Windows) will retain the existing
error message text.  The Visual Studio for Mac instructions are
replaced with instructions for command-line builds, for use from
Visual Studio Code:

	# Visual Studio
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed;
	  it was expected to be in `…`.
	  Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change the .NET Android project
	  to target an API version that is installed.
	  See https://aka.ms/xa5207 for more details.

	# Visual Studio Code
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed;
	  it was expected to be in `…`.
	  You can install the missing API level by running
	  `dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=…"`,
	  or change the project to target an API version that is installed.
	  See https://aka.ms/xa5207 for more details.


Update some of the documentation around the
`InstallAndroidDependencies` target to mention `dotnet build` options
which are required in order for the target to function correctly.

Finally, update various error messages, replacing "Xamarin.Android"
with ".NET Android".

[0]: https://github.com/xamarin/xamarin-android/blob/40cc8eaf78eb9f95abcc0e966ab274cef1692acc/Documentation/guides/messages/xa5207.md
[1]: https://learn.microsoft.com/en-us/visualstudio/mac/what-happened-to-vs-for-mac?view=vsmac-2022
[2]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit
[3]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui
[4]: https://devblogs.microsoft.com/visualstudio/announcing-the-dotnet-maui-extension-for-visual-studio-code/
jonathanpeppers pushed a commit that referenced this issue Dec 6, 2023
@dellis1972 @jonathanpeppers
[Xamarin.Android.Build.Tasks] Update XA5207 for VSCode (#8494)
c020626 
Context: #8413
Context: #8522

The [XA5207][0] error message contained IDE-specific instructions:

	# Visual Studio
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed.
	  Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change your Xamarin.Android project
	  to target an API version that is installed.

	# Visual Studio for Mac
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed.
	  Either install it in the Android SDK Manager (Tools > Open Android SDK Manager...), or change your Xamarin.Android project
	  to target an API version that is installed.

[Visual Studio for Mac is now deprecated][1]:

> Visual Studio for Mac is scheduled for retirement by August 31, 2024

Visual Studio Code is now supported, via [C# Dev Kit][2] and the
[.NET MAUI][3] extensions.  ([Announcement][4].)

These changes mean that our error messages are obsolete (building on
macOS) or misleading (building within VSCode on Windows).

Update the XA5207 error generation logic to take these changes into
consideration.  Visual Studio (Windows) will retain the existing
error message text.  The Visual Studio for Mac instructions are
replaced with instructions for command-line builds, for use from
Visual Studio Code:

	# Visual Studio
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed;
	  it was expected to be in `…`.
	  Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change the .NET Android project
	  to target an API version that is installed.
	  See https://aka.ms/xa5207 for more details.

	# Visual Studio Code
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed;
	  it was expected to be in `…`.
	  You can install the missing API level by running
	  `dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=…"`,
	  or change the project to target an API version that is installed.
	  See https://aka.ms/xa5207 for more details.


Update some of the documentation around the
`InstallAndroidDependencies` target to mention `dotnet build` options
which are required in order for the target to function correctly.

Finally, update various error messages, replacing "Xamarin.Android"
with ".NET Android".

[0]: https://github.com/xamarin/xamarin-android/blob/40cc8eaf78eb9f95abcc0e966ab274cef1692acc/Documentation/guides/messages/xa5207.md
[1]: https://learn.microsoft.com/en-us/visualstudio/mac/what-happened-to-vs-for-mac?view=vsmac-2022
[2]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit
[3]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui
[4]: https://devblogs.microsoft.com/visualstudio/announcing-the-dotnet-maui-extension-for-visual-studio-code/
@jpobst
Copy link
Contributor Author

jpobst commented May 17, 2024

This seems to have been covered by #8494 and other work in this area.

@jpobst jpobst closed this as completed May 17, 2024
@github-actions github-actions bot locked and limited conversation to collaborators Jun 17, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@dellis1972 dellis1972

@jonathanpeppers jonathanpeppers

Labels
Area: App+Library Build Issues when building Library projects or Application projects. Area: Documentation Issues with documentation. enhancement Proposed change to current functionality.
Projects
None yet
Milestone
.NET 9
Development

No branches or pull requests
4 participants
@jpobst @BretJohnson @dellis1972 @jonathanpeppers