Device Provisioning

Setting up a device for development

PDF for offline use:
Related Articles:

Let us know how you feel about this.


0/250
Thanks for the feedback!

last updated: 2016-12

Once Xamarin.iOS has been successfully installed, the next step in iOS development is to provision your iOS device. This guide will explore requesting development certificates and profiles, working with app services, and deploying an app to device.

Contents

This article covers the following topics in detail:

Overview

While developing a Xamarin.iOS application it is essential to test it by deploying the app to a physical device, in addition to the simulator. Device-only bugs and performance issues can transpire when running on a device, due to hardware limits such as memory or network connectivity. To test on a physical device, the device must be provisioned, and Apple must be informed that the device will be used for testing.

The highlighted sections in the image below show the steps required to get set up for iOS provisioning:

This guide illustrates how to set up an Apple device for deployment and how to deploy an application. After this, the next step is to distribute the application. For more information on deployment, visit the App Distribution guides.

Before deploying the application to a device, you need to have an active subscription to Apple's Developer Program, or use Free Provisioning. Apple offers two program options:

  • Apple Developer Program – Regardless of whether you are an individual or represent an organization, the Apple Developer Program allows you to develop, test, and distribute apps.
  • Apple Developer Enterprise Program – The Enterprise program is most suited to organizations that want to develop and distribute apps in-house only. Members of the Enterprise program do not have access to iTunes Connect, and apps created cannot be published to the App Store.

To register for either of these programs, visit the Apple Developer Portal to register. Note that in order to register as an Apple developer, it is necessary to have an Apple ID. This guide has been created with the assumption that you are a member of an Apple Developer Program.

Alternatively, Apple introduced Free Provisioning in Xcode 7 which allows a single application to run on a single device without being a member of Apple's Developer Program. There are a number of limitations when provisioning in this way, as detailed here.

Any application that runs on a device needs to include a set of metadata (or thumbprint), which contains information about the application and the developer. Apple uses this thumbprint to make sure that the application is not tampered with when deploying to, or running on, a user's device. This is achieved by requiring app developers to register their Apple ID as a developer, and to setup an App ID, request a Certificate, and register the device on which the application will be deployed.

When deploying an application to a device, a Provisioning Profile is also installed on the iOS device. The Provisioning Profile exists to verify the information that the app was signed with at build time and is cryptographically signed by Apple. Together, the Provisioning Profile and 'thumbprint' checks determine if an application can be deployed to a device by checking:

  • Who (Certificates – has the app been signed with a private key, which has a corresponding public key in the provisioning profile? The certificate also associates the developer with a development team)
  • What (Individual App ID – Does the Bundle Identifier set in the Info.plist match the App ID in the provisioning profile?)
  • Where (Devices – Is the device contained in the provisioning profile?)

These steps ensure that everything that is created or used during the development process, including the applications and devices, can be traced back to an Apple Developer account.

To many developers, provisioning is regarded as being particularly difficult. It is therefore recommended to completely read this guide, be familiar with its contents, and make sure everything is set up properly before continuing iOS development.

Requesting a Development Certificate

The first step in setting up a development device is to request a development certificate from Apple. Development certificates and associated keys are critical for an iOS developer: they establish your identity with Apple and associate you with a given device and profile for development, akin to putting your digital signature on your applications. Apple checks for certificates to control access to the devices you are allowed to deploy.

Apple provides two ways to manage development teams, certificates and profiles:

Apple requires you to have a development certificate or signing identity in order to build your code for device or simulator. It is recommended to use Xcode to set up and configure accounts, and to use the Members Center as a fallback, but both methods are described in more detail in the following sections.

⚠️

It is important to note that you can only have two iOS Development certificates at any one time. If you need to create any more, you will need to revoke an existing one. Any machine using a revoked certificate will not be able to sign their app.

Using Xcode

Before any of the required certificates or profiles can be added, the developer must attach their Apple ID Account to Xcode:

