Setting up a device for development
- PDF for offline use
- Related Articles:
Let us know how you feel about this
last updated: 2017-03
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.
This article covers the following topics in detail:
- Requesting a Development Certificate
- Understanding Certificate Key Pairs
- Provisioning an iOS Device for Development
- Updating Profiles and Certificates in Xcode
- Deploying to a Device
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:
- Via Xcode
- Manually, by accessing the Certificates, Identifiers & Profiles section of Apple's Members Center.
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.
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:
- Open Xcode.
- Choose Xcode Menu >Preferences...
- Click the Accounts tab.
Click the + button and select Add Apple ID... from the popup menu:
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.
Select the team, and click Manage Certificates:
Xcode will display all the Signing Identities that are associated with your account. Click the plus(+) and select the type of signing identity required to create a new certificate. Note that the offerings may differ to those shown in the screenshot depending on the type of account:
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 be displayed:
Log on to the Developer Center to accept this license:
Depending on the team privileges of the Apple account, 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 provision a device by using the Apple Developer Portal. This requires a few more steps:
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:
Select the iOS App Development option for the certificate type and click Continue. This screen may look different depending on your account privileges:
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:
Fill in your information, and select the option to Save to disk:
Save the CSR at a location where it can be easily found:
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.
Once the Certificate is approved, download it from the Provisioning Portal:
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:
- Start Xcode.
- Connect the device to be provisioned to the Mac with its supplied USB cable.
From the Windows menu select Devices:
Select the desired iOS device from the DEVICES list on the left side of the Devices Window.
Highlight the Identifier string and copy it to the clipboard:
In Safari, navigate to the Apple Developer Center and log in.
Click the Certificates, Identifiers & Profiles link:
Click on the Devices link:
Click the + button:
Provide a name for the new device and paste the device Identifier that we copied above into the UUID field:
Click the Continue button.
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:
- Creating a Team Provisioning Profile through Xcode.
- Manually creating a Provisioning Profile (and App ID, if required).
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 capabilities 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.
- In the developer portal browse to the Certificate, Identifiers and Profiles section in the Apple Developer Center. Select App IDs under Identifiers.
Click the + button and provide a Name:
The App prefix should be preset. Select Wildcard App ID for the app suffix. Enter a Bundle ID in the format
Click the Continue button and following the on screen instructions to create the new App ID.
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:
- Use Safari to browse to the Apple Developers Member Center, and under the section Certificates, Identifiers & Profiles select Provisioning Profiles.
- Click the + button, in the top right corner to create a new profile.
From the Development section, select the radio button next to iOS App Development, and press Continue:
From the dropdown menu, select the App ID that to use:
Select the Certificate(s) to include in the provisioning profile, and press Continue:
Select all the devices that the app will be installed on.
Provide the Provisioning Profile with an identifiable a name, and press Continue to create the profile:
Press Download to download the provisioning profile onto a Mac:
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:
- Quit Xamarin Studio or Visual Studio.
- Start Xcode.
- Choose Xcode Menu > Preferences...
- Click the Accounts tab.
Select a team and click the Download all Profiles button:
- 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 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
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:
- Plug the device in to a Mac.
In the project's Info.plist, make sure the Bundle Identifier matches the App ID (unless the App ID is a wildcard):
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.
Make sure to set the build configuration to iPhone / iPad, rather the simulator.
- Click Run in Xamarin Studio and view the app running on the device.
- Plug the device in to a Mac.
In the project's Info.plist, make sure the Bundle Identifier matches the App ID:
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 Visual 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.
Make sure to set the build configuration to iPhone or iPad, rather the simulator.
- Click Run in Visual Studio and view the app running on the device.
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.