Publish an iOS app for ad-hoc distribution

• Publish for app store distribution
• Publish for in-house distribution
• Publish using the command line

Ad-hoc distribution is primarily used for testing apps within a wide group of people, and is available for the Apple Developer Program and the Apple Developer Enterprise Program. Another use case for ad-hoc distribution is distribution within a company when App Store Connect isn't an option.

Ad-hoc distribution has the advantage of not requiring App Store approval, with apps being installed with Apple Configurator. However, it's limited to 100 devices per membership year, for both development and distribution, and the devices must be added to your Apple Developer Account.

Distributing an iOS app requires that the app is provisioned using a provisioning profile. Provisioning profiles are files that contain code signing information, as well as the identity of the app and its intended distribution mechanism.

To distribute a .NET Multi-platform App UI (.NET MAUI) iOS app, you'll need to build a distribution provisioning profile specific to it. This profile enables the app to be digitally signed for release so that it can be installed on an iOS device. An ad-hoc distribution provisioning profile contains an App ID, a distribution certificate, and a list of the devices that can install the app. You can use the same App ID that you used when deploying your app to a device for testing. However, you'll need to create a distribution certificate to identify yourself or your organization, if you don't already have one.

The process for creating an ad-hoc distribution provisioning profile is as follows:

1. Create a distribution certificate. For more information, see Create a distribution certificate.
2. Add devices to your Apple Developer Account. For more information, see Add a device.
3. Create an App ID. For more information, see Create an App ID.
4. Create a provisioning profile. For more information, see Create a provisioning profile.

Create a distribution certificate

A distribution certificate is used to confirm your identity. Before creating a distribution certificate, you should ensure that you've added your Apple Developer Account to Visual Studio. For more information, see Apple account management.

You only need to create a distribution certificate if you don't already one. The distribution certificate must be created using the Apple ID for your Apple Developer Account.

To create a distribution certificate:

Visual Studio

1. In Visual Studio, go to Tools > Options > Xamarin > Apple Accounts.
2. In the Apple Developer Accounts dialog, select a team and click the View Details... button.
3. In the Details dialog, click Create Certificate and select iOS Distribution. A new signing identity will be created and will sync with Apple provided that you have the correct permissions.

Important

The private key and certificate that make up your signing identity will also be exported to Keychain Access on your Mac build host, provided that the IDE is paired to it. For more information, see Pair to Mac for iOS development.

Visual Studio for Mac

Note

Visual Studio for Mac is scheduled for retirement by August 31 2024 in accordance with Microsoft's Modern Lifecycle Policy. Visual Studio for Mac 17.6 will continue to be supported until August 31 2024, with servicing updates for security issues and updated platforms from Apple. For more information, including alternative options for developing on a Mac, see What's happening to Visual Studio for Mac?.

1. In Visual Studio for Mac, go to Visual Studio > Preferences > Publishing > Apple Developer Account.
2. In the Apple Developer Accounts window, select a team and click the View Details... button.
3. In the Details window, click Create Certificate and select Apple Distribution or iOS Distribution. A new signing identity will be created and will sync with Apple provided that you have the correct permissions.

Understanding certificate key pairs

A distribution profile contains certificates, their associated keys, and any provisioning profiles associated with your Apple Developer Account. There are two versions of a distribution profile — one exists in your Apple Developer Account, and the other lives on a local machine. The difference between the two is the type of keys they contain: the profile in your Apple Developer Account contains all of the public keys associated with your certificates, while the copy on your local machine contains all of the private keys. For certificates to be valid, the key pairs must match.

Warning

Losing the certificate and associated keys can be incredibly disruptive, as it will require revoking existing certificates and re-creating provisioning profiles.

Create a distribution profile

An ad-hoc distribution provisioning profile enables your .NET MAUI iOS app to be digitally signed for release, so that it can be installed on specific iOS devices. An ad-hoc distribution provisioning profile contains an App ID, a distribution certificate, and a list of the devices that can install the app. The devices you wish to support must be running a version of iOS that's supported by Xcode.

Add a device

When you create a provisioning profile, the profile must include which devices can run the app. Before selecting a device to be added to a provisioning profile, you must first add the device to your Apple Developer Account. You can add the device with the following steps:

1. Connect the device to be provisioned to your local Mac with a USB cable.

2. Open Xcode, and navigate to Window > Devices and Simulators.

3. In Xcode, select the Devices tab, and select the device from the list of connected devices.

4. In Xcode, copy the Identifier value to the clipboard:

   

5. In a web browser, go to the Devices section of your Apple Developer Account and click the + button.

6. In the Register a New Device page, set the correct Platform and provide a name for the new device. Then paste the identifier from the clipboard into the Device ID (UDID) field, and click Continue:

   

7. In the Register a New Device page, review the information and then click Register.

Repeat the previous steps for any iOS device that you want to deploy a .NET MAUI iOS app onto.