The following steps will need to be done on the Mac that is connected to Visual Studio via the Xamarin Mac Agent, allowing you to develop and build iOS applications:

  1. Open Xcode.
  2. Choose Xcode Menu >Preferences...
  3. Click the Accounts tab.
  4. Click the + button and select Add Apple ID... from the popup menu:

  5. If you have an Apple ID, enter the Apple ID and password, and click the Sign In button:

    Otherwise, click Create an Apple ID and follow the steps to create a new Apple ID. Note that you will be able to log in here, regardless of if your Apple ID is connected to a Developer Program. If it's not, you can either sign up for one by visiting the Apple Developer Portal or use Free Provisioning.

  6. Select the team, and click View Details:

  7. Xcode will display all the possible Signing Identities that can be requested for a membership Level. Click the Create button next to iOS Development:

  8. Apple may prompt you to Review and Accept any updated license agreements before you will be allowed to create a new development certificate. If this is the case, the error message below will bw displayed:

    Log on to the Developer Center to accept this license:

  9. Depending on the team privileges of the Apple acount, the signing identity will be generated, or a team agent or admin approve it. Note that there is not always visual feedback on this part of the process, and so the best way to confirm that the signing Identity has been created is by browsing to the Keychain Access application, and searching for the certificate, as shown below:

It may be necessary to stop and restart Visual Studio for the provisioning changes to take effect.

Generate a Development Certificate Manually

It is possible to manually provisioning manual using the Apple Developer Portal. This requires a few more steps:

  1. Login to the Certificates, Identifiers, and Profiles section of the Developer Portal and select the Certificates section from the iOS Apps column. Then, hit the + to create a new certificate:

  2. Select the iOS App Development option for the certificate type and click Continue. This screen may look different depending on your account privileges:

  3. Request a Certificate Signing Request, which will be uploaded to generate a certificate manually. To do this, launch Keychain Access on a Mac. Navigate to the main menu, and select Certificate Assistant and Request a Certificate from a Certificate Authority..., as illustrated below:

  4. Fill in your information, and select the option to Save to disk:

  5. Save the CSR at a location where it can be easily found:

  6. Return to the Provisioning Portal, upload the Certificate to the portal, and submit:

    If you do not have admin privileges, the Certificate must be approved by an admin or team agent.

  7. Once the Certificate is approved, download it from the Provisioning Portal:

  8. Double-click on the downloaded Certificate to launch Keychain Access and open the My Certificates panel, showing the new certificate(s), and associated private key:

Understanding Certificate Key Pairs

The Developer Profile contains certificates, their associated keys, and any provisioning profiles associated with the account. There are actually two versions of a Developer Profile — one is on the Developer Portal, and the other lives on a local Mac. The difference between the two is the type of keys they contain: the Profile on the Portal houses all the public keys associated with your certificates, while the copy on your local Mac contains all the private keys. For the certificates to be valid, the key pairs must match. Keep a backup of the Developer Profile on the local Mac, because if the private keys are lost, all the certificates and provisioning profiles will need to be regenerated.

The Developer Profile contains certificates, their associated keys, and any provisioning profiles associated with the account. There are actually two versions of a Developer Profile — one is on the Developer Portal, and the other lives on a Mac. The difference between the two is the type of keys they contain: the Profile on the Portal houses all the public keys associated with your certificates, while the copy on your the Mac contains all the private keys. For the certificates to be valid, the key pairs must match. Keep a backup of the Developer Profile on from the Xamarin Build Host's Mac, because if the private keys are lost, all the certificates and provisioning profiles will need to be regenerated.

🚫

Note: Losing the certificate and associated keys can be incredibly disruptive, as it will require revoking existing certificates and re-provisioning any associated devices, including those registered for ad-hoc deployment. After successfully setting up Development Certificates, export a backup copy and store them in a safe place. For more information on how to do this, refer to the Exporting and Importing Certificates and Profiles section of the Maintaining Certificates guide in Apple's docs.

