diff --git a/docs/android/TOC.yml b/docs/android/TOC.yml index bdb778a..9a042b8 100644 --- a/docs/android/TOC.yml +++ b/docs/android/TOC.yml @@ -106,6 +106,8 @@ href: messages/apt0000.md - name: APT0001 href: messages/apt0001.md + - name: APT2000 + href: messages/apt2000.md - name: APT2264 href: messages/apt2264.md - name: APT2265 @@ -274,6 +276,12 @@ href: messages/xa1037.md - name: XA1038 href: messages/xa1038.md + - name: XA1039 + href: messages/xa1039.md + - name: XA1040 + href: messages/xa1040.md + - name: XA1041 + href: messages/xa1041.md - name: "XA2xxx: Linker" items: - name: "XA2xxx: Linker" diff --git a/docs/android/binding-libs/advanced-concepts/android-maven-library.md b/docs/android/binding-libs/advanced-concepts/android-maven-library.md index 16e4425..532aa9b 100644 --- a/docs/android/binding-libs/advanced-concepts/android-maven-library.md +++ b/docs/android/binding-libs/advanced-concepts/android-maven-library.md @@ -1,7 +1,7 @@ --- title: AndroidMavenLibrary Build Action .NET for Android description: AndroidMavenLibrary Build Action .NET for Android -ms.author: jopobst +ms.author: jopepper ms.date: 05/11/2024 --- # AndroidMavenLibrary diff --git a/docs/android/binding-libs/advanced-concepts/distributing.md b/docs/android/binding-libs/advanced-concepts/distributing.md index 549c12b..c4dcc03 100644 --- a/docs/android/binding-libs/advanced-concepts/distributing.md +++ b/docs/android/binding-libs/advanced-concepts/distributing.md @@ -1,7 +1,7 @@ --- title: Distributing bindings libraries description: Once a Java library has been bound, it may be desirable to distribute it internally or via NuGet for consumption. -ms.author: jopobst +ms.author: jopepper ms.date: 05/08/2024 --- diff --git a/docs/android/binding-libs/advanced-concepts/java-dependency-verification.md b/docs/android/binding-libs/advanced-concepts/java-dependency-verification.md index 8acd9bd..8b70906 100644 --- a/docs/android/binding-libs/advanced-concepts/java-dependency-verification.md +++ b/docs/android/binding-libs/advanced-concepts/java-dependency-verification.md @@ -1,7 +1,7 @@ --- title: Java Dependency Verification in .NET for Android description: Java Dependency Verification in .NET for Android -ms.author: jopobst +ms.author: jopepper ms.date: 05/11/2024 --- diff --git a/docs/android/binding-libs/advanced-concepts/resolving-java-dependencies.md b/docs/android/binding-libs/advanced-concepts/resolving-java-dependencies.md index 471be48..97b6fb0 100644 --- a/docs/android/binding-libs/advanced-concepts/resolving-java-dependencies.md +++ b/docs/android/binding-libs/advanced-concepts/resolving-java-dependencies.md @@ -1,7 +1,7 @@ --- title: Resolving Java Dependencies in .NET for Android description: Resolving Java Dependencies in .NET for Android -ms.author: jopobst +ms.author: jopepper ms.date: 05/11/2024 --- diff --git a/docs/android/binding-libs/binding-java-libs/binding-java-library.md b/docs/android/binding-libs/binding-java-libs/binding-java-library.md index 649f1f6..257bc84 100644 --- a/docs/android/binding-libs/binding-java-libs/binding-java-library.md +++ b/docs/android/binding-libs/binding-java-libs/binding-java-library.md @@ -1,7 +1,7 @@ --- title: Binding a Java Library description: Bind an existing Java library to use it from a .NET for Android application. -ms.author: jopobst +ms.author: jopepper ms.date: 05/07/2024 --- diff --git a/docs/android/binding-libs/binding-java-libs/binding-java-maven-library.md b/docs/android/binding-libs/binding-java-libs/binding-java-maven-library.md index 83f88eb..91360d1 100644 --- a/docs/android/binding-libs/binding-java-libs/binding-java-maven-library.md +++ b/docs/android/binding-libs/binding-java-libs/binding-java-maven-library.md @@ -1,7 +1,7 @@ --- title: Binding a Java Library from Maven description: allows a Maven artifact to be specified which will automatically be downloaded and added to a .NET for Android binding project. This can be useful to simplify maintenance of .NET for Android bindings for artifacts hosted in Maven. -ms.author: jopobst +ms.author: jopepper ms.date: 05/11/2024 --- diff --git a/docs/android/binding-libs/binding-java-libs/index.md b/docs/android/binding-libs/binding-java-libs/index.md index 305966f..fe7939e 100644 --- a/docs/android/binding-libs/binding-java-libs/index.md +++ b/docs/android/binding-libs/binding-java-libs/index.md @@ -1,7 +1,7 @@ --- title: Overview description: "The Android community has many Java libraries that you may want to use in your app; this guide explains how to incorporate Java libraries into your .NET for Android application by creating a Bindings Library." -ms.author: jopobst +ms.author: jopepper ms.date: 05/08/2024 --- diff --git a/docs/android/binding-libs/customizing-bindings/creating-enums.md b/docs/android/binding-libs/customizing-bindings/creating-enums.md index 1348dd7..7446d1e 100644 --- a/docs/android/binding-libs/customizing-bindings/creating-enums.md +++ b/docs/android/binding-libs/customizing-bindings/creating-enums.md @@ -1,7 +1,7 @@ --- title: "Creating enumerations" description: There are cases where Java Android libraries use integer constants to represent states that are passed to properties or methods of the libraries. For widely distributed bindings, it may useful to bind these integer constants to enums in C# to provide a nicer API for consumers. -ms.author: jopobst +ms.author: jopepper ms.date: 05/08/2024 --- diff --git a/docs/android/binding-libs/customizing-bindings/index.md b/docs/android/binding-libs/customizing-bindings/index.md index c0c4cae..f42c5ef 100644 --- a/docs/android/binding-libs/customizing-bindings/index.md +++ b/docs/android/binding-libs/customizing-bindings/index.md @@ -1,7 +1,7 @@ --- title: "Customizing Bindings" description: "You can customize a .NET for Android binding by editing the metadata that controls the binding process. These manual modifications are often necessary for resolving build errors and for shaping the resulting API so that it is more consistent with C#/.NET. These guides explain the structure of this metadata and how to modify the metadata." -ms.author: jopobst +ms.author: jopepper ms.date: 05/06/2024 --- diff --git a/docs/android/binding-libs/customizing-bindings/java-bindings-metadata.md b/docs/android/binding-libs/customizing-bindings/java-bindings-metadata.md index 81ad7a0..9c3ed95 100644 --- a/docs/android/binding-libs/customizing-bindings/java-bindings-metadata.md +++ b/docs/android/binding-libs/customizing-bindings/java-bindings-metadata.md @@ -1,7 +1,7 @@ --- title: "Java Bindings Metadata" description: "C# code in .NET for Android calls Java libraries through bindings, which are a mechanism that abstracts the low-level details that are specified in Java Native Interface (JNI). .NET for Android provides a tool that generates these bindings. This tooling lets the developer control how a binding is created by using metadata, which allows procedures such as modifying namespaces and renaming members. This document discusses how metadata works, summarizes the attributes that metadata supports, and explains how to resolve binding problems by modifying this metadata." -ms.author: jopobst +ms.author: jopepper ms.date: 05/09/2024 --- diff --git a/docs/android/binding-libs/customizing-bindings/namespace-customization.md b/docs/android/binding-libs/customizing-bindings/namespace-customization.md index 99523de..62cb04d 100644 --- a/docs/android/binding-libs/customizing-bindings/namespace-customization.md +++ b/docs/android/binding-libs/customizing-bindings/namespace-customization.md @@ -1,7 +1,7 @@ --- title: "Customizing Namespaces" description: "Renaming Java package names to better fit C# namespaces conventions is a very common use of binding metadata. In order to make this task easier, customizations can be made in the MSBuild project file instead of writing metadata." -ms.author: jopobst +ms.author: jopepper ms.date: 05/06/2024 --- diff --git a/docs/android/binding-libs/customizing-bindings/troubleshooting-bindings.md b/docs/android/binding-libs/customizing-bindings/troubleshooting-bindings.md index 45a4292..a7c0a15 100644 --- a/docs/android/binding-libs/customizing-bindings/troubleshooting-bindings.md +++ b/docs/android/binding-libs/customizing-bindings/troubleshooting-bindings.md @@ -1,7 +1,7 @@ --- title: "Troubleshooting Bindings" description: "This article summarizes serveral common errors that may occur when generating bindings, along with possible causes and suggested ways to resolve them." -ms.author: jopobst +ms.author: jopepper ms.date: 05/09/2024 --- diff --git a/docs/android/binding-libs/msbuild-reference/build-items.md b/docs/android/binding-libs/msbuild-reference/build-items.md index 12c9c97..8c0db24 100644 --- a/docs/android/binding-libs/msbuild-reference/build-items.md +++ b/docs/android/binding-libs/msbuild-reference/build-items.md @@ -1,7 +1,7 @@ --- title: Binding Projects MSBuild Items description: This guide documents the various MSBuild items available for bindings projects. -ms.author: jopobst +ms.author: jopepper ms.date: 05/08/2024 --- diff --git a/docs/android/binding-libs/msbuild-reference/build-properties.md b/docs/android/binding-libs/msbuild-reference/build-properties.md index e72e3cc..3351e6b 100644 --- a/docs/android/binding-libs/msbuild-reference/build-properties.md +++ b/docs/android/binding-libs/msbuild-reference/build-properties.md @@ -1,7 +1,7 @@ --- title: Binding Projects MSBuild Properties description: This guide documents the various MSBuild properties available for bindings projects. -ms.author: jopobst +ms.author: jopepper ms.date: 05/08/2024 --- diff --git a/docs/android/building-apps/build-items.md b/docs/android/building-apps/build-items.md index 57cc85c..02b7f05 100644 --- a/docs/android/building-apps/build-items.md +++ b/docs/android/building-apps/build-items.md @@ -33,7 +33,7 @@ The following MSBuild metadata are required: - `%(JavaArtifact)`: The group and artifact id of the Java library matching the specifed POM file in the form `{GroupId}:{ArtifactId}`. - `%(JavaVersion)`: The version of the Java library matching the specified POM file. - + See the [Java Dependency Resolution documentation](../features/maven/java-dependency-verification.md) for more details. @@ -279,9 +279,9 @@ installing app bundles. ## AndroidMavenLibrary -`` allows a Maven artifact to be specified which will -automatically be downloaded and added to a .NET for Android binding project. -This can be useful to simplify maintenance of .NET for Android bindings for artifacts +`` allows a Maven artifact to be specified which will +automatically be downloaded and added to a .NET for Android binding project. +This can be useful to simplify maintenance of .NET for Android bindings for artifacts hosted in Maven. ```xml @@ -336,6 +336,20 @@ used to specify the ABI that the library targets. Thus, if you add ``` +## AndroidNativeLibraryNoJniPreload + +Every native library included in this item group will be exempt from the +JNI library preload mechanism. By default, all such libraries will be loaded +by the runtime early during application startup in order to assure their +proper initialization. However, in some cases it might not be the desired +behavior and this item group allows exclusion of libraries from this process +on an individual basis. + +Some framework libraries which must be loaded at application startup will not +be affected if included in this item group. + +See also [`$(AndroidIgnoreAllJniPreload)`](build-properties.md#androidignorealljnipreload) + ## AndroidPackagingOptionsExclude A set of file glob compatible items which will allow for items to be diff --git a/docs/android/building-apps/build-properties.md b/docs/android/building-apps/build-properties.md index d109e9e..bbe51e6 100644 --- a/docs/android/building-apps/build-properties.md +++ b/docs/android/building-apps/build-properties.md @@ -273,6 +273,9 @@ Possible values include: Xamarin.Android 6.1 or later. Xamarin.Android 6.1 and later bind `Mono.Android.dll` with this value. +- **JavaInterop1**: experimental value, currently the default for the + NativeAOT runtime. + The default value is `XAJavaInterop1`. ## AndroidCreatePackagePerAbi @@ -395,6 +398,17 @@ final `.apk`. This property is `False` by default. +## AndroidEnableProfiler + +Synonym for the [`$(EnableDiagnostics)`](#enablediagnostics) property. + +Required for using `dotnet-trace` or `dotnet-gcdump` in Android +applications. If set to `true`, it includes the Mono diagnostic +component in the application. This component is the +`libmono-component-diagnostics_tracing.so` native library. + +This property is `False` by default. + ## AndroidEnableObsoleteOverrideInheritance A boolean property that determines if bound methods automatically inherit `[Obsolete]` @@ -445,8 +459,8 @@ This property is `False` by default. An enum-style property with valid values of `obsolete` and `disable`. -When set to `obsolete`, types and members that are marked with the Java annotation -`androidx.annotation.RestrictTo` *or* are in non-exported Java packages will +When set to `obsolete`, types and members that are marked with the Java annotation +`androidx.annotation.RestrictTo` *or* are in non-exported Java packages will be marked with an `[Obsolete]` attribute in the C# binding. This `[Obsolete]` attribute has a descriptive message explaining that the @@ -458,9 +472,9 @@ independently of "normal" obsolete API. When set to `disable`, API will be generated as normal with no additional attributes. (This is the same behavior as before .NET 8.) -Adding `[Obsolete]` attributes instead of automatically removing the API was done to -preserve API compatibility with existing packages. If you would instead prefer to -*remove* members that have the `@RestrictTo` annotation *or* are in non-exported +Adding `[Obsolete]` attributes instead of automatically removing the API was done to +preserve API compatibility with existing packages. If you would instead prefer to +*remove* members that have the `@RestrictTo` annotation *or* are in non-exported Java packages, you can use [Transform files](/xamarin/android/platform/binding-java-library/customizing-bindings/java-bindings-metadata#metadataxml-transform-file) in addition to this property to prevent these types from being bound: @@ -675,6 +689,20 @@ The most common values for this property are: > [`@(AndroidEnvironment)`](build-items.md#androidenvironment) > will take precedence. +## AndroidIgnoreAllJniPreload + +A boolean value which, if set to `true`, exempts all the native JNI libraries +from being preloaded at application startup. By default, all such libraries +will be loaded by the runtime early during application startup in order to +assure their proper initialization. However, in some cases it might not be the +desired behavior and this property allows you to effectively disable it. + +Some framework libraries which must be loaded at application startup will not +be affected by this property. + +See also [`@(AndroidNativeLibraryNoJniPreload)`](build-items.md#androidnativelibrarynojnipreload) +for a more fine-grained way to exempt libraries from the preload mechanism. + ## AndroidIncludeWrapSh A boolean value that indicates whether the Android wrapper script @@ -989,7 +1017,7 @@ that are intended for submission on Google Play. The default value is `apk`. When `$(AndroidPackageFormat)` is set to `aab`, other MSBuild properties are set, which are required for Android App Bundles: -- [`$(AndroidUseAapt2)`](build-properties.md#androiduseaapt2) is `True`. +- [`$(AndroidUseAapt2)`](#androiduseaapt2) is `True`. - [`$(AndroidUseApkSigner)`](#androiduseapksigner) is `False`. - [`$(AndroidCreatePackagePerAbi)`](#androidcreatepackageperabi) is `False`. @@ -1232,7 +1260,13 @@ This means that in Release configuration builds -- in which This can result in increased app sizes. This behavior can be overridden by explicitly setting `$(AndroidEnableProfiledAot)` to `true` within your project file. -Support for this property was added in .NET 8. +Experimental support for this property was added in .NET 8, removed in .NET 10. + +## AndroidStripNativeLibraries + +A bool property which tells the packaging process to strip debug symbols from the native shared libraries (`.so` files). + +The default value is `false` and the debug symbols, if any, will be preserved when packaging. ## AndroidSupportedAbis @@ -1253,11 +1287,8 @@ This property is obsolete and should not be used. ## AndroidUseAapt2 -A boolean property that allows the developer to -control the use of the `aapt2` tool for packaging. -By default this will be True. - -This property cannot be set to false. +This was a Xamarin.Android property that has no effect in .NET for Android. +`aapt2` is always used and cannot be disabled. ## AndroidUseApkSigner @@ -1524,6 +1555,83 @@ If `DebugType` is not set or is the empty string, then the `DebugSymbols` property controls whether or not the Application is debuggable. +## Device + +Specifies which Android device or emulator to target when using +`dotnet run --device ` or MSBuild targets that interact with +devices (such as `Run`, `Install`, or `Uninstall`). + +The value must be the full device serial number or identifier as +returned by `adb devices`. For example, if the device serial is +`emulator-5554`, you must use `-p:Device=emulator-5554`. + +When set, this property is used to initialize the +[`AdbTarget`](#adbtarget) property with the value `-s ""`. + +For more information about device selection, see the +[.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md). + +## DiagnosticAddress + +A value provided by `dotnet-dsrouter` such as `127.0.0.1`, the IP +address component of `$(DiagnosticConfiguration)` or `$DOTNET_DiagnosticPorts`. + +Implicitly enables the Mono diagnostic component, meaning that +`$(EnableDiagnostics)`/`$(AndroidEnableProfiler)` is set to `true`. + +Defaults to `127.0.0.1`. + +## DiagnosticConfiguration + +A value provided by `dotnet-dsrouter` for `$DOTNET_DiagnosticPorts` such as: + +* `127.0.0.1:9000,suspend,connect` +* `127.0.0.1:9000,nosuspend,connect` + +Note that the `,` character will need to be escaped with `%2c` if +passed in command-line to `dotnet build`: + +```dotnetcli +dotnet build -c Release -p:DiagnosticConfiguration=127.0.0.1:9000%2csuspend%2cconnect +``` + +This will automatically set the `$DOTNET_DiagnosticPorts` environment +variable packaged inside the application. + +Implicitly enables the Mono diagnostic component, meaning that +`$(EnableDiagnostics)`/`$(AndroidEnableProfiler)` is set to `true`. + +## DiagnosticListenMode + +A value provided by `dotnet-dsrouter` such as `connect`, the listening +mode component of `$(DiagnosticConfiguration)` or `$DOTNET_DiagnosticPorts`. + +Implicitly enables the Mono diagnostic component, meaning that +`$(EnableDiagnostics)`/`$(AndroidEnableProfiler)` is set to `true`. + +Defaults to `connect`. + +## DiagnosticPort + +A value provided by `dotnet-dsrouter` such as `9000`, the port +component of `$(DiagnosticConfiguration)` or `$DOTNET_DiagnosticPorts`. + +Implicitly enables the Mono diagnostic component, meaning that +`$(EnableDiagnostics)`/`$(AndroidEnableProfiler)` is set to `true`. + +Defaults to `9000`. + +## DiagnosticSuspend + +A boolean value provided by `dotnet-dsrouter` such as `true/suspend` +or `false/nosuspend`, a component of `$(DiagnosticConfiguration)` +or `$DOTNET_DiagnosticPorts`. + +Implicitly enables the Mono diagnostic component, meaning that +`$(EnableDiagnostics)`/`$(AndroidEnableProfiler)` is set to `true`. + +Defaults to `false`. + ## EmbedAssembliesIntoApk A boolean property that @@ -1540,6 +1648,18 @@ MSBuild property also controls what will be embedded into the `.apk`, which can impact deployment and rebuild times. +## EnableDiagnostics + +Synonym for the [`$(AndroidEnableProfiler)`](#androidenableprofiler) +property. + +Required for using `dotnet-trace` or `dotnet-gcdump` in Android +applications. If set to `true`, it includes the Mono diagnostic +component in the application. This component is the +`libmono-component-diagnostics_tracing.so` native library. + +This property is `False` by default. + ## EnableLLVM A boolean property that determines whether @@ -1567,6 +1687,18 @@ When `True`, files will be used to control `proguard` execution. +## EventSourceSupport + +When set to `false`, disables .NET's [EventSource][eventsource] +support from trimmed Android applications. Disabling this feature +would prevent .NET diagnostic tools like `dotnet-counters` from +functioning, but at the benefit of reduced application size. + +Set to `false` by default in `Release` mode, unless +`$(EnableDiagnostics)` or `$(AndroidEnableProfiler)` are enabled. + +[eventsource]: /dotnet/core/diagnostics/eventsource + ## GenerateApplicationManifest Enables or disables the following MSBuild properties that emit values @@ -1645,6 +1777,28 @@ The default value is False. This MSBuild property is obsolete and is no longer supported. +## MetricsSupport + +When set to `false`, disables .NET's [Metrics][dotnetmetrics] support +from trimmed Android applications. Disabling this feature would +prevent APIs such as `System.Diagnostics.Metrics` from functioning, +but at the benefit of reduced application size. + +Set to `false` by default in `Release` mode, unless +`$(EnableDiagnostics)` or `$(AndroidEnableProfiler)` are enabled. + +[dotnetmetrics]: /dotnet/core/diagnostics/metrics + +## MonoAndroidAssetPrefix + +Specifies a *path prefix* +that is removed from the start of filenames with a Build action of +`AndroidAsset`. This is to allow changing where resources are +located. + +The default value is `Assets`. Change this to `assets` for the +Java project structure. + ## MonoAndroidResourcePrefix Specifies a *path prefix* @@ -1657,6 +1811,9 @@ Java project structure. ## MonoSymbolArchive +> [!NOTE] +> This was a legacy MSBuild property from Xamarin.Android. Not available in .NET 6+. + A boolean property that controls whether `.mSYM` artifacts are created for later use with `mono-symbolicate`, to extract “real” filename and line @@ -1682,3 +1839,21 @@ This MSBuild property replaces the Xamarin.Android. This is the same property used for [Blazor WASM][blazor]. [blazor]: /aspnet/core/blazor/host-and-deploy/webassembly/#ahead-of-time-aot-compilation + +## WaitForExit + +A boolean property that controls the behavior of `dotnet run` when launching +Android applications. + +When `$(WaitForExit)` is not `false` (the default), `dotnet run` will: + +* Launch the Android application +* Stream `logcat` output filtered to the application's process +* Wait for the application to exit or for the user to press Ctrl+C +* Force-stop the application when Ctrl+C is pressed + +When `$(WaitForExit)` is `false`, `dotnet run` will simply launch the +application using `adb shell am start` and return immediately without +waiting for the application to exit or streaming any output. + +Introduced in .NET 11. diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index b611efe..bd43e2d 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -36,6 +36,36 @@ Added in Xamarin.Android 10.2. Removes all files generated by the build process. +## ComputeAvailableDevices + +Queries and returns a list of available Android devices and emulators that can be used with `dotnet run`. + +This target is called automatically by the .NET SDK's `dotnet run` command to support device selection via the `--device` option. It returns an `@(Devices)` item group where each device has the following metadata: + +- **Description**: A human-friendly name (e.g., "Pixel 7 - API 35" for emulators, "Pixel 6 Pro" for physical devices) +- **Type**: Either "Device" or "Emulator" +- **Status**: Device status - "Online", "Offline", "Unauthorized", or "NoPermissions" +- **Model**: The device model identifier (optional) +- **Product**: The product name (optional) +- **Device**: The device name (optional) +- **TransportId**: The adb transport ID (optional) + +For example, to list all available devices: + +```shell +dotnet build -t:ComputeAvailableDevices +``` + +This target is part of the [.NET SDK device selection specification](https://github.com/dotnet/sdk/blob/2b9fc02a265c735f2132e4e3626e94962e48bdf5/documentation/specs/dotnet-run-for-maui.md) and enables commands like: + +```shell +dotnet run --device +``` + +When a device is selected via the `$(Device)` property, the [`$(AdbTarget)`](build-properties.md#adbtarget) property is automatically set to target that specific device for all adb operations. + +Added in .NET 11. + ## FinishAotProfiling Must be called *after* the [BuildAndStartAotProfiling](#buildandstartaotprofiling) diff --git a/docs/android/getting-started/installation/dependencies.md b/docs/android/getting-started/installation/dependencies.md index ce9e169..3008d4b 100644 --- a/docs/android/getting-started/installation/dependencies.md +++ b/docs/android/getting-started/installation/dependencies.md @@ -1,7 +1,7 @@ --- title: "Install .NET for Android dependencies" description: "Learn how to install .NET for Android dependencies so you can create native Android applications." -ms.date: 11/01/2023 +ms.date: 03/06/2026 --- # Install .NET for Android dependencies @@ -49,7 +49,12 @@ Here are all the arguments which the target will use when installing the depende In order to build .NET for Android applications or libraries you need to have a version of the Java Development Kit installed. We recommend you use the Microsoft Open JDK, this has been tested against our .NET for Android builds: - 1. Download [Microsoft OpenJDK 11](/java/openjdk/download#openjdk-11). + 1. Download [Microsoft OpenJDK 21](/java/openjdk/download#openjdk-21). + + 2. Depending on your platform run the appropriate installer. + + 3. It is also good practice to set the `JAVA_HOME` environment variable. + This will allow you to use the JDK from the Command Prompt or Terminal. ## Install the Android SDK manually @@ -73,14 +78,15 @@ You might find it necessary to install the Android SDK manually: 6. Run the `sdkmanager` command to install the desired components. 7. Set the `$ANDROID_HOME` environment variable to your Android SDK path: -```powershell -$env:ANDROID_HOME = "C:\android-sdk" -``` + + ```powershell + $env:ANDROID_HOME = "C:\android-sdk" + ``` For example, to install the latest platform and platform tools, use: ```console -sdkmanager "platforms;android-34" "platform-tools" "build-tools;34.0.0" "emulator" "system-images;android-34;default;x86_64" "cmdline-tools;11.0" --sdk_root=c:\android-sdk +sdkmanager "platforms;android-34" "platform-tools" "build-tools;34.0.0" "emulator" "system-images;android-34;default;x86_64" "cmdline-tools;latest" --sdk_root=c:\android-sdk ``` Note that double-quotes should be used liberally to enclose the semicolon `;`, which is part of the component names. @@ -107,9 +113,3 @@ The following component types are useful to know: It is also good practice to set the `ANDROID_HOME` environment variable, as this allows you to use certain tooling from the command line. - - 2. Depending on your platform run the appropriate installer. - - 3. It is also good practice to set the `JAVA_HOME` environment variable. - This will allow you to use the JDK from the Command Prompt or Terminal. - diff --git a/docs/android/index.yml b/docs/android/index.yml index 869bde9..9f7987f 100644 --- a/docs/android/index.yml +++ b/docs/android/index.yml @@ -9,9 +9,11 @@ brand: dotnet metadata: title: .NET for Android description: The .NET for Android guide has everything you need to learn .NET on the Android platform. + ms.service: dotnet-mobile + ms.subservice: dotnet-android ms.topic: hub-page - author: jonpryor - ms.author: jopryo + author: jonathanpeppers + ms.author: jopepper ms.date: 04/18/2024 # highlightedContent section (Optional; Remove if not applicable.) diff --git a/docs/android/messages/apt2000.md b/docs/android/messages/apt2000.md new file mode 100644 index 0000000..c09e946 --- /dev/null +++ b/docs/android/messages/apt2000.md @@ -0,0 +1,32 @@ +--- +title: .NET for Android error/warning APT2000 +description: APT2000 error/warning code +ms.date: 04/11/2024 +f1_keywords: + - "APT2000" +--- + +# .NET for Android error/warning APT2000 + +## Example APT2000 error messages + +- `error APT2000 Cannot find the specified file` +- `error APT2000: Resource entry resource_name is already defined.` +- `error APT2000: No resource found that matches the given name (at 'resource_name' with value '@string/foo').` +- `error APT2000: invalid resource directory name: "obj\Debug\dir with spaces" "dir with spaces".` +- `warning APT2000: warn: removing resource com.companyname.example:drawable/foo without required default value.` + +## Issue + +This message indicates that `aapt2` (Android Asset Packaging Tool) reported an error or warning. `aapt2` is part of the Android SDK and is used internally by .NET for Android to process and compile resources into binary assets. + +Errors reported by `aapt2` are outside of .NET for Android's control, so a general error code of APT2000 is used to report the exact message coming from `aapt2`. + +## Solution + +Reading the actual error message and looking at the diagnostic log output can +usually give you enough information to solve the issue yourself. It can be +helpful to do an internet search for the error message. Looking at solutions +which are for Java based Android applications can also help. + +To learn more about `aapt2` and Android resources, see the [Android documentation](https://developer.android.com/guide/topics/resources/accessing-resources.html). diff --git a/docs/android/messages/index.md b/docs/android/messages/index.md index 328f4d0..0122292 100644 --- a/docs/android/messages/index.md +++ b/docs/android/messages/index.md @@ -30,6 +30,8 @@ ms.date: 04/11/2024 + APT0002: Invalid file name: It must contain only \[^a-zA-Z0-9_.-\]+. + APT0003: Invalid file name: It must contain only \[^a-zA-Z0-9_.\]+. + APT0004: Invalid file name: It must start with either A-Z or a-z or an underscore. ++ APT0005: Invalid file name: filenames cannot use java reserved words. ++ [APT2000](apt2000.md): Generic `aapt2` error/warning. + [APT2264](apt2264.md): The system cannot find the file specified. (2). + [APT2265](apt2265.md): The system cannot find the file specified. (2). @@ -144,13 +146,16 @@ or 'Help->Report a Problem' in Visual Studio for Mac. + [XA1036](xa1036.md): AndroidManifest.xml //uses-sdk/@android:minSdkVersion '29' does not match the $(SupportedOSPlatformVersion) value '21' in the project file (if there is no $(SupportedOSPlatformVersion) value in the project file, then a default value has been assumed). Either change the value in the AndroidManifest.xml to match the $(SupportedOSPlatformVersion) value, or remove the value in the AndroidManifest.xml (and add a $(SupportedOSPlatformVersion) value to the project file if it doesn't already exist). + [XA1037](xa1037.md): The '{0}' MSBuild property is deprecated and will be removed in .NET {1}. See https://aka.ms/net-android-deprecations for more details. -+ [XA1038](xa1038.md): The '{0}' MSBuild property has an invalid value. Value values are {1}. ++ [XA1038](xa1038.md): The '{0}' MSBuild property has an invalid value. Valid values are {1}. ++ [XA1039](xa1039.md): The Android Support libraries are not supported in .NET 9 and later, please migrate to AndroidX. See https://aka.ms/xamarin/androidx for more details. ++ [XA1040](xa1040.md): The NativeAOT runtime on Android is an experimental feature and not yet suitable for production use. File issues at: https://github.com/dotnet/android/issues ++ [XA1041](xa1041.md): The MSBuild property 'MonoAndroidAssetPrefix' has an invalid value of 'c:\Foo\Assets'. The value is expected to be a directory path representing the relative location of your Assets or Resources. ## XA2xxx: Linker + [XA2000](xa2000.md): Use of AppDomain.CreateDomain() detected in assembly: {assembly}. .NET 6 will only support a single AppDomain, so this API will no longer be available in .NET for Android once .NET 6 is released. + [XA2001](xa2001.md): Source file '{filename}' could not be found. -+ [XA2002](xa2002.md): Can not resolve reference: \`{missing}\`, referenced by {assembly}. Perhaps it doesn't exist in the Mono for Android profile? ++ [XA2002](xa2002.md): Can not resolve reference: \`{missing}\`, referenced by {assembly}. Perhaps it doesn't exist in the .NET for Android profile? + XA2006: Could not resolve reference to '{member}' (defined in assembly '{assembly}') with scope '{scope}'. When the scope is different from the defining assembly, it usually means that the type is forwarded. + XA2007: Exception while loading assemblies: {exception} + XA2008: In referenced assembly {assembly}, Java.Interop.DoNotPackageAttribute requires non-null file name. @@ -159,7 +164,6 @@ Either change the value in the AndroidManifest.xml to match the $(SupportedOSPla + XA3001: Could not AOT the assembly: {assembly} + XA3002: Invalid AOT mode: {mode} -+ XA3003: Could not strip IL of assembly: {assembly} + XA3004: Android NDK r10d is buggy and provides an incompatible x86_64 libm.so. + XA3005: The detected Android NDK version is incompatible with the targeted LLVM configuration. + XA3006: Could not compile native assembly file: {file} @@ -262,30 +266,23 @@ and `NNN` is a 3 digit number indicating the type of the unhandled `Exception`. * `BBA` - `BuildBaseAppBundle` * `BGN` - `BindingsGenerator` * `BLD` - `BuildApk` -* `CAL` - `CreateAdditionalLibraryResourceCache` -* `CAR` - `CalculateAdditionalResourceCacheDirectories` * `CCR` - `CopyAndConvertResources` * `CCV` - `ConvertCustomView` * `CDF` - `ConvertDebuggingFiles` * `CDJ` - `CheckDuplicateJavaLibraries` * `CFI` - `CheckForInvalidResourceFileNames` -* `CFR` - `CheckForRemovedItems` * `CGJ` - `CopyGeneratedJavaResourceClasses` * `CGS` - `CheckGoogleSdkRequirements` * `CIC` - `CopyIfChanged` -* `CIL` - `CilStrip` -* `CLA` - `CollectLibraryAssets` * `CLC` - `CalculateLayoutCodeBehind` * `CLP` - `ClassParse` * `CLR` - `CreateLibraryResourceArchive` * `CMD` - `CreateMultiDexMainDexClassList` * `CML` - `CreateManagedLibraryResourceArchive` -* `CMM` - `CreateMsymManifest` * `CNA` - `CompileNativeAssembly` * `CNE` - `CollectNonEmptyDirectories` * `CNL` - `CreateNativeLibraryArchive` * `CPD` - `CalculateProjectDependencies` -* `CPF` - `CollectPdbFiles` * `CPI` - `CheckProjectItems` * `CPR` - `CopyResource` * `CPT` - `ComputeHash` @@ -306,7 +303,6 @@ and `NNN` is a 3 digit number indicating the type of the unhandled `Exception`. * `GAR` - `GetAdditionalResourcesFromAssemblies` * `GAS` - `GetAppSettingsDirectory` * `GCB` - `GenerateCodeBehindForLayout` -* `GCJ` - `GetConvertedJavaLibraries` * `GEP` - `GetExtraPackages` * `GFT` - `GetFilesThatExist` * `GIL` - `GetImportedLibraries` @@ -330,7 +326,6 @@ and `NNN` is a 3 digit number indicating the type of the unhandled `Exception`. * `LNS` - `LinkAssembliesNoShrink` * `LNT` - `Lint` * `LWF` - `LogWarningsForFiles` -* `MBN` - `MakeBundleNativeCodeExternal` * `MDC` - `MDoc` * `PAI` - `PrepareAbiItems` * `PAW` - `ParseAndroidWearProjectAndManifest` diff --git a/docs/android/messages/xa0004.md b/docs/android/messages/xa0004.md index e6e5cd8..884344c 100644 --- a/docs/android/messages/xa0004.md +++ b/docs/android/messages/xa0004.md @@ -11,7 +11,7 @@ f1_keywords: ## Issue This error means the value for `android:versionCode` in the -`AndroidManifest.xml` file is and integer but is not +`AndroidManifest.xml` file is an integer but is not within the value range of 0 to 2100000000. Google requires that the value be an integer within the diff --git a/docs/android/messages/xa0110.md b/docs/android/messages/xa0110.md index a33d448..07dd09b 100644 --- a/docs/android/messages/xa0110.md +++ b/docs/android/messages/xa0110.md @@ -8,6 +8,9 @@ f1_keywords: # .NET for Android warning XA0110 +> [!NOTE] +> This warning only applied to Xamarin.Android. In .NET for Android, `aapt2` is always used and the `$(AndroidUseAapt2)` property has no effect. + ## Issue This warning is raised because your project is set up to use `$(AndroidExplicitCrunch)`. diff --git a/docs/android/messages/xa0132.md b/docs/android/messages/xa0132.md index dba8ed1..8db74cd 100644 --- a/docs/android/messages/xa0132.md +++ b/docs/android/messages/xa0132.md @@ -18,4 +18,4 @@ You should be able to uninstall the app via the Settings app on the device. This error only seems to happen when the same app is installed under multiple user account. Check that you do not have the app installed under a Guest user or a secondary account on -you device. +your device. diff --git a/docs/android/messages/xa0133.md b/docs/android/messages/xa0133.md index c572827..2a1c43d 100644 --- a/docs/android/messages/xa0133.md +++ b/docs/android/messages/xa0133.md @@ -15,4 +15,4 @@ The 'run-as' tool required by the Fast Deployment system has been disabled on th ## Solution Unfortunately the manufacturer of the device has explicitly disabled the tool we need for Fast Deployment. -The only option currently is to disable Fast Deployment from the IDE or by setting the the 'EmbedAssembliesIntoApk' MSBuild property to 'true' in the csproj. +The only option currently is to disable Fast Deployment from the IDE or by setting the 'EmbedAssembliesIntoApk' MSBuild property to 'true' in the csproj. diff --git a/docs/android/messages/xa0141.md b/docs/android/messages/xa0141.md index eabb8fb..0173798 100644 --- a/docs/android/messages/xa0141.md +++ b/docs/android/messages/xa0141.md @@ -1,7 +1,7 @@ --- title: .NET for Android warning XA0141 description: XA0141 warning code -ms.date: 07/22/2024 +ms.date: 01/08/2025 f1_keywords: - "XA0141" --- @@ -10,8 +10,22 @@ f1_keywords: ## Issue -NuGet package '{0}' version '{1}' contains a shared library '{2}' which is not correctly aligned. See https://developer.android.com/guide/practices/page-sizes for more details +Future versions of Android on arm64 will require that native libraries use 16 KB page sizes. +This requires that the mentioned native libraries be recompiled, and all apps using those +native libraries be rebuilt to contain the fixed versions of the native libraries. + +See the Android SDK [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes) +documentation for more information. ## Solution -The indicated native shared library must be recompiled and relinked with the 16k alignment, as per URL indicated in the message. +The indicated native shared library must be recompiled and relinked with the 16k alignment, as per +the Android SDK [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes) +documentation. + +## Example messages + +> warning XA0141: Android 16 will require 16 KB page sizes, Shared library 'libface_detector_v2_jni.so' does not have a 16 KB page size. +> Please inform the authors of the NuGet package 'Xamarin.GooglePlayServices.Vision.Face.Contour.Internal' version '116.1.0.19' +> which contains 'lib/net8.0-android34.0/play-services-vision-face-contour-internal.aar'. +> See https://developer.android.com/guide/practices/page-sizes for more details. diff --git a/docs/android/messages/xa1026.md b/docs/android/messages/xa1026.md index eaaf285..2ac4631 100644 --- a/docs/android/messages/xa1026.md +++ b/docs/android/messages/xa1026.md @@ -8,6 +8,9 @@ f1_keywords: # .NET for Android error/warning XA1026 +> [!NOTE] +> This message only applied to Xamarin.Android. In .NET for Android, `aapt2` is always used and the `$(AndroidUseAapt2)` property has no effect. + ## Example messages ``` diff --git a/docs/android/messages/xa1040.md b/docs/android/messages/xa1040.md new file mode 100644 index 0000000..04369e8 --- /dev/null +++ b/docs/android/messages/xa1040.md @@ -0,0 +1,32 @@ +--- +title: .NET for Android warning XA1040 +description: XA1040 warning code +ms.date: 02/24/2025 +f1_keywords: + - "XA1040" +--- + +# .NET for Android warning XA1040 + +## Example messages + +``` +warning XA1040: The NativeAOT runtime on Android is an experimental feature and not yet suitable for production use. File issues at: https://github.com/dotnet/android/issues +``` + +## Issue + +NativeAOT is an experimental runtime option for .NET for Android. When you enable NativeAOT via `$(PublishAot)=true`, this warning is emitted to indicate that NativeAOT is not yet suitable for production use. + +The supported runtimes are: + +* CoreCLR (default) +* MonoVM, used via `$(UseMonoRuntime)=true` + +## Solution + +To silence this warning, you can either: + +* Use a supported runtime by removing `$(PublishAot)=true` from your project file. + +* Set `$(EnablePreviewFeatures)` to `true` in your project file to acknowledge the experimental nature of NativeAOT. diff --git a/docs/android/messages/xa1041.md b/docs/android/messages/xa1041.md new file mode 100644 index 0000000..ebb07f1 --- /dev/null +++ b/docs/android/messages/xa1041.md @@ -0,0 +1,46 @@ +--- +title: .NET for Android error XA1041 +description: XA1041 error code +ms.date: 03/31/2025 +f1_keywords: + - "XA1041" +--- + +# .NET for Android error XA1041 + +## Example messages + +```dotnetcli +error XA1041: The MSBuild property 'MonoAndroidAssetPrefix' has an invalid value of 'c:\Foo\Assets'. The value is expected to be a directory path representing the relative location of your Assets or Resources. +error XA1041: The MSBuild property 'MonoAndroidResourcePrefix' has an invalid value of 'c:\Foo\Resources'. The value is expected to be a directory path representing the relative location of your Assets or Resources. +``` + +## Issue + +The problem is that both `MonoAndroidAssetPrefix` and `MonoAndroidResourcePrefix` are expected to be +a relative directory path. This information is used to "strip" the root directory +information off the asset or resource when we package the app. +The error is raised because the property contains a full path. + +For example, consider the following structure: + +```dotnetcli +Foo.csproj +MyAssets/ + Foo.txt + Subfolder/ + Bar.txt +MainActivity.cs +``` + +In the final `.apk` we expect the files `Foo.txt` and `Bar.txt` to be placed in the `assets` folder. In order to do this correctly, the build system needs to know +the name of the folder in which the assets are located. By default this is "Assets", but other folder names are also supported. + +In the example above we would expect the user to set `MonoAndroidAssetPrefix` to a value of "MyAssets". This would ensure that the "MyAssets" part of the path +to "Foo.txt" etc is removed during packaging. If `MonoAndroidAssetPrefix` is set to +`/Users/xxx/Foo/MyAssets` or `c:\Users\xxx\Foo\MyAssets` you would see this error message. + +## Solution + +The fix for this is to not use a full path for the values of `MonoAndroidAssetPrefix` or `MonoAndroidResourcePrefix`. They should be a relative +directory path which matches the folder path in which your assets are stored. diff --git a/docs/android/messages/xa8000.md b/docs/android/messages/xa8000.md index ab10be5..667dc9a 100644 --- a/docs/android/messages/xa8000.md +++ b/docs/android/messages/xa8000.md @@ -17,9 +17,9 @@ Could not find Android Resource '@anim/enterfromright'. Please update @(AndroidR ## Solution -When trying to upgrade older nuget package references to use the +When trying to upgrade older NuGet package references to use the more recent Resource Designer Assembly, the system might encounter fields which cannot be upgraded because the resource is missing from either the dependency or the app. -To fix this issue the missing `AndroidResource` needs to be added to the application. Or the Nuget should be upgraded to use .net 8 or later. +To fix this issue, either add the missing `AndroidResource` to the application, or update the relevant NuGet package to a version that supports .NET 8 or later and ensure the project's Target Framework is set to .NET 8 or later. diff --git a/docs/docfx.json b/docs/docfx.json index 33695d0..daafcbd 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -60,11 +60,11 @@ }, "fileMetadata": { "author": { - "android/**/*.md": "jonpryor", + "android/**/*.md": "jonathanpeppers", "ios/**/*.md": "rolfbjarne" }, "ms.author": { - "android/**/*.md": "jopryo", + "android/**/*.md": "jopepper", "ios/**/*.md": "rokvin" }, "ms.subservice": {