Everything you need to know to run a Xamarin app on an iPhone from Debug to Release builds to beyond

You might find this article helpful if you work on Xamarin Forms in a situation similar to the one I’m about to describe. You have no problem writing the code but it seems like you always struggle every time you have to deal with Certificates and Provisioning Profiles on iOS. It’s hard for anyone to remember what they did months ago. That’s understandable because writing code happens every day whereas dealing with Certificates and Provisioning Profiles only occurs occasionally.

Unfortunately, all the documentation that’s available out there right now are just too damm hard to follow. Some docs or articles contains links inside links inside links (that’s like pointers to pointers to pointers). Some are not written specifically for Xamarin. Some are written for Xamarin but do not take advantage of the latest Visual Studio on Mac.

So my goal here is to write a comprehensive article that will help you starting from zero to release to post-release and beyond. It starts with a plan.

But before I start, I want to note that I am adding one more build mode. This is completely optional and you don’t have to have it. Normally, you would have a Debug and a Release build. They are just as you expected. But this additional build mode called Stage helps me to create a build just like a Release build, but instead of getting released to the App Store, it gets distributed to my team members (Manager, Sales, etc) in an Ad Hoc manner like via HockeyApp. The table below compares Debug vs Stage vs Release:

Stage has the same Compiler options as Release and shown here:

Figure 1

So let’s start. Here are the steps:

Register a device (on developer.apple.com)

Just follow the link below. Consult with Google to find the way to get the UDID of your device.

Sign in with your Apple ID - Apple Developer

Note that it would be almost impossible to know all the devices up front. During the project, you will need to add new devices for one reason or another. What to remember is when a new device is added here, you will have to re-create the Provisioning Profiles (but no need to re-create Certificates which will be described shortly)

Register the App (on developer.apple.com)

Again, fairly simple. Just follow the link

Sign in with your Apple ID - Apple Developer

The question I struggled with initially was whether to use the “Explicit App ID” option or the “Wildcard App ID” option. To answer, I find it easier and more straightforward to pick the “Explicit App ID” option. Make another app in the future? Just register again with a new “Bundle ID”.

It’s important to note that the “Bundle ID” that you specify here has to match the Bundle Identifier in the Info.plist in the iOS project in the code. Just follow Apple’s suggestion and use the pattern com.domainname.appname as the Bundle ID.

Create Certificates (done on Visual Studio for Mac)

On Visual Studio, look for the first Menu Item called “Visual Studio Community”, select “Preferences”, then “Apple Developer Accounts”. Log in and select “View Details”

Figure 2

We will now create 1 “iOS Development” certificate and 1 “iOS Distribution” certificate (this distribution certificate is to be used for both Stage and Release)

Warning: This dialog on Visual Studio for Mac version 7.0 (build 3146) is buggy and might not show the “iOS Distribution” certificates. But son’t worry, you can confirm on developer.apple.com with the following links

Sign in with your Apple ID - Apple Developer

Sign in with your Apple ID - Apple Developer

The certificates we just created should expire after 1 year. So we should never have to touch this again. This is as opposed to the Provision Profiles where we might have to generate more often. One reason was already mentioned when a new device has to be registered. Talking about Provision Profiles, let’s take a look at how we generate them next.

Generate Provision Profiles (done on developer.apple.com)

We will generate 1 “Development Provision Profile” and 2 “Distribution Provision Profiles” (1 for Stage and 1 for Release)

Follow this link to generate a Development Provision Profile. Simple.

Figure 3

Then select the App ID, then the iOS Development Certificate, then the devices that were registered(all were already carried out by you in previous steps). Finally, in the last step, name the profile something like ”AppName Development”.

Once this Development Provision Profile has been generated, go ahead and download it. Don’t do anything to it yet. We’ll do something with it after we also generate the Stage Provision Profile and the Release Production Profile.

So, clearly the Provision Profile depends on the App Bundle ID, the certificate and the devices. Anytime one of those three (App Bundle ID, certificate and devices) changes, we have to re generate a new Provision Profile. (It’s also a good idea to delete the old one to keep things tidy).

Follow this link to generate the Stage Provision Profile. Note the difference here and when we created the Development Provision Profile. Here, we select the “Ad Hoc” option under “Distribution”.

Figure 4

The next few steps where you choose the App ID, Certificate and Devices are the same. You only need to note that the certificate selected here has to be an iOS Distribution certificate. Final step is to name the profile something like “AppName AdHoc”. Download the Stage Provisioning Profile and wait.

Use the same link that we used for Stage to generate the Release Provision Profile. This time, select the “App Store” option under “Distribution”.

Figure 5

You will see that this time, there’s no page where you are asked to select devices. This makes sense because the Release Provisioning Profile we create here is used to build that app that will gets released to the AppStore. Download the Release Provisioning Profile.

Install Provision Profiles and Verify

Now that we have 3 Provisioning Profile generated and downloaded on our Mac. We are ready to install them. But before doing so, use Finder and go to the following path /Users/[you]/Library/MobileDevice/Provisioning Profiles

You will see that as you install each one of them by simply double-clicking, a file with .mobileprovision extension will show up in the file path above.

There’s one more place to verify that everything is correct is in the Solution Explorer, right click on the iOS project and select “Options”. For Debug, Stage and Release builds, in Figure 6, 7 and 8 respectively, you should see the Provision Profile set to Automatic if everything is done correctly. You DON’T have to mess with anything here.

Figure 6

Figure 7

Figure 8

If you have the above and verify, then you can build the app in Debug mode and run it on a physical device (connected to your Mac via USB). You can build the app in Stage mode, archive it to publish on HockeyApp (or something like that) and distribute to whoever you want, provided that you have to register their devices in advance. Finally, you can build in Release mode, publish to the App Store where your customers and users can install on their devices just like Instagram, Twitter, etc.

Points of Interests

I want to leave you here with some points of interests:

1. The certificates depend on the Mac hardware (where Xcode and Visual Studio for Mac are installed). Since each provisioning profile depends on the certificate (and also app Bundle ID and registered devices), you can’t simply copy the provisioning file to another Mac and expect it to be working.
2. So if you work on a Mac at work and a Mac at home, generate the certificates on each Mac using Visual Studio as described above. When you generate the Provisioning Profiles, you can select more than 1 certificates. This is also the same scenario when there are 2 developers working on the same app.
3. Don’t worry if you accidentally delete the Provisioning Profiles on your Mac. They can always be be downloaded from your developer.apple.com portal.
4. Don’t worry if you delete the Provisioning Profiles on developer.apple.com portal. They can always be re-generated. Keep in my mind that the ones already on your Mac are no longer good. Just go to the file path /Users/[you]/Library/MobileDevice/Provisioning Profiles, move them to trash. Download the newly generated ones and install by double-clicking on them.
5. Since the Provisioning Profiles also depend on the registered device, if you or some team member has to replace the iPhone, repeat the steps above.
6. Likewise, don’t worry if you accidentally revoke the certificates on developer.apple.com. They will expire in 1 year and you have to repeat the steps above anyway.