Provisioning an iOS Device for Development

Now that you’ve established your identity with Apple and have a development certificate, let's set up a provisioning profile and the required entities so it is possible to deploy an app to an Apple device. The device must be running a version of iOS that is supported by Xcode — it may be necessary to update the device, Xcode or both.

Add a Device

When creating a provisioning profile for development, we must state which devices can run the application. To enable this, up to 100 devices per calendar year can be added to our Developer Portal, and from here we can select the devices to be added to a particular provisioning profile. Follow the steps below to add a device to the Developer Portal

The following step will need to be done on the Mac:

  1. Start Xcode.
  2. Connect the device to be provisioned to the Mac with its supplied USB cable.
  3. From the Windows menu select Devices:

  4. Select the desired iOS device from the DEVICES list on the left side of the Devices Window.

  5. Highlight the Identifier string and copy it to the clipboard:

  6. In Safari, navigate to the Apple Developer Center and log in.

  7. Click the Certificates, Identifiers & Profiles link:

  8. Click on the Devices link:

  9. Click the + button:

  10. Provide a name for the new device and paste the device Identifier that we copied above into the UUID field:

  11. Click the Continue button.

  12. Finally, review the information and click the Register button:

Repeat the above steps for any iOS device that will be used to test or debug a Xamarin.iOS application.

After adding the device to the developer portal, it is necessary to create a provisioning profile and add the device to it.

Creating a Development Provisioning Profile

As with the Development Certificate, Apple provides two ways to create a Provisioning Profile for an application:

The next few sections explain those two ways.

Creating a Team Provisioning Profile via Xcode

Team Provisioning Profiles can be created and managed through Xcode automatically. Provisioning Profiles created in this way do the following:

  • Add all team members.
  • Add all devices.
  • Add Keychain, In-App Purchase, and Game Center capabilites

To create a Team Provisioning Profile, create a dummy iOS Application in Xcode, by browsing to File > New > Project. Select your Team from the dropdown list:

This will automatically generate a new provisioning profile, as displayed in the Signing section of the General tab:

If Xcode does not automatically generate a new provisioning profile, you may need to select the Automatically Manage Signing checkbox, as illustrated below:

The provisioning profile can be inspected by clicking on the i next to Xcode Managed Profiles.

Xcode automatically adds an App ID, certificates, your Team and some basic capabilities to the provisioning profile. The Capabilities tab in Xcode can be used to add additional capabilites as required by your app.

A device is considered provisioned when a provisioning profile containing information about that device is installed on the device.

Manually Creating an App ID and Provisioning Profile

ℹ️

If a Team Provisioning Profile has been created via Xcode it is NOT necessary to create a provisioning profile and app ID manually. It is only necessary to create one or the other. You can skip ahead to the section on Downloading Profiles and Certificates in Xcode.

Provisioning Profiles can also be created through Apple's Developer Portal, but before creating a provisioning profile, an App ID must be made. An App ID is a reverse-DNS style string that uniquely identifies an application. The steps below will demonstrate how to create a Wildcard App ID, which can be used to build and install most applications. Explicit App IDs only allow the installation of one application (with the matching bundle ID), and are generally used for certain iOS features such as Apple Pay and HealthKit. For information on creating Explicit App IDs, refer to the Provisioning for Application services section of this guide.

App ID

  1. In the developer portal browse to the Certificate, Identifiers and Profiles section in the Apple Developer Center. Select App IDs under Identifiers.
  2. Click the + button and provide a Name:
  3. The App prefix should be preset. Select Wildcard App ID for the app suffix. Enter a Bundle ID in the format com.[DomainName].*:

  4. Click the Continue button and following the on screen instructions to create the new App ID.

Provisioning Profile