Create an App ID

An App ID is required to identify the app that you are distributing. An App ID is similar to a reverse-DNS string, that uniquely identifies an app, and should be identical to the bundle identifier for your app. You can use the same App ID that you used when deploying your app to a device for testing.

There are two types of App ID:

• Wildcard. A wildcard App ID allows you to use a single App ID to match multiple apps, and typically takes the form com.domainname.*. A wildcard App ID can be used to distribute multiple apps, and should be used for apps that do not enable app-specific capabilities.
• Explicit. An explicit App ID is unique to a single app, and typically takes the form com.domainname.myid. An explicit App ID allows the distribution of one app, with a matching bundle identifier. Explicit App IDs are typically used for apps that enable app-specific capabilities such as Apple Pay, or Game Center. For more information about capabilities, see Capabilities.

To create a new App ID:

1. In your Apple Developer Account, navigate to Certificates, IDs & Profiles.

2. On the Certificates, Identifiers & Profiles page, select the Identifiers tab.

3. On the Identifiers page, click the + button to create a new App ID.

4. On the Register a new identifier page, select the App IDs radio button before clicking the Continue button:

   

5. On the Register a new identifier page, select App before clicking the Continue button:

   

6. On the Register an App ID page, enter a description, and select either the Explicit or Wildcard Bundle ID radio button. Then, enter the Bundle ID for your app in reverse DS format:

   

   Important

   The Bundle ID you enter must correspond to the Bundle identifier in the Info.plist file in your app project.

   The bundle identifier for a .NET MAUI app is stored in the project file as the Application ID property:

   • In Visual Studio, in Solution Explorer right-click on your .NET MAUI app project and select Properties. Then, navigate to the MAUI Shared > General tab. The Application ID field lists the bundle identifier.
   • In Visual Studio for Mac, in the Solution Window, right-click on your .NET MAUI app project and select Properties. Then, in the Project Properties window, select the Build > App Info tab. The Application ID field lists the bundle identifier.

   When the value of the Application ID field is updated, the value of the Bundle identifier in the Info.plist will be automatically updated.

7. On the Register an App ID page, select any capabilities that the app uses. Any capabilities must be configured both on this page and in the Entitlements.plist file in your app project. For more information see Capabilities and Entitlements.

8. On the Register an App ID page, click the Continue button.

9. On the Confirm your App ID page, click the Register button.

Create a provisioning profile

Once the App ID has been created, you should create a distribution provisioning profile. This profile enables the app to be digitally signed for release so that it can be installed on an iOS device.

To create a provisioning profile for ad-hoc distribution:

1. In the Certificates, Identifiers & Profiles page of your Apple Developer Account, select the Profiles tab.

2. In the Profiles tab, click the + button to create a new profile.

3. In the Register a New Provisioning Profile page, select the Ad Hoc radio button before clicking the Continue button:

   

4. In the Generate a Provisioning Profile page, in the App ID drop-down, select the App ID that you previously created, and choose whether to create an offline profile, before clicking the Continue button:

   

5. In the Generate a Provisioning Profile page, select the radio button that corresponds to your distribution certificate before clicking the Continue button:

   

6. In the Generate a Provisioning Profile page, select the devices that the app will be installed on and then click the Continue button.

   

7. In the Generate a Provisioning Profile page, enter a name for the provisioning profile before clicking the Generate button:

   

   Note

   Make a note of the provisioning profile name, as it will be required when signing your app.

8. In the Generate a Provisioning Profile page, optionally click the Download button to download your provisioning profile.

   Note

   It's not necessary to download your provisioning profile now. Instead, you will do this in Visual Studio.

Download provisioning profiles in Visual Studio

After you create a distribution provisioning profile in your Apple Developer Account, Visual Studio can download it so that it's available for signing your app.

Visual Studio

1. In Visual Studio, go to Tools > Options > Xamarin > Apple Accounts.
2. In the Apple Developer Accounts dialog, select your team and click View Details.
3. In the Details dialog, verify that the new profile appears in the Provisioning Profiles list. You may need to restart Visual Studio to refresh the list.
4. In the Details dialog, click Download All Profiles.

The provisioning profiles are downloaded on Windows, and exported to your Mac build host if the IDE is paired to it. For more information, see Pair to Mac for iOS development.

Visual Studio for Mac

Note

Visual Studio for Mac is scheduled for retirement by August 31 2024 in accordance with Microsoft's Modern Lifecycle Policy. Visual Studio for Mac 17.6 will continue to be supported until August 31 2024, with servicing updates for security issues and updated platforms from Apple. For more information, including alternative options for developing on a Mac, see What's happening to Visual Studio for Mac?.

1. In Visual Studio for Mac, go to Visual Studio > Preferences > Publishing > Apple Developer Account.
2. In the Apple Developer Accounts window, select your team and click View Details.
3. 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.
4. In the Details dialog, click Download All Profiles.

