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.
© Copyright 2024