Once the App ID has been created, the Provisioning Profile can be produced. This Provisioning Profile contains information on what app (or apps, if it's a wildcard app ID) this profile relates to, who can use the profile (depending on what developer certificates are added), and what devices can install the app.

ℹ️

Note that when using an Apple Enterprise Developer account, only Admins and Team Agents can manually create provisioning profiles, members cannot. Instead, members should use the Xcode method, listed above.

To manually create a provisioning profile for development, do this:

  1. Use Safari to browse to the Apple Developers Member Center, and under the section Certificates, Identifiers & Profiles select Provisioning Profiles.
  2. Click the + button, in the top right corner to create a new profile.
  3. From the Development section, select the radio button next to iOS App Development, and press Continue:
  4. From the dropdown menu, select the App ID that to use:
  5. Select the Certificate(s) to include in the provisioning profile, and press Continue:
  6. Select all the devices that the app will be installed on.
  7. Provide the Provisioning Profile with an identifiable a name, and press Continue to create the profile:
  8. Press Download to download the provisioning profile onto a Mac:
  9. Double-click on the file to install the provisioning profile in Xcode. Note that Xcode might not show any visual clues that it has installed the profile except for opening. This can be verified by browsing to Xcode > Preferences > Accounts. Select your Apple ID and click View Details.... Your new provisioning profile should be listed, as illustrated below:

After the provisioning profile has been successfully created it may be necessary to refresh Xcode so that all the development certificates are available to Xamarin Studio and Visual Studio.

Downloading Profiles and Certificates in Xcode

Certificates and provisioning profiles that have been created in the Apple Developer Portal, may not automatically appear in Xcode. Therefore, it may be necessary to download them so they that they can be accessed by Xamarin Studio and Visual Studio. To update and download any certificates created in the Apple Developer portal, do the following:

  1. Quit Xamarin Studio or Visual Studio.
  2. Start Xcode.
  3. Choose Xcode Menu > Preferences...
  4. Click the Accounts tab.
  5. Click the View Details... button:

  6. The Account Details sheet will be displayed. If a Download button appears next to a provisioning profile, it is not on the machine. If an Update button appears, changes have been made to the provisioning profile on the machine:

  7. Provisioning profiles can be updated or downloaded individually by clicking the button next to its name. Otherwise, click the Download All button in the lower left hand corner of the screen to download and update all provisioning profiles at once.

  8. After the list of available Provisioning Profiles has been updated, click the Done button.
  9. Quit Xcode.
  10. Start Xamarin Studio or Visual Studio.

The new certificates or provisioning profiles will be available in Xamarin Studio or Visual Studio and ready to use.

⚠️

Note: It is sometime necessary to stop and restart Xamarin Studio before it will see any new or modified certificates or profiles updated by Xcode.

⚠️

Note: It is sometime necessary to stop and restart Visual Studio before it will see any new or modified certificates or profiles updated by Xcode.

Provisioning for Application Services

Apple provides a selection of special Application Services, also called capabilites, that can be activated for a Xamarin.iOS application. The following services are available:

  • App Groups
  • Associated Domains
  • Data Protection
  • Game Center
  • HealthKit
  • HomeKit
  • Wireless Accessory Configuration
  • iCloud
  • In-App Purchase
  • Inter-App Audio
  • Apple Pay
  • Wallet
  • Push Notification
  • Personal VPN
  • Siri
  • Maps
  • Background Modes
  • Keychain Sharing

These Application Services must be configured on both the iOS Provisioning Portal when the App ID is created and in the Entitlements.plist file that is part of the Xamarin.iOS application's project.

Set Entitlements for an App ID

A unique App ID is required before it is possible to select any Application Services for a Xamarin.iOS application. It is possible to view existing App IDs and add additional App IDs by browsing to the iOS Provisioning Portal and navigating to Identifiers > App ID:

To add a new App ID, do the following:

  1. Click the + button and provide a Name. Selet the Explicit App ID and set the Bundle ID for the new application. This should match the Bundle Identifier that has been set in the application's Info.plist:

  2. Scroll to the bottom of the screen and select any App Services that will be required by the Xamarin.iOS application:

  3. Click the Continue button and following the on screen instructions to create the new App ID.

Several of the Application Services (such as Passbook, Push Notifications, iCloud, App Groups and Apple Pay) will require additional setup before they can be used in a Xamarin.iOS application. The screenshot below from the developer portal shows the various IDs and containers that can be created:

Information on using these Application services can be found in the following guides:

Once the App ID is created, it is necessary to create a new provisioning profile that contains this App ID.

It may be necessary to quit Xamarin Studio and have Xcode refresh its list of available Signing Identities and Provisioning Profiles (by following the instructions in Requesting Signing Identities section) before a provisioning profile with the new App ID is available in Xamarin Studio.

It may be necessary to quit Visual Studio and have Xcode (on the Mac) refresh its list of available Signing Identities and Provisioning Profiles (by following the instructions in Requesting Signing Identities section) before a provisioning profile with the new App ID becomes available in Visual Studio.

Set Entitlements in the Xamarin.iOS Project

As stated above, in addition to selecting and configuring the required Application Services when defining the App ID, the entitlements also need to be configured in the Xamarin.iOS project by editing both the Info.plist and Entitlements.plist files.

To configure the entitlements in Xamarin Studio, do the following:

  1. In the Solution Explorer, double-click the Info.plist file to open it for editing.
  2. In the iOS Application Target section, fill in a name for the application and enter the Bundle Identifier that was created when the App ID was defined:

  3. Save the changes to the Info.plist file.

  4. In the Solution Explorer, double-click the Entitlements.plist file to open it for editing:

  5. Select and configure any entitlements required for the Xamarin.iOS application so that they match the setup that was defined when the App ID was created.

  6. Save the changes to the Entitlements.plist file.

To configure the entitlements in Visual Studio, do the following:

  1. In the Solution Explorer, double-click the Info.plist file to open it for editing.
  2. In the iOS Application Target section, fill in a name for the application and enter the Bundle Identifier that was created when the App ID was defined:

  3. Save the changes to the Info.plist file.

  4. In the Solution Explorer, double-click the Entitlements.plist file to open it for editing:

  5. Select and configure any entitlements required for the Xamarin.iOS application so that they match the setup that was defined when the App ID was created.

  6. Save the changes to the Entitlements.plist file.
⚠️

Note: The special configuration required for the Passbook, Push Notifications, iCloud, App Groups, and Apple Pay Application Services is beyond the scope of this article. Please see our documentation on the specific Application Services for more details.

Working with App Groups

An App Group allows different applications (or an application and its extensions) to access a shared file storage location. App Groups can be used for data like:

Configure an App Group

The shared location is configured using an App Group, which is configured in the Certificates, Identifiers & Profiles section on iOS Dev Center. This value must also be referenced in each project's Entitlements.plist.

The app group will have an identifier, which is typically the Bundle ID with a group. prefix. For example, the Bundle ID com.xamarin.WatchSettings would have the app group group.com.xamarin.WatchSettings.

To create a new App Group, do the following:

  1. Visit Apple's iOS Dev Center, open your Account and log in.
  2. From the Program Resources menu select Certificates, IDs & Profiles.
  3. Under Identifiers select App Groups and click the + button to create a new group:

  4. Enter a Name and an Identifier for the new group and click the Continue button.

  5. Click the Register button to create the group and the Done to return to the list of registered App Groups.

Configure an App to use App Groups

With the App Group created, it is ncessary to configure the App IDs so that they can use App Groups.

Do the following:

  1. Visit Apple's iOS Dev Center, and log in with an Apple Developer Account.
  2. From the Program Resources menu select Certificates, IDs & Profiles.
  3. Under Identifiers select App IDs and click the + button to create a new ID.
  4. Create an Explicit App ID and under App Services enable App Groups, then click the Continue button:

  5. Verify the settings and click the Register button to created the App ID.

  6. Click the Done button to return to the list of registered App IDs.
  7. Select the newly created App ID from the list and click the Edit button:

  8. Under Service App Group, click the Edit button:

  9. Select the App Group that was created above and click the Continue button:

  10. Click the Assign button, then the Done button to return to the list of registered App IDs.

  11. Repeat these steps for any Apps (or Extensions) that will be using the App Group.

Configuring A Xamarin Projects

With the required App Group and App IDs created, it is necessary to modify the Xamarin App (or Extension) project to use the App Group.

Do the following:

  1. After downloading and installing the App IDs and Provisioning Profiles (see Downloading Profiles and Certificates in Xcode below), edit the Solution in Xamarin Studio.
  2. Edit each Project's Info.plist file and ensure that the App ID matches one that was selected above:

  3. Next, edit the Entitlements.plist file, scroll to the App Groups section, check Enable App Groups and add the App Group that was created above:

  4. Repeat for each App or Extension in the Solution that will be using the App Group.

Testing App Groups

When testing and debugging App Groups, either in the Simulator or on physical iOS hardware, ensure that the Entitlements.plist file gets included in the build. This setting is not automatically selected for iOS Simulator and Debug builds.

Do the following:

  1. Edit the Project Options.
  2. Select iOS Bundle Signing (ensure Debug and iPhoneSimulator are selected for the Configuration and Platform):

  3. Click the ... button by Custom Entitlements and select the Entitlements.plist that was previous modified.

  4. Click the OK button to save the changes.
  5. Repeat for each App or Extension in the Solution that will be using the App Group.

Troubleshooting App Group Issues

If there issues accessing shared data when developing an App or Extension using App Groups, check one of the following common causes:

  • Ensure that the App Group has been properly created and registered in the Certificates, IDs & Profiles of Apple's Developer Portal.
  • Ensure that the App Groups Service have been added to the App's (or Extension's) ID and that the service is configured to use the App Group created above in the Certificates, IDs & Profiles of Apple's Developer Portal.
  • Ensure that the Provisioning Profiles and App IDs have been installed and that the App's Info.plist (in the Xamarin Project) is using one of the App IDs configured above.
  • Ensure that the App's Entitlements.plist file (in the Xamarin Project) has the App Groups Service enabled and that the App Group created above is included in the list of App Groups.
  • In the App's Build Settings, ensure that the Entitlements.plist file is included in the App's Bundle. Note: This is not the default setting for Debug and iOS Simulator builds.

