| title | description | ms.date |
|---|---|---|
Mac Catalyst capabilities |
Learn how to add capabilities to your .NET MAUI Mac Catalyst app's provisioning profile, to code sign your app. |
03/28/2023 |
On Mac Catalyst .NET Multi-platform App UI (.NET MAUI) apps run in a sandbox that provides a set of rules that limit access between the app and system resources or user data. Apple provides capabilities, also known as app services, as a means of extending functionality and widening the scope of what Mac Catalyst apps can do. For more information about capabilities, see Capabilities on developer.apple.com.
Capabilities are added to your app's provisioning profile, and are used when code signing your app. The provisioning profile must contain an App ID, that matches your app's bundle identifier, with the required capabilities enabled. The provisioning profile should be created in your Apple Developer Account.
Capabilities are closely related to the concept of entitlements. They both request the expansion of the sandbox your app runs in, to give it additional capabilities. Entitlements are typically added when developing your app, while capabilities are typically added when code signing your app for distribution. For more information about entitlements, see Entitlements.
Capabilities can be added to your app's provisioning profile in your Apple Developer Account. This is a multi-step process that requires creating a signing certificate, App ID, and provisioning profile.
When adding a new capability to your provisioning profile, you should also add the same capability to your app's Entitlements.plist file and ensure that the app consumes this file. For more information, see Entitlements. It may also be necessary to set privacy keys in Info.plist, for certain capabilities.
Creating a provisioning profile requires you to have previously created a signing certificate. The type of signing certificate depends on the intended distribution channel for your app:
- If you intend to distribute your app via the Mac App Store, see Create a distribution certificate in Publish a Mac Catalyst app for Mac App Store distribution.
- If you intend to distribute your app outside the Mac App Store, see Create a developer ID application certificate in Publish a Mac Catalyst app for distribution outside the Mac App Store.
- If you intend to distribute your app to a limited number of users on registered devices, outside the Mac App Store, see Create a development certificate in Publish a Mac Catalyst app for ad-hoc distribution.
[!INCLUDE Create an App ID]
Once you've created an App ID you must create a provisioning profile for the App ID. The provisioning profile you create will also depend on the intended distribution channel for your app:
- If you intend to distribute your app via the Mac App Store, see Create a provisioning profile in Publish a Mac Catalyst app for Mac App Store distribution.
- If you intend to distribute your app outside the Mac App Store, see Create a provisioning profile in Publish a Mac Catalyst app for distribution outside the Mac App Store.
- If you intend to distribute your app to a limited number of users on registered devices, outside the Mac App Store, see Create a provisioning profile in Publish a Mac Catalyst app for ad-hoc distribution.
[!INCLUDE Visual Studio for Mac end of life]
Once you've created a provisioning profile it must be downloaded by Visual Studio for Mac:
- In Visual Studio for Mac, go to Visual Studio > Preferences > Publishing > Apple Developer Account.
- In the Apple Developer Accounts window, select a team and click the View Details... button.
- In the Details window, verify that the new profile appears in the Provisioning Profiles list. You may need to restart Visual Studio for Mac to refresh the list.
- In the Details dialog, click the Download All Profiles button.
The provisioning profile will then be available for use.
Note
You can also download your provisioning profile in Xcode. For more information, see Download your provisioning profile in Xcode.
The project file for your app should be updated to use the signing certificate, provisioning profile, and entitlements file. This can be achieved by adding the following build properties to a <PropertyGroup> in your project file:
| Property | Value |
|---|---|
<CodesignKey> |
The name of the code signing key. Set to the name of your distribution certificate, as displayed in Keychain Access. |
<CodesignEntitlements> |
The path to the entitlements file that specifies the entitlements the app requires. Set to Platforms\MacCatalyst\Entitlements.plist. |
<CodesignProvision> |
The provisioning profile to use when signing the app bundle. |
<EnableCodeSigning> |
Set to true so that code signing is enabled. |
The following example shows a typical property group for building and signing your Mac Catalyst app for Mac App Store distribution:
<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Release|net8.0-maccatalyst|AnyCPU'">
<EnableCodeSigning>True</EnableCodeSigning>
<CodesignKey>Apple Distribution: John Smith (AY2GDE9QM7)</CodesignKey>
<CodesignProvision>MyMauiApp</CodesignProvision>
<CodesignEntitlements>Platforms\MacCatalyst\Entitlements.plist</CodesignEntitlements>
</PropertyGroup>The following list details the common issues that can cause issues when developing a .NET MAUI Mac Catalyst app that uses capabilities:
[!INCLUDE Troubleshooting capabilities]