Edit

Share via

Publish an iOS app for ad-hoc distribution

  • Article

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 in 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.

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:

    Xcode devices and simulator window with the iOS identifier string location highlighted.

  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:

    Register a device by naming it and entering its unique device identifier.

  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:

    Create an App ID.

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

    Register an App ID.

  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:

    Specify the bundle identifier for the app.

    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.

    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:

    Register a provisioning profile for ad hoc distribution.

  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:

    Select your App ID.

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

    Select your distribution certificate.

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

    Screenshot of adding a device to a provisioning profile.

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

    Generate the provisioning profile.

    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:

  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.

Publish the app

Visual Studio can publish a .NET MAUI iOS app for ad-hoc distribution:

  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:

    Select your remote device in Visual Studio.

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

    Select the release configuration in Visual Studio.

  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:

    Screenshot of bundle signing tab for iOS in Visual Studio.

    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...:

    Select the publish menu item in Visual Studio.

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

    Screenshot of the archive manager in Visual Studio.

    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:

    Screenshot of the archive manager in Visual Studio once archiving is complete.

    The Distribute - Select Channel dialog will appear.

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

    Screenshot of selecting a distribution channel in the distribution dialog.

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

    Screenshot of selecting a signing identity in the distribution dialog.

    Note

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

  3. 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.

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

For information about publishing an iOS app using the Command Line Interface (CLI), see Publish an iOS app using the command line.