Deploying to a Device

At this point provisioning should be complete, and the app is ready to be deployed to the device. To do this, follow the steps below:

  1. Plug the device in to a Mac.
  2. In the project's Info.plist, make sure the Bundle Identifier matches the App ID (unless the App ID is a wildcard):

  3. Right-click on the project to view the Project Options dialog and browse to Build > iOS Bundle Signing. From the drop-down list next to both the Signing Identity and Provisioning Profile, verify that Xamarin Studio can see the correct profiles, and select a specific identity & profile:

    If this is set to Automatic, Xamarin Studio will select the identity and profile based on the Bundle ID that was set in step #2.

  4. Make sure to set the build configuration to iPhone / iPad, rather the simulator.

  5. Click Run in Xamarin Studio and view the app running on the device.
  1. Plug the device in to a Mac.
  2. In the project's Info.plist, make sure the Bundle Identifier matches the App ID:

  3. Right-click on the project to view the Project Options dialog, and browse to Build > iOS Bundle Signing. From the drop-down list next to both the Signing Identity and Provisioning Profile verify that Xamarin Studio can see the correct profiles, and select a specific identity & profile.

    If this is set to Automatic, Visual Studio will select the identity and profile based on the Bundle ID that was set in step #2.

  4. Make sure to set the build configuration to iPhone or iPad, rather the simulator.

  5. Click Run in Visual Studio and view the app running on the device.

Summary

This guide covered the steps required to setup the development environment for Xamarin.iOS. It explored how an application is code signed with information about the developer, their team, the devices that an app can run on, and individual app id.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.