Document application artifacts

docs/ios/building-apps/build-items.md

@@ -248,6 +248,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 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

docs/ios/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.
@@ -633,6 +669,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.
@@ -1103,6 +1141,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.

docs/ios/building-apps/build-targets.md

@@ -44,6 +44,25 @@ $ 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.
+
+```shell
+$ dotnet build MyApp.csproj -t:GetApplicationArtifacts -getTargetResult:GetApplicationArtifacts
+$ dotnet build MyApp.csproj -t:Publish -getTargetResult:Publish
+```
+
+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