The development provisioning profile is now available for use.

Publish the app

Visual Studio can publish a .NET MAUI iOS app for ad-hoc distribution. For information about publishing an iOS app using the Command Line Interface (CLI), see Publish an iOS app using the command line.

Visual Studio

1. In Visual Studio, ensure that the IDE is paired to a Mac Build host. For more information, see Pair to Mac for iOS development.

2. In the Visual Studio toolbar, use the Debug Target drop-down to select iOS Remote Devices and then Remote Device:

   

3. In the Visual Studio toolbar, use the Solutions Configuration drop-down to change from the debug configuration to the release configuration:

   

4. In Solution Explorer, right-click on your .NET MAUI app project and select Properties. Then, navigate to the iOS Bundle Signing tab and ensure that Scheme is set to Manual Provisioning, Signing identity is set to Distribution (Automatic), and Provisioning profile is set to Automatic:

   

   These settings will ensure that Visual Studio will select the correct provisioning profile based on the bundle identifier in Info.plist (which is identical to the value of the Application ID property in your project file). Alternatively, set the Signing identity to the appropriate distribution certificate and Provisioning profile to the profile you created in your Apple Developer Account.

5. In Solution Explorer, right-click on your .NET MAUI app project and select Publish...:

   

   The Archive Manager will open and Visual Studio will begin to archive your app bundle:

   

   The archiving process signs the app with the certificate and provisioning profiles that you specified in the iOS Bundle Signing tab, for the selected solution configuration.

6. In the Archive Manager, once archiving has successfully completed, ensure your archive is selected and then select the Distribute ... button to begin the process of packaging your app for distribution:

   

   The Distribute - Select Channel dialog will appear.

7. In the Distribute - Select Channel dialog, select the Ad Hoc button:

   

8. In the Distribute - Signing Identity dialog, select your signing identity and provisioning profile:

   

   Note

   You should use the signing identity and provisioning profile that were created for your app and the selected distribution channel.

9. In the Distribute - Signing Identity dialog, select the Save As button and enter a filename. Your app will then be re-signed and published to an .ipa file on your file system.

Visual Studio for Mac

Note

Visual Studio for Mac is scheduled for retirement by August 31 2024 in accordance with Microsoft's Modern Lifecycle Policy. Visual Studio for Mac 17.6 will continue to be supported until August 31 2024, with servicing updates for security issues and updated platforms from Apple. For more information, including alternative options for developing on a Mac, see What's happening to Visual Studio for Mac?.

1. In the Visual Studio for Mac toolbar, use the Build Configuration drop-down to change from the debug configuration to the release configuration:

   

2. In the Visual Studio for Mac toolbar, use the Debug Target drop-down to select iOS Build Only Device > Generic Device:

   

3. In the Solution Window, right-click on your .NET MAUI app project and select Properties. Then, in the Project Properties window, select the Build > iOS > Bundle Signing tab and ensure that Signing Identity is set to Distribution (Automatic), and Provisioning profile is set to Automatic or the distribution channel for your app (such as App Store (Automatic)):

   

   These settings will ensure that Visual Studio for Mac will select the correct provisioning profile based on the bundle identifier in Info.plist (which is identical to the value of the Application ID property in your project file). Alternatively, set the Signing identity to the appropriate distribution certificate and Provisioning profile to the profile you created in your Apple Developer Account.

   Select the OK button to close the Project Properties window.

4. In the Solution Window, right-click on your .NET MAUI app project and select Archive for Publishing:

   

   Visual Studio for Mac will begin to archive your app bundle, and progress can be monitored in the Archive window. The archiving process signs the app with the certificate and provisioning profiles that you specified in the iOS Bundle Signing tab, for the selected solution configuration. When the archiving process successfully completes, the Archives tab will be opened.

5. In the Archives tab, ensure your archive is selected and then select the Sign and Distribute... button to begin the process of packaging your app for distribution:

   

   The Sign and Distribute window will appear.

6. In the Sign and Distribute window, select the Ad Hoc distribution channel, and then select the Next button:

   

7. In the Sign and Distribute window, ensure that the Use Existing Identity and Provisioning Profile radio button is selected and then select the Next button:

   

   Note

   You should use the signing identity and provisioning profile that were created for your app and the selected distribution channel.

   Alternatively, select the Re-sign With Another Identity and Provisioning Profile radio button and choose your signing identity and provisioning profile.

8. In the Sign and Distribute window, select the Publish button:

   

9. In the Output IPA file dialog, choose a location and filename for your IPA file, and select the Save button:

   

   Your app will then be published to an .ipa file on your file system:

   

10. In the Sign and Distribute window, select the Close button.

The app can then be distributed using Apple Configurator. For more information, see Apple Configurator user guide on support.apple.com.