diff --git a/Documentation/docs-mobile/TOC.yml b/Documentation/docs-mobile/TOC.yml new file mode 100644 index 00000000000..ef5e9432fa8 --- /dev/null +++ b/Documentation/docs-mobile/TOC.yml @@ -0,0 +1,354 @@ +- name: .NET for Android + items: + - name: Getting Started + items: + - name: Installation + items: + - name: Overview + href: getting-started/installation/index.md + - name: Install .NET for Android + href: getting-started/installation/net-android.md + - name: Install dependencies + href: getting-started/installation/dependencies.md + - name: Building apps + items: + - name: Build process + href: building-apps/build-process.md + - name: Build targets + href: building-apps/build-targets.md + - name: Build properties + href: building-apps/build-properties.md + - name: Build items + href: building-apps/build-items.md + - name: Features + items: + - name: Layout code behind + href: features/layout-code-behind/index.md + - name: Maven + items: + - name: "@(AndroidMavenLibrary) build item" + href: features/maven/android-maven-library.md + - name: Resolving Java ependencies + href: features/maven/resolving-java-dependencies.md + - name: Java dependency verification + href: features/maven/java-dependency-verification.md + - name: Message reference + items: + - name: Overview + href: messages/index.md + - name: "ADBxxxx: ADB tooling" + items: + - name: "ADBxxxx: ADB tooling" + href: "messages/index.md#adbxxxx-adb-tooling" + - name: ADB0000 + href: messages/adb0000.md + - name: ADB0010 + href: messages/adb0010.md + - name: ADB0020 + href: messages/adb0020.md + - name: ADB0030 + href: messages/adb0030.md + - name: ADB0040 + href: messages/adb0040.md + - name: ADB0050 + href: messages/adb0050.md + - name: ADB0060 + href: messages/adb0060.md + - name: "ANDXXxxxx: Generic Android tooling" + items: + - name: "ANDXXxxxx: Generic Android tooling" + href: "messages/index.md#andxxxxxx-generic-android-tooling" + - name: ANDAS0000 + href: messages/andas0000.md + - name: ANDJS0000 + href: messages/andjs0000.md + - name: ANDKT0000 + href: messages/andkt0000.md + - name: ANDZA0000 + href: messages/andza0000.md + - name: "APTxxxx: AAPT tooling" + items: + - name: "APTxxxx: AAPT tooling" + href: "messages/index.md#aptxxxx-aapt-tooling" + - name: APT0000 + href: messages/apt0000.md + - name: APT0001 + href: messages/apt0001.md + - name: APT2264 + href: messages/apt2264.md + - name: APT2265 + href: messages/apt2265.md + - name: "JAVAxxxx: Java tool" + items: + - name: "JAVAxxxx: Java tool" + href: "messages/index.md#javaxxxx-java-tool" + - name: JAVA0000 + href: messages/java0000.md + - name: "JAVACxxxx: Java compiler" + items: + - name: "JAVACxxxx: Java compiler" + href: "messages/index.md#javacxxxx-java-compiler" + - name: JAVAC0000 + href: messages/javac0000.md + - name: "XA0xxx: Environment issue or missing tooling" + items: + - name: "XA0xxx: Environment issue or missing tooling" + href: "messages/index.md#xa0xxx-environment-issue-or-missing-tooling" + - name: XA0000 + href: messages/xa0000.md + - name: XA0001 + href: messages/xa0001.md + - name: XA0002 + href: messages/xa0002.md + - name: XA0003 + href: messages/xa0003.md + - name: XA0004 + href: messages/xa0004.md + - name: XA0030 + href: messages/xa0030.md + - name: XA0031 + href: messages/xa0031.md + - name: XA0032 + href: messages/xa0032.md + - name: XA0033 + href: messages/xa0033.md + - name: XA0034 + href: messages/xa0034.md + - name: XA0035 + href: messages/xa0035.md + - name: XA0036 + href: messages/xa0036.md + - name: XA0101 + href: messages/xa0101.md + - name: XA0102 + href: messages/xa0102.md + - name: XA0103 + href: messages/xa0103.md + - name: XA0105 + href: messages/xa0105.md + - name: XA0107 + href: messages/xa0107.md + - name: XA0108 + href: messages/xa0108.md + - name: XA0109 + href: messages/xa0109.md + - name: XA0111 + href: messages/xa0111.md + - name: XA0112 + href: messages/xa0112.md + - name: XA0113 + href: messages/xa0113.md + - name: XA0115 + href: messages/xa0115.md + - name: XA0116 + href: messages/xa0116.md + - name: XA0117 + href: messages/xa0117.md + - name: XA0118 + href: messages/xa0118.md + - name: XA0119 + href: messages/xa0119.md + - name: XA0121 + href: messages/xa0121.md + - name: XA0122 + href: messages/xa0122.md + - name: XA0125 + href: messages/xa0125.md + - name: XA0126 + href: messages/xa0126.md + - name: XA0127 + href: messages/xa0127.md + - name: XA0128 + href: messages/xa0128.md + - name: XA0129 + href: messages/xa0129.md + - name: XA0130 + href: messages/xa0130.md + - name: XA0131 + href: messages/xa0131.md + - name: XA0132 + href: messages/xa0132.md + - name: XA0133 + href: messages/xa0133.md + - name: XA0134 + href: messages/xa0134.md + - name: XA0135 + href: messages/xa0135.md + - name: XA0136 + href: messages/xa0136.md + - name: XA0137 + href: messages/xa0137.md + - name: XA0138 + href: messages/xa0138.md + - name: XA0139 + href: messages/xa0139.md + - name: XA0140 + href: messages/xa0140.md + - name: "XA1xxx: Project related" + items: + - name: "XA1xxx: Project related" + href: "messages/index.md#xa1xxx-project-related" + - name: XA1000 + href: messages/xa1000.md + - name: XA1001 + href: messages/xa1001.md + - name: XA1002 + href: messages/xa1002.md + - name: XA1003 + href: messages/xa1003.md + - name: XA1004 + href: messages/xa1004.md + - name: XA1005 + href: messages/xa1005.md + - name: XA1006 + href: messages/xa1006.md + - name: XA1007 + href: messages/xa1007.md + - name: XA1008 + href: messages/xa1008.md + - name: XA1009 + href: messages/xa1009.md + - name: XA1010 + href: messages/xa1010.md + - name: XA1011 + href: messages/xa1011.md + - name: XA1023 + href: messages/xa1023.md + - name: XA1024 + href: messages/xa1024.md + - name: XA1025 + href: messages/xa1025.md + - name: XA1027 + href: messages/xa1027.md + - name: XA1028 + href: messages/xa1028.md + - name: XA1029 + href: messages/xa1029.md + - name: XA1031 + href: messages/xa1031.md + - name: XA1032 + href: messages/xa1032.md + - name: XA1033 + href: messages/xa1033.md + - name: XA1035 + href: messages/xa1035.md + - name: XA1036 + href: messages/xa1036.md + - name: XA1037 + href: messages/xa1037.md + - name: "XA2xxx: Linker" + items: + - name: "XA2xxx: Linker" + href: "messages/index.md#xa2xxx-linker" + - name: XA2000 + href: messages/xa2000.md + - name: XA2001 + href: messages/xa2001.md + - name: XA2002 + href: messages/xa2002.md + - name: "XA3xxx: Unmanaged code compilation" + href: "messages/index.md#xa3xxx-unmanaged-code-compilation" + - name: "XA4xxx: Code generation" + items: + - name: "XA4xxx: Code generation" + href: "messages/index.md#xa4xxx-code-generation" + - name: XA4214 + href: messages/xa4214.md + - name: XA4215 + href: messages/xa4215.md + - name: XA4216 + href: messages/xa4216.md + - name: XA4218 + href: messages/xa4218.md + - name: XA4231 + href: messages/xa4231.md + - name: XA4232 + href: messages/xa4232.md + - name: XA4234 + href: messages/xa4234.md + - name: XA4235 + href: messages/xa4235.md + - name: XA4236 + href: messages/xa4236.md + - name: XA4237 + href: messages/xa4237.md + - name: XA4239 + href: messages/xa4239.md + - name: XA4241 + href: messages/xa4241.md + - name: XA4242 + href: messages/xa4242.md + - name: XA4243 + href: messages/xa4243.md + - name: XA4244 + href: messages/xa4244.md + - name: XA4245 + href: messages/xa4245.md + - name: XA4246 + href: messages/xa4246.md + - name: XA4247 + href: messages/xa4247.md + - name: XA4248 + href: messages/xa4248.md + - name: XA4301 + href: messages/xa4301.md + - name: XA4302 + href: messages/xa4302.md + - name: XA4303 + href: messages/xa4303.md + - name: XA4304 + href: messages/xa4304.md + - name: XA4305 + href: messages/xa4305.md + - name: XA4306 + href: messages/xa4306.md + - name: XA4307 + href: messages/xa4307.md + - name: XA4308 + href: messages/xa4308.md + - name: XA4309 + href: messages/xa4309.md + - name: XA4310 + href: messages/xa4310.md + - name: XA4312 + href: messages/xa4312.md + - name: XA4313 + href: messages/xa4313.md + - name: XA4314 + href: messages/xa4314.md + - name: "XA5xxx: GCC and toolchain" + items: + - name: "XA5xxx: GCC and toolchain" + href: "messages/index.md#xa5xxx-gcc-and-toolchain" + - name: XA5205 + href: messages/xa5205.md + - name: XA5207 + href: messages/xa5207.md + - name: XA5300 + href: messages/xa5300.md + - name: XA5301 + href: messages/xa5301.md + - name: XA5302 + href: messages/xa5302.md + - name: "XA6xxx: Internal tools" + href: "messages/index.md#xa6xxx-internal-tools" + - name: "XAccc7xxx: Unhandled MSBuild exceptions" + href: "messages/index.md#xaccc7xxx-unhandled-msbuild-exceptions" + - name: "XA8xxx: Linker step errors" + items: + - name: "XA8xxx: Linker step errors" + href: "messages/index.md#xa8xxx-linker-step-errors" + - name: XA8000/IL8000 + href: messages/xa8000.md + - name: Resources + items: + - name: .NET 8 Release Notes + items: + - name: .NET 8 34.0.95 + href: https://github.com/xamarin/xamarin-android/releases/tag/34.0.95 + - name: .NET 8 34.0.85 + href: https://github.com/xamarin/xamarin-android/releases/tag/34.0.85 + - name: .NET 8 34.0.79 + href: https://github.com/xamarin/xamarin-android/releases/tag/34.0.85 + - name: .NET 8 34.0.52 + href: https://github.com/xamarin/xamarin-android/releases/tag/34.0.52 diff --git a/Documentation/guides/building-apps/build-items.md b/Documentation/docs-mobile/building-apps/build-items.md similarity index 74% rename from Documentation/guides/building-apps/build-items.md rename to Documentation/docs-mobile/building-apps/build-items.md index e6d6d954d75..64034a575f5 100644 --- a/Documentation/guides/building-apps/build-items.md +++ b/Documentation/docs-mobile/building-apps/build-items.md @@ -1,22 +1,18 @@ --- -title: "Build Items" -description: "This document will list all supported item groups in the Xamarin.Android build process." -ms.prod: xamarin -ms.assetid: 5EBEE1A5-3879-45DD-B1DE-5CD4327C2656 -ms.technology: xamarin-android -author: jonpryor -ms.author: jopryo -ms.date: 07/26/2022 +title: .NET for Android Build Items +description: .NET for Android Build Items +ms.date: 04/11/2024 --- # Build Items -Build items control how a Xamarin.Android application +Build items control how a .NET for Android application or library project is built. ## AndroidAdditionalJavaManifest -`` is used in conjunction with [Java Dependency Resolution](../JavaDependencyVerification.md). +`` is used in conjunction with +[Java Dependency Resolution](../features/maven/java-dependency-verification.md). It is used to specify additional POM files that will be needed to verify dependencies. These are often parent or imported POM files referenced by a Java library's POM file. @@ -33,7 +29,7 @@ The following MSBuild metadata are required: file in the form `{GroupId}:{ArtifactId}`. - `%(JavaVersion)`: The version of the Java library matching the specified POM file. -See the [Java Dependency Resolution documentation](../JavaDependencyVerification.md) +See the [Java Dependency Resolution documentation](../features/maven/java-dependency-verification.md) for more details. This build action was introduced in .NET 9. @@ -43,7 +39,7 @@ This build action was introduced in .NET 9. Supports [Android Assets](https://developer.android.com/guide/topics/resources/providing-resources#OriginalFiles), files that would be included in the `assets` folder in a Java Android project. -Starting with .NET 9 the `@(AndroidAsset)` build action also supports additional metadata for generating [Asset Packs](https://developer.android.com/guide/playcore/asset-delivery). The `%(AndroidAsset.AssetPack)` metadata can be used to automatically generate an asset pack of that name. This feature is only supported when the [`$(AndroidPackageFormat)`](#androidpackageformat) is set to `.aab`. The following example will place `movie2.mp4` and `movie3.mp4` in separate asset packs. +Starting with .NET 9 the `@(AndroidAsset)` build action also supports additional metadata for generating [Asset Packs](https://developer.android.com/guide/playcore/asset-delivery). The `%(AndroidAsset.AssetPack)` metadata can be used to automatically generate an asset pack of that name. This feature is only supported when the [`$(AndroidPackageFormat)`](build-properties.md#androidpackageformat) is set to `.aab`. The following example will place `movie2.mp4` and `movie3.mp4` in separate asset packs. ```xml @@ -72,7 +68,7 @@ assets into the asset pack. In this example, `movie.mp4` and `some.png` will end up in the `base` aab file, while all the other assets will end up in the `assets1` asset pack. -The additional metadata is only supported on .NET Android 9 and above. +The additional metadata is only supported on .NET for Android 9 and above. ## AndroidAarLibrary @@ -111,14 +107,14 @@ to be stored. See [bundletool](https://developer.android.com/studio/build/building-cmdline#build_your_app_bundle_using_bundletool) documentation for more details. -Added in Xamarin.Android 12.3. - ## AndroidBoundLayout -Indicates that the layout file is to have code-behind generated for it in case when -the `AndroidGenerateLayoutBindings` property is set to `false`. In all other aspects -it is identical to `AndroidResource` described above. This action can be used **only** -with layout files: +Indicates that the layout file is to have [code-behind generated](../features/layout-code-behind/index.md) +for it in case when the [`$(AndroidGenerateLayoutBindings)`](build-properties.md#androidgeneratelayoutbindings) +property is set to `false`. In all other aspects +it is identical to [`AndroidResource`](#androidresource). + +This action can be used **only** with layout files: ```xml @@ -127,7 +123,7 @@ with layout files: ## AndroidEnvironment Files with a Build action of `AndroidEnvironment` are used -to [initialize environment variables and system properties during process startup](~/android/deploy-test/environment.md). +to [initialize environment variables and system properties during process startup](/xamarin/android/deploy-test/environment). The `AndroidEnvironment` Build action may be applied to multiple files, and they will be evaluated in no particular order (so don't specify the same environment variable or system property in multiple @@ -141,7 +137,7 @@ package. ## AndroidIgnoredJavaDependency -`` is used in conjunction with [Java Dependency Resolution](../JavaDependencyVerification.md). +`` is used in conjunction with [Java Dependency Resolution](../features/maven/java-dependency-verification.md). It is used to specify a Java dependency that should be ignored. This can be used if a dependency will be fulfilled in a way that Java dependency resolution @@ -158,7 +154,7 @@ The following MSBuild metadata are required: - `%(Version)`: The version of the Java library matching the specified `%(Include)`. -See the [Java Dependency Resolution documentation](../JavaDependencyVerification.md) +See the [Java Dependency Resolution documentation](../features/maven/java-dependency-verification.md) for more details. This build action was introduced in .NET 9. @@ -190,7 +186,7 @@ Any project can specify: ``` The result of the above code snippet has a different effect for each -Xamarin.Android project type: +.NET for Android project type: * Application and class library projects: * `foo.jar` maps to [**AndroidJavaLibrary**](#androidjavalibrary). @@ -203,12 +199,10 @@ Xamarin.Android project type: This simplification means you can use **AndroidLibrary** everywhere. -This build action was added in Xamarin.Android 11.2. - ## AndroidLintConfig The Build action 'AndroidLintConfig' should be used in conjunction with the -[`$(AndroidLintEnabled)`](~/android/deploy-test/building-apps/build-properties.md#androidlintenabled) +[`$(AndroidLintEnabled)`](/xamarin/android/deploy-test/building-apps/build-properties.md#androidlintenabled) property. Files with this build action will be merged together and passed to the android `lint` tooling. They should be XML files containing information on tests to enable and disable. @@ -230,7 +224,7 @@ have a specific permission only while debugging, you can use the overlay to inject that permission when debugging. For example, given the following overlay file contents: -``` +```xml @@ -238,26 +232,22 @@ overlay file contents: You can use the following to add a manifest overlay for a debug build: -``` +```xml ``` -This build action was introduced in Xamarin.Android 11.2. - ## AndroidInstallModules Specifies the modules that get installed by **bundletool** command when installing app bundles. -This build action was introduced in Xamarin.Android 11.3. - ## AndroidMavenLibrary `` allows a Maven artifact to be specified which will -automatically be downloaded and added to a .NET Android binding project. -This can be useful to simplify maintenance of .NET Android bindings for artifacts +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 @@ -273,18 +263,18 @@ The following MSBuild metadata are supported: - `%(Repository)`: Optional Maven repository to use. Supported values are `Central` (default), `Google`, or an `https` URL to a Maven repository. -The `` item is translated to an -[``](https://github.com/xamarin/xamarin-android/blob/main/Documentation/guides/building-apps/build-items.md#androidlibrary) -item, so any metadata supported by `` like `Bind` or `Pack` are also supported. +The `` item is translated to +[`AndroidLibrary`](#androidlibrary), so any metadata supported by +`` like `%(Bind)` or `%(Pack)` are also supported. -See the [AndroidMavenLibrary documentation](../AndroidMavenLibrary.md) +See the [AndroidMavenLibrary documentation](../features/maven/android-maven-library.md) for more details. This build action was introduced in .NET 9. ## AndroidNativeLibrary -[Native libraries](~/android/platform/native-libraries.md) +[Native libraries](/xamarin/android/platform/native-libraries) are added to the build by setting their Build action to `AndroidNativeLibrary`. @@ -317,7 +307,7 @@ used to specify the ABI that the library targets. Thus, if you add A set of file glob compatible items which will allow for items to be excluded from the final package. The default values are as follows -``` +```xml @@ -325,12 +315,13 @@ excluded from the final package. The default values are as follows ``` Items can use file blob characters for wildcards such as `*` and `?`. -However these Items MUST use URL encoding or '$([MSBuild]::Escape(''))'. +However these Items MUST be URL encoded or use +[`$([MSBuild]::Escape(''))`](/visualstudio/msbuild/how-to-escape-special-characters-in-msbuild). This is so MSBuild does not try to interpret them as actual file wildcards. For example -``` +```xml @@ -343,20 +334,20 @@ appropriate file globs. If the default file glob is too restrictive you can remove it by adding the following to your csproj -``` +```xml ``` -Added in Xamarin.Android 13.1 and .NET 7. +Added in .NET 7. ## AndroidPackagingOptionsInclude A set of file glob compatible items which will allow for items to be included from the final package. The default values are as follows -``` +```xml @@ -367,7 +358,7 @@ However these Items MUST use URL encoding or '$([MSBuild]::Escape(''))'. This is so MSBuild does not try to interpret them as actual file wildcards. For example -``` +```xml @@ -398,10 +389,10 @@ conditionally include different files in different configurations. For example: ```xml - + - + @@ -424,38 +415,25 @@ distinct resource names. ``` -## AndroidResourceAnalysisConfig - -The Build action `AndroidResourceAnalysisConfig` marks a file as a -severity level configuration file for the Xamarin Android Designer -layout diagnostics tool. This is currently only used in the layout -editor and not for build messages. - -See the [Android Resource Analysis -documentation](../../user-interface/android-designer/diagnostics.md) for more -details. - -Added in Xamarin.Android 10.2. - ## Content The normal `Content` Build action is not supported (as we haven't figured out how to support it without a possibly costly first-run step). -Starting in Xamarin.Android 5.1, attempting to use the `@(Content)` -Build action will result in a `XA0101` warning. +Attempting to use the `@(Content)` Build action will result in a +[XA0101](../messages/xa0101.md) warning. ## EmbeddedJar -In a Xamarin.Android binding project, the **EmbeddedJar** build action +In a .NET for Android binding project, the **EmbeddedJar** build action binds the Java/Kotlin library and embeds the `.jar` file into the -library. When a Xamarin.Android application project consumes the +library. When a .NET for Android application project consumes the library, it will have access to the Java/Kotlin APIs from C# as well as include the Java/Kotlin code in the final Android application. -Since Xamarin.Android 11.2, you can use the -[**AndroidLibrary**](#androidlibrary) build action as an alternative +You should instead use the +[AndroidLibrary](#androidlibrary) build action as an alternative such as: ```xml @@ -468,25 +446,25 @@ such as: ## EmbeddedNativeLibrary -In a Xamarin.Android class library or Java binding project, the +In a .NET for Android class library or Java binding project, the **EmbeddedNativeLibrary** build action bundles a native library such as `lib/armeabi-v7a/libfoo.so` into the library. When a -Xamarin.Android application consumes the library, the `libfoo.so` file +.NET for Android application consumes the library, the `libfoo.so` file will be included in the final Android application. -Since Xamarin.Android 11.2, you can use the +You can use the [**AndroidNativeLibrary**](#androidnativelibrary) build action as an alternative. ## EmbeddedReferenceJar -In a Xamarin.Android binding project, the **EmbeddedReferenceJar** +In a .NET for Android binding project, the **EmbeddedReferenceJar** build action embeds the `.jar` file into the library but does not create a C# binding as [**EmbeddedJar**](#embeddedjar) does. When a -Xamarin.Android application project consumes the library, it will +.NET for Android application project consumes the library, it will include the Java/Kotlin code in the final Android application. -Since Xamarin.Android 11.2, you can use the +You can use the [**AndroidLibrary**](#androidlibrary) build action as an alternative such as ``: @@ -501,39 +479,20 @@ such as ``: ``` -## JavaDocJar - -In a Xamarin.Android binding project, the **JavaDocJar** build action -is used on `.jar` files that contain *Javadoc HTML*. The Javadoc HTML -is parsed in order to extract parameter names. - -Only certain "Javadoc HTML variations" are supported, including: - - * JDK 1.7 `javadoc` output. - * JDK 1.8 `javadoc` output. - * Droiddoc output. - -This build action is deprecated in Xamarin.Android 11.3, and will not be -supported in .NET 6. -The `@(JavaSourceJar)` build action is preferred. - ## JavaSourceJar -In a Xamarin.Android binding project, the **JavaSourceJar** build action +In a .NET for Android binding project, the **JavaSourceJar** build action is used on `.jar` files that contain *Java source code*, that contain [Javadoc documentation comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). -Prior to Xamarin.Android 11.3, the Javadoc would be converted into HTML -via the `javadoc` utility during build time, and later turned into -XML documentation. - -Starting with Xamarin.Android 11.3, Javadoc will instead be converted into +Javadoc will instead be converted into [C# XML Documentation Comments](/dotnet/csharp/codedoc) within the generated binding source code. -`$(AndroidJavadocVerbosity)` controls how "verbose" or "complete" the imported Javadoc is. +[`$(AndroidJavadocVerbosity)`](build-properties.md#androidjavadocverbosity) +controls how "verbose" or "complete" the imported Javadoc is. -Starting in Xamarin.Android 11.3, the following MSBuild metadata is supported: +The following MSBuild metadata is supported: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to @@ -546,38 +505,31 @@ Starting in Xamarin.Android 11.3, the following MSBuild metadata is supported: online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. -Starting in Xamarin.Android 12.3, the following MSBuild metadata is supported: - -* `%(DocRootUrl)`: A URL prefix to use in place of all {@docroot} +* `%(DocRootUrl)`: A URL prefix to use in place of all `{@docroot}` instances in the imported documentation. ## LibraryProjectZip -In a Xamarin.Android binding project, the **LibraryProjectZip** build +The **LibraryProjectZip** build action binds the Java/Kotlin library and embeds the `.zip` or `.aar` -file into the library. When a Xamarin.Android application project +file into the library. When a .NET for Android application project consumes the library, it will have access to the Java/Kotlin APIs from C# as well as include the Java/Kotlin code in the final Android application. -> [!NOTE] -> Only a single **LibraryProjectZip** can be included in a -> Xamarin.Android binding project. This limitation will be removed -> in .NET 6. - ## LinkDescription Files with a *LinkDescription* build action are used to -[control linker behavior](~/cross-platform/deploy-test/linker.md). +[control linker behavior](/xamarin/cross-platform/deploy-test/linker). ## ProguardConfiguration Files with a *ProguardConfiguration* build action contain options which are used to control `proguard` behavior. For more information about this build action, see -[ProGuard](~/android/deploy-test/release-prep/proguard.md). +[ProGuard](/xamarin/android/deploy-test/release-prep/proguard). These files are ignored unless the -[`$(EnableProguard)`](~/android/deploy-test/building-apps/build-properties.md#enableproguard) +[`$(EnableProguard)`](/xamarin/android/deploy-test/building-apps/build-properties.md#enableproguard) MSBuild property is `True`. diff --git a/Documentation/guides/building-apps/build-process.md b/Documentation/docs-mobile/building-apps/build-process.md similarity index 54% rename from Documentation/guides/building-apps/build-process.md rename to Documentation/docs-mobile/building-apps/build-process.md index 0ec934e1610..6ebcfb2c822 100644 --- a/Documentation/guides/building-apps/build-process.md +++ b/Documentation/docs-mobile/building-apps/build-process.md @@ -1,31 +1,26 @@ --- -title: "Build Process" -description: "This document will provide an overview of the Xamarin.Android build process." -ms.prod: xamarin -ms.assetid: 3BE5EE1E-3FF6-4E95-7C9F-7B443EE3E94C -ms.technology: xamarin-android -author: davidortinau -ms.author: daortin -ms.date: 03/29/2022 +title: .NET for Android Build Process +description: .NET for Android Build Process +ms.date: 04/11/2024 --- # Build Process -The Xamarin.Android build process is responsible for gluing everything +The .NET for Android build process is responsible for gluing everything together: -[generating `Resource.designer.cs`](~/android/internals/api-design.md), +[generating `Resource.designer.cs`](/xamarin/android/internals/api-design), supporting the -[`@(AndroidAsset)`](~/android/deploy-test/building-apps/build-items.md#androidasset), -[`@(AndroidResource)`](~/android/deploy-test/building-apps/build-items.md#androidresource), -and other [build actions](~/android/deploy-test/building-apps/build-items.md), +[`@(AndroidAsset)`](build-items.md#androidasset), +[`@(AndroidResource)`](build-items.md#androidresource), +and other [build actions](build-items.md), generating -[Android-callable wrappers](~/android/platform/java-integration/android-callable-wrappers.md), +[Android-callable wrappers](/xamarin/android/platform/java-integration/android-callable-wrappers), and generating a `.apk` for execution on Android devices. ## Application Packages In broad terms, there are two types of Android application packages -(`.apk` files) which the Xamarin.Android build system can generate: +(`.apk` files) which the .NET for Android build system can generate: - **Release** builds, which are fully self-contained and don't require extra packages to execute. These are the @@ -36,22 +31,6 @@ In broad terms, there are two types of Android application packages These package types match the MSBuild `Configuration` which produces the package. -## Shared Runtime - -Prior to Xamarin.Android 11.2, the *shared runtime* was a pair -of extra Android packages which -provide the Base Class Library (`mscorlib.dll`, etc.) and the -Android binding library (`Mono.Android.dll`, etc.). Debug builds -rely upon the shared runtime in lieu of including the Base Class Library and -Binding assemblies within the Android application package, allowing the -Debug package to be smaller. - -The shared runtime could be disabled in Debug builds by setting the -[`$(AndroidUseSharedRuntime)`](~/android/deploy-test/building-apps/build-properties.md#androidusesharedruntime) -property to `False`. - -Support for the Shared Runtime was removed in Xamarin.Android 11.2. - ## Fast Deployment @@ -74,7 +53,7 @@ Only the updated assemblies are resynchronized to the target device. Fast deployment is enabled by default, and may be disabled in Debug builds by setting the `$(EmbedAssembliesIntoApk)` property to `True`. -The [Enhanced Fast Deployment](~/android/deploy-test/building-apps/build-properties.md#androidfastdeploymenttype) mode can +The [Enhanced Fast Deployment](build-properties.md#androidfastdeploymenttype) mode can be used in conjunction with this feature to speed up deployments even further. This will deploy both assemblies, native libraries, typemaps and dexes to the `files` directory. But you should only really need to enable this if you are changing @@ -82,7 +61,7 @@ native libraries, bindings or Java code. ## MSBuild Projects -The Xamarin.Android build process is based on MSBuild, which is also +The .NET for Android build process is based on MSBuild, which is also the project file format used by Visual Studio for Mac and Visual Studio. Ordinarily, users will not need to edit the MSBuild files by hand – the IDE creates fully functional projects and updates them with @@ -90,7 +69,7 @@ any changes made, and automatically invoke build targets as needed. Advanced users may wish to do things not supported by the IDE's GUI, so the build process is customizable by editing the project file directly. -This page documents only the Xamarin.Android-specific features and +This page documents only the .NET for Android-specific features and customizations – many more things are possible with the normal MSBuild items, properties and targets. @@ -99,30 +78,30 @@ MSBuild items, properties and targets. ## Binding Projects The following MSBuild properties are used with -[Binding projects](~/android/platform/binding-java-library/index.md): +[Binding projects](/xamarin/android/platform/binding-java-library): -- [`$(AndroidClassParser)`](~/android/deploy-test/building-apps/build-properties.md#androidclassparser) -- [`$(AndroidCodegenTarget)`](~/android/deploy-test/building-apps/build-properties.md#androidcodegentarget) +- [`$(AndroidClassParser)`](build-properties.md#androidclassparser) +- [`$(AndroidCodegenTarget)`](build-properties.md#androidcodegentarget) ## `Resource.designer.cs` Generation The Following MSBuild properties are used to control generation of the `Resource.designer.cs` file: -- [`$(AndroidAapt2CompileExtraArgs)`](~/android/deploy-test/building-apps/build-properties.md#androidaapt2compileextraargs) -- [`$(AndroidAapt2LinkExtraArgs)`](~/android/deploy-test/building-apps/build-properties.md#androidaapt2linkextraargs) -- [`$(AndroidExplicitCrunch)`](~/android/deploy-test/building-apps/build-properties.md#androidexplicitcrunch) -- [`$(AndroidR8IgnoreWarnings)`](~/android/deploy-test/building-apps/build-properties.md#androidr8ignorewarnings) -- [`$(AndroidResgenExtraArgs)`](~/android/deploy-test/building-apps/build-properties.md#androidresgenextraargs) -- [`$(AndroidResgenFile)`](~/android/deploy-test/building-apps/build-properties.md#androidresgenfile) -- [`$(AndroidUseAapt2)`](~/android/deploy-test/building-apps/build-properties.md#androiduseaapt2) -- [`$(MonoAndroidResourcePrefix)`](~/android/deploy-test/building-apps/build-properties.md#monoandroidresourceprefix) +- [`$(AndroidAapt2CompileExtraArgs)`](build-properties.md#androidaapt2compileextraargs) +- [`$(AndroidAapt2LinkExtraArgs)`](build-properties.md#androidaapt2linkextraargs) +- [`$(AndroidExplicitCrunch)`](build-properties.md#androidexplicitcrunch) +- [`$(AndroidR8IgnoreWarnings)`](build-properties.md#androidr8ignorewarnings) +- [`$(AndroidResgenExtraArgs)`](build-properties.md#androidresgenextraargs) +- [`$(AndroidResgenFile)`](build-properties.md#androidresgenfile) +- [`$(AndroidUseAapt2)`](build-properties.md#androiduseaapt2) +- [`$(MonoAndroidResourcePrefix)`](build-properties.md#monoandroidresourceprefix) ## Signing Properties Signing properties control how the Application package is signed so that it may be installed onto an Android device. To allow -quicker build iteration, the Xamarin.Android tasks do not sign packages +quicker build iteration, the .NET for Android tasks do not sign packages during the build process, because signing is quite slow. Instead, they are signed (if necessary) before installation or during export, by the IDE or the *Install* build target. Invoking the *SignAndroidPackage* @@ -133,16 +112,16 @@ By default, the signing target generates a new debug-signing key if necessary. If you wish to use a specific key, for example on a build server, the following MSBuild properties are used: -- [`$(AndroidDebugKeyAlgorithm)`](~/android/deploy-test/building-apps/build-properties.md#androiddebugkeyalgorithm) -- [`$(AndroidDebugKeyValidity)`](~/android/deploy-test/building-apps/build-properties.md#androiddebugkeyvalidity) -- [`$(AndroidDebugStoreType)`](~/android/deploy-test/building-apps/build-properties.md#androiddebugstoretype) -- [`$(AndroidKeyStore)`](~/android/deploy-test/building-apps/build-properties.md#androidkeystore) -- [`$(AndroidSigningKeyAlias)`](~/android/deploy-test/building-apps/build-properties.md#androidsigningkeyalias) -- [`$(AndroidSigningKeyPass)`](~/android/deploy-test/building-apps/build-properties.md#androidsigningkeypass) -- [`$(AndroidSigningKeyStore)`](~/android/deploy-test/building-apps/build-properties.md#androidsigningkeystore) -- [`$(AndroidSigningStorePass)`](~/android/deploy-test/building-apps/build-properties.md#androidsigningstorepass) -- [`$(JarsignerTimestampAuthorityCertificateAlias)`](~/android/deploy-test/building-apps/build-properties.md#jarsignertimestampauthoritycertificatealias) -- [`$(JarsignerTimestampAuthorityUrl)`](~/android/deploy-test/building-apps/build-properties.md#jarsignertimestampauthorityurl) +- [`$(AndroidDebugKeyAlgorithm)`](build-properties.md#androiddebugkeyalgorithm) +- [`$(AndroidDebugKeyValidity)`](build-properties.md#androiddebugkeyvalidity) +- [`$(AndroidDebugStoreType)`](build-properties.md#androiddebugstoretype) +- [`$(AndroidKeyStore)`](build-properties.md#androidkeystore) +- [`$(AndroidSigningKeyAlias)`](build-properties.md#androidsigningkeyalias) +- [`$(AndroidSigningKeyPass)`](build-properties.md#androidsigningkeypass) +- [`$(AndroidSigningKeyStore)`](build-properties.md#androidsigningkeystore) +- [`$(AndroidSigningStorePass)`](build-properties.md#androidsigningstorepass) +- [`$(JarsignerTimestampAuthorityCertificateAlias)`](build-properties.md#jarsignertimestampauthoritycertificatealias) +- [`$(JarsignerTimestampAuthorityUrl)`](build-properties.md#jarsignertimestampauthorityurl) ### `keytool` Option Mapping @@ -177,7 +156,7 @@ To use the keystore generated above, use the property group: ## Build Extension Points -The Xamarin.Android build system exposes a few public extension points +The .NET for Android build system exposes a few public extension points for users wanting to hook into our build process. To use one of these extension points you will need to add your custom target to the appropriate MSBuild property in a `PropertyGroup`. For example: @@ -193,9 +172,9 @@ appropriate MSBuild property in a `PropertyGroup`. For example: Extension points include: -- [`$(AfterGenerateAndroidManifest)](~/android/deploy-test/building-apps/build-properties.md#aftergenerateandroidmanifest) -- [`$(BeforeGenerateAndroidManifest)](~/android/deploy-test/building-apps/build-properties.md#beforegenerateandroidmanifest) -- [`$(BeforeBuildAndroidAssetPacks)`](~/android/deploy-test/building-apps/build-properties.md#beforebuildandroidassetpacks) +- [`$(AfterGenerateAndroidManifest)](build-properties.md#aftergenerateandroidmanifest) +- [`$(BeforeGenerateAndroidManifest)](build-properties.md#beforegenerateandroidmanifest) +- [`$(BeforeBuildAndroidAssetPacks)`](build-properties.md#beforebuildandroidassetpacks) A word of caution about extending the build process: If not written correctly, build extensions can affect your build @@ -205,7 +184,7 @@ before implementing such extensions. ## Target Definitions -The Xamarin.Android-specific parts of the build process are defined in +The .NET for Android-specific parts of the build process are defined in `$(MSBuildExtensionsPath)\Xamarin\Android\Xamarin.Android.CSharp.targets`, but normal language-specific targets such as *Microsoft.CSharp.targets* are also required to build the assembly. diff --git a/Documentation/guides/building-apps/build-properties.md b/Documentation/docs-mobile/building-apps/build-properties.md similarity index 72% rename from Documentation/guides/building-apps/build-properties.md rename to Documentation/docs-mobile/building-apps/build-properties.md index 5e3468f8a55..9964444fd6c 100644 --- a/Documentation/guides/building-apps/build-properties.md +++ b/Documentation/docs-mobile/building-apps/build-properties.md @@ -1,18 +1,13 @@ --- -title: "Build Properties" -description: "This document will list all supported properties in the Xamarin.Android build process." -ms.prod: xamarin -ms.assetid: FC0DBC08-EBCB-4D2D-AB3F-76B54E635C22 -ms.technology: xamarin-android -author: jonpryor -ms.author: jopryo -ms.date: 07/27/2022 +title: .NET for Android Build Properties +description: .NET for Android Build Properties +ms.date: 04/11/2024 --- # Build Properties MSBuild properties control the behavior of the -[targets](~/android/deploy-test/building-apps/build-targets.md). +[targets](build-targets.md). They're specified within the project file, for example **MyApp.csproj**, within an [MSBuild PropertyGroup](/visualstudio/msbuild/propertygroup-element-msbuild). @@ -32,24 +27,18 @@ in the `$(IntermediateOutputPath)`. If you want to make any modifications to the generated `AndroidManifest.xml` file, you can do that using this extension point. -Added in Xamarin.Android 9.4. - ## AndroidAapt2CompileExtraArgs Specifies command-line options to pass to the **aapt2 compile** command when processing Android assets and resources. -Added in Xamarin.Android 9.1. - ## AndroidAapt2LinkExtraArgs Specifies command-line options to pass to the **aapt2 link** command when processing Android assets and resources. -Added in Xamarin.Android 9.1. - ## AndroidAddKeepAlives A boolean property that controls whether the linker will insert @@ -58,8 +47,6 @@ object collection. The default value is `True` for Release configuration builds. -This property was added in Xamarin.Android 11.2. - ## AndroidAotAdditionalArguments A string property that allows @@ -89,7 +76,6 @@ The file that `aprofutil` should create to hold profiler data. A string property that allows the developer to add AOT profiles from the command line. It's a semicolon or comma-separated list of absolute paths. -Added in Xamarin.Android 10.1. ## AndroidAotProfilerPort @@ -108,27 +94,19 @@ Introduced in .NET 6. A string value that specifies the digest algorithm to use with `jarsigner -digestalg`. -The default value is `SHA-256`. In Xamarin.Android 10.0 and earlier, -the default value was `SHA1`. - -Added in Xamarin.Android 9.4. +The default value is `SHA-256`. ## AndroidApkSignerAdditionalArguments A string property that allows the developer to provide arguments to the `apksigner` tool. -Added in Xamarin.Android 8.2. - ## AndroidApkSigningAlgorithm A string value that specifies the signing algorithm to use with `jarsigner -sigalg`. -The default value is `SHA256withRSA`. In Xamarin.Android 10.0 and -earlier, the default value was `md5withRSA`. - -Added in Xamarin.Android 8.2. +The default value is `SHA256withRSA`. ## AndroidApplication @@ -151,8 +129,6 @@ from [Android.App.Application](xref:Android.App.Application). The `$(AndroidApplicationJavaClass)` property is generally set by *other* properties, such as the [`$(AndroidEnableMultiDex)`](#androidenablemultidex) MSBuild property. -Added in Xamarin.Android 6.1. - ## AndroidAvoidEmitForPerformance A boolean property that determines whether or not `System.Reflection.Emit` is @@ -184,18 +160,16 @@ Added in .NET 8. A path to a directory containing the Android [binutils][binutils] such as `ld`, the native linker, and `as`, the native assembler. These tools are included in the -Xamarin.Android installation. +.NET for Android workload. The default value is `$(MonoAndroidBinDirectory)\binutils\bin\`. -Added in Xamarin.Android 10.0. - [binutils]: https://github.com/xamarin/xamarin-android-binutils/ ## AndroidBoundExceptionType A string value that specifies how -exceptions should be propagated when a Xamarin.Android-provided type +exceptions should be propagated when a .NET for Android-provided type implements a .NET type or interface in terms of Java types, for example `Android.Runtime.InputStreamInvoker` and `System.IO.Stream`, or `Android.Runtime.JavaDictionary` and `System.Collections.IDictionary`. @@ -206,9 +180,6 @@ implements a .NET type or interface in terms of Java types, for example the `System.IO.Stream` API because `Java.IO.IOException` may be thrown from `Stream.Read()` instead of `System.IO.IOException`. - `Java` is the exception propagation behavior in all releases of - Xamarin.Android, including Xamarin.Android 13.0. - - `System`: The original Java exception type is caught and wrapped in an appropriate .NET exception type. @@ -217,9 +188,7 @@ implements a .NET type or interface in terms of Java types, for example instances. (It may instead throw a `System.IO.IOException` containing a `Java.IO.IOException` as the `Exception.InnerException` value.) - `System` is the default value in .NET 6.0. - -Added in Xamarin.Android 10.2. + `System` is the default value. ## AndroidBoundInterfacesContainConstants @@ -228,7 +197,7 @@ determines whether binding constants on interfaces will be supported, or the workaround of creating an `IMyInterfaceConsts` class will be used. -The default value is `True` in .NET 6 and `False` for legacy. +The default value is `True`. ## AndroidBoundInterfacesContainStaticAndDefaultInterfaceMethods @@ -252,11 +221,9 @@ The default value is `True` in .NET 6 and `False` for legacy. A boolean value that indicates whether to create and sign the package (.apk). Setting this value to `True` is equivalent to using the -[`SignAndroidPackage`](~/android/deploy-test/building-apps/build-targets.md#install) +[`SignAndroidPackage`](build-targets.md#install) build target. -Support for this property was added after Xamarin.Android 7.1. - This property is `False` by default. ## AndroidBundleConfigurationFile @@ -266,14 +233,12 @@ Specifies a filename to use as a when building an Android App Bundle. This file controls some aspects of how APKs are generated from the bundle, such as on what dimensions the bundle is split to produce APKs. -Xamarin.Android configures some of these settings automatically, +.NET for Android configures some of these settings automatically, including the list of file extensions to leave uncompressed. This property is only relevant if [`$(AndroidPackageFormat)`](#androidpackageformat) is set to `aab`. -Added in Xamarin.Android 10.3. - [bundle-config-format]: https://developer.android.com/studio/build/building-cmdline#bundleconfig ## AndroidBundleToolExtraArgs @@ -282,8 +247,6 @@ Specifies command-line options to pass to the **bundletool** command when build app bundles. -This property was added in Xamarin.Android 11.3. - ## AndroidClassParser A string property that controls how @@ -292,64 +255,29 @@ A string property that controls how - **class-parse**: Uses `class-parse.exe` to parse Java bytecode directly, without assistance of a JVM. -- **jar2xml**: Use `jar2xml.jar` to use Java reflection to extract - types and members from a `.jar` file. - -The advantages of `class-parse` over `jar2xml` are: - -- `class-parse` can extract parameter names from Java - bytecode containing *debug* symbols (bytecode compiled - with `javac -g`). - -- `class-parse` doesn't "skip" classes that inherit from or - contain members of unresolvable types. - -Added in Xamarin.Android 6.0. - -The default value is `jar2xml` in "legacy" Xamarin.Android and -`class-parse` in .NET 6 and higher. - -Support for `jar2xml` is obsolete, and `jar2xml` is removed in .NET 6. +- **jar2xml**: this value is obsolete and is no longer supported. ## AndroidCodegenTarget A string property that controls the code generation target ABI. Possible values include: -- **XamarinAndroid**: Uses the JNI binding API present since - Mono for Android 1.0. Binding assemblies built with - Xamarin.Android 5.0 or later can only run on Xamarin.Android 5.0 - or later (API/ABI additions), but the *source* is compatible with - prior product versions. +- **XamarinAndroid**: this value is obsolete and is no longer supported. - **XAJavaInterop1**: Use Java.Interop for JNI invocations. Binding assemblies using `XAJavaInterop1` can only build and execute with Xamarin.Android 6.1 or later. Xamarin.Android 6.1 and later bind `Mono.Android.dll` with this value. -The benefits of `XAJavaInterop1` include: - -- Smaller assemblies. - -- `jmethodID` caching for `base` method invocations, - so long as all other binding types in the inheritance - hierarchy are built with `XAJavaInterop1` or later. - -- `jmethodID` caching of Java Callable Wrapper constructors for - managed subclasses. - The default value is `XAJavaInterop1`. -Support for `XamarinAndroid` is obsolete, and support for `XamarinAndroid` will be removed -as part of .NET 6. - ## AndroidCreatePackagePerAbi A boolean property that determines if a *set* of files--one per ABI specified in [`$(AndroidSupportedAbis)`](#androidsupportedabis)--should be created instead of having support for all ABIs in a single `.apk`. -See also the [Building ABI-Specific APKs](~/android/deploy-test/building-apps/abi-specific-apks.md) +See also the [Building ABI-Specific APKs](/xamarin/android/deploy-test/building-apps/abi-specific-apks) guide. ## AndroidCreateProguardMappingFile @@ -373,8 +301,6 @@ manually uploaded. The default value is `True` when using [`$(AndroidLinkTool)`](#androidlinktool)=r8. -Added in Xamarin.Android 12.3. - ## AndroidDebugKeyAlgorithm Specifies the default @@ -393,8 +319,6 @@ Specifies the key store file format to use for the `debug.keystore`. It defaults to `pkcs12`. -Added in Xamarin.Android 10.2. - ## AndroidDeviceUserId @@ -402,7 +326,7 @@ Allows deploying and debugging the application under guest or work accounts. The value is the `uid` value you get from the following adb command: -``` +```shell adb shell pm list users ``` @@ -417,13 +341,11 @@ Users: The `uid` is the first integer value. In the above output, they're `0` and `10`. -The `$(AndroidDeviceUserId)` property was added in Xamarin.Android 11.2. - ## AndroidDexTool An enum-style property with valid values of `dx` or `d8`. Indicates which Android [dex][dex] -compiler is used during the Xamarin.Android build process. +compiler is used during the .NET for Android build process. The default value is `dx`. See our documentation on [D8 and R8][d8-r8]. @@ -449,16 +371,15 @@ Store checks: XA1004, XA1005 and XA1006. Disabling these checks is useful for developers who are not targeting the Google Play Store and do not wish to run those checks. -Added in Xamarin.Android 9.4. - ## AndroidEnableMarshalMethods -A bool property, not available in the classic Xamarin.Android -releases. +A bool property, that determines whether or not LLVM marshal methods are enabled. +LLVM marshal methods are an app startup optimization which uses native entry points +for Java `native` method registration. -Enable or disable generation of [marshal -methods](../../internals/JavaJNI_Interop.md). Defaults to `True` for -`Release` builds and to `False` for `Debug` builds. +This property is False by default. + +Added in .NET 8. ## AndroidEnableMultiDex @@ -466,8 +387,6 @@ A boolean property that determines whether or not multi-dex support will be used in the final `.apk`. -Support for this property was added in Xamarin.Android 5.1. - This property is `False` by default. ## AndroidEnableObsoleteOverrideInheritance @@ -487,7 +406,6 @@ are loaded during process startup or not. When set to `True`, all assemblies bundled within the application package will be loaded during process startup, before any application code is invoked. -Preloading assemblies is what Xamarin.Android does. When set to `False`, assemblies will only be loaded on an as-needed basis. Loading assemblies on an as-needed basis allows applications to launch faster, @@ -501,10 +419,7 @@ this property be `True` if they in turn require that `AppDomain.CurrentDomain.GetAssemblies()` return all assemblies within the application bundle, even if the assembly wouldn't otherwise have been needed. -By default this value will be set to `True` for Xamarin.Android, and will be -set to `False` for .NET 6+ builds. - -Added in Xamarin.Android 9.2. +By default this value is False. ## AndroidEnableProfiledAot @@ -513,12 +428,10 @@ determines whether or not the AOT profiles are used during Ahead-of-Time compilation. The profiles are listed in -[`@(AndroidAotProfile)`](~/android/deploy-test/building-apps/build-items.md#androidaotprofile) +[`@(AndroidAotProfile)`](build-items.md#androidaotprofile) item group. This ItemGroup contains default profile(s). It can be overridden by removing the existing one(s) and adding your own AOT profiles. -Support for this property was added in Xamarin.Android 9.4. - This property is `False` by default. @@ -542,7 +455,7 @@ 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 -Java packages, you can use [Transform files](https://learn.microsoft.com/xamarin/android/platform/binding-java-library/customizing-bindings/java-bindings-metadata#metadataxml-transform-file) in addition to +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: ```xml @@ -560,8 +473,6 @@ determines whether or not Mono's [concurrent GC collector](https://www.mono-project.com/docs/about-mono/releases/4.8.0/#concurrent-sgen) will be used. -Support for this property was added in Xamarin.Android 7.2. - This property is `False` by default. ## AndroidErrorOnCustomJavaObject @@ -585,13 +496,11 @@ class BadType : IJavaObject { When True, such types will generate an XA4212 error, otherwise an XA4212 warning will be generated. -Support for this property was added in Xamarin.Android 8.1. - This property is `True` by default. ## AndroidExplicitCrunch -No longer supported in Xamarin.Android 11.0. +This property is no longer supported. ## AndroidExtraAotOptions @@ -614,15 +523,13 @@ compiler. `$(AndroidExtraAotOptions)` instead passes full standalone space-separated options like `--verbose` or `--debug` to the compiler. -Added in Xamarin.Android 10.2. - ## AndroidFastDeploymentType A `:` (colon)-separated list of values to control what types can be deployed to the -[Fast Deployment directory](~/android/deploy-test/building-apps/build-process.md#Fast_Deployment) +[Fast Deployment directory](build-process.md#Fast_Deployment) on the target device when the [`$(EmbedAssembliesIntoApk)`](#embedassembliesintoapk) MSBuild property is `False`. If a resource is fast deployed, it is *not* @@ -642,7 +549,7 @@ Support for Fast Deploying resources and assets via that system was removed in commit [f0d565fe](https://github.com/xamarin/xamarin-android/commit/f0d565fe4833f16df31378c77bbb492ffd2904b9). This was becuase it required the use of deprecated API's to work. -**Experimental**. This property was added in Xamarin.Android 6.1. +**Experimental**. ## AndroidFragmentType @@ -668,11 +575,10 @@ in their `.csproj`. Alternatively provide the property on the command line via ```shell -/p:AndroidGenerateJniMarshalMethods=True +-p:AndroidGenerateJniMarshalMethods=True ``` -**Experimental**. Added in Xamarin.Android 9.2. -The default value is `False`. +**Experimental**. The default value is `False`. ## AndroidGenerateJniMarshalMethodsAdditionalArguments @@ -691,23 +597,21 @@ on the command line. For example: or: ```shell -/p:AndroidGenerateJniMarshalMethodsAdditionalArguments="-v -d --keeptemp" +-p:AndroidGenerateJniMarshalMethodsAdditionalArguments="-v -d --keeptemp" ``` -Added in Xamarin.Android 9.2. - ## AndroidGenerateLayoutBindings -Enables generation of [layout code-behind](https://github.com/xamarin/xamarin-android/blob/main/Documentation/guides/LayoutCodeBehind.md) -if set to `true` or disables it completely if set to `false`. The -default value is `false`. +Enables generation of +[layout code-behind](../features/layout-code-behind/index.md) +if set to `true` or disables it completely if set to `false`. + +The default value is `false`. ## AndroidGenerateResourceDesigner The default value is `true`. When set to `false`, disables the generation of `Resource.designer.cs`. -Added in .NET 6 RC 1. Not supported in Xamarin.Android. - ## AndroidHttpClientHandlerType Controls the default @@ -731,31 +635,6 @@ The most common values for this property are: HTTP message handler to use with [Grpc.Net.Client](https://www.nuget.org/packages/Grpc.Net.Client). This value is equivalent to `$(UseNativeHttpHandler)=false`. -> [!NOTE] -> There are differences in the internal implementation of .NET 6 and -> "legacy" Xamarin.Android and the valid values for this property are -> different. In .NET 6, the type you specify must not be -> `Xamarin.Android.Net.AndroidClientHandler` or `System.Net.Http.HttpClientHandler` -> or inherit from either of these classes. If you are migrating from -> "legacy" Xamarin.Android, use `AndroidMessageHandler` or derive your -> custom handler from it instead. - -In legacy Xamarin apps, the most common values for this property are: - -- `Xamarin.Android.Net.AndroidClientHandler`: Use the Android Java APIs - to perform network requests. Using Java APIs allows accessing TLS 1.2 URLs when - the underlying Android version supports TLS 1.2. Only Android 5.0 and - later reliably provide TLS 1.2 support through Java. - - Corresponds to the **Android** option in the Visual Studio - property pages and the **AndroidClientHandler** option in the Visual - Studio for Mac property pages. - - The new project wizard selects this option for new projects when the - **Minimum Android Version** is configured to **Android 5.0 - (Lollipop)** or higher in Visual Studio or when **Target Platforms** - is set to **Latest and Greatest** in Visual Studio for Mac. - - Unset/the empty string, which is equivalent to `System.Net.Http.HttpClientHandler, System.Net.Http` @@ -774,20 +653,20 @@ In legacy Xamarin apps, the most common values for this property are: property pages. > [!NOTE] -> If TLS 1.2 support is required on Android versions prior to 5.0, -> *or* if TLS 1.2 support is required with the `System.Net.WebClient` and -> related APIs, then [`$(AndroidTlsProvider)`](#androidtlsprovider) should be used. +> In .NET 6, the type you specify must not be +> `Xamarin.Android.Net.AndroidClientHandler` or `System.Net.Http.HttpClientHandler` +> or inherit from either of these classes. If you are migrating from +> "classic" Xamarin.Android, use `AndroidMessageHandler` or derive your +> custom handler from it instead. > [!NOTE] > Support for the `$(AndroidHttpClientHandlerType)` property works by setting the -> [`XA_HTTP_CLIENT_HANDLER_TYPE` environment variable](~/android/deploy-test/environment.md). +> [`XA_HTTP_CLIENT_HANDLER_TYPE` environment variable](/xamarin/android/deploy-test/environment). > A `$XA_HTTP_CLIENT_HANDLER_TYPE` value found in a file > with a Build action of -> [`@(AndroidEnvironment)`](~/android/deploy-test/building-apps/build-items.md#androidenvironment) +> [`@(AndroidEnvironment)`](build-items.md#androidenvironment) > will take precedence. -Added in Xamarin.Android 6.1. - ## AndroidIncludeWrapSh A boolean value that indicates whether the Android wrapper script @@ -799,7 +678,7 @@ when necessary, for example when debugging or otherwise changing the application startup/runtime behavior. The script is added to the project using the -[`@(AndroidNativeLibrary)`](~/android/deploy-test/building-apps/build-items.md#androidnativelibrary) +[`@(AndroidNativeLibrary)`](build-items.md#androidnativelibrary) build action, because it is placed in the same directory as architecture-specific native libraries, and must be named `wrap.sh`. @@ -858,7 +737,7 @@ Specifies how "verbose" should be when importing Javadoc documentation within binding projects. Requires use of the -[`@(JavaSourceJar)`](~/android/deploy-test/building-apps/build-items.md#javasourcejar) +[`@(JavaSourceJar)`](build-items.md#javasourcejar) build action. The `$(AndroidJavadocVerbosity)` property is enum-like, with possible values of `full` or @@ -876,8 +755,6 @@ The `$(AndroidJavadocVerbosity)` property is enum-like, with possible values of The default value is `intellisense`. -Support for this property was added in Xamarin.Android 11.3. - ## AndroidKeyStore A boolean value that indicates whether @@ -892,7 +769,7 @@ The Android activity to launch. ## AndroidLinkMode Specifies which type of -[linking](~/android/deploy-test/linker.md) should be +[linking](/xamarin/android/deploy-test/linker) should be performed on assemblies contained within the Android package. Only used in Android Application projects. The default value is *SdkOnly*. Valid values are: @@ -932,8 +809,6 @@ var view = FindViewById(Resources.Ids.foo); Any other scenarios (such as reflection) will not be supported. -Support for this property was added in Xamarin.Android 11.3 - ## AndroidLinkSkip Specifies a semicolon-delimited (`;`) @@ -968,7 +843,7 @@ When `$(AndroidLintEnabled)`=True, the following properties are used: The following build actions may also be used: -- [`@(AndroidLintConfig)`](~/android/deploy-test/building-apps/build-items.md#androidlintconfig): +- [`@(AndroidLintConfig)`](build-items.md#androidlintconfig): See [Lint Help](https://developer.android.com/studio/write/lint) for more details on the android `lint` tooling. @@ -999,12 +874,10 @@ A boolean property that controls whether sequence points are generated so that file name and line number information can be extracted from `Release` stack traces. -Added in Xamarin.Android 6.1. - ## AndroidManifest Specifies a filename to use as the template for the app's -[`AndroidManifest.xml`](~/android/platform/android-manifest.md). +[`AndroidManifest.xml`](/xamarin/android/platform/android-manifest). During the build, any other necessary values will be merged into to produce the actual `AndroidManifest.xml`. The `$(AndroidManifest)` must contain the package name in the `/manifest/@package` attribute. @@ -1026,8 +899,6 @@ use the old version add the following to your csproj Google's merger enables support for `xmlns:tools="http://schemas.android.com/tools"` as described in the [Android documentation][manifest-merger]. -Introduced in Xamarin.Android 10.2 - [manifest-merger]: https://developer.android.com/studio/build/manifest-merge ## AndroidManifestMergerExtraArgs @@ -1042,27 +913,21 @@ If you want detailed output from the tool you can add the following to the --log VERBOSE ``` -Introduced in Xamarin.Android 11.x - ## AndroidManifestType An enum-style property with valid values of `Xamarin` or `GoogleV2`. This controls which repository is used by the -[`InstallAndroidDependencies`](~/android/deploy-test/building-apps/build-targets.md#installandroiddependencies) +[`InstallAndroidDependencies`](build-targets.md#installandroiddependencies) target to determine which Android packages and package versions are available and can be installed. `Xamarin` is the **Approved List (Recommended)** repository within the -[Visual Studio SDK Manager](~/android/get-started/installation/android-sdk.md?tabs=windows#repository-selection). +[Visual Studio SDK Manager](/xamarin/android/get-started/installation/android-sdk?tabs=windows#repository-selection). `GoogleV2` is the **Full List (Unsupported)** repository within the -[Visual Studio SDK Manager](~/android/get-started/installation/android-sdk.md?tabs=windows#repository-selection). +[Visual Studio SDK Manager](/xamarin/android/get-started/installation/android-sdk?tabs=windows#repository-selection). -Added in Xamarin.Android 13.0. In Xamarin.Android 13.0, if `$(AndroidManifestType)` -is not set, then `Xamarin` is used. - -Prior to Xamarin.Android 13.0, setting `$(AndroidManifestType)` has no effect, and -`GoogleV2` is used. +If `$(AndroidManifestType)` is not set, then `Xamarin` is used. ## AndroidManifestPlaceholders @@ -1105,8 +970,6 @@ If you are getting this error you can add the following to the which will allow the `dx` step to succeed. -Added in Xamarin.Android 8.3. - ## AndroidPackageFormat An enum-style property with valid @@ -1118,7 +981,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)`](~/android/deploy-test/building-apps/build-properties.md#androiduseaapt2) is `True`. +- [`$(AndroidUseAapt2)`](build-properties.md#androiduseaapt2) is `True`. - [`$(AndroidUseApkSigner)`](#androiduseapksigner) is `False`. - [`$(AndroidCreatePackagePerAbi)`](#androidcreatepackageperabi) is `False`. @@ -1126,7 +989,7 @@ properties are set, which are required for Android App Bundles: [bundle]: https://developer.android.com/platform/technology/app-bundle This property will be deprecated for .net 6. Users should switch over to -the newer [`AndroidPackageFormats`](~/android/deploy-test/building-apps/build-properties.md#androidpackageformats). +the newer [`AndroidPackageFormats`](build-properties.md#androidpackageformats). ## AndroidPackageFormats @@ -1143,41 +1006,17 @@ Setting `AndroidPackageFormats` to `aab;apk` will result in both being generated. Setting `AndroidPackageFormats` to either `aab` or `apk` will generate only one file. -For .net 6 `AndroidPackageFormats` will be set to `aab;apk` for -`Release` builds only. It is recommended that you continue to use -just `apk` for debugging. - -For Legacy Xamarin.Android The default value is `""`. -As a result Legacy Xamarin.Android will NOT by default produce -both as part of a release build. If a user wants to produce both -outputs they will need to define the following in their `Release` -configuration. - -```xml -aab;apk -``` - -You will also need to remove the existing `AndroidPackageFormat` for -that configuration if you have it. - -Added in Xamarin.Android 11.5. +The default value is `aab;apk` for `Release` builds only. +It is recommended that you continue to use just `apk` for debugging. ## AndroidPackageNamingPolicy An enum-style property for specifying the Java package names of generated Java source code. -In Xamarin.Android 10.2 and later, the only supported value is +The only supported value is `LowercaseCrc64`. -In Xamarin.Android 10.1, a transitional `LowercaseMD5` value was -also available that allowed switching back to the original Java -package name style as used in Xamarin.Android 10.0 and earlier. That -option was removed in Xamarin.Android 10.2 to improve compatibility -with build environments that have FIPS compliance enforced. - -Added in Xamarin.Android 10.1. - ## AndroidProguardMappingFile Specifies the `-printmapping` proguard rule for `r8`. This will @@ -1198,8 +1037,6 @@ Add the following in your project or use `-p:AndroidCreateProguardMappingFile=False` on the command line. -This property was added in Xamarin.Android 11.2. - ## AndroidD8IgnoreWarnings Specifies `--map-diagnostics warning info` to be passed to `d8`. The @@ -1219,15 +1056,13 @@ enforce more strict behavior. See the [ProGuard manual](https://www.guardsquare. Starting in .NET 8, specifies `--map-diagnostics warning info`. See the [D8 and R8 source code][r8-source] for details. -Added in Xamarin.Android 10.3. - [r8-source]: https://r8.googlesource.com/r8/+/refs/tags/3.3.75/src/main/java/com/android/tools/r8/BaseCompilerCommandParser.java#246 ## AndroidR8JarPath The path to `r8.jar` for use with the -r8 dex-compiler and shrinker. The default value is a path in the -Xamarin.Android installation. For further information see our +r8 dex-compiler and shrinker. The default value is a path into the +.NET for Android workload installation. For further information see our documentation on [D8 and R8][d8-r8]. ## AndroidResgenExtraArgs @@ -1254,7 +1089,7 @@ the "preferred" version is *not* present, then the highest versioned installed build-tools package is used. The `$(AndroidSdkBuildToolsVersion)` MSBuild property contains -the preferred build-tools version. The Xamarin.Android build system +the preferred build-tools version. The .NET for Android build system provides a default value in `Xamarin.Android.Common.targets`, and the default value may be overridden within your project file to choose an alternate build-tools version, if (for example) the @@ -1273,13 +1108,9 @@ Specifies the password of the key within the keystore file. This is the value entered when `keytool` asks **Enter key password for $(AndroidSigningKeyAlias)**. -In Xamarin.Android 10.0 and earlier, this property only supports -plain text passwords. - -In Xamarin.Android 10.1 and later, this property also supports -`env:` and `file:` prefixes that can be used to specify an -environment variable or file that contains the password. These -options provide a way to prevent the password from appearing in +This property also supports `env:` and `file:` prefixes that can be +used to specify an environment variable or file that contains the password. +These options provide a way to prevent the password from appearing in build logs. For example, to use an environment variable named @@ -1287,7 +1118,7 @@ For example, to use an environment variable named ```xml - env:AndroidSigningPassword + env:AndroidSigningPassword ``` @@ -1295,7 +1126,7 @@ To use a file located at `C:\Users\user1\AndroidSigningPassword.txt`: ```xml - file:C:\Users\user1\AndroidSigningPassword.txt + file:C:\Users\user1\AndroidSigningPassword.txt ``` @@ -1317,12 +1148,8 @@ This is the value provided to `keytool` when creating the keystore file and asked **Enter keystore password:**. -In Xamarin.Android 10.0 and earlier, this property only supports -plain text passwords. - -In Xamarin.Android 10.1 and later, this property also supports -`env:` and `file:` prefixes that can be used to specify an -environment variable or file that contains the password. These +This property also supports `env:` and `file:` prefixes that can be used to +specify an environment variable or file that contains the password. These options provide a way to prevent the password from appearing in build logs. @@ -1331,7 +1158,7 @@ For example, to use an environment variable named ```xml - env:AndroidSigningPassword + env:AndroidSigningPassword ``` @@ -1339,7 +1166,7 @@ To use a file located at `C:\Users\user1\AndroidSigningPassword.txt`: ```xml - file:C:\Users\user1\AndroidSigningPassword.txt + file:C:\Users\user1\AndroidSigningPassword.txt ``` @@ -1352,15 +1179,11 @@ To use a file located at `C:\Users\user1\AndroidSigningPassword.txt`: Specifies the key file to use to sign the apk. This is only used when building `system` applications. -Support for this property was added in Xamarin.Android 11.3. - ## AndroidSigningPlatformCert Specifies the certificate file to use to sign the apk. This is only used when building `system` applications. -Support for this property was added in Xamarin.Android 11.3. - ## AndroidStripILAfterAOT A bool property that specifies whether or not the *method bodies* of AOT compiled methods will be removed. @@ -1385,80 +1208,26 @@ Supported values include: - `armeabi-v7a` - `x86` -- `arm64-v8a`: Requires Xamarin.Android 5.1 and later. -- `x86_64`: Requires Xamarin.Android 5.1 and later. +- `arm64-v8a` +- `x86_64` ## AndroidTlsProvider -A string value that specifies which -TLS provider should be used in an application. Possible values are: - -- Unset/the empty string: In Xamarin.Android 7.3 and higher, this is - equivalent to `btls`. - - In Xamarin.Android 7.1, this is equivalent to `legacy`. - - This corresponds to the **Default** setting in the Visual Studio - property pages. - -- `btls`: Use - [Boring SSL](https://boringssl.googlesource.com/boringssl) for - TLS communication with - [HttpWebRequest](xref:System.Net.HttpWebRequest). - - This allows use of TLS 1.2 on all Android versions. - - This corresponds to the **Native TLS 1.2+** setting in the - Visual Studio property pages. - -- `legacy`: In Xamarin.Android 10.1 and earlier, use the historical - managed SSL implementation for network interaction. This *doesn't* support TLS 1.2. - - This corresponds to the **Managed TLS 1.0** setting in the - Visual Studio property pages. - - In Xamarin.Android 10.2 and later, this value is ignored and the - `btls` setting is used. - -- `default`: This value is unlikely to be used in Xamarin.Android - projects. The recommended value to use instead is the empty string, - which corresponds to the **Default** setting in the Visual Studio - property pages. - - The `default` value is not offered in the Visual Studio property - pages. - - This is currently equivalent to `legacy`. - -Added in Xamarin.Android 7.1. +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 False and Xamarin.Android will use `aapt`. -If the developer wishes to use the new `aapt2` functionality, add: - -```xml -True -``` - -in their `.csproj`. Alternatively provide the property on the command line: - -```shell -/p:AndroidUseAapt2=True -``` +By default this will be True. -This property was added in Xamarin.Android 8.3. Setting `AndroidUseAapt2` to `false` is -deprecated in Xamarin.Android 11.2. +This property cannot be set to false. ## AndroidUseApkSigner A bool property that allows the developer to use the `apksigner` tool rather than `jarsigner`. -Added in Xamarin.Android 8.2. - ## AndroidUseDefaultAotProfile A bool property that allows @@ -1466,8 +1235,6 @@ the developer to suppress usage of the default AOT profiles. To suppress the default AOT profiles, set the property to `false`. -Added in Xamarin.Android 10.1. - ## AndroidUseDesignerAssembly A bool property which controls if the build system will generate an @@ -1476,14 +1243,13 @@ faster startup time. The default value is `true` in .NET 8. -This setting is not backward compatible with Classic Xamarin.Android. As a Nuget Author it is recommended that you ship three versions of the assembly if you want to maintain backward compatibility. One for MonoAndroid, one for net6.0-android and one for net8.0-android. You can do this by using [Xamarin.Legacy.Sdk](https://www.nuget.org/packages/Xamarin.Legacy.Sdk). This is only required if your Nuget Library project makes use of `AndroidResource` items in the project or via a dependency. -``` +```xml monoandroid90;net6.0-android;net8.0-android ``` @@ -1495,7 +1261,7 @@ consume references which do use it. If you try to use an assembly which does have this feature enabled in a project that does not, you will get a `XA1034` build error. -Added in .NET 8. Unsupported in Classic Xamarin.Android. +Added in .NET 8. ## AndroidUseInterpreter @@ -1504,8 +1270,6 @@ A boolean property that causes the `.apk` to contain the mono ***Experimental***. -Support for this property was added in Xamarin.Android 11.3. - ## AndroidUseLegacyVersionCode A boolean property that allows @@ -1515,41 +1279,27 @@ with existing applications in the Google Play Store. It is highly recommended that the new [`$(AndroidVersionCodePattern)`](#androidversioncodepattern) property is used. -Added in Xamarin.Android 8.2. - ## AndroidUseManagedDesignTimeResourceGenerator A boolean property that will switch over the design time builds to use the managed resource parser rather than `aapt`. -Added in Xamarin.Android 8.1. - ## AndroidUseNegotiateAuthentication A boolean property that enables support for NTLMv2/Negotiate authentication in `AndroidMessageHandler`. The default value is False. -Added in .NET 7. Unsupported in Classic Xamarin.Android. +Added in .NET 7. ## AndroidUseSharedRuntime -A boolean property that -determines whether the *shared runtime packages* are required in -order to run the Application on the target device. Relying on the -shared runtime packages allows the Application package to be -smaller, speeding up the package creation and deployment process, -resulting in a faster build/deploy/debug turnaround cycle. - -Prior to Xamarin.Android 11.2, this property should be `True` for -Debug builds, and `False` for Release projects. - -This property was *removed* in Xamarin.Android 11.2. +This property is obsolete and should not be used. ## AndroidVersionCode An MSBuild property that can be used as an alternative to -`/manifest/@android:versionCode` in the [`AndroidManifest.xml`](~/android/platform/android-manifest.md) +`/manifest/@android:versionCode` in the [`AndroidManifest.xml`](/xamarin/android/platform/android-manifest) file. To opt into this feature you must also enable `true`. This will be the default going forward in .NET 6. @@ -1563,13 +1313,11 @@ for each Google Play release. See the [Android documentation][manifest-element] for further details about the requirements for `/manifest/@android:versionCode`. -Support for this property was added in Xamarin.Android 11.3. - ## AndroidVersionCodePattern A string property that allows the developer to customize the `versionCode` in the manifest. -See [Creating the Version Code for the APK](~/android/deploy-test/building-apps/abi-specific-apks.md#creating-the-version-code-for-the-apk) +See [Creating the Version Code for the APK](/xamarin/android/deploy-test/building-apps/abi-specific-apks#creating-the-version-code-for-the-apk) for information on deciding a `versionCode`. Some examples, if `abi` is `armeabi` and `versionCode` in the manifest @@ -1612,8 +1360,6 @@ By default the value will be set to `{abi}{versionCode:D6}`. If a developer wants to keep the old behavior you can override the default by setting the `$(AndroidUseLegacyVersionCode)` property to `true` -Added in Xamarin.Android 7.2. - ## AndroidVersionCodeProperties A string property that @@ -1625,12 +1371,10 @@ example: `screen=23;target=$(_AndroidApiLevel)`. As you can see you can make use of existing or custom MSBuild properties in the string. -Added in Xamarin.Android 7.2. - ## ApplicationId An MSBuild property that can be used as an alternative to -`/manifest/@package` in the [`AndroidManifest.xml`](~/android/platform/android-manifest.md) +`/manifest/@package` in the [`AndroidManifest.xml`](/xamarin/android/platform/android-manifest) file. To opt into this feature you must also enable `true`. This will be the default going forward in .NET 6. @@ -1640,12 +1384,10 @@ about the requirements for `/manifest/@package`. [manifest-element]: https://developer.android.com/guide/topics/manifest/manifest-element -Support for this property was added in Xamarin.Android 11.3. - ## ApplicationTitle An MSBuild property that can be used as an alternative to -`/manifest/application/@android:label` in the [`AndroidManifest.xml`](~/android/platform/android-manifest.md) +`/manifest/application/@android:label` in the [`AndroidManifest.xml`](/xamarin/android/platform/android-manifest) file. To opt into this feature you must also enable `true`. This will be the default going forward in .NET 6. @@ -1653,14 +1395,12 @@ This will be the default going forward in .NET 6. See the [Android documentation][application-element] for further details about the requirements for `/manifest/application/@android:label`. -Support for this property was added in Xamarin.Android 11.3. - [application-element]: https://developer.android.com/guide/topics/manifest/application-element ## ApplicationVersion An MSBuild property that can be used as an alternative to -`/manifest/@android:versionName` in the [`AndroidManifest.xml`](~/android/platform/android-manifest.md) +`/manifest/@android:versionName` in the [`AndroidManifest.xml`](/xamarin/android/platform/android-manifest) file. To opt into this feature you must also enable `true`. This will be the default going forward in .NET 6. @@ -1668,16 +1408,12 @@ This will be the default going forward in .NET 6. See the [Android documentation][manifest-element] for further details about the requirements for `/manifest/@android:versionName`. -Support for this property was added in Xamarin.Android 11.3. - ## AotAssemblies A boolean property that determines whether or not assemblies will be Ahead-of-Time compiled into native code and included in applications. This property is `False` by default. -Support for this property was added in Xamarin.Android 5.1. - Deprecated in .NET 7. Migrate to the new [`$(RunAOTCompilation)`](#runaotcompilation) MSBuild property instead, as support for `$(AotAssemblies)` will be removed in a future release. @@ -1698,8 +1434,6 @@ Added in .NET 9 MSBuild Targets listed in this property will run directly before `_GenerateJavaStubs`. -Added in Xamarin.Android 9.4. - ## Configuration Specifies the build configuration to use, @@ -1709,16 +1443,16 @@ other properties which determine target behavior. Additional configurations may be created within your IDE. *By default*, the `Debug` configuration will result in the -[`Install`](~/android/deploy-test/building-apps/build-targets.md#install) +[`Install`](build-targets.md#install) and -[`SignAndroidPackage`](~/android/deploy-test/building-apps/build-targets.md#signandroidpackage) +[`SignAndroidPackage`](build-targets.md#signandroidpackage) targets creating a smaller Android package which requires the presence of other files and packages to operate. The default `Release` configuration will result in the -[`Install`](~/android/deploy-test/building-apps/build-targets.md#install) +[`Install`](build-targets.md#install) and -[`SignAndroidPackage`](~/android/deploy-test/building-apps/build-targets.md#signandroidpackage) +[`SignAndroidPackage`](build-targets.md#signandroidpackage) targets creating an Android package which is *stand-alone*, and may be used without installing any other packages or files. @@ -1779,8 +1513,6 @@ into native code. The Android NDK must be installed to build a project that has this property enabled. -Support for this property was added in Xamarin.Android 5.1. - This property is `False` by default. This property is ignored unless the @@ -1792,29 +1524,24 @@ A boolean property that determines whether or not [proguard](https://developer.android.com/tools/help/proguard.html) is run as part of the packaging process to link Java code. -Support for this property was added in Xamarin.Android 5.1. - This property is `False` by default. When `True`, -[@(ProguardConfiguration)](~/android/deploy-test/building-apps/build-items.md#proguardconfiguration) +[@(ProguardConfiguration)](build-items.md#proguardconfiguration) files will be used to control `proguard` execution. ## GenerateApplicationManifest Enables or disables the following MSBuild properties that emit values -in the final [`AndroidManifest.xml`](~/android/platform/android-manifest.md) file: +in the final [`AndroidManifest.xml`](/xamarin/android/platform/android-manifest) file: - [`$(AndroidVersionCode)`](#androidversioncode) - [`$(ApplicationId)`](#applicationid) - [`$(ApplicationTitle)`](#applicationtitle) - [`$(ApplicationVersion)`](#applicationversion) -The default value `$(GenerateApplicationManifest)` is `true` in .NET 6 and -`false` in "legacy" Xamarin.Android. - -Support for this property was added in Xamarin.Android 11.3. +The default value `$(GenerateApplicationManifest)` is `true`. ## JavaMaximumHeapSize @@ -1881,84 +1608,7 @@ The default value is False. ## MandroidI18n -Specifies the internationalization support -included with the Application, such as collation and sorting -tables. The value is a comma- or semicolon-separated list of one or -more of the following case-insensitive values: - -- **None**: Include no additional encodings. - -- **All**: Include all available encodings. - -- **CJK**: Include Chinese, Japanese, and Korean encodings such as - *Japanese (EUC)* \[enc-jp, CP51932\], *Japanese (Shift-JIS)* - \[iso-2022-jp, shift\_jis, CP932\], *Japanese (JIS)* \[CP50220\], - *Chinese Simplified (GB2312)* \[gb2312, CP936\], *Korean (UHC)* - \[ks\_c\_5601-1987, CP949\], *Korean (EUC)* \[euc-kr, CP51949\], - *Chinese Traditional (Big5)* \[big5, CP950\], and *Chinese - Simplified (GB18030)* \[GB18030, CP54936\]. - -- **MidEast**: Include Middle-Eastern encodings such as *Turkish - (Windows)* \[iso-8859-9, CP1254\], *Hebrew (Windows)* - \[windows-1255, CP1255\], *Arabic (Windows)* \[windows-1256, - CP1256\], *Arabic (ISO)* \[iso-8859-6, CP28596\], *Hebrew (ISO)* - \[iso-8859-8, CP28598\], *Latin 5 (ISO)* \[iso-8859-9, CP28599\], - and *Hebrew (Iso Alternative)* \[iso-8859-8, CP38598\]. - -- **Other**: Include Other encodings such as *Cyrillic (Windows)* - \[CP1251\], *Baltic (Windows)* \[iso-8859-4, CP1257\], *Vietnamese - (Windows)* \[CP1258\], *Cyrillic (KOI8-R)* \[koi8-r, CP1251\], - *Ukrainian (KOI8-U)* \[koi8-u, CP1251\], *Baltic (ISO)* - \[iso-8859-4, CP1257\], *Cyrillic (ISO)* \[iso-8859-5, CP1251\], - *ISCII Davenagari* \[x-iscii-de, CP57002\], *ISCII Bengali* - \[x-iscii-be, CP57003\], *ISCII Tamil* \[x-iscii-ta, CP57004\], - *ISCII Telugu* \[x-iscii-te, CP57005\], *ISCII Assamese* - \[x-iscii-as, CP57006\], *ISCII Oriya* \[x-iscii-or, CP57007\], - *ISCII Kannada* \[x-iscii-ka, CP57008\], *ISCII Malayalam* - \[x-iscii-ma, CP57009\], *ISCII Gujarati* \[x-iscii-gu, CP57010\], - *ISCII Punjabi* \[x-iscii-pa, CP57011\], and *Thai (Windows)* - \[CP874\]. - -- **Rare**: Include Rare encodings such as *IBM EBCDIC (Turkish)* - \[CP1026\], *IBM EBCDIC (Open Systems Latin 1)* \[CP1047\], *IBM - EBCDIC (US-Canada with Euro)* \[CP1140\], *IBM EBCDIC (Germany with - Euro)* \[CP1141\], *IBM EBCDIC (Denmark/Norway with Euro)* - \[CP1142\], *IBM EBCDIC (Finland/Sweden with Euro)* \[CP1143\], - *IBM EBCDIC (Italy with Euro)* \[CP1144\], *IBM EBCDIC (Latin - America/Spain with Euro)* \[CP1145\], *IBM EBCDIC (United Kingdom - with Euro)* \[CP1146\], *IBM EBCDIC (France with Euro)* \[CP1147\], - *IBM EBCDIC (International with Euro)* \[CP1148\], *IBM EBCDIC - (Icelandic with Euro)* \[CP1149\], *IBM EBCDIC (Germany)* - \[CP20273\], *IBM EBCDIC (Denmark/Norway)* \[CP20277\], *IBM EBCDIC - (Finland/Sweden)* \[CP20278\], *IBM EBCDIC (Italy)* \[CP20280\], - *IBM EBCDIC (Latin America/Spain)* \[CP20284\], *IBM EBCDIC (United - Kingdom)* \[CP20285\], *IBM EBCDIC (Japanese Katakana Extended)* - \[CP20290\], *IBM EBCDIC (France)* \[CP20297\], *IBM EBCDIC - (Arabic)* \[CP20420\], *IBM EBCDIC (Hebrew)* \[CP20424\], *IBM - EBCDIC (Icelandic)* \[CP20871\], *IBM EBCDIC (Cyrillic - Serbian, - Bulgarian)* \[CP21025\], *IBM EBCDIC (US-Canada)* \[CP37\], *IBM - EBCDIC (International)* \[CP500\], *Arabic (ASMO 708)* \[CP708\], - *Central European (DOS)* \[CP852\]*, Cyrillic (DOS)* \[CP855\], - *Turkish (DOS)* \[CP857\], *Western European (DOS with Euro)* - \[CP858\], *Hebrew (DOS)* \[CP862\], *Arabic (DOS)* \[CP864\], - *Russian (DOS)* \[CP866\], *Greek (DOS)* \[CP869\], *IBM EBCDIC - (Latin 2)* \[CP870\], and *IBM EBCDIC (Greek)* \[CP875\]. - -- **West**: Include Western encodings such as *Western European - (Mac)* \[macintosh, CP10000\], *Icelandic (Mac)* \[x-mac-icelandic, - CP10079\], *Central European (Windows)* \[iso-8859-2, CP1250\], - *Western European (Windows)* \[iso-8859-1, CP1252\], *Greek - (Windows)* \[iso-8859-7, CP1253\], *Central European (ISO)* - \[iso-8859-2, CP28592\], *Latin 3 (ISO)* \[iso-8859-3, CP28593\], - *Greek (ISO)* \[iso-8859-7, CP28597\], *Latin 9 (ISO)* - \[iso-8859-15, CP28605\], *OEM United States* \[CP437\], *Western - European (DOS)* \[CP850\], *Portuguese (DOS)* \[CP860\], *Icelandic - (DOS)* \[CP861\], *French Canadian (DOS)* \[CP863\], and *Nordic - (DOS)* \[CP865\]. - -```xml -West -``` +This MSBuild property is obsolete and is no longer supported. ## MonoAndroidResourcePrefix @@ -1980,13 +1630,11 @@ number information from Release stack traces. This is True by default for “Release” apps which have debugging symbols enabled: [`$(EmbedAssembliesIntoApk)`](#embedassembliesintoapk) is True, -[`$(DebugSymbols)`](~/android/deploy-test/building-apps/build-properties.md#debugsymbols) +[`$(DebugSymbols)`](#debugsymbols) is True, and [`$(Optimize)`](/visualstudio/msbuild/common-msbuild-project-properties) is True. -Added in Xamarin.Android 7.1. - ## RunAOTCompilation A boolean property that determines whether or not assemblies will be @@ -1998,6 +1646,4 @@ This MSBuild property replaces the [`$(AotAssemblies)`](#aotassemblies) MSBuild property from Xamarin.Android. This is the same property used for [Blazor WASM][blazor]. -Added in .NET 6, not supported in Xamarin.Android. - -[blazor]: https://docs.microsoft.com/aspnet/core/blazor/host-and-deploy/webassembly/#ahead-of-time-aot-compilation +[blazor]: /aspnet/core/blazor/host-and-deploy/webassembly/#ahead-of-time-aot-compilation diff --git a/Documentation/guides/building-apps/build-targets.md b/Documentation/docs-mobile/building-apps/build-targets.md similarity index 74% rename from Documentation/guides/building-apps/build-targets.md rename to Documentation/docs-mobile/building-apps/build-targets.md index 4e62ceab39e..1bfd31d1310 100644 --- a/Documentation/guides/building-apps/build-targets.md +++ b/Documentation/docs-mobile/building-apps/build-targets.md @@ -1,17 +1,12 @@ --- -title: "Build Targets" -description: "This document will list all supported targets in the Xamarin.Android build process." -ms.prod: xamarin -ms.assetid: 17DE89FF-F316-4620-B865-EF6E0963A29C -ms.technology: xamarin-android -author: jonpryor -ms.author: jopryo -ms.date: 03/29/2022 +title: .NET for Android Build Targets +description: "This document will list all supported targets in the .NET for Android build process." +ms.date: 04/11/2024 --- # Build Targets -The following build targets are defined for Xamarin.Android projects. +The following build targets are defined in .NET for Android projects. ## Build @@ -20,7 +15,7 @@ Builds the source code within a project and all dependencies. This target *does not* create an Android package (`.apk` file). To create an Android package, use the [SignAndroidPackage](#signandroidpackage) target, *or* set the -[`$(AndroidBuildApplicationPackage)](~/android/deploy-test/building-apps/build-properties.md#androidbuildapplicationpackage) +[`$(AndroidBuildApplicationPackage)](build-properties.md#androidbuildapplicationpackage) property to True when building: ```shell @@ -30,7 +25,7 @@ msbuild /p:AndroidBuildApplicationPackage=True App.sln ## BuildAndStartAotProfiling Builds the app with an embedded AOT profiler, sets the profiler TCP port to -[`$(AndroidAotProfilerPort)`](~/android/deploy-test/building-apps/build-properties.md#androidaotprofilerport), +[`$(AndroidAotProfilerPort)`](build-properties.md#androidaotprofilerport), and starts the default activity. The default TCP port is `9999`. @@ -47,14 +42,14 @@ Must be called *after* the [BuildAndStartAotProfiling](#buildandstartaotprofilin target. Collects the AOT profiler data from the device or emulator through the TCP port -[`$(AndroidAotProfilerPort)`](~/android/deploy-test/building-apps/build-properties.md#androidaotprofilerport) +[`$(AndroidAotProfilerPort)`](build-properties.md#androidaotprofilerport) and writes them to -[`$(AndroidAotCustomProfilePath)`](~/android/deploy-test/building-apps/build-properties.md#androidaotcustomprofilepath). +[`$(AndroidAotCustomProfilePath)`](build-properties.md#androidaotcustomprofilepath). The default values for port and custom profile are `9999` and `custom.aprof`. To pass additional options to `aprofutil`, set them in the -[`$(AProfUtilExtraOptions)`](~/android/deploy-test/building-apps/build-properties.md#aprofutilextraoptions) +[`$(AProfUtilExtraOptions)`](build-properties.md#aprofutilextraoptions) property. This is equivalent to: @@ -76,7 +71,7 @@ which Android SDK packages to install. [Creates, signs](#signandroidpackage), and installs the Android package onto the default device or virtual device. -The [`$(AdbTarget)`](~/android/deploy-test/building-apps/build-properties.md#adbtarget) +The [`$(AdbTarget)`](build-properties.md#adbtarget) property specifies the Android target device the Android package may be installed to or removed from. @@ -95,7 +90,7 @@ the Android SDK packages specified in the `@(AndroidDependency)` item group. dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=" "-p:JavaSdkDirectory=" ``` -The `-f net8.0-android` is required as this target is a .NET Android specific target. If you omit this argument +The `-f net8.0-android` is required as this target is a .NET for Android specific target. If you omit this argument you will get the following error: ``` @@ -105,9 +100,9 @@ error MSB4057: The target "InstallAndroidDependencies" does not exist in the pro The `AndroidSdkDirectory` and `JavaSdkDirectory` properties are required as we need to know where to install the required components. These directories can be empty or existing. Sdk components will be installed on top on an existing sdk installation. -The [`$(AndroidManifestType)`](~/android/deploy-test/building-apps/build-properties.md#androidmanifesttype) +The [`$(AndroidManifestType)`](build-properties.md#androidmanifesttype) MSBuild property controls which -[Visual Studio SDK Manager repository](~/android/get-started/installation/android-sdk.md?tabs=windows#repository-selection) +[Visual Studio SDK Manager repository](/xamarin/android/get-started/installation/android-sdk?tabs=windows#repository-selection) is used for package name and package version detection, and URLs to download. ## RunWithLogging @@ -133,7 +128,7 @@ Use with `/p:Configuration=Release` to generate self-contained "Release" package Starts the default activity on the device or the running emulator. To start a different activity, set the -[`$(AndroidLaunchActivity)`](~/android/deploy-test/building-apps/build-properties.md#androidlaunchactivity) +[`$(AndroidLaunchActivity)`](build-properties.md#androidlaunchactivity) property to the activity name. This is equivalent to: @@ -160,7 +155,7 @@ Added in Xamarin.Android 10.2. Uninstalls the Android package from the default device or virtual device. -The [`$(AdbTarget)`](~/android/deploy-test/building-apps/build-properties.md#adbtarget) +The [`$(AdbTarget)`](build-properties.md#adbtarget) property specifies the Android target device the Android package may be installed to or removed from. diff --git a/Documentation/guides/LayoutCodeBehind.md b/Documentation/docs-mobile/features/layout-code-behind/index.md similarity index 81% rename from Documentation/guides/LayoutCodeBehind.md rename to Documentation/docs-mobile/features/layout-code-behind/index.md index ae4c5ed9ae7..909e6ba1305 100644 --- a/Documentation/guides/LayoutCodeBehind.md +++ b/Documentation/docs-mobile/features/layout-code-behind/index.md @@ -1,13 +1,14 @@ --- -id: 11763499-79e9-4868-83e6-41f3061745d1 -title: "Layout CodeBehind" -dateupdated: 2018-05-14 +title: Layout Code Behind in .NET for Android +description: Layout Code Behind in .NET for Android +ms.date: 04/11/2024 --- # Overview -The Xamarin.Android build processes [Android resources][android-res], exposing -[Android IDs][android-id] via a generated `Resource.designer.cs` file. +As part of the .NET for Android build, [Android resources][android-res] +are processed, exposing [Android IDs][android-id] via a generated +`_Microsoft.Android.Resource.Designer.dll` assembly. For example, given the file `Reources\layout\Main.axml` with contents: [android-res]: https://developer.android.com/guide/topics/resources/providing-resources @@ -28,17 +29,20 @@ For example, given the file `Reources\layout\Main.axml` with contents: ``` -Then during build-time a `Resource.designer.cs` file will be generated: +Then during build-time a `_Microsoft.Android.Resource.Designer.dll` assembly +with contents similar to: ```csharp +namespace _Microsoft.Android.Resource.Designer; + partial class Resource { partial class Id { - public const int myButton; - public const int log_fragment; - public const int secondary_log_fragment; + public static int myButton {get;} + public static int log_fragment {get;} + public static int secondary_log_fragment {get;} } partial class Layout { - public const int Main; + public static int Main {get;} } } ``` @@ -47,9 +51,7 @@ partial class Resource { constants from the `Resource` type and the `FindViewById()` method: ```csharp -class MainActivity : Activity { - - // Code omitted for brevity +partial class MainActivity : Activity { protected override void OnCreate (Bundle savedInstanceState) { @@ -69,11 +71,12 @@ with Android resources when using C#: 1. [Bindings](#resource-bindings) 2. [Code-Behind](#resource-codebehind) -To enable these new features, set the `$(AndroidGenerateLayoutBindings)` +To enable these new features, set the +[`$(AndroidGenerateLayoutBindings)`](../../building-apps/build-properties.md#androidgeneratelayoutbindings) MSBuild property to `True` either on the msbuild command line: -``` -msbuild /p:AndroidGenerateLayoutBindings=true MyProject.csproj +```dotnetcli +dotnet build -p:AndroidGenerateLayoutBindings=true MyProject.csproj ``` or in your .csproj file: @@ -84,9 +87,9 @@ or in your .csproj file: ``` - + -# Bindings +## Bindings A *binding* is a generated class, one per *Android layout file*, which contains strongly typed properties for all of the *ids* within the layout file. Binding @@ -137,16 +140,18 @@ namespace Binding { public Button myButton => FindView (global::Xamarin.Android.Tests.CodeBehindFew.Resource.Id.myButton, ref __myButton); CommonSampleLibrary.LogFragment __fragmentWithExplicitManagedType; - public CommonSampleLibrary.LogFragment fragmentWithExplicitManagedType => FindFragment (global::Xamarin.Android.Tests.CodeBehindFew.Resource.Id.fragmentWithExplicitManagedType, __fragmentWithExplicitManagedType, ref __fragmentWithExplicitManagedType); + public CommonSampleLibrary.LogFragment fragmentWithExplicitManagedType => + FindFragment (global::Xamarin.Android.Tests.CodeBehindFew.Resource.Id.fragmentWithExplicitManagedType, __fragmentWithExplicitManagedType, ref __fragmentWithExplicitManagedType); global::Android.App.Fragment __fragmentWithInferredType; - public global::Android.App.Fragment fragmentWithInferredType => FindFragment (global::Xamarin.Android.Tests.CodeBehindFew.Resource.Id.fragmentWithInferredType, __fragmentWithInferredType, ref __fragmentWithInferredType); + public global::Android.App.Fragment fragmentWithInferredType => + FindFragment (global::Xamarin.Android.Tests.CodeBehindFew.Resource.Id.fragmentWithInferredType, __fragmentWithInferredType, ref __fragmentWithInferredType); } } ``` The binding's base type, `Xamarin.Android.Design.LayoutBinding` is **not** part of the -Xamarin.Android class library but rather shipped with Xamarin.Android in source form +.NET for Android class library but rather shipped with .NET for Android in source form and included in the application's build automatically whenever bindings are used. The generated binding type can be created around `Activity` instances, allowing @@ -154,9 +159,7 @@ for strongly-typed access to IDs within the layout file: ```csharp // User-written code -class MainActivity : Activity { - - // Code omitted for brevity +partial class MainActivity : Activity { protected override void OnCreate (Bundle savedInstanceState) { @@ -179,7 +182,7 @@ strongly-typed access to Resource IDs *within* the View or its children: var binding = new Binding.Main (some_view); ``` -## Missing Resource IDs +### Missing Resource IDs Properties on binding types still use `FindViewById()` in their implementation. If `FindViewById()` returns `null`, then the default @@ -191,11 +194,9 @@ the generated binding on its instantiation: ```csharp // User-written code -class MainActivity : Activity { - - // Code omitted for brevity +partial class MainActivity : Activity { - Java.Lang.Object OnLayoutItemNotFound (int resourceId, Type expectedViewType) + Java.Lang.Object? OnLayoutItemNotFound (int resourceId, Type expectedViewType) { // Find and return the View or Fragment identified by `resourceId` // or `null` if unknown @@ -222,16 +223,16 @@ of the corresponding Binding property. The returned value is cast to that type, isn't correctly typed an exception will be thrown. - + -# Code-Behind +## Code-Behind Code-Behind involves build-time generation of a `partial` class which contains strongly typed properties for all of the *ids* within the layout file. Code-Behind builds atop the Binding mechanism, while requiring that layout files "opt-in" to Code-Behind generation by using the new -[`xamarin:classes`](#xamarin:classes) XML attribute, which is a `;`-separated +[`xamarin:classes`](#attr-xamarin-classes) XML attribute, which is a `;`-separated list of full class names to be generated. Given the Android Layout file `Resources\layout\Main.axml`: @@ -264,15 +265,15 @@ namespace Example { public override void SetContentView (global::Android.Views.View view); void SetContentView (global::Android.Views.View view, - global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound); + global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound); public override void SetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params); void SetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params, - global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound); + global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound); public override void SetContentView (int layoutResID); void SetContentView (int layoutResID, - global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound); + global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound); partial void OnSetContentView (global::Android.Views.View view, ref bool callBaseAfterReturn); partial void OnSetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params, ref bool callBaseAfterReturn); @@ -308,13 +309,6 @@ of `SetContentView` the activity is using: ```csharp // User-written code -Java.Lang.Object OnLayoutItemNotFound (int resourceId, Type expectedViewType) -{ - // Find and return the View or Fragment identified by `resourceId` - // or `null` if unknown - return null; -} - partial class MainActivity : Activity { protected override void OnCreate (Bundle savedInstanceState) { @@ -322,6 +316,13 @@ partial class MainActivity : Activity { SetContentView (Resource.Layout.Main, OnLayoutItemNotFound); } + + Java.Lang.Object? OnLayoutItemNotFound (int resourceId, Type expectedViewType) + { + // Find and return the View or Fragment identified by `resourceId` + // or `null` if unknown + return null; + } } ``` @@ -329,9 +330,9 @@ As Code-Behind relies on partial classes, *all* declarations of a partial class *must* use `partial class` in their declaration, otherwise a [CS0260][cs0260] C# compiler error will be generated at build time. -[cs0260]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/cs0260 +[cs0260]: /dotnet/csharp/language-reference/compiler-messages/cs0260 -## Customization +### Customization The generated Code Behind type *always* overrides `Activity.SetContentView()`, and by default it *always* calls `base.SetContentView()`, forwarding the @@ -351,7 +352,7 @@ namespace Example } ``` -## Example Generated Code +### Example Generated Code ```csharp // Generated code @@ -359,9 +360,10 @@ namespace Example { partial class MainActivity { - Binding.Main __layout_binding; + Binding.Main? __layout_binding; - public override void SetContentView (global::Android.Views.View view) { + public override void SetContentView (global::Android.Views.View view) + { __layout_binding = new global::Binding.Main (view); bool callBase = true; OnSetContentView (view, ref callBase); @@ -370,7 +372,8 @@ namespace Example } } - void SetContentView (global::Android.Views.View view, global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound) { + void SetContentView (global::Android.Views.View view, global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound) + { __layout_binding = new global::Binding.Main (view, onLayoutItemNotFound); bool callBase = true; OnSetContentView (view, ref callBase); @@ -379,7 +382,8 @@ namespace Example } } - public override void SetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params) { + public override void SetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params) + { __layout_binding = new global::Binding.Main (view); bool callBase = true; OnSetContentView (view, @params, ref callBase); @@ -388,7 +392,8 @@ namespace Example } } - void SetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params, global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound) { + void SetContentView (global::Android.Views.View view, global::Android.Views.ViewGroup.LayoutParams @params, global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound) + { __layout_binding = new global::Binding.Main (view, onLayoutItemNotFound); bool callBase = true; OnSetContentView (view, @params, ref callBase); @@ -397,7 +402,8 @@ namespace Example } } - public override void SetContentView (int layoutResID) { + public override void SetContentView (int layoutResID) + { __layout_binding = new global::Binding.Main (this); bool callBase = true; OnSetContentView (layoutResID, ref callBase); @@ -406,7 +412,8 @@ namespace Example } } - void SetContentView (int layoutResID, global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound) { + void SetContentView (int layoutResID, global::Xamarin.Android.Design.LayoutBinding.OnLayoutItemNotFoundHandler onLayoutItemNotFound) + { __layout_binding = new global::Binding.Main (this, onLayoutItemNotFound); bool callBase = true; OnSetContentView (layoutResID, ref callBase); @@ -427,7 +434,7 @@ namespace Example ``` -# Layout XML Attributes +## Layout XML Attributes Many new Layout XML attributes control Binding and Code-Behind behavior, which are within the `xamarin` XML namespace @@ -440,7 +447,7 @@ These include: -## `xamarin:classes` +### `xamarin:classes` The `xamarin:classes` XML attribute is used as part of [Code-Behind](#resource-codebehind) to specify which types should be generated. @@ -449,9 +456,9 @@ The `xamarin:classes` XML attribute contains a `;`-separated list of *full class names* that should be generated. - + -## `xamarin:managedType` +### `xamarin:managedType` The `xamarin:managedType` layout attribute is used to explicitly specify the managed type to expose the bound ID as. If not specified, the type will be @@ -462,7 +469,7 @@ inferred from the declaring context, e.g. `