In this article

Manual provisioning for Xamarin.iOS

07/15/2017

10 minutes to read

Contributors

In this article

Once Xamarin.iOS has been successfully installed, the next step in iOS development is to provision your iOS device. This guide explores using manual provisioning to set up development certificates and profiles.

Note

The instructions on this page are relevant for developers who have
paid access to the Apple Developer Program. If you have a free account,
please take a look at the Free provisioning
guide for more information about on-device testing.

Creating a signing identity

The first step in setting up a development device is to create a signing identity. A signing identity consists of two things:

A Development Certificate

A private key

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.

Development teams, certificates, and profiles can be managed by accessing the Certificates, Identifiers & Profiles (login required) section of Apple's Member Center. Apple requires you to have a signing identity to build your code for device or simulator.

Important

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.

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.

Warning

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, you must 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 on your Mac to add a device to the Developer Portal

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.

Creating a development provisioning profile

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 Working with Capabilities guide.

App ID

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 com.[DomainName].*:

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.

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 Visual Studio for Mac 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
Visual Studio for Mac and Visual Studio. To update and download any certificates created in the Apple Developer portal, do the following:

Quit Visual Studio for Mac or Visual Studio.

Start Xcode.

Choose Xcode Menu > Preferences...

Click the Accounts tab.

Select a team and click the Download Manual Profiles button:

Quit Xcode.

Start Visual Studio for Mac or Visual Studio.

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

It may be necessary to stop and restart Visual Studio for Mac before it will see any new or modified certificates or profiles updated by Xcode.

Important

It may be 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.

Deploying to a device

Before you begin, make sure to select Manual Provisioning in the Info.plist.

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 Visual Studio for Mac can see the correct profiles, and select a specific identity & profile:

If this is set to Automatic, Visual Studio for Mac 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 Visual Studio for Mac and view the app running on the device.

Important

Before you begin, make sure to select Manual Provisioning in Project > Provisioning Properties….

Plug the device in to the Mac build host.

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.

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.