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.
AltoolPath
The full path to the altool
tool.
The default behavior is to use xcrun altool
.
AppBundleDir
The location of the built app bundle.
AppBundleExtraOptions
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.
AppIcon
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.
ApplicationDisplayVersion
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.
ApplicationId
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.
ApplicationTitle
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.
ApplicationVersion
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.
ArchiveBasePath
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).
ArchiveOnBuild
If an Xcode archive should be created at the end of the build.
BGenEmitDebugInformation
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
.
BGenExtraArgs
Any extra arguments to the bgen
tool (the binding generator).
BGenToolExe
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.
BGenToolPath
The directory to where the bgen
(BGenToolExe) is located.
The default behavior is to use the bgen
tool shipped with our workload.
BuildIpa
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.
CodesignAllocate
The path to the codesign_allocate
tool.
By default this value is auto-detected.
CodesignDependsOn
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>
CodesignEntitlements
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
.
CodesignExtraArgs
Extra arguments passed to the 'codesign' tool when signing the app bundle.
CodesignKey
Specifies the code signing key to use when signing the app bundle.
CodesignKeychain
The keychain to use during code signing.
CodeSigningKey
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).
CodesignProvision
Specifies the provisioning profile to use when signing the app bundle.
CodesignResourceRules
The path to the ResourceRules.plist to copy to the app bundle.
CodesignRequireProvisioningProfile
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.
CreateAppBundleDependsOn
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>
CreateIpaDependsOn
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>
CreatePackage
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.
DeviceSpecificBuild
If the build should be specific to the selected device.
Applicable to all platforms that support device-specific builds (currently iOS and tvOS).
DeviceSpecificIntermediateOutputPath
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).
DeviceSpecificOutputPath
The output path to use when device-specific builds are enabled.
Applicable to all platforms that support device-specific builds (currently iOS and tvOS).
DittoPath
The full path to the ditto
executable.
The default behavior is to use /usr/bin/ditto
.
EmbedOnDemandResources
If on-demand resources should be embedded in the app bundle.
Default: true
EnableCodeSigning
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.
EnableDefaultCodesignEntitlements
See CodesignEntitlements.
EnableOnDemandResources
If on-demand resources are enabled.
Default: false for macOS, true for all other platforms.
EnablePackageSigning
If the .pkg that was created (if CreatePackage
was enabled) should be signed.
Only applicable to macOS and Mac Catalyst.
EnableSGenConc
Enables the concurrent mode for the SGen garbage collector.
Only applicable to iOS, tvOS and Mac Catalyst (when not using NativeAOT).
GenerateApplicationManifest
If an application manifest (Info.plist
) should be generated.
Default: true
GeneratedSourcesDir
Where the generated source from the generator are saved.
IncludeAllAppIcons
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.
iOSMinimumVersion
Specifies the minimum iOS version the app can run on.
Applicable to iOS; setting this value will set SupportedOSPlatformVersion for iOS projects (only).
IPhoneResourcePrefix
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.
IpaIncludeArtwork
If artwork should be included in the IPA.
Only applicable to iOS and tvOS projects.
IpaPackageName
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.
IpaPackageDir
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.
IpaPackagePath
Specifies the path to the resulting .ipa file when creating an IPA package (see BuildIpa).
Only applicable to iOS and tvOS projects.
IsAppExtension
If a project is an app extension.
IsBindingProject
If a project is a binding project.
IsXPCService
If a macOS extension is an xpc service.
Only applicable to macOS projects.
LinkMode
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.
LinkWithSwiftSystemLibraries
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.
MacCatalystMinimumVersion
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).
MaciOSPrepareForBuildDependsOn
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.
macOSMinimumVersion
Specifies the minimum macOS version the app can run on.
Applicable to macOS; setting this value will set SupportedOSPlatformVersion for macOS projects (only).
MacOSXSdkVersion
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.
MdimportPath
The full path to the mdimport
tool.
The default behavior is to use xcrun mdimport
.
MetalLibPath
The full path to the metallib
tool (the Metal Linker).
The default behavior is to use xcrun metallib
.
MetalPath
The full path to the Metal compiler.
The default behavior is to use xcrun metal
.
MmpDebug
Enables debug mode for app bundle creation.
Only applicable to macOS projects.
See also MtouchDebug.
MonoBundlingExtraArgs
Additional arguments specifying how to create the app bundle.
Only applicable to macOS projects.
This property is deprecated, use AppBundleExtraOptions instead.
MonoMacResourcePrefix
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.
MtouchDebug
Enables debug mode for app bundle creation.
Applicable to iOS, tvOS and Mac Catalyst projects.
See also MmpDebug.
MtouchEnableSGenConc
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.
MtouchExtraArgs
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.
MtouchInterpreter
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.
Note
MAUI changes the default by setting UseInterpreter=true
for the "Debug"
configuration.
MtouchLink
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.
MtouchSdkVersion
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.
MtouchUseLlvm
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.
NoBindingEmbedding
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).
Note
Xcframeworks won't work correctly if embedded inside the managed assembly (if this property is not true
).
NoDSymUtil
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
).
OnDemandResourcesInitialInstallTags
A string property that specifies the initial install tags for on-demand resources.
OnDemandResourcesPrefetchOrder
A string property that specifies the prefetch order for on-demand resources.
OnDemandResourcesUrl
A string property that specifies the resource url for on-demand resources.
OptimizePNGs
A boolean property that specifies whether png images should be optimized.
OptimizePngImagesDependsOn
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>
OptimizePropertyLists
A boolean property that specifies whether property lists (plists) should be optimized.
OptimizePropertyListsDependsOn
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>
PackageSigningKey
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.
PackagingExtraArgs
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.
PkgPackagePath
Specifies the path to the resulting .pkg file when creating a package (see CreatePackage).
Only applicable to macOS and Mac Catalyst apps.
PlutilPath
The full path to the plutil
command-line tool.
The default behavior is to use xcrun plutil
.
PngCrushPath
The full path to the pngcrush
command-line tool.
The default behavior is to use xcrun pngcrush
.
ProcessEnums
A boolean property that specifies whether enums should be processed as an api definition in binding projects.
ProductBuildPath
The full path to the productbuild
tool.
The default behavior is to use xcrun productbuild
.
ProductDefinition
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.
ReferenceNativeSymbol
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
: eitherObjectiveCClass
,Function
orField
. Used to compute the complete native name of a symbol (for instance, the native symbol for the Objective-C classMyClass
is_OBJC_CLASS_$_MyClass
, while for a functionMyFunction
it's just_MyFunction
.SymbolMode
: eitherIgnore
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>
RequireLinkWithAttributeForObjectiveCClassSearch
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>
StripPath
The full path to the strip
command-line tool.
The default behavior is to use xcrun strip
.
SupportedOSPlatformVersion
Specifies the minimum OS version the app can run on.
It's also possible to use a platform-specific property:
TrimMode
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.
Note
For technical reasons, the trimmer must run for all iOS, tvOS, macOS
and Mac Catalyst projects, even if no assemblies are to be trimmed. For this
reason, it's not valid to disable trimming by setting
PublishTrimmed
to false
- to disable trimming, set TrimMode=copy
instead (a build error
will be raised if PublishTrimmed
is set to false
).
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):
MtouchLink/LinkMode | TrimMode |
---|---|
Full | full |
SdkOnly | partial |
None | copy |
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 theDebug
configuration and the interpreter is enabled using UseInterpreter (which MAUI also enables by default when using the"Debug"
configuration).
Note
The default trim mode may change in the future.
tvOSMinimumVersion
Specifies the minimum tvOS version the app can run on.
Applicable to tvOS; setting this value will set SupportedOSPlatformVersion for tvOS projects (only).
UseHardenedRuntime
A boolean property that specifies if a hardened runtime is enabled.
Applicable to macOS and Mac Catalyst projects.
UseInterpreter
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.
Note
MAUI changes the default by setting UseInterpreter=true
for the "Debug"
configuration.
See MtouchInterpreter for more information.
UseNativeHttpHandler
Whether the native http handler should be the default http handler or not.
Default: true for all platforms except macOS.
XamMacResourcePrefix
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.
ZipPath
The full path to the zip
command-line tool.
The default behavior is to use xcrun zip
.