Build properties for iOS, Mac Catalyst, macOS and tvOS

MSBuild properties control the behavior of the targets. They're specified within the project file, for example MyApp.csproj, within an MSBuild PropertyGroup.

The full path to the altool tool.

The default behavior is to use xcrun altool.

The location of the built app bundle.

Advanced additional arguments for app bundle creation.

The valid set of arguments depend on the platform.

Typically these shouldn't be used unless specified by a Microsoft engineer.

The AppIcon item group can be used to specify an app icon for the app.

The value of the property must point to the filename of an .appiconset (for iOS, macOS and Mac Catalyst) or .brandassets (for tvOS) image resource inside an asset catalog.

Example:

<PropertyGroup>
    <!-- The value to put in here for the "Resources/MyImages.xcassets/MyAppIcon.appiconset" resource would be "MyAppIcon" -->
    <AppIcon>MyAppIcon</AppIcon>
</PropertyGroup>

See also:

• The AlternateAppIcon item group.
• The IncludeAllAppIcons property.

If set, specifies the CFBundleShortVersionString value in the app manifest (Info.plist).

This is a property that supports .NET "Single Project".

See OneDotNetSingleProject for more information.

If set, specifies the CFBundleIdentifier value in the app manifest (Info.plist).

This is a property that supports .NET "Single Project".

See OneDotNetSingleProject for more information.

If set, specifies the CFBundleDisplayName in the app manifest (Info.plist).

This is a property that supports .NET "Single Project".

See OneDotNetSingleProject for more information.

If set, specifies the CFBundleVersion in the app manifest (Info.plist).

This is a property that supports .NET "Single Project".

See OneDotNetSingleProject for more information.

The location where archives are stored on Windows for a remote build.

The default is: %LocalAppData%\Xamarin\iOS\Archives

Only applicable to iOS projects (since only iOS projects can be built remotely from Windows).

If an Xcode archive should be created at the end of the build.

Whether the bgen tool (the binding generator) should emit debug information or not.

The default behavior is true when the Debug property is set to true.

Any extra arguments to the bgen tool (the binding generator).

The name of the bgen executable (a tool used by binding projects to generate bindings).

The default behavior is to use the bgen tool shipped with our workload.

The directory to where the bgen (BGenToolExe) is located.

The default behavior is to use the bgen tool shipped with our workload.

If a package (.ipa) should be created for the app bundle at the end of the build.

Only applicable to iOS and tvOS projects.

See CreatePackage for macOS and Mac Catalyst projects.

The path to the codesign_allocate tool.

By default this value is auto-detected.

This is an extension point for the build: a developer can add any targets to this property to execute those targets before the app bundle is signed.

Example:

<PropertyGroup>
  <CodesignDependsOn>$(CodesignDependsOn);DoThisBeforeCodesign</CodesignDependsOn>
</PropertyGroup>
<Target Name="DoThisBeforeCodesign">
  <Exec Command="echo This is executed right before the app is signed." />
</Target>

The path to the entitlements file that specifies the entitlements the app requires.

Typically "Entitlements.plist".

We'll automatically set this to "Entitlements.plist" if such a file exists in the project root directory.

This can be prevented by setting the EnableDefaultCodesignEntitlements property to false.

Extra arguments passed to the 'codesign' tool when signing the app bundle.

Specifies the code signing key to use when signing the app bundle.

The keychain to use during code signing.

Specifies the code signing key to use when signing the app bundle.

Only applicable to macOS and Mac Catalyst apps, but it's recommended to use the CodesignKey property instead (which works on all platforms).

Specifies the provisioning profile to use when signing the app bundle.

The path to the ResourceRules.plist to copy to the app bundle.

Specifies whether a provisioning profile is required when signing the app bundle.

By default we require a provisioning profile if:

• macOS, Mac Catalyst: a provisioning profile has been specified (with the CodesignProvision property).
• iOS, tvOS, watchOS: building for device or an entitlements file has been specified (with the CodesignEntitlements property).

Setting this property to true or false will override the default logic.

This is an extension point for the build: a developer can add any targets to this property to execute those targets when creating the app bundle.

Example:

<PropertyGroup>
  <CreateAppBundleDependsOn>$(CreateAppBundleDependsOn);DoThisBeforeCreatingAppBundle</CreateAppBundleDependsOn>
</PropertyGroup>
<Target Name="DoThisBeforeCreatingAppBundle">
  <Exec Command="echo This is executed before the app bundle is created." />
</Target>

This is an extension point for the build: a developer can add any targets to this property to execute those targets when creating an IPA.

Applicable to all platforms that build IPA archives (currently iOS and tvOS).

Example:

<PropertyGroup>
  <CreateIpaDependsOn>$(CreateIpaDependsOn);DoThisBeforeCreatingIPA</CreateIpaDependsOn>
</PropertyGroup>
<Target Name="DoThisBeforeCreatingIPA">
  <Exec Command="echo This is executed before the IPA is created." />
</Target>

If a package (.pkg) should be created for the app bundle at the end of the build.

Only applicable to macOS and Mac Catalyst projects.

See BuildIpa for iOS and tvOS projects.

If the build should be specific to the selected device.

Applicable to all platforms that support device-specific builds (currently iOS and tvOS).

The intermediate output path to use when device-specific builds are enabled.

Applicable to all platforms that support device-specific builds (currently iOS and tvOS).

The output path to use when device-specific builds are enabled.

Applicable to all platforms that support device-specific builds (currently iOS and tvOS).

The full path to the ditto executable.

The default behavior is to use /usr/bin/ditto.

If on-demand resources should be embedded in the app bundle.

Default: true

If code signing is enabled.

Typically the build will automatically determine whether code signing is required; this automatic detection can be overridden with this property.

See CodesignEntitlements.

If on-demand resources are enabled.

Default: false for macOS, true for all other platforms.

If the .pkg that was created (if CreatePackage was enabled) should be signed.

Only applicable to macOS and Mac Catalyst.

Enables the concurrent mode for the SGen garbage collector.

Only applicable to iOS, tvOS and Mac Catalyst (when not using NativeAOT).

If an application manifest (Info.plist) should be generated.

Default: true

Where the generated source from the generator are saved.

Set the IncludeAllAppIcons property to true to automatically include all app icons from all asset catalogs in the app.

Example:

<PropertyGroup>
    <IncludeAllAppIcons>true</IncludeAllAppIcons>
</PropertyGroup>

See also:

• The AlternateAppIcon item group.
• The AppIcon property.

Specifies the minimum iOS version the app can run on.

Applicable to iOS; setting this value will set SupportedOSPlatformVersion for iOS projects (only).

The directory where resources are stored (this prefix will be removed when copying resources to the app bundle).

Applicable to iOS, tvOS and Mac Catalyst projects.

See also MonoMacResourcePrefix and XamMacResourcePrefix.

If artwork should be included in the IPA.

Only applicable to iOS and tvOS projects.

Specifies the name of the resulting .ipa file (without the path) when creating an IPA package (see BuildIpa). IpaPackagePath will override this value.

Only applicable to iOS and tvOS projects.

Specifies the directory of the resulting .ipa file when creating an IPA package (see BuildIpa). IpaPackagePath will override this value.

Only applicable to iOS and tvOS projects.

Specifies the path to the resulting .ipa file when creating an IPA package (see BuildIpa).

Only applicable to iOS and tvOS projects.

If a project is an app extension.

If a project is a binding project.

If a macOS extension is an xpc service.

Only applicable to macOS projects.

Specifies the link mode for the project (None, SdkOnly or Full).

Applicable to macOS projects, but this property is deprecated, use TrimMode instead.

See also MtouchLink.

If set to true, the build will tell the native linker where to find Swift's system libraries.

This is useful when a native library uses Swift somehow, in which case the native linker needs to know where to find Swift's system libraries.

Currently this means these arguments will be passed to the native linker:

• -L/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift/[platform]
• -L/Applications/Xcode.app/Contents/Developer/Platforms/[platform].platform/Developer/SDKs/[platform].sdk/usr/lib/swift

The exact set of arguments may change in the future.

Specifies the minimum Mac Catalyst (iOS) version the app can run on.

Applicable to Mac Catalyst; setting this value will set SupportedOSPlatformVersion for Mac Catalyst projects (only).

A semi-colon delimited property that can be used to extend the build process. MSBuild targets added to this property will execute early in the build for both application and library project types. This property is empty by default.

Example:

<PropertyGroup>
  <MaciOSPrepareForBuildDependsOn>$(MaciOSPrepareForBuildDependsOn);MyCustomTarget</MaciOSPrepareForBuildDependsOn>
</PropertyGroup>

<Target Name="MyCustomTarget" >
  <Message Text="Running target: 'MyCustomTarget'" Importance="high"  />
</Target>

This property was introduced in .NET 9.

Specifies the minimum macOS version the app can run on.

Applicable to macOS; setting this value will set SupportedOSPlatformVersion for macOS projects (only).

The macOS SDK version to use for the build.

Default: automatically detected according to the default version shipped with the selected Xcode.

See also MtouchSdkVersion.

The full path to the mdimport tool.

The default behavior is to use xcrun mdimport.

The full path to the metallib tool (the Metal Linker).

The default behavior is to use xcrun metallib.

The full path to the Metal compiler.

The default behavior is to use xcrun metal.

Enables debug mode for app bundle creation.

Only applicable to macOS projects.

See also MtouchDebug.

Additional arguments specifying how to create the app bundle.

Only applicable to macOS projects.

This property is deprecated, use AppBundleExtraOptions instead.

The directory where resources are stored (this prefix will be removed when copying resources to the app bundle).

Only applicable to macOS projects.

See also IPhoneResourcePrefix and XamMacResourcePrefix.

Enables debug mode for app bundle creation.

Applicable to iOS, tvOS and Mac Catalyst projects.

See also MmpDebug.

Enables the concurrent mode for the SGen garbage collector.

Only applicable to iOS, tvOS and Mac Catalyst when not using NativeAOT.

This property is deprecated, use EnableSGenConc instead.

Additional arguments specifying how to create the app bundle.

Only applicable to iOS, tvOS and Mac Catalyst projects.

This property is deprecated, use AppBundleExtraOptions instead.

Enables the interpreter, and optionally takes a comma-separated list of assemblies to interpret (if prefixed with a minus sign, the assembly will be AOT-compiled instead). 'all' can be used to specify all assemblies. This argument can be specified multiple times.

Example:

<PropertyGroup>
  <!-- interpret all assemblies -->
  <MtouchInterpreter>all</MtouchInterpreter>

  <!-- AOT-compile all assemblies, except System.dll, which will be interpreted. -->
  <MtouchInterpreter>System</MtouchInterpreter>

  <!-- interpret all assemblies, except System.Core.dll, which will be AOT-compiled. -->
  <MtouchInterpreter>all,-System.Core</MtouchInterpreter>
</PropertyGroup>

A shorthand for the MtouchInterpreter is to set UseInterpreter=true, which is equivalent to MtouchInterpreter=all.

If both UseInterpreter and MtouchInterpreter are set, then MtouchInterpreter takes precedence.

Applicable to iOS, tvOS and Mac Catalyst apps (when not using NativeAOT).

The default behavior is to not enable the interpreter.

Specifies the link mode for the project (None, SdkOnly, Full).

Applicable to iOS, tvOS and Mac Catalyst projects, but this property is deprecated, use TrimMode instead.

See also LinkMode.

The iOS or tvOS SDK version to use for the build.

Default: automatically detected according to the default version shipped with the selected Xcode.

See also MacOSXSdkVersion.

A boolean property that specifies whether AOT compilation should be done using LLVM.

Applicable to iOS, tvOS and Mac Catalyst projects.

Default:

• On iOS and tvOS: enabled for Release builds (where Configuration="Release").
• On Mac Catalyst: never enabled by default.

A boolean property that specifies whether native libraries in binding projects should be embedded in the managed assembly, or put into a .resources directory next to the managed assembly.

The default value is true (which means native libraries will not be embeddded in the managed assembly).

A boolean property that specifies whether .dSYM generation should be disabled.

Default:

• true for iOS and tvOS when building for the simulator.
• true for macOS and Mac Catalyst unless creating an archive (ArchiveOnBuild=true)

This means the .dSYM archive will be generated in the following cases (by default):

• On iOS and tvOS when building for device.
• On macOS and Mac Catalyst when creating an archive (ArchiveOnBuild=true).

A string property that specifies the initial install tags for on-demand resources.

A string property that specifies the prefetch order for on-demand resources.

A string property that specifies the resource url for on-demand resources.

A boolean property that specifies whether png images should be optimized.

This is an extension point for the build: a developer can add any targets to this property to execute those targets before any png images are optimized.

Example:

<PropertyGroup>
  <OptimizePngImagesDependsOn>$(OptimizePngImagesDependsOn);MyCustomTarget</OptimizePngImagesDependsOn>
</PropertyGroup>

<Target Name="MyCustomTarget" >
  <Message Text="Running target: 'MyCustomTarget'" Importance="high"  />
</Target>

A boolean property that specifies whether property lists (plists) should be optimized.

This is an extension point for the build: a developer can add any targets to this property to execute those targets before any property lists (plists) are optimized.

Example:

<PropertyGroup>
  <OptimizePropertyListsDependsOn>$(OptimizePropertyListsDependsOn);MyCustomTarget</OptimizePropertyListsDependsOn>
</PropertyGroup>

<Target Name="MyCustomTarget" >
  <Message Text="Running target: 'MyCustomTarget'" Importance="high"  />
</Target>

Specifies the code signing key to sign the package when creating .pkg for a macOS and Mac Catalyst project.

Only applicable to macOS and Mac Catalyst apps.

Specifies any extra arguments to pass to the 'productbuild' tool when creating .pkg for a macOS and Mac Catalyst project.

Only applicable to macOS and Mac Catalyst apps.

Specifies the path to the resulting .pkg file when creating a package (see CreatePackage).

Only applicable to macOS and Mac Catalyst apps.

The full path to the plutil command-line tool.

The default behavior is to use xcrun plutil.

The full path to the pngcrush command-line tool.

The default behavior is to use xcrun pngcrush.

A boolean property that specifies whether enums should be processed as an api definition in binding projects.

The full path to the productbuild tool.

The default behavior is to use xcrun productbuild.

The product definition template (.plist) to be used when creating the product definition to pass to the product build tool when creating packages (.pkg).

Only applicable to macOS and Mac Catalyst apps.

The item group ReferenceNativeSymbol can be used to specify how we should handle a given native symbol: either ignore it, or ask the native linker to keep it (by passing the symbol as -u ... or in a symbol file to the native linker).

There are two supported types of metadata:

• SymbolType: either ObjectiveCClass, Function or Field. Used to compute the complete native name of a symbol (for instance, the native symbol for the Objective-C class MyClass is _OBJC_CLASS_$_MyClass, while for a function MyFunction it's just _MyFunction.
• SymbolMode: either Ignore or not set. Ignore means to not pass the given symbol to the native linker, the default is to do so.

SymbolType is required, while SymbolMode isn't.

Example symbol to keep:

<ItemGroup>
    <ReferenceNativeSymbol Include="MyClass" SymbolType="ObjectiveCClass" />
</ItemGroup>

Example symbol to ignore:

<ItemGroup>
    <ReferenceNativeSymbol Include="MyClass" SymbolType="ObjectiveCClass" SymbolMode="Ignore" />
</ItemGroup>

We will automatically scan all libraries for managed classes that map to existing Objective-C classes, and then create a native reference at build time for those Objective-C classes.

This way the native linker won't remove these Objective-C classes, thinking they're not used.

However, this can cause a problem if a managed class references an Objective-C class that doesn't exist. The proper fix for this is to remove such managed classes from the build, but this may be cumbersome, in particular if the managed class comes from a binary reference (such as NuGet).

In these cases, it's possible to set the property RequireLinkWithAttributeForObjectiveCClassSearch to true so that we'll only scan libraries with the [LinkWith] attribute for Objective-C classes:

<PropertyGroup>
  <RequireLinkWithAttributeForObjectiveCClassSearch>true</RequireLinkWithAttributeForObjectiveCClassSearch>
</PropertyGroup>

The full path to the strip command-line tool.

The default behavior is to use xcrun strip.

Specifies the minimum OS version the app can run on.

It's also possible to use a platform-specific property:

• iOSMinimumVersion
• tvOSMinimumVersion
• macOSMinimumVersion
• MacCatalystMinimumVersion

Specifies the trimming granularity.

The valid options are:

• full: Trim every assembly.
• partial: Trim assemblies that have opted into trimming.
• copy: Trim no assemblies.

See TrimMode for a bit more information about the TrimMode property.

The TrimMode property is equivalent to the existing MtouchLink (for iOS, tvOS and Mac Catalyst) and LinkMode (for macOS) properties, but the valid properties values are different (even though the semantics are the same):

Going forward, the MtouchLink and LinkMode properties will be deprecated, please use TrimMode instead.

The default trim mode depends on numerous factors, and may also change in the future.

The current (as of .NET 9) default values are:

• iOS and iOS: partial when building for device, copy when building for the simulator.
• macOS: always copy.
• Mac Catalyst: partial when building for the "Release" configuration, copy otherwise.

Exceptions:

• The default value is always full when building with NativeAOT.
• MAUI changes the default value to copy when building for the Debug configuration and the interpreter is enabled using UseInterpreter (which MAUI also enables by default when using the "Debug" configuration).

Specifies the minimum tvOS version the app can run on.

Applicable to tvOS; setting this value will set SupportedOSPlatformVersion for tvOS projects (only).

A boolean property that specifies if a hardened runtime is enabled.

Applicable to macOS and Mac Catalyst projects.

Enables the interpreter (for all assemblies).

This is equivalent to setting MtouchInterpreter=all.

Applicable to iOS, tvOS and Mac Catalyst apps (when not using NativeAOT).

The default behavior is to not enable the interpreter.

See MtouchInterpreter for more information.

Whether the native http handler should be the default http handler or not.

Default: true for all platforms except macOS.

The directory where resources are stored (this prefix will be removed when copying resources to the app bundle).

Applicable to macOS projects.

See also IPhoneResourcePrefix and MonoMacResourcePrefix.

The full path to the zip command-line tool.

The default behavior is to use xcrun zip.