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..3b61bf3 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,38 @@ 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. +## ApplicationArtifact + +`@(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. + +Each item includes the following metadata: + +- `%(PackageFormat)`: `apk` or `aab`. +- `%(Signed)`: `true` when the package is signed. +- `%(PackageId)`: The resolved Android package name. +- `%(Abi)`: The Android ABI for a per-ABI APK output. This metadata is only + set for per-ABI APKs. + +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. +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). + ## 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..420353b 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,13 @@ 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 +[`@(ApplicationArtifact)`](build-items.md#applicationartifact) item group. +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..c6826f5 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,35 @@ Creates the `@(AndroidDependency)` item group, which is used by the [`InstallAndroidDependencies`](#installandroiddependencies) target to determine which Android SDK packages to install. +## GetApplicationArtifacts + +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 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: + +```shell +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 build MyApp.csproj -t:Publish -getTargetResult:Publish +``` + +This target is available in .NET 11 and later. + ## Install [Creates, signs](#signandroidpackage), and installs the Android package onto @@ -135,6 +164,27 @@ 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)`. + +`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: + +```shell +dotnet build MyApp.csproj -t:Publish -getTargetResult:Publish +``` + ## RunWithLogging Runs the application with additional logging enabled. Helpful when reporting or investigating an issue with @@ -153,6 +203,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 +[`@(ApplicationArtifact)`](build-items.md#applicationartifact) 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..39a50d0 --- /dev/null +++ b/docs/android/building-apps/package-outputs.md @@ -0,0 +1,147 @@ +--- +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 [`@(ApplicationArtifact)`](build-items.md#applicationartifact) +item group that is populated by the .NET for Android build. + +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 `@(ApplicationArtifact)` from a target that runs after +[`SignAndroidPackage`](build-targets.md#signandroidpackage), or call +[`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 + + + + + +``` + +## 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 build MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts +``` + +Use the `Publish` target result when the caller needs the copied publish +outputs in `$(PublishDir)`: + +```shell +dotnet build MyApp.csproj -t:Publish -getTargetResult:Publish +``` + +## Extend application artifact metadata + +Targets imported after .NET for Android can append to +`$(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 + + + + $(GetApplicationArtifactsDependsOn); + AddCustomApplicationArtifactMetadata + + + + + + + + + +``` + +## Capture outputs after publish + +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 + + + + + +``` + +## 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="@(ApplicationArtifact)" + Condition="'%(PackageFormat)' == 'apk' and '%(Signed)' == 'true'" /> + <_SignedAab Include="@(ApplicationArtifact)" + 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 `@(ApplicationArtifact)` 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. | +| `%(Abi)` | The Android ABI for per-ABI APK outputs. This metadata is omitted for non-per-ABI outputs. |