From 51f1e4c904cb68958ef51c5e152f6d09753b0058 Mon Sep 17 00:00:00 2001 From: redth Date: Tue, 16 Jun 2026 16:26:34 -0400 Subject: [PATCH 01/10] Document Android package output items Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/TOC.yml | 2 + docs/android/building-apps/build-items.md | 41 +++++- docs/android/building-apps/build-process.md | 17 ++- docs/android/building-apps/build-targets.md | 18 ++- docs/android/building-apps/package-outputs.md | 119 ++++++++++++++++++ 5 files changed, 191 insertions(+), 6 deletions(-) create mode 100644 docs/android/building-apps/package-outputs.md diff --git a/docs/android/TOC.yml b/docs/android/TOC.yml index 9a042b8..6eebea6 100644 --- a/docs/android/TOC.yml +++ b/docs/android/TOC.yml @@ -14,6 +14,8 @@ items: - name: Build process href: building-apps/build-process.md + - name: Discover package outputs + href: building-apps/package-outputs.md - name: Build targets href: building-apps/build-targets.md - name: Build properties diff --git a/docs/android/building-apps/build-items.md b/docs/android/building-apps/build-items.md index 02b7f05..cdd867a 100644 --- a/docs/android/building-apps/build-items.md +++ b/docs/android/building-apps/build-items.md @@ -1,7 +1,7 @@ --- title: .NET for Android Build Items description: .NET for Android Build Items -ms.date: 09/09/2024 +ms.date: 06/16/2026 --- # Build items @@ -15,6 +15,45 @@ an [MSBuild ItemGroup](/visualstudio/msbuild/itemgroup-element-msbuild). > [!NOTE] > In .NET for Android there is technically no distinction between an application and a bindings project, so build items will work in both. In practice it is highly recommended to create separate application and bindings projects. Build items that are primarily used in bindings projects are documented in the [MSBuild bindings project items](../binding-libs/msbuild-reference/build-items.md) reference guide. +## AndroidPackageOutput + +`@(AndroidPackageOutput)` contains the final Android package files produced +in the build output directory by the package and signing targets. This item +group can be used by custom MSBuild targets to discover APK and Android App +Bundle outputs without recalculating the final file names. + +This item group is available in .NET 11 and later. + +Each item includes the following metadata: + +- `%(PackageFormat)`: `apk` or `aab`. +- `%(Signed)`: `true` when the package is signed. +- `%(PackageId)`: The resolved Android package name. +- `%(RuntimeIdentifier)`: The current runtime identifier, if any. +- `%(TargetFramework)`: The current target framework. +- `%(Configuration)`: The current configuration. +- `%(AndroidPackageFormat)`: The effective primary package format. +- `%(AndroidPackageFormats)`: The requested package formats. +- `%(IsUniversal)`: `true` for the signed universal APK generated from an Android App Bundle. +- `%(SourcePackageFormat)`: The package format that produced the item. +- `%(RelativePath)`: The output file name. + +For examples that write these items to files or CI outputs, see +[Discover Android package outputs](package-outputs.md). + +## AndroidPublishedPackageOutput + +`@(AndroidPublishedPackageOutput)` contains the Android package files copied +to the publish directory by `dotnet publish`. It preserves the metadata from +`@(AndroidPackageOutput)` and adds: + +- `%(OriginalPath)`: The corresponding build output artifact before publish copy. + +This item group is available in .NET 11 and later. + +For examples that write these items to files or CI outputs, see +[Discover Android package outputs](package-outputs.md). + ## AndroidAdditionalJavaManifest `` is used in conjunction with diff --git a/docs/android/building-apps/build-process.md b/docs/android/building-apps/build-process.md index ee9fc49..97b0bf6 100644 --- a/docs/android/building-apps/build-process.md +++ b/docs/android/building-apps/build-process.md @@ -1,7 +1,7 @@ --- title: .NET for Android Build Process description: .NET for Android Build Process -ms.date: 04/11/2024 +ms.date: 06/16/2026 --- # Build process @@ -15,12 +15,13 @@ supporting the and other [build actions](build-items.md), generating [Android-callable wrappers](/xamarin/android/platform/java-integration/android-callable-wrappers), -and generating a `.apk` for execution on Android devices. +and generating an APK or Android App Bundle (AAB) for execution on Android +devices or distribution through an app store. ## Application packages -In broad terms, there are two types of Android application packages -(`.apk` files) which the .NET for Android build system can generate: +In broad terms, there are two types of Android application packages 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 @@ -31,6 +32,14 @@ In broad terms, there are two types of Android application packages These package types match the MSBuild `Configuration` which produces the package. +Package file names, formats, and publish paths are resolved during the +MSBuild target execution. To discover the final package artifacts from a +custom target or CI workflow, use the +[`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) and +[`@(AndroidPublishedPackageOutput)`](build-items.md#androidpublishedpackageoutput) +item groups. For more information, see +[Discover Android package outputs](package-outputs.md). + ## Fast deployment diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index bd43e2d..a129ac4 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -1,7 +1,7 @@ --- 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 +ms.date: 06/16/2026 --- # Build targets @@ -96,6 +96,19 @@ Creates the `@(AndroidDependency)` item group, which is used by the [`InstallAndroidDependencies`](#installandroiddependencies) target to determine which Android SDK packages to install. +## GetAndroidPackageOutputs + +Creates and returns the +[`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) item group, +which contains the APK and Android App Bundle files produced in the build +output directory. + +This target depends on [`SignAndroidPackage`](#signandroidpackage), so it can +be used when a custom target needs the resolved package output paths and +metadata without running `dotnet publish`. + +This target is available in .NET 11 and later. + ## Install [Creates, signs](#signandroidpackage), and installs the Android package onto @@ -153,6 +166,9 @@ Creates and signs the Android package (`.apk`) file. Use with `/p:Configuration=Release` to generate self-contained "Release" packages. +Package files created by this target are available in the +[`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) item group. + ## StartAndroidActivity Starts the default activity on the device or the running emulator. diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md new file mode 100644 index 0000000..9145c5f --- /dev/null +++ b/docs/android/building-apps/package-outputs.md @@ -0,0 +1,119 @@ +--- +title: Discover Android package outputs +description: Learn how to discover APK and Android App Bundle outputs from .NET for Android MSBuild targets. +ms.date: 06/16/2026 +--- + +# Discover Android package outputs + +When a .NET for Android project creates an APK or Android App Bundle (AAB), the final +file names and paths are resolved during the MSBuild target execution. They can depend +on properties such as [`$(AndroidPackageFormats)`](build-properties.md#androidpackageformats), +`$(Configuration)`, `$(RuntimeIdentifier)`, `$(OutputPath)`, `$(PublishDir)`, and whether +the package is signed. + +Starting in .NET 11, instead of recalculating those paths in a custom target or +CI script, consume the package output item groups that are populated by the +.NET for Android build: + +- [`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) contains package files + produced in the build output directory. +- [`@(AndroidPublishedPackageOutput)`](build-items.md#androidpublishedpackageoutput) + contains package files copied to the publish directory by `dotnet publish`. + +These item groups include metadata such as the package format, whether the package is +signed, and whether an APK is the universal APK generated from an Android App Bundle. + +## Capture outputs after package signing + +Use `@(AndroidPackageOutput)` from a target that runs after +[`SignAndroidPackage`](build-targets.md#signandroidpackage), or call +[`GetAndroidPackageOutputs`](build-targets.md#getandroidpackageoutputs) from another target. + +For example, the following target writes the build output package paths and selected +metadata to a text file: + +```xml + + + + + +``` + +## Capture outputs after publish + +Use `@(AndroidPublishedPackageOutput)` from a target that runs after `Publish` when you +need the final files in `$(PublishDir)`: + +```xml + + + + + +``` + +`@(AndroidPublishedPackageOutput)` preserves the metadata from `@(AndroidPackageOutput)` +and adds `%(OriginalPath)`, which points to the corresponding artifact before it was +copied to the publish directory. + +## Emit GitHub Actions outputs + +In GitHub Actions, a custom target can append selected package paths to the file named by +the `GITHUB_OUTPUT` environment variable: + +```xml + + + + <_SignedApk Include="@(AndroidPublishedPackageOutput)" + Condition="'%(PackageFormat)' == 'apk' and '%(Signed)' == 'true'" /> + <_SignedAab Include="@(AndroidPublishedPackageOutput)" + Condition="'%(PackageFormat)' == 'aab' and '%(Signed)' == 'true'" /> + + + + + + +``` + +This pattern lets later workflow steps upload or deploy the resolved packages without +hardcoding the package naming convention. For JSON, YAML, or other structured manifests, +pass `@(AndroidPublishedPackageOutput)` to a custom task or script and serialize the +metadata needed by your pipeline. + +## Package output metadata + +The package output item metadata provides the values most commonly needed by custom +targets and CI systems: + +| Metadata | Description | +| --- | --- | +| `%(PackageFormat)` | `apk` or `aab`. | +| `%(Signed)` | `true` when the package is signed. | +| `%(PackageId)` | The resolved Android package name. | +| `%(RuntimeIdentifier)` | The current runtime identifier, if any. | +| `%(TargetFramework)` | The current target framework. | +| `%(Configuration)` | The current build configuration. | +| `%(AndroidPackageFormat)` | The effective primary package format. | +| `%(AndroidPackageFormats)` | The requested package formats. | +| `%(IsUniversal)` | `true` for the signed universal APK generated from an Android App Bundle. | +| `%(SourcePackageFormat)` | The package format that produced the item. | +| `%(RelativePath)` | The output file name. | +| `%(OriginalPath)` | On published items, the corresponding build output artifact before publish copy. | From 90b97ccd114a0bde90293c4833ad3693be0d1bbb Mon Sep 17 00:00:00 2001 From: redth Date: Tue, 16 Jun 2026 18:35:11 -0400 Subject: [PATCH 02/10] Update Android artifact item docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-items.md | 37 ++++-------- docs/android/building-apps/build-process.md | 5 +- docs/android/building-apps/build-targets.md | 6 +- docs/android/building-apps/package-outputs.md | 56 +++++++------------ 4 files changed, 37 insertions(+), 67 deletions(-) diff --git a/docs/android/building-apps/build-items.md b/docs/android/building-apps/build-items.md index cdd867a..ae62884 100644 --- a/docs/android/building-apps/build-items.md +++ b/docs/android/building-apps/build-items.md @@ -15,12 +15,14 @@ an [MSBuild ItemGroup](/visualstudio/msbuild/itemgroup-element-msbuild). > [!NOTE] > In .NET for Android there is technically no distinction between an application and a bindings project, so build items will work in both. In practice it is highly recommended to create separate application and bindings projects. Build items that are primarily used in bindings projects are documented in the [MSBuild bindings project items](../binding-libs/msbuild-reference/build-items.md) reference guide. -## AndroidPackageOutput +## ApplicationArtifact -`@(AndroidPackageOutput)` contains the final Android package files produced -in the build output directory by the package and signing targets. This item -group can be used by custom MSBuild targets to discover APK and Android App -Bundle outputs without recalculating the final file names. +`@(ApplicationArtifact)` contains the final application artifact files +produced by package, signing, and publish targets. This item group can be +used by custom MSBuild targets to discover APK and Android App Bundle outputs +without recalculating the final file names. .NET for Android populates this +item group with Android-specific artifacts, and other .NET mobile platforms +can use the same item name for their final application artifacts. This item group is available in .NET 11 and later. @@ -29,27 +31,12 @@ Each item includes the following metadata: - `%(PackageFormat)`: `apk` or `aab`. - `%(Signed)`: `true` when the package is signed. - `%(PackageId)`: The resolved Android package name. -- `%(RuntimeIdentifier)`: The current runtime identifier, if any. -- `%(TargetFramework)`: The current target framework. -- `%(Configuration)`: The current configuration. -- `%(AndroidPackageFormat)`: The effective primary package format. -- `%(AndroidPackageFormats)`: The requested package formats. -- `%(IsUniversal)`: `true` for the signed universal APK generated from an Android App Bundle. -- `%(SourcePackageFormat)`: The package format that produced the item. -- `%(RelativePath)`: The output file name. +- `%(Abi)`: The Android ABI for a per-ABI APK output. This metadata is only + set for per-ABI APKs. -For examples that write these items to files or CI outputs, see -[Discover Android package outputs](package-outputs.md). - -## AndroidPublishedPackageOutput - -`@(AndroidPublishedPackageOutput)` contains the Android package files copied -to the publish directory by `dotnet publish`. It preserves the metadata from -`@(AndroidPackageOutput)` and adds: - -- `%(OriginalPath)`: The corresponding build output artifact before publish copy. - -This item group is available in .NET 11 and later. +MSBuild also provides well-known metadata for each item. For example, +`%(Filename)%(Extension)` is the package file name and `%(FullPath)` is the +full package path. For examples that write these items to files or CI outputs, see [Discover Android package outputs](package-outputs.md). diff --git a/docs/android/building-apps/build-process.md b/docs/android/building-apps/build-process.md index 97b0bf6..420353b 100644 --- a/docs/android/building-apps/build-process.md +++ b/docs/android/building-apps/build-process.md @@ -35,9 +35,8 @@ produces the package. Package file names, formats, and publish paths are resolved during the MSBuild target execution. To discover the final package artifacts from a custom target or CI workflow, use the -[`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) and -[`@(AndroidPublishedPackageOutput)`](build-items.md#androidpublishedpackageoutput) -item groups. For more information, see +[`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group. +For more information, see [Discover Android package outputs](package-outputs.md). diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index a129ac4..5b11ab6 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -96,10 +96,10 @@ Creates the `@(AndroidDependency)` item group, which is used by the [`InstallAndroidDependencies`](#installandroiddependencies) target to determine which Android SDK packages to install. -## GetAndroidPackageOutputs +## GetApplicationArtifacts Creates and returns the -[`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) item group, +[`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group, which contains the APK and Android App Bundle files produced in the build output directory. @@ -167,7 +167,7 @@ Creates and signs the Android package (`.apk`) file. Use with `/p:Configuration=Release` to generate self-contained "Release" packages. Package files created by this target are available in the -[`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) item group. +[`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group. ## StartAndroidActivity diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md index 9145c5f..c92270d 100644 --- a/docs/android/building-apps/package-outputs.md +++ b/docs/android/building-apps/package-outputs.md @@ -13,32 +13,27 @@ on properties such as [`$(AndroidPackageFormats)`](build-properties.md#androidpa the package is signed. Starting in .NET 11, instead of recalculating those paths in a custom target or -CI script, consume the package output item groups that are populated by the -.NET for Android build: +CI script, consume the [`@(ApplicationArtifact)`](build-items.md#applicationartifact) +item group that is populated by the .NET for Android build. -- [`@(AndroidPackageOutput)`](build-items.md#androidpackageoutput) contains package files - produced in the build output directory. -- [`@(AndroidPublishedPackageOutput)`](build-items.md#androidpublishedpackageoutput) - contains package files copied to the publish directory by `dotnet publish`. - -These item groups include metadata such as the package format, whether the package is -signed, and whether an APK is the universal APK generated from an Android App Bundle. +This item group includes metadata such as the package format, whether the package is +signed, the resolved package ID, and the ABI for per-ABI APKs. ## Capture outputs after package signing -Use `@(AndroidPackageOutput)` from a target that runs after +Use `@(ApplicationArtifact)` from a target that runs after [`SignAndroidPackage`](build-targets.md#signandroidpackage), or call -[`GetAndroidPackageOutputs`](build-targets.md#getandroidpackageoutputs) from another target. +[`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) from another target. For example, the following target writes the build output package paths and selected metadata to a text file: ```xml - + @@ -46,24 +41,21 @@ metadata to a text file: ## Capture outputs after publish -Use `@(AndroidPublishedPackageOutput)` from a target that runs after `Publish` when you -need the final files in `$(PublishDir)`: +Use `@(ApplicationArtifact)` from a target that runs after `Publish` when you need the +final files in `$(PublishDir)`. During publish, .NET for Android updates the item +identities to the copied publish-directory paths while preserving package metadata: ```xml - + ``` -`@(AndroidPublishedPackageOutput)` preserves the metadata from `@(AndroidPackageOutput)` -and adds `%(OriginalPath)`, which points to the corresponding artifact before it was -copied to the publish directory. - ## Emit GitHub Actions outputs In GitHub Actions, a custom target can append selected package paths to the file named by @@ -71,13 +63,13 @@ the `GITHUB_OUTPUT` environment variable: ```xml - - <_SignedApk Include="@(AndroidPublishedPackageOutput)" + <_SignedApk Include="@(ApplicationArtifact)" Condition="'%(PackageFormat)' == 'apk' and '%(Signed)' == 'true'" /> - <_SignedAab Include="@(AndroidPublishedPackageOutput)" + <_SignedAab Include="@(ApplicationArtifact)" Condition="'%(PackageFormat)' == 'aab' and '%(Signed)' == 'true'" /> @@ -95,7 +87,7 @@ the `GITHUB_OUTPUT` environment variable: This pattern lets later workflow steps upload or deploy the resolved packages without hardcoding the package naming convention. For JSON, YAML, or other structured manifests, -pass `@(AndroidPublishedPackageOutput)` to a custom task or script and serialize the +pass `@(ApplicationArtifact)` to a custom task or script and serialize the metadata needed by your pipeline. ## Package output metadata @@ -108,12 +100,4 @@ targets and CI systems: | `%(PackageFormat)` | `apk` or `aab`. | | `%(Signed)` | `true` when the package is signed. | | `%(PackageId)` | The resolved Android package name. | -| `%(RuntimeIdentifier)` | The current runtime identifier, if any. | -| `%(TargetFramework)` | The current target framework. | -| `%(Configuration)` | The current build configuration. | -| `%(AndroidPackageFormat)` | The effective primary package format. | -| `%(AndroidPackageFormats)` | The requested package formats. | -| `%(IsUniversal)` | `true` for the signed universal APK generated from an Android App Bundle. | -| `%(SourcePackageFormat)` | The package format that produced the item. | -| `%(RelativePath)` | The output file name. | -| `%(OriginalPath)` | On published items, the corresponding build output artifact before publish copy. | +| `%(Abi)` | The Android ABI for per-ABI APK outputs. This metadata is omitted for non-per-ABI outputs. | From 04d5d5072cb36e26d050825b8b7f0ac827547be7 Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 09:15:17 -0400 Subject: [PATCH 03/10] Document application artifact extension point Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-items.md | 3 +++ docs/android/building-apps/build-targets.md | 10 ++++---- docs/android/building-apps/package-outputs.md | 24 +++++++++++++++++++ 3 files changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/android/building-apps/build-items.md b/docs/android/building-apps/build-items.md index ae62884..f331616 100644 --- a/docs/android/building-apps/build-items.md +++ b/docs/android/building-apps/build-items.md @@ -38,6 +38,9 @@ MSBuild also provides well-known metadata for each item. For example, `%(Filename)%(Extension)` is the package file name and `%(FullPath)` is the full package path. +Use the [`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) +target when another target needs to query the application artifacts directly. + For examples that write these items to files or CI outputs, see [Discover Android package outputs](package-outputs.md). diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index 5b11ab6..cf09cf0 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -100,12 +100,12 @@ which Android SDK packages to install. Creates and returns the [`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group, -which contains the APK and Android App Bundle files produced in the build -output directory. +which contains the APK and Android App Bundle files produced by the build. -This target depends on [`SignAndroidPackage`](#signandroidpackage), so it can -be used when a custom target needs the resolved package output paths and -metadata without running `dotnet publish`. +This target depends on `$(GetApplicationArtifactsDependsOn)`, which defaults to +`Build;$(GetApplicationArtifactsDependsOn)`. Later imports can append targets to +`$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` +metadata before the target returns the items. This target is available in .NET 11 and later. diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md index c92270d..c242151 100644 --- a/docs/android/building-apps/package-outputs.md +++ b/docs/android/building-apps/package-outputs.md @@ -39,6 +39,30 @@ metadata to a text file: ``` +## Extend application artifact metadata + +Targets imported after .NET for Android can append to +`$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` +before [`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) +returns the items. For example: + +```xml + + + + $(GetApplicationArtifactsDependsOn); + AddCustomApplicationArtifactMetadata + + + + + + + + + +``` + ## Capture outputs after publish Use `@(ApplicationArtifact)` from a target that runs after `Publish` when you need the From ece96440d9e01889238d44263b9e4a14ef5ed0fa Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 10:12:33 -0400 Subject: [PATCH 04/10] Document publish artifact extensions Clarify that GetApplicationArtifactsDependsOn enrichment applies before both GetApplicationArtifacts and Publish return ApplicationArtifact items. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-items.md | 2 ++ docs/android/building-apps/build-targets.md | 2 +- docs/android/building-apps/package-outputs.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/android/building-apps/build-items.md b/docs/android/building-apps/build-items.md index f331616..5d4047a 100644 --- a/docs/android/building-apps/build-items.md +++ b/docs/android/building-apps/build-items.md @@ -40,6 +40,8 @@ full package path. Use the [`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) target when another target needs to query the application artifacts directly. +Targets appended to `$(GetApplicationArtifactsDependsOn)` can enrich the item +metadata before `GetApplicationArtifacts` or `Publish` returns the items. For examples that write these items to files or CI outputs, see [Discover Android package outputs](package-outputs.md). diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index cf09cf0..38f3605 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -105,7 +105,7 @@ which contains the APK and Android App Bundle files produced by the build. This target depends on `$(GetApplicationArtifactsDependsOn)`, which defaults to `Build;$(GetApplicationArtifactsDependsOn)`. Later imports can append targets to `$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` -metadata before the target returns the items. +metadata before this target or the `Publish` target returns the items. This target is available in .NET 11 and later. diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md index c242151..ec36dcb 100644 --- a/docs/android/building-apps/package-outputs.md +++ b/docs/android/building-apps/package-outputs.md @@ -44,7 +44,7 @@ metadata to a text file: Targets imported after .NET for Android can append to `$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` before [`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) -returns the items. For example: +or `Publish` returns the items. For example: ```xml From a49146981f191742e0cee16e3a536826c64e9332 Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 10:59:49 -0400 Subject: [PATCH 05/10] Document application artifact query targets Add command-line target-result examples for GetApplicationArtifacts and Publish so callers can discover returned ApplicationArtifact items from the documented target surface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-targets.md | 32 +++++++++++++++++++ docs/android/building-apps/package-outputs.md | 17 ++++++++++ 2 files changed, 49 insertions(+) diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index 38f3605..a54c2a9 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -107,6 +107,20 @@ This target depends on `$(GetApplicationArtifactsDependsOn)`, which defaults to `$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` metadata before this target or the `Publish` target returns the items. +Call this target directly when a CI job or custom tool needs the build output +artifact paths: + +```shell +dotnet msbuild MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts +``` + +Use the `Publish` target result when the caller needs the copied publish +outputs in `$(PublishDir)`: + +```shell +dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish +``` + This target is available in .NET 11 and later. ## Install @@ -148,6 +162,24 @@ MSBuild property controls which [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. +## Publish + +Builds the application, copies final APK and Android App Bundle files to +`$(PublishDir)`, and returns the +[`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group. +Returned items use the copied publish-directory paths and preserve artifact +metadata such as `%(PackageFormat)`, `%(Signed)`, `%(PackageId)`, and `%(Abi)`. + +Targets appended to `$(GetApplicationArtifactsDependsOn)` run before `Publish` +calculates publish files and before `Publish` returns `@(ApplicationArtifact)`, +so later imports can enrich artifact metadata for publish callers. + +For example, to query the published artifacts: + +```shell +dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish +``` + ## RunWithLogging Runs the application with additional logging enabled. Helpful when reporting or investigating an issue with diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md index ec36dcb..8853139 100644 --- a/docs/android/building-apps/package-outputs.md +++ b/docs/android/building-apps/package-outputs.md @@ -39,6 +39,23 @@ metadata to a text file: ``` +## Query outputs from the command line + +Use the callable +[`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) target +when a CI job or custom tool needs the build output artifact paths: + +```shell +dotnet msbuild MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts +``` + +Use the `Publish` target result when the caller needs the copied publish +outputs in `$(PublishDir)`: + +```shell +dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish +``` + ## Extend application artifact metadata Targets imported after .NET for Android can append to From 48c357bd778ba810790d42d5c7afcf45c59d2bae Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 11:49:23 -0400 Subject: [PATCH 06/10] Clarify application artifact enrichment docs State that GetApplicationArtifactsDependsOn extension targets run after platform ApplicationArtifact items are populated so later imports can update existing items with additional metadata. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-items.md | 5 +++-- docs/android/building-apps/build-targets.md | 17 +++++++++++------ docs/android/building-apps/package-outputs.md | 11 +++++++---- 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/android/building-apps/build-items.md b/docs/android/building-apps/build-items.md index 5d4047a..3b61bf3 100644 --- a/docs/android/building-apps/build-items.md +++ b/docs/android/building-apps/build-items.md @@ -40,8 +40,9 @@ full package path. Use the [`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) target when another target needs to query the application artifacts directly. -Targets appended to `$(GetApplicationArtifactsDependsOn)` can enrich the item -metadata before `GetApplicationArtifacts` or `Publish` returns the items. +Targets appended to `$(GetApplicationArtifactsDependsOn)` run after .NET for +Android populates this item group, so they can update the existing items with +additional metadata before `GetApplicationArtifacts` or `Publish` returns them. For examples that write these items to files or CI outputs, see [Discover Android package outputs](package-outputs.md). diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index a54c2a9..534353e 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -103,9 +103,11 @@ Creates and returns the which contains the APK and Android App Bundle files produced by the build. This target depends on `$(GetApplicationArtifactsDependsOn)`, which defaults to -`Build;$(GetApplicationArtifactsDependsOn)`. Later imports can append targets to -`$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` -metadata before this target or the `Publish` target returns the items. +`Build;$(GetApplicationArtifactsDependsOn)`. The `Build` target populates +`@(ApplicationArtifact)` with the platform-produced artifacts, then later +imports can append targets to `$(GetApplicationArtifactsDependsOn)` to update +those existing items with additional metadata before this target or the +`Publish` target returns them. Call this target directly when a CI job or custom tool needs the build output artifact paths: @@ -170,9 +172,12 @@ Builds the application, copies final APK and Android App Bundle files to Returned items use the copied publish-directory paths and preserve artifact metadata such as `%(PackageFormat)`, `%(Signed)`, `%(PackageId)`, and `%(Abi)`. -Targets appended to `$(GetApplicationArtifactsDependsOn)` run before `Publish` -calculates publish files and before `Publish` returns `@(ApplicationArtifact)`, -so later imports can enrich artifact metadata for publish callers. +`Publish` first runs `GetApplicationArtifacts`, which builds the project and +populates `@(ApplicationArtifact)` with the platform-produced artifacts. Targets +appended to `$(GetApplicationArtifactsDependsOn)` then run against those +existing items before `Publish` calculates publish files and before `Publish` +returns `@(ApplicationArtifact)`, so later imports can add metadata for publish +callers. For example, to query the published artifacts: diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md index 8853139..a023729 100644 --- a/docs/android/building-apps/package-outputs.md +++ b/docs/android/building-apps/package-outputs.md @@ -59,9 +59,11 @@ dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish ## Extend application artifact metadata Targets imported after .NET for Android can append to -`$(GetApplicationArtifactsDependsOn)` to update or enrich `@(ApplicationArtifact)` -before [`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) -or `Publish` returns the items. For example: +`$(GetApplicationArtifactsDependsOn)`. These targets run after .NET for Android +populates `@(ApplicationArtifact)`, so they can update the existing items with +additional metadata before +[`GetApplicationArtifacts`](build-targets.md#getapplicationartifacts) or +`Publish` returns them. For example: ```xml @@ -74,7 +76,8 @@ or `Publish` returns the items. For example: - + From bdcc10a9b37af864be40cc5add2180c70dd2d17e Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 12:10:33 -0400 Subject: [PATCH 07/10] Document mandatory artifact build dependency Clarify that GetApplicationArtifacts always runs Build before GetApplicationArtifactsDependsOn extension targets, so overriding the extension property cannot skip platform artifact population. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-targets.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index 534353e..226c533 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -102,12 +102,12 @@ Creates and returns the [`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group, which contains the APK and Android App Bundle files produced by the build. -This target depends on `$(GetApplicationArtifactsDependsOn)`, which defaults to -`Build;$(GetApplicationArtifactsDependsOn)`. The `Build` target populates -`@(ApplicationArtifact)` with the platform-produced artifacts, then later -imports can append targets to `$(GetApplicationArtifactsDependsOn)` to update -those existing items with additional metadata before this target or the -`Publish` target returns them. +This target always depends on `Build`, which populates +`@(ApplicationArtifact)` with the platform-produced artifacts. Later imports can +set or append targets to `$(GetApplicationArtifactsDependsOn)` to update those +existing items with additional metadata before this target or the `Publish` +target returns them. Replacing `$(GetApplicationArtifactsDependsOn)` does not +remove the required `Build` dependency. Call this target directly when a CI job or custom tool needs the build output artifact paths: From 2172b3be20e3b5e8f4a12ed59de385bdc8320aee Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 13:14:46 -0400 Subject: [PATCH 08/10] Use dotnet build in artifact query docs Prefer dotnet build for ApplicationArtifact target-result examples instead of dotnet msbuild. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-targets.md | 6 +++--- docs/android/building-apps/package-outputs.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index 226c533..4cdd079 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -113,14 +113,14 @@ Call this target directly when a CI job or custom tool needs the build output artifact paths: ```shell -dotnet msbuild MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts +dotnet build MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts ``` Use the `Publish` target result when the caller needs the copied publish outputs in `$(PublishDir)`: ```shell -dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish +dotnet build MyApp.csproj -t:Publish -getTargetResult:Publish ``` This target is available in .NET 11 and later. @@ -182,7 +182,7 @@ callers. For example, to query the published artifacts: ```shell -dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish +dotnet build MyApp.csproj -t:Publish -getTargetResult:Publish ``` ## RunWithLogging diff --git a/docs/android/building-apps/package-outputs.md b/docs/android/building-apps/package-outputs.md index a023729..39a50d0 100644 --- a/docs/android/building-apps/package-outputs.md +++ b/docs/android/building-apps/package-outputs.md @@ -46,14 +46,14 @@ Use the callable when a CI job or custom tool needs the build output artifact paths: ```shell -dotnet msbuild MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts +dotnet build MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts ``` Use the `Publish` target result when the caller needs the copied publish outputs in `$(PublishDir)`: ```shell -dotnet msbuild MyApp.csproj -t:Publish -getTargetResult:Publish +dotnet build MyApp.csproj -t:Publish -getTargetResult:Publish ``` ## Extend application artifact metadata From 5dabe6a49cc16640896ced90ca133bb776161c71 Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 15:59:18 -0400 Subject: [PATCH 09/10] Clarify Android artifact target production Document that GetApplicationArtifacts runs the required build and artifact-production steps before extension targets can enrich the returned items. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-targets.md | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index 4cdd079..e583f64 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -102,12 +102,12 @@ Creates and returns the [`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group, which contains the APK and Android App Bundle files produced by the build. -This target always depends on `Build`, which populates -`@(ApplicationArtifact)` with the platform-produced artifacts. Later imports can -set or append targets to `$(GetApplicationArtifactsDependsOn)` to update those -existing items with additional metadata before this target or the `Publish` -target returns them. Replacing `$(GetApplicationArtifactsDependsOn)` does not -remove the required `Build` dependency. +This target always runs the required `Build` step, then packages, signs, and +collects platform-produced artifacts into `@(ApplicationArtifact)`. Later +imports can set or append targets to `$(GetApplicationArtifactsDependsOn)` to +update those existing items with additional metadata before this target or the +`Publish` target returns them. Replacing `$(GetApplicationArtifactsDependsOn)` +does not remove the required build or artifact-production steps. Call this target directly when a CI job or custom tool needs the build output artifact paths: @@ -173,11 +173,11 @@ Returned items use the copied publish-directory paths and preserve artifact metadata such as `%(PackageFormat)`, `%(Signed)`, `%(PackageId)`, and `%(Abi)`. `Publish` first runs `GetApplicationArtifacts`, which builds the project and -populates `@(ApplicationArtifact)` with the platform-produced artifacts. Targets -appended to `$(GetApplicationArtifactsDependsOn)` then run against those -existing items before `Publish` calculates publish files and before `Publish` -returns `@(ApplicationArtifact)`, so later imports can add metadata for publish -callers. +populates `@(ApplicationArtifact)` with the platform-produced artifacts after +package and signing outputs are available. Targets appended to +`$(GetApplicationArtifactsDependsOn)` then run against those existing items +before `Publish` calculates publish files and before `Publish` returns +`@(ApplicationArtifact)`, so later imports can add metadata for publish callers. For example, to query the published artifacts: From 2900c428b6acd344cdf15855f19668b69a607adc Mon Sep 17 00:00:00 2001 From: redth Date: Wed, 17 Jun 2026 16:18:54 -0400 Subject: [PATCH 10/10] Simplify Android artifact target docs Describe GetApplicationArtifacts as depending directly on Build before extension targets enrich ApplicationArtifact items. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/android/building-apps/build-targets.md | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/android/building-apps/build-targets.md b/docs/android/building-apps/build-targets.md index e583f64..c6826f5 100644 --- a/docs/android/building-apps/build-targets.md +++ b/docs/android/building-apps/build-targets.md @@ -102,12 +102,12 @@ Creates and returns the [`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group, which contains the APK and Android App Bundle files produced by the build. -This target always runs the required `Build` step, then packages, signs, and -collects platform-produced artifacts into `@(ApplicationArtifact)`. Later -imports can set or append targets to `$(GetApplicationArtifactsDependsOn)` to -update those existing items with additional metadata before this target or the -`Publish` target returns them. Replacing `$(GetApplicationArtifactsDependsOn)` -does not remove the required build or artifact-production steps. +This target always depends on the required `Build` target, which produces and +collects platform artifacts into `@(ApplicationArtifact)`. Later imports can set +or append targets to `$(GetApplicationArtifactsDependsOn)` to update those +existing items with additional metadata before this target or the `Publish` +target returns them. Replacing `$(GetApplicationArtifactsDependsOn)` does not +remove the required `Build` dependency. Call this target directly when a CI job or custom tool needs the build output artifact paths: @@ -173,11 +173,11 @@ Returned items use the copied publish-directory paths and preserve artifact metadata such as `%(PackageFormat)`, `%(Signed)`, `%(PackageId)`, and `%(Abi)`. `Publish` first runs `GetApplicationArtifacts`, which builds the project and -populates `@(ApplicationArtifact)` with the platform-produced artifacts after -package and signing outputs are available. Targets appended to -`$(GetApplicationArtifactsDependsOn)` then run against those existing items -before `Publish` calculates publish files and before `Publish` returns -`@(ApplicationArtifact)`, so later imports can add metadata for publish callers. +populates `@(ApplicationArtifact)` with the platform-produced artifacts. Targets +appended to `$(GetApplicationArtifactsDependsOn)` then run against those +existing items before `Publish` calculates publish files and before `Publish` +returns `@(ApplicationArtifact)`, so later imports can add metadata for publish +callers. For example, to query the published artifacts: