Device Provisioning

Setting up a device for development

PDF for offline use
Related Articles:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-07

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:

⚠️

  This guide illustrates how to use Visual Studio for Mac to set up an Apple device for deployment and how to deploy an application. For manual steps on how to do this or to do this with Visual Studio on Windows, it is recommended that you follow the detailed steps in the manual provisioning guide.

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:

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 and the manual provisioning guide, be familiar with its contents, and make sure everything is set up properly before continuing iOS development.

Selecting a Team

Before starting to code sign your app in Visual Studio for Mac, you'll have to select the Team that you belong to. This allows certificates, profiles, and other IDs to be made against the team. The team ID is also used to create a the prefix for an App ID that will be included in the provisioning profile. Having this allows Apple to verify that you are who you say you are.

There are two ways to select your team in Visual Studio for Mac:

New Project Wizard

When you create a new iOS project, the following screenshot is the first page of the wizard that is displayed:

New Project Wizard screen

It displays a bundle identifier – a string that must match the App ID contained in the provisioning profile – and a Team selector drop-down:

Team Selector drop down

Select your Team from this list, or if you haven't added one yet click the Add Team… button and follow the steps in the Apple Account Management guide.

iOS Bundle Signing Tab

Access the iOS bundle signing tab by right-clicking on the project and selecting Options > iOS Bundle Signing:

This displays a bundle identifier – a string that must match the App ID contained in the provisioning profile – and a Team selector drop-down (or button if you haven't added an account):

Team selector drop down

Select your Team from this list, or if you haven't added one yet click the Add Team… button and follow the steps in the Apple Account Management guide.

Creating or Selecting a Signing Identity

Apple requires you to have a development certificate or signing identity in order to build your code for device or simulator.

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

To select or create a new signing identity, do the following:

  1. Open the iOS bundle signing tab by right-clicking on the project and selecting Options > iOS Bundle Signing:

    Bundle Signing Tab

  2. If you have a valid development certificate, you can select it from the drop-down list next to Signing Identity, otherwise follow step #3 to create a new one.

    ⚠️

    This list displays both development and distribution certificates, so make sure to select a development certificate.

  3. From the drop-down, select Create Signing Identity…. After a few seconds a new signing identity associated with your Apple developer account is created:

    Create Signing Identity option

Creating or Selecting a Provisioning Profile

Once you have established your identity with Apple and have a development certificate, you must set up a provisioning profile and the required entities so it is possible to deploy an app to an iOS device.

To select or create a new provisioning profile, do the following:

  1. In the Provisioning Profile section of the iOS Bundle Signing tab, select the drop-down.

  2. If you have a valid provisioning profile you can select it in the list. In order for a provisioning profile to be shown in the list it must:

    • Not be expired
    • Be valid (include a valid certificate)
    • Match current distribution type (Debug => Development or Release => Distribution)
    • Include an app ID that matches the bundle identifier (located in the info.plist)
  3. To create a new profile select Create provisioning profile from the drop-down list:

    Create a provisioing profile option

Adding a device to an existing Profile

By default, creating a provisioning profile in Visual Studio for Mac automatically adds all devices that are connected to your Apple Development account. You should only need to follow the steps below for new devices.

  1. To add a device to your provisioning profile, make sure it is plugged in and selected in the active configuration:

    Select iOS device configuration dropdown

  2. Browse to the iOS Bundle Signing section of project options and ensure that the signing identity and provisioning profile drop-downs have been selected. If you device is not registered with your Team, the following message will be displayed. Click Register to add the device to your Team:

    Register option

  3. Finally, click the Add button to add the device to the existing provisioning profile.

    Add button is displayed

At this point provisioning is complete, and the app is ready to be deployed to the device.

Provisioning for Application Services

Apple provides a selection of special Application Services, also called capabilities, that can be activated for a Xamarin.iOS application. 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. For information on adding Application Services to your app, refer to the Introduction to Capabilities guide and the Working with Entitlements guide.

  • Create an App ID with the required app services.
  • Create a new provisioning profile that contains this App ID.
  • Set Entitlements in the Xamarin.iOS Project
ℹ️

Currently, provisioning profiles created in Visual Studio for Mac will not take into account entitlements selected in your projects (Entitlements.plist). This functionality will be added in future versions of the IDE. If you need to use App Services, it is recommended that you follow the instructions in the Manual Provisioning guide.

Troubleshooting

  • If you need to switch back to the previous version of signing controls, set the Team selector to None.

  • If an existing signing identity is not appearing in the drop-down list, check the following criteria:

    • The certificate is displayed on Apple Developer Portal in "Certificates" section.
    • That it has been issue for the selected team or developer
    • Both the certificate and private key should be installed in local Keychain
    • The certificate should not be expired or revoked.
  • If an existing signing identity is not appearing in the drop-down list, check the following criteria:

    • The provisioning profile is not expired
    • It is valid and includes registered devices and valid certificates
    • It matches the current distribution type (Debug or Release based on configuration)
    • The bundle identifier matches the App ID identically. Wild card profiles with a matching pattern will be also displayed in this list.
  • The device must be select in the active configuration to show the Register and Add buttons. To get the device to display in the configuration, you may need to open Xcode or iTunes in order to allow the iPhone to Trust the computer.

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.