Device Provisioning
Setting Up your Device for Development
Contents
This article covers the following topics in detail:
Requesting a Development Certificate
Understanding Certificate Key Pairs
Provisioning an iOS Device for Development
Team Provisioning Profile
Requesting Signing Identities
Provisioning for Application Services
Set Entitlements in your App ID
Set Entitlements in your Xamarin.iOS Project
Creating a Distribution Profile
Selecting a Distribution Profile in a Xamarin.iOS Project
Overview
Before you can deploy your application to a device, you need to have an active subscription with the Apple
Developer Program. Visit the Apple Developer Portal to get registered.
Apple has outlined a set of special guidelines that developers must follow in order to do everything from
deploying to a device to shipping to the App Store. These steps ensure that everything you create or use during
the development process, including your applications and devices, can be traced back to your Apple Developer
account.
This guide illustrates how to set up an Apple device for deployment, and deploy an application. It covers how to:
1. Generate a certificate
2. Provision the device
3. Provision the application and device to use store technologies
4. Launch the application on device with Xamarin Studio and Visual Studio
Let's get started.
WARNING: Because of changes that Apple recently made to the way provisioning works, Xamarin Studio
currently is unable to refresh changes or additions to iOS Provisioning profiles directly. As a current work around,
you'll need to do the following:
1. Quit Xamarin Studio.
2. Start Xcode.
3. Select Xcode menu > Preferences... > Accounts and click the View Details... button:
4. Click the Refresh button and then click the Done button:
5. Restart Xamarin Studio.
This issue will be corrected in a future release of Xamarin Studio.
WARNING: Because of changes that Apple recently made to the way provisioning works, Xamarin Build Host
currently is unable to refresh changes or additions to iOS Provisioning profiles directly. As a current work around,
you'll need to do the following:
1. Quit Visual Studio.
2. Switch to the Mac that houses the Xamarin Build Host.
3. Quit the Xamarin Build Host.
4. Start Xcode.
5. Select Xcode menu > Preferences... > Accounts and click the View Details... button:
6. Click the Refresh button and then click the Done button:
7. Restart the Xamarin Build Host.
8. Return to your Windows PC and restart Visual Studio.
This issue will be corrected in a future release of the Xamarin Build Host.
Requesting a Development Certificate
The first step in setting up a development device is requesting a development certificate from Apple.
Development certificates and associated keys are a critical piece of information for you as 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 enforce control over the
devices to which you are allowed to deploy.
Apple's Xcode will be required to manage development teams, certificates and provisioning profiles. The
following sections describe the steps required to use Xcode to generate and install the necessary certificates and
profiles to develop and deploy iOS applications from Xamarin Studio.
Adding Your Apple ID Account in Xcode
Before any of the required certificates or profiles and be added, the developer must attach their Apple ID Account
to Xcode.
The following step will need to be done on the Mac that houses the Xamarin Build Host that you will be attaching
to from Visual Studio to develop and build iOS applications:
1. Start Xcode.
2. Choose Xcode Menu > Preferences...
3. Click the Accounts tab.
4. Click the Add (+) button and select Add Apple ID... from the popup menu:
5. If you have an Apple ID that belongs to an Apple Developer Program, enter your Apple ID and password,
and click the Add button:
6. Otherwise, click Join a Program in the lower-left corner of the dialog and the Apple Developer Program
Page will be displayed in the default web browser:
7. Select a program from the list and follow the onscreen instructions to sign up for an account.
8. Once the new account has been successfully created, return to Xcode and fill in the new account
information and click the Add button to continue:
You may need to stop and restart both the Xamarin Build Host and Visual Studio for the changes to provisioning
to be seen.
Understanding Certificate Key Pairs
We've mentioned that the Developer Profile contains certificates, their associated keys, as well as any
provisioning profiles associated with the account. There are actually two versions of your Developer Profile - one
is on the Developer Portal, and the other lives on your 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 your local Mac, because if the private keys are lost, all the certificates
and provisioning profiles will need to be regenerated.
We've mentioned that the Developer Profile contains certificates, their associated keys, as well as any
provisioning profiles associated with the account. There are actually two versions of your Developer Profile - one
is on the Developer Portal, and the other lives on your the Mac that houses the Xamarin Build Host. 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 with the Xamarin Build Host 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 you to revoke your
existing certificate and re-provision any associated devices, including those registered for ad-hoc deployment.
After successfully setting up your Development Certificates, you should export a backup copy and store them in a
safe place.
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 so you can deploy to your Apple device. A provisioning profile is a set of digital entities that
connects devices and developers with a valid Apple developer account. A device must have your provisioning
profile installed in order for you to deploy to it.
Add a Device
To generate a provisioning profile, we will first add a device. Devices are added manually using the Apple
Developer Portal.
The following step will need to be done on the Mac that houses the Xamarin Build Host:
1. Start Xcode.
2. Connect the device to be provisioned to the Mac with it's 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 iOS Dev 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.
Repeat the above steps for any iOS device that you will want to test or debug Xamarin.iOS applications on.
Team Provisioning Profile
By default, adding a device will create an iOS Team Provisioning Profile. We can view this profile and add
additional profiles by returning to the iOS Provisioning Portal and navigating to Provisioning > Development:
If you are an individual developer, the Team Provisioning Profile will contain information about all of your devices
and development certificates. If you are sharing a team Apple Developer account, the Team Provisioning Profile
will keep track of all devices used by your team, as well as all developer certificates. The Team Provisioning
Profile also includes a Wildcard App ID. This in an App ID that will match any app created by you or your team
that does not use store technologies, and allow you to deploy these apps to your device:
A device is considered provisioned when a provisioning profile contains information about that device is installed
on the device.
Requesting Signing Identities
After the certificates or provisioning profiles have been created in the Apple Developer Portal using the steps
above, they will need to be pulled into Xcode so they that they can be accessed by Xamarin Studio Visual Studio
and the Xamarin Build Host.
1. Quit Xamarin Studio Visual Studio and the Xamarin Build Host.
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.
7. Click the Refresh icon button in the lower left hand corner of the screen:
8. After the list of available Provisioning Profiles has been updated, click the Done button.
9. Quit Xcode.
10. Start Xamarin Studio the Xamarin Build Host and Visual Studio.
The new certificates or provisioning profiles will be available in Xamarin Studio Visual Studio and the Xamarin
Build Host 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 the Xamarin Build Host and 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 entitlements, that can be activated for your
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
Passbook
Push Notification
VPN Configuration & Control
These Application Services must be configured on both the iOS Provisioning Portal when you are defining your
App ID and in the Entitlements.plist file that is part of your Xamarin.iOS application's project.
Set Entitlements in your App ID
Before you can select any of the Application Services for your Xamarin.iOS application, you'll need need to
create a unique App ID for it. We can view our existing App IDs and add additional ID by returning to the iOS
Provisioning Portal and navigating to Provisioning > Development:
To add a new App ID, do the following:
1. Click the + button and provide a Name and Bundle ID for the new application:
2. Scroll to the bottom of the screen and select any App Services that will be required by your 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 your Xamarin.iOS application. For Example:
You may have to quit Xamarin Studio and have Xcode refresh it's list of available Signing Identities and
Provisioning Profiles (by following the instructions in Requesting Signing Identities section) before a new App ID
is available in Xamarin Studio.
You may have to quit Visual Studio and the Xamarin Build Host and have Xcode (on the Xamarin Build Host's
Mac) refresh it's list of available Signing Identities and Provisioning Profiles (by following the instructions in
Requesting Signing Identities section) before a new App ID is available in Visual Studio.
Set Entitlements in your Xamarin.iOS Project
As stated above, in addition to selecting and configuring the required Application Services when defining your
App ID, you also need to configure the entitlements in your Xamarin.iOS project by editing both the Info.plist
and Entitlements.plist files.
To configure your 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 your application and enter the Bundle Identifier
that you created when you defined the App ID:
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 and entitlements required for you Xamarin.iOS application so that they match the
setup you did above when you defined the App ID.
6. Save the changes to the Entitlements.plist file.
To configure your 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 your application and enter the Bundle Identifier
that you created when you defined the App ID:
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 and entitlements required for you Xamarin.iOS application so that they match the
setup you did above when you defined the App ID.
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.
Provisioning for Distribution
Whether you plan to release your Xamarin.iOS application for sale in the iTunes App Store or deliver it Ad-Hoc
for Enterprise Deployment, you'll need to build a Distribution Provisioning Profile specific to it. This profile allow
you to digitally sign the application for release so it can be installed on an iOS device.
Creating a Distribution Profile
Return to the iOS Provisioning Portal and select Provisioning > Distribution:
Click the + button and select the type of Distribution Profile that you want to create as either App Store or Ad
Hoc:
Click the Continue button and select App ID from the dropdown list that you want to create a Distribution Profile
for:
Click the Continue button and select certificate required to sign the application:
Click the Continue button and select the iOS devices that the Xamarin.iOS application will be allowed to run on:
Click the Continue button and enter a Name for the new Distribution Profile:
Click the Generate button to create the new profile and finalize the process.
You may have to quit Xamarin Studio and have Xcode refresh it's list of available Signing Identities and
Provisioning Profiles (by following the instructions in Requesting Signing Identities section) before a new
Distribution Profile is available in Xamarin Studio.
You may have to quit Visual Studio and the Xamarin Build Host and have Xcode (on the Xamarin Build Host's
Mac) refresh it's list of available Signing Identities and Provisioning Profiles (by following the instructions in
Requesting Signing Identities section) before a new Distribution Profile is available in Visual Studio.
Selecting a Distribution Profile in a Xamarin.iOS Project
When you are ready to do a final build of a Xamarin.iOS application for sale in the iTunes App Store or for AdHoc delivery, you'll need to select the Distribution Profile that you created above.
In Xamarin Studio, do the following:
1. Double-click the project name in the Solution Explorer to open it for edit.
2. Select iOS Bundle Signing and the type of build from the Configuration dropdown:
3. In most cases, you can leave the Signing Identity and the Provisioning Profile set to their default values
of Automatic:
4. If required, select the Signing Identity and Distribution Profile (the one we created above) from the
dropdowns:
5. Click the OK button to save the changes.
In Visual Studio, do the following:
1. Right-click the project name in the Solution Explorer and select Properties to open it for edit.
2. Select iOS Bundle Signing and the type of build from the Configuration dropdown:
3. In most cases, you can leave the Identity and the Provisioning profile set to their default values of
Automatic:
4. If required, select the Signing Identity and Distribution Profile (the one we created above) from the
dropdowns:
5. Save the changes to the project's Properties.
Multiple Team Deployment
If you are working in an Enterprise Environment or are member of multiple iOS development teams, there might
be cases where you wish to sign an iOS application for release by a specific Enterprise/Team. In these situations,
you will need to select the specific Identity and Provisioning profile from the Bundle Signing tab of the
project's properties instead of leaving them at the default Automatic setting.
Summary
In this article we have covered the steps required to setup the development environment for Xamarin.iOS. From
creating the required Development Certificates, to provisioning an iOS device for testing, to provisioning an iOS
application and configuring an required Application Services, to creating the final Distribution Provisioning
Profiles.