dotnet · dalexsoto · Jun 22, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
diff --git a/docs/building-apps/build-items.md b/docs/building-apps/build-items.md
@@ -249,6 +249,35 @@ An item group that contains environment variables that will be set when the app
 > [!NOTE]
 > This only applies when launching the app from the command line (`dotnet run` or `dotnet build -t:Run`), not when launching from the IDE.
 
+## ApplicationArtifact
+
+An item group that contains final application artifacts produced by Apple platform builds and publishes. The item identity is the absolute path to the artifact. This can include:
+
+* `.app` app bundles for iOS, tvOS, macOS, and Mac Catalyst apps.
+* `.ipa` packages when [BuildIpa](build-properties.md#buildipa) is enabled.
+* `.pkg` installer packages when [CreatePackage](build-properties.md#createpackage) is enabled.
+* `.xcarchive` directories when [ArchiveOnBuild](build-properties.md#archiveonbuild) is enabled.
+
+The following metadata is set:
+
+* `PackageFormat`: The artifact format. Possible values are `app`, `ipa`, `pkg`, and `xcarchive`.
+* `IsDirectory`: `true` for `.app` and `.xcarchive` outputs; `false` for `.ipa` and `.pkg` outputs.
+* `PlatformName`: The Apple platform name, such as `iOS`, `tvOS`, `macOS`, or `MacCatalyst`.
+* `BundleIdentifier`: The resolved app bundle identifier.
+
+Example:
+
+```xml
+<Target Name="WriteApplicationArtifacts" AfterTargets="Build">
+    <WriteLinesToFile
+        File="$(OutputPath)application-artifacts.txt"
+        Lines="%(ApplicationArtifact.Identity)|%(ApplicationArtifact.PackageFormat)"
+        Overwrite="true" />
+</Target>
+```
+
+See also the [GetApplicationArtifacts](build-targets.md#getapplicationartifacts) target.
+
 ## NativeReference
 
 An item group that contains any native references that should be linked into

diff --git a/docs/building-apps/build-properties.md b/docs/building-apps/build-properties.md
@@ -109,6 +109,8 @@ Only applicable to iOS projects (since only iOS projects can be built remotely f
 
 If an Xcode archive should be created at the end of the build.
 
+Created archives are exposed in the [ApplicationArtifact](build-items.md#applicationartifact) item group.
+
 ## BGenEmitDebugInformation
 
 Whether the `bgen` tool (the binding generator) should emit debug information or not.
@@ -139,6 +141,8 @@ Only applicable to iOS and tvOS projects.
 
 See [CreatePackage](#createpackage) for macOS and Mac Catalyst projects.
 
+Created IPA packages are exposed in the [ApplicationArtifact](build-items.md#applicationartifact) item group.
+
 ## BundleCreateDump
 
 CoreCLR has a command-line utility called [`createdump`][createdump] to create
@@ -350,6 +354,8 @@ Only applicable to macOS and Mac Catalyst projects.
 
 See [BuildIpa](#buildipa) for iOS and tvOS projects.
 
+Created PKG packages are exposed in the [ApplicationArtifact](build-items.md#applicationartifact) item group.
+
 ## Device
 
 Specifies which mobile device or simulator to target when using `dotnet run --device <Device>` or MSBuild targets that interact with devices (such as `Run`, `Install`, or `Uninstall`).
@@ -535,6 +541,36 @@ Default: true
 
 Where the generated source from the generator are saved.
 
+## GetApplicationArtifactsDependsOn
+
+A semi-colon delimited property that can be used to extend the
+[GetApplicationArtifacts](build-targets.md#getapplicationartifacts) and
+`Publish` targets. `Build` is a mandatory dependency of
+`GetApplicationArtifacts`; MSBuild targets added to this property execute after
+the platform build has collected `@(ApplicationArtifact)` items and before
+`GetApplicationArtifacts` or `Publish` returns them.
+
+This can be used by SDKs such as .NET MAUI to add shared application metadata
+to platform-produced artifacts. Extension targets should update existing
+`@(ApplicationArtifact)` items to add metadata; they should only add new items
+when introducing additional artifacts.
+
+Example:
+
+```xml
+<PropertyGroup>
+  <GetApplicationArtifactsDependsOn>$(GetApplicationArtifactsDependsOn);AddApplicationArtifactMetadata</GetApplicationArtifactsDependsOn>
+</PropertyGroup>
+
+<Target Name="AddApplicationArtifactMetadata">
+  <ItemGroup>
+    <ApplicationArtifact Update="@(ApplicationArtifact)">
+      <ApplicationTitle>$(ApplicationTitle)</ApplicationTitle>
+    </ApplicationArtifact>
+  </ItemGroup>
+</Target>
+```
+
 ## IBToolPath
 
 The full path to the `ibtool` tool.
@@ -669,6 +705,8 @@ Specifies the path to the resulting .ipa file when creating an IPA package (see
 
 Only applicable to iOS and tvOS projects.
 
+The resulting IPA is exposed in the [ApplicationArtifact](build-items.md#applicationartifact) item group.
+
 ## IsAppExtension
 
 If a project is an app extension.
@@ -1139,6 +1177,8 @@ Specifies the path to the resulting .pkg file when creating a package (see [Crea
 
 Only applicable to macOS and Mac Catalyst apps.
 
+The resulting PKG is exposed in the [ApplicationArtifact](build-items.md#applicationartifact) item group.
+
 ## PlutilPath
 
 The full path to the `plutil` command-line tool.

diff --git a/docs/building-apps/build-targets.md b/docs/building-apps/build-targets.md
@@ -44,6 +44,36 @@ $ dotnet run --device UDID
 
 Added in .NET 11.
 
+## GetApplicationArtifacts
+
+Builds the project and returns the `@(ApplicationArtifact)` item group. This
+target always runs `Build` first so platform `.app`, `.ipa`, `.pkg`, and
+`.xcarchive` artifacts are produced and collected before any custom metadata
+extension targets run. The `Publish` target returns the same item group for
+artifacts it creates.
+
+The returned item group reflects the artifacts the current invocation is
+configured to build; it does not scan for `.ipa`, `.pkg`, or `.xcarchive` files
+left on disk by a previous build. The `.app` bundle is always collected for an
+application project (excluding app extension and watch app projects), while the
+`.ipa`, `.pkg`, and `.xcarchive` outputs are only collected when
+[BuildIpa](build-properties.md#buildipa),
+[CreatePackage](build-properties.md#createpackage), or
+[ArchiveOnBuild](build-properties.md#archiveonbuild) (respectively) is enabled in
+the same invocation. The `Publish` target enables `BuildIpa` (mobile) or
+`CreatePackage` (desktop) by default.
+
+```shell
+$ dotnet build MyApp.csproj -t:GetApplicationArtifacts -getItem:ApplicationArtifact
+$ dotnet build MyApp.csproj -t:Publish -getItem:ApplicationArtifact
+```
+
+See [ApplicationArtifact](build-items.md#applicationartifact) for supported metadata.
+
+Targets that need to add or update `@(ApplicationArtifact)` metadata before
+`GetApplicationArtifacts` or `Publish` returns can append to
+[GetApplicationArtifactsDependsOn](build-properties.md#getapplicationartifactsdependson).
+
 ## Run
 
 Builds the source code within a project and all dependencies, and then deploys and runs it

diff --git a/dotnet/targets/Xamarin.Shared.Sdk.Publish.targets b/dotnet/targets/Xamarin.Shared.Sdk.Publish.targets
@@ -20,7 +20,7 @@
 			Condition="$(RuntimeIdentifiers.Contains('iossimulator-')) Or $(RuntimeIdentifiers.Contains('tvossimulator-'))"
 		/>
 	</Target>
-	<Target Name="Publish" DependsOnTargets="_PrePublish;Build">
+	<Target Name="Publish" DependsOnTargets="_PrePublish;GetApplicationArtifacts" Returns="@(ApplicationArtifact)">
 		<Message Importance="high" Text="Created the package: $(IpaPackagePath)" Condition="'$(BuildIpa)' == 'true' And '$(SdkIsMobile)' == 'true'" />
 		<Message Importance="high" Text="Created the package: $(PkgPackagePath)" Condition="'$(CreatePackage)' == 'true' And '$(SdkIsDesktop)' == 'true'" />
 	</Target>

@@ -2370,6 +2370,24 @@ Copyright (C) 2018 Microsoft. All rights reserved.
 
 	<Target Name="Codesign" Condition="'$(_CanOutputAppBundle)' == 'true'" DependsOnTargets="$(CodesignDependsOn)" />
 
+	<!-- On a Windows (Pair to Mac) build the .app bundle is produced on the Mac and is not copied
+	     back to the local $(AppBundleDir) (CopyAppBundleFromMac, and only when CopyAppBundle is set,
+	     extracts it to a separate AppBundle\ subfolder instead). Skip collecting it on remote builds
+	     ($(IsRemoteBuild) == 'true') so we never surface an incomplete local bundle; surfacing the
+	     .app on Windows is left for a follow-up. -->
+	<Target Name="_CollectAppleAppBundleOutput"
+		Condition="'$(_CanOutputAppBundle)' == 'true' And '$(OutputType)' == 'Exe' And '$(IsAppExtension)' != 'true' And '$(IsWatchApp)' != 'true' And '$(IsRemoteBuild)' != 'true' And Exists('$(AppBundleDir)')"
+		AfterTargets="Codesign">
+		<ItemGroup>
+			<ApplicationArtifact Include="$([MSBuild]::NormalizePath('$(MSBuildProjectDirectory)', '$(AppBundleDir)'))">
+				<PackageFormat>app</PackageFormat>
+				<IsDirectory>true</IsDirectory>
+				<PlatformName>$(_PlatformName)</PlatformName>
+				<BundleIdentifier>$(_BundleIdentifier)</BundleIdentifier>
+			</ApplicationArtifact>
+		</ItemGroup>
+	</Target>
+
 	<!--
 
 		Code signing
@@ -2690,9 +2708,14 @@ Copyright (C) 2018 Microsoft. All rights reserved.
 
 	<!-- App extensions -->
 
-	<Target Name="GetAppExtensionBundlePath" DependsOnTargets="_GenerateBundleName;$(GetTargetPathDependsOn)" Outputs="@(_AppExtensionBundlePath)" />
+	<!-- These two targets are invoked across projects (via the MSBuild task) to get the app extension's
+	     bundle path back as TargetOutputs. They must specify 'Returns' explicitly: once any target in this
+	     file uses the 'Returns' attribute (e.g. GetApplicationArtifacts), MSBuild stops treating the
+	     'Outputs' attribute of targets without 'Returns' as their return value, so relying on 'Outputs'
+	     alone would return an empty set and the extension would not be embedded into the container app. -->
+	<Target Name="GetAppExtensionBundlePath" DependsOnTargets="_GenerateBundleName;$(GetTargetPathDependsOn)" Outputs="@(_AppExtensionBundlePath)" Returns="@(_AppExtensionBundlePath)" />
 
-	<Target Name="BuildAndGetAppExtensionBundlePath" DependsOnTargets="Build" Outputs="@(_AppExtensionBundlePath)" />
+	<Target Name="BuildAndGetAppExtensionBundlePath" DependsOnTargets="Build" Outputs="@(_AppExtensionBundlePath)" Returns="@(_AppExtensionBundlePath)" />
 
 	<Target Name="_AssignAppExtensionConfiguration" Condition="'@(_AppExtensionReference)' != ''">
 		<!-- assign configs if building a solution file -->
@@ -3257,6 +3280,28 @@ Copyright (C) 2018 Microsoft. All rights reserved.
 		</Archive>
 	</Target>
 
+	<Target Name="_CollectAppleArchiveOutput"
+		Condition="'$(ArchiveOnBuild)' == 'true'"
+		AfterTargets="Archive">
+		<!-- On a Windows (Pair to Mac) build the archive is copied back to Windows by
+		     CopyArchiveFromMac (the last target in ArchiveDependsOn), which sets $(ArchivePath)
+		     to the local Windows path while $(ArchiveDir) keeps pointing to the Mac path. Prefer
+		     $(ArchiveDir) when it exists locally (the normal macOS build) and fall back to the
+		     copied-back $(ArchivePath) otherwise. -->
+		<PropertyGroup>
+			<_ApplicationArtifactArchivePath>$(ArchiveDir)</_ApplicationArtifactArchivePath>
+			<_ApplicationArtifactArchivePath Condition="'$(ArchivePath)' != '' And !Exists('$(_ApplicationArtifactArchivePath)')">$(ArchivePath)</_ApplicationArtifactArchivePath>
+		</PropertyGroup>
+		<ItemGroup Condition="'$(_ApplicationArtifactArchivePath)' != '' And Exists('$(_ApplicationArtifactArchivePath)')">
+			<ApplicationArtifact Include="$([MSBuild]::NormalizePath('$(MSBuildProjectDirectory)', '$(_ApplicationArtifactArchivePath)'))">
+				<PackageFormat>xcarchive</PackageFormat>
+				<IsDirectory>true</IsDirectory>
+				<PlatformName>$(_PlatformName)</PlatformName>
+				<BundleIdentifier>$(_BundleIdentifier)</BundleIdentifier>
+			</ApplicationArtifact>
+		</ItemGroup>
+	</Target>
+
 	<Target Name="_GenerateBundleName" Condition="'$(_CanOutputAppBundle)' == 'true'" DependsOnTargets="_ComputeTargetArchitectures;_ParseBundlerArguments">
 		<PropertyGroup Condition="'$(AppBundleDir)' == ''">
 			<_AppContainerDir Condition="'$(IsAppDistribution)' != 'true'">$(DeviceSpecificOutputPath)</_AppContainerDir>
@@ -3360,6 +3405,19 @@ Copyright (C) 2018 Microsoft. All rights reserved.
 		</CreateInstallerPackage>
 	</Target>
 
+	<Target Name="_CollectApplePkgOutput"
+		Condition="'$(CreatePackage)' == 'true' And '$(PkgPackagePath)' != '' And Exists('$(PkgPackagePath)')"
+		AfterTargets="_CreateInstaller">
+		<ItemGroup>
+			<ApplicationArtifact Include="$([MSBuild]::NormalizePath('$(MSBuildProjectDirectory)', '$(PkgPackagePath)'))">
+				<PackageFormat>pkg</PackageFormat>
+				<IsDirectory>false</IsDirectory>
+				<PlatformName>$(_PlatformName)</PlatformName>
+				<BundleIdentifier>$(_BundleIdentifier)</BundleIdentifier>
+			</ApplicationArtifact>
+		</ItemGroup>
+	</Target>
+
 	<!-- 
 		Creates a plist with the entitlements used to sign the App bundle.
 		MacCatalyst apps don't have a compiled entitlements file in the app bundle, 
@@ -3390,12 +3448,15 @@ Copyright (C) 2018 Microsoft. All rights reserved.
 			_PackageOnDemandResources;
 			_ZipIpa
 		</CreateIpaDependsOn>
+
 	</PropertyGroup>
 
 	<Target Name="_BeforeCreateIpaForDistribution" Condition="'$(IsAppDistribution)' == 'true'" DependsOnTargets="$(_BeforeCreateIpaForDistributionDependsOn)" />
 
 	<Target Name="CreateIpa" Condition="'$(_CanArchive)' == 'true' And '$(SdkIsDesktop)' != 'true'" DependsOnTargets="$(CreateIpaDependsOn)" />
 
+	<Target Name="GetApplicationArtifacts" DependsOnTargets="Build;$(GetApplicationArtifactsDependsOn)" Returns="@(ApplicationArtifact)" />
+
 	<PropertyGroup>
 		<PrepareAssemblies Condition="'$(PrepareAssemblies)' == ''">false</PrepareAssemblies>
 	</PropertyGroup>

@@ -488,6 +488,19 @@ Copyright (C) 2013-2016 Xamarin. All rights reserved.
 		</Zip>
 	</Target>
 
+	<Target Name="_CollectAppleIpaOutput"
+		Condition="'$(BuildIpa)' == 'true' And '$(IpaPackagePath)' != '' And Exists('$(IpaPackagePath)')"
+		AfterTargets="CreateIpa">
+		<ItemGroup>
+			<ApplicationArtifact Include="$([MSBuild]::NormalizePath('$(MSBuildProjectDirectory)', '$(IpaPackagePath)'))">
+				<PackageFormat>ipa</PackageFormat>
+				<IsDirectory>false</IsDirectory>
+				<PlatformName>$(_PlatformName)</PlatformName>
+				<BundleIdentifier>$(_BundleIdentifier)</BundleIdentifier>
+			</ApplicationArtifact>
+		</ItemGroup>
+	</Target>
+
 	<Import Project="$(MSBuildThisFileDirectory)$(MSBuildThisFileName).After.targets"
 			Condition="Exists('$(MSBuildThisFileDirectory)$(MSBuildThisFileName).After.targets')"/>
 

diff --git a/tests/dotnet/MySimpleAppWithArtifactMetadata/AppDelegate.cs b/tests/dotnet/MySimpleAppWithArtifactMetadata/AppDelegate.cs
@@ -0,0 +1,17 @@
+using System;
+using System.Runtime.InteropServices;
+
+using Foundation;
+
+namespace MySimpleAppWithArtifactMetadata {
+	public class Program {
+		static int Main (string [] args)
+		{
+			GC.KeepAlive (typeof (NSObject)); // prevent linking away the platform assembly
+
+			Console.WriteLine (Environment.GetEnvironmentVariable ("MAGIC_WORD"));
+
+			return args.Length;
+		}
+	}
+}
@@ -0,0 +1 @@
+include ../shared.mk
diff --git a/...dotnet/MySimpleAppWithArtifactMetadata/MacCatalyst/MySimpleAppWithArtifactMetadata.csproj b/...dotnet/MySimpleAppWithArtifactMetadata/MacCatalyst/MySimpleAppWithArtifactMetadata.csproj
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+	<PropertyGroup>
+		<TargetFramework>net$(BundledNETCoreAppTargetFrameworkVersion)-maccatalyst</TargetFramework>
+	</PropertyGroup>
+	<Import Project="..\shared.csproj" />
+</Project>
@@ -0,0 +1,3 @@
+TOP=../../..
+
+include $(TOP)/tests/common/shared-dotnet-test.mk
@@ -0,0 +1 @@
+include ../shared.mk
diff --git a/tests/dotnet/MySimpleAppWithArtifactMetadata/iOS/MySimpleAppWithArtifactMetadata.csproj b/tests/dotnet/MySimpleAppWithArtifactMetadata/iOS/MySimpleAppWithArtifactMetadata.csproj
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+	<PropertyGroup>
+		<TargetFramework>net$(BundledNETCoreAppTargetFrameworkVersion)-ios</TargetFramework>
+	</PropertyGroup>
+	<Import Project="..\shared.csproj" />
+</Project>
@@ -0,0 +1 @@
+include ../shared.mk
diff --git a/tests/dotnet/MySimpleAppWithArtifactMetadata/macOS/MySimpleAppWithArtifactMetadata.csproj b/tests/dotnet/MySimpleAppWithArtifactMetadata/macOS/MySimpleAppWithArtifactMetadata.csproj
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+	<PropertyGroup>
+		<TargetFramework>net$(BundledNETCoreAppTargetFrameworkVersion)-macos</TargetFramework>
+	</PropertyGroup>
+	<Import Project="..\shared.csproj" />
+</Project>
diff --git a/tests/dotnet/MySimpleAppWithArtifactMetadata/shared.csproj b/tests/dotnet/MySimpleAppWithArtifactMetadata/shared.csproj
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+	<PropertyGroup>
+		<OutputType>Exe</OutputType>
+
+		<ApplicationTitle>MySimpleAppWithArtifactMetadata</ApplicationTitle>
+		<ApplicationId>com.xamarin.mysimpleappwithartifactmetadata</ApplicationId>
+		<ApplicationVersion>3.14</ApplicationVersion>
+
+		<!-- Simulates an SDK (such as .NET MAUI) enriching the platform-produced @(ApplicationArtifact) items -->
+		<GetApplicationArtifactsDependsOn>$(GetApplicationArtifactsDependsOn);AddMauiApplicationArtifactMetadata</GetApplicationArtifactsDependsOn>
+	</PropertyGroup>
+
+	<Import Project="../../common/shared-dotnet.csproj" />
+
+	<ItemGroup>
+		<Compile Include="../*.cs" />
+	</ItemGroup>
+
+	<Target Name="AddMauiApplicationArtifactMetadata">
+		<ItemGroup>
+			<_MauiObservedAppArtifact Include="@(ApplicationArtifact)" Condition="'%(ApplicationArtifact.PackageFormat)' == 'app'" />
+			<_MauiObservedPackageArtifact Include="@(ApplicationArtifact)" Condition="'%(ApplicationArtifact.PackageFormat)' == '$(ExpectedAugmentedPackageFormat)'" />
+			<ApplicationArtifact Update="@(ApplicationArtifact)">
+				<ApplicationTitle>My MAUI App</ApplicationTitle>
+				<MauiObservedPackageFormat>%(ApplicationArtifact.PackageFormat)</MauiObservedPackageFormat>
+			</ApplicationArtifact>
+		</ItemGroup>
+		<Error Condition="'@(_MauiObservedAppArtifact)' == ''" Text="Expected app ApplicationArtifact items before MAUI metadata is added." />
+		<Error Condition="'@(_MauiObservedPackageArtifact)' == ''" Text="Expected $(ExpectedAugmentedPackageFormat) ApplicationArtifact items before MAUI metadata is added." />
+	</Target>
+</Project>
diff --git a/tests/dotnet/MySimpleAppWithArtifactMetadata/shared.mk b/tests/dotnet/MySimpleAppWithArtifactMetadata/shared.mk
@@ -0,0 +1,3 @@
+TOP=../../../..
+TESTNAME=MySimpleAppWithArtifactMetadata
+include $(TOP)/tests/common/shared-dotnet.mk
@@ -0,0 +1 @@
+include ../shared.mk
diff --git a/tests/dotnet/MySimpleAppWithArtifactMetadata/tvOS/MySimpleAppWithArtifactMetadata.csproj b/tests/dotnet/MySimpleAppWithArtifactMetadata/tvOS/MySimpleAppWithArtifactMetadata.csproj
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+	<PropertyGroup>
+		<TargetFramework>net$(BundledNETCoreAppTargetFrameworkVersion)-tvos</TargetFramework>
+	</PropertyGroup>
+	<Import Project="..\shared.csproj" />
+</Project>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		TOP=../../..

		include $(TOP)/tests/common/shared-dotnet-test.mk