Productive day... Thanks @VSTS for fully automating all my NuGet packages. pic.twitter.com/pDzYUXnG5I

— James Montemagno 🙈 (@JamesMontemagno) May 10, 2018

If you look at this screenshot from VSTS it is everything that I wanted for so long in my development cycle. I push code, things are built, and automatically packages are pushed. In this post I am going to show you how I set this up for my projects and how you can too in just a few minutes.

.NET Standard and Multi-Target Projects

Before we start to setup our CI/CD for libraries I highly recommend you move your projects to SDK style projects. You can read my full guide on how to convert a PCL to .NET Standard or how to convert a Xamarin.iOS or Xamarin.Android project to SDK Style.

Everything that I develop now is based on a single .NET Standard 2.0 library or a Multi-Targeted project for plugins. I have previously written on how to convert your PCLs to .NET Standard and also have templates for Visual Studio 2017 to create Multi-Target projects for plugins.

The reason to use these types of projects is that they include full NuGet packaging including all metadata and dependencies. This also means you can fully delete the .nuspec file that always gets out of sync. It is worth your time to update any and all projects to these types of projects to simplify your life.

If you need to learn more about multi-targeting be sure to check out Oren's amazing MSBuildSdkExtras package which is the core of my templates and all of my projects.

If you are building only an iOS or Android library do not fear as you can still just convert your existing library over to an SDK Style. Take a look at my MonoDroid.Toolkit csproj on GitHub.

Build Definition in VSTS

My builds inside of VSTS are actually really simplistic and only contain 6 steps to fully build my libraries. You can use the Hosted Visual Studio 2017 machines, however I have a small Intel NUC that runs a local VSTS agent so all my NuGets are cached which reduces my build times to seconds instead of minutes.

Empty Definition

Select New and pick your source code that you would like to build. I then like to select Empty process because we can easily fill it in.

NuGet Steps

Under Phase 1 we are going to add two NUGet steps.

First is the NuGet Tool Installer task and change the Version to 4.5.1

Second will be the regular NuGet task which we will use the restore command on our solution that we are going to build. I like to pick the specific .sln or folder where it lives (no need to build other stuff).

Build Steps

I build my libraries twice! That is right twice! Once for a "beta" NuGet and once again for "public" NuGet. They are super quick and all it is really doing is changing the version flags. The reason I do this is for my release definition that will allow me to have a single release that goes from beta to public easily. We will be building the .csproj specifically using the MSBuild task:

We will add it twice so we can build the beta and public releases. Name the first Build Beta and the second Build Public. For each of them set the following:

• Project: Select the .csproj specifically
• Configuration: $(BuildConfiguration)

For MSBuild Arguments user the following for Beta:

/t:restore;build;pack /p:PackageVersion=$(Build.BuildNumber)-beta /p:PackageOutputPath=$(build.artifactstagingdirectory)/beta /p:AssemblyFileVersion=$(Build.BuildNumber)

For Public use:

/t:restore;build;pack /p:PackageVersion=$(Build.BuildNumber) /p:PackageOutputPath=$(build.artifactstagingdirectory)/public  /p:AssemblyFileVersion=$(Build.BuildNumber)

This will ensure that the build numbers are configured correctly and copy the artifacts to different folders.

Optionally, you may have some additional unit tests or device runners that may need to be run here.

Copy and Publish

The next thing to add is the Copy Files task to stage the NuGet packages for release.

Set these properties:

• Source Folder: $(build.sourcesdirectory)
• Contents: **\bin\$(BuildConfiguration)\**\*.nupkg
• Target Folder: $(build.artifactstagingdirectory)

Finally, add the Publish Build Artifacts task and set the following:

• Path to publish: $(build.artifactstagingdirectory)
• Artifact name: drop
• Artifact public location: Visual Studio Team Services/TFS

This will pull only .nupkg files that we will distribute into a folder that release can pick up.

All in all the definition should look like:

Configure Version Number

Under the Options tab in the build definition I like to format the Build number format such as: 4.5.0$(rev:.r)

This means that the next version would be: 4.5.0.1 and then 4.5.0.2.

Now if you change this to: 5.0.0$(rev:.r) it will reset the revision so it will be 5.0.0.1.

Other things!

You will probably want to setup *Triggers so CI and PR validation are configured. This means that every time master is pushed to a package is generated.

Release Definition in VSTS

Now we have our full build complete it is time to setup our release. Our goal for me was to automatically have every build of master go to MyGet and then manually approve the next release to go to NuGet (beta) and finally another approval to go to NuGet with the public non-beta package.

Head over to the Releases section and create a new release definition with an Empty process. Think of Environments as the stages of release. We can create three of them to define each release of the artifacts. Inside of each environment are a sequence of tasks, just like our build definition, that will be run. For my libraries it is really simple as each has just one task. However, before the NuGet beta and production environments I turn on pre-deployment approval steps.

Push to MyGet

In our first environment we will want to push to MyGet. Add the NuGet task with the following settings:

• Command: push
• Path to NuGet package: $(System.DefaultWorkingDirectory)/**/drop/beta/*.nupkg
• Target Feed: External NuGet server

For this step you will want to configure the feed information from MyGet:

Push NuGet Beta

For this step you can select Clone or if you already create the new environment simply add the NuGet task again. The settings will be the same as above:

• Command: push
• Path to NuGet package: $(System.DefaultWorkingDirectory)/**/drop/beta/*.nupkg
• Target Feed: External NuGet server

However, we will now want to select or configure NuGet as our destination:

Head back to Pipeline and for this environment we don't want it to automatically trigger, we want to approve this release. You will see a lightning bolt and a person shape on the left side of the environment to configure pre-deployment conditions. I turn on pre-deployment approvals and select myself and turn off the policies since I am a solo developer:

There is all sorts of rad stuff you can do here on pre and post-deployment so you should totally look into that for larger projects.

Push NuGet Production

Add or clone another environment for after the Beta environment. This is going to be almost the same as the previous step but we are going to change our Path to NuGet package:

• Command: push
• Path to NuGet package: $(System.DefaultWorkingDirectory)/**/drop/public/*.nupkg
• Target Feed: External NuGet server

Notice I am using public here :)

Add Artifact

Finally, click the big Add artifact button on the left side and select the build definition that you created earlier. Also tap on that little lightning bolt and turn on the Continuous deployment trigger so this flow automatically happens!

CI/CD Pro!

You did it! You are totally a Continuous integration and delivery pro!! Enjoy a seamless deployment of every push to master to MyGet and then approval steps to push to NuGet for any and all of your .NET Libraries. <3 Feel free to ask questions below.

Unload that Project

First things first, we need to get at that raw .csproj madness. Right click on the project and click Unload Project. Then right click again and select Edit *.csproj:

Delete Everything!

That is right! Delete it all because we don't need it at all!

Replace it with my base project information. It is a bit verbose but based on the type of library you are creating there are some special things that you may want to include such as Android resources.

Note: I like to only compile items that end in .shared.cs, .ios.cs, or .android.cs to keep it tidy, but you can easily change what you compile into your library in the project structure.

Right click and re-load the project!

Spice it up

Now you can go in and any NuGets you may need with the PackageReference node in the ItemGroup of your choosing. Additionally, you can also turn on Multi-Targeting to generate both an iOS and Android (or whatever else like UWP and netstandard) by change TargetFramework to TargetFrameworks and specifying more frameworks.

NuGet that Library

What is great about the SDK style projects is that you don't need a .nuspec at all for your NuGet and it can be generated automatically at build time! Whoa! Amazing Yes! You can also see the contents with the NuGet Package Explorer

All you need to do is turn on GeneratePackageOnBuild in the Release property group and then add the following items to the main PropertyGroup for the NuGet's information:

You can read more about these attributes over on the NuGet documentation.

Now when you compile in release mode you get a full NuGet with your library:

SDK and Multi-Target Everything

If you have multiple libraries like me or building multiple libraries from a single solution you can also look into Directory.Build.props and Directory.Build.targets that enable you to group common properties together for a full solution.

I have gone through just about every project I have created and switched over to this new style of project because CI is so simple with it that I can manage a full CI/CD cycle for all of my libraries from one location:

Check back later this week for my blog on how to take the SDK style projects that we have here and set them up for CI in VSTS.

See Me Convert a Library Live!

Because I love seeing things in action I walk through the exact steps here in this short video:

Times change and it is time for an update to this near perfect library. If you have ever used this library or had it as a dependency then you will remember a magical MainApplication.cs file that would get added to your application. This laid down everything that the plugin needed to track the current Activity state with IActivityLifecycleCallbacks. While this was a really simple use case it sometimes ran into issues when developers already had a custom Application class and more over now that Package References are the default for Visual Studio this file no longer gets added to the project.

Automatic Tracking

Thanks to the mastermind Jon Dick who I am working with on some new libraries and pointed out that instead of having developers write their own custom Application or rely on a magical file that I could just create my own IActivityLifecycleCallbacks and have a simple Init call. On top of that I could preserve backwards compatibility with any installations of 1.0!

How can this be? Well I created my own lifecycle listener and now there is just a tiny bit of setup inside of your existing custom application or main activity:

Main/Base Activity Level

Simply call the Init method on OnCreate:

CrossCurrentActivity.Current.Init(this, bundle);

Application Level

Add a new C# class file in you project called "MainApplication.cs". Override the OnCreate method and call the Init method:

#if DEBUG
[Application(Debuggable = true)]
#else
[Application(Debuggable = false)]
#endif
public class MainApplication : Application
{
    public MainApplication(IntPtr handle, JniHandleOwnership transer)
      : base(handle, transer)
    {
    }

    public override void OnCreate()
    {
        base.OnCreate();
        CrossCurrentActivity.Current.Init(this);
    }
}

Extended API

In version 1.0, I simply returned the current Activity as part of the plugin, but now I expose a new event that is triggered when any activity lifecycle changes and access to the current Context:

void Register()
{
    CrossCurrentActivity.Current.ActivityStateChanged += Current_ActivityStateChanged;
}

private void Current_ActivityStateChanged(object sender, ActivityEventArgs e)
{
    Toast.MakeText(Application.Context, $"Activity Changed: {e.Activity.LocalClassName} -  {e.Event}", ToastLength.Short).Show();
}

Try it Today

You can grab a copy of version 2.0 today on NuGet. Throughout the month of April I will be updating all of my plugins to use this new version. I am really excited for it and hope that you find it useful. If you are building a library that depends on CurrentActivity please update to version 2.0 today!

What is .NET Standard?

Great question! Essentially think of .NET Standard as the defacto way of sharing code across all .NET Platforms including Xamarin, .NET Framework, .NET Core, and others. Essentially all of these .NET Platforms implement a standard set of APIs so you as a developer can just create a library and share it everywhere. They are the evolution, improvement, and replacement for Portable Class Libraries, and I could not be more excited about it.

I highly recommend you checkout our podcast episode of Merge Conflict, which you should totally listen to:

Merge Conflict 38: One Library to Rule Them All

The Big Move & More Platforms

There are actually two large changes that I have done to my plugins. First, each and every plugin’s “Abstractions” and Core for bait and switch have moved to .NET Standard 1.0. This means that you can easily add them into any .NET Standard library and are 100% backwards compatible with your PCL libraries! The other switch was more on the development side of the plugins, which I have moved fully to Visual Studio 2017 and C# 7. This means that all new versions of my plugins will no longer support Windows Phone 8 Silverlight, Phone 8.1 RT, or Windows Store RT (8.1). I additionally will no longer be accepting any new issues or fixing any bugs for those operating systems in any of my plugins. I don’t have the environment to maintain them so I can’t support them.

What will you support?

With the loss of these platforms comes the rise of other platforms being added into several of my plugins. All plugins today already support iOS, Android, and UWP, and I have done my best to add in macOS, tvOS, and watchOS support to plugins where they make sense, such as Settings, Connectivity, and Text to Speech.

The Brand New IsSupported Boolean!

Previously, when you installed a plugin on a platform that wasn’t supported (or you forgot to install the NuGet in the core project) and you tried to call the method it would simply throw an exception. This is still the case, but I tried to figure out a better way for developers to check to see if an implementation exists before making calls.

You can simply now call CrossPluginName.IsSupported to check if it exists. For instance:

There you have it, super simple way of checking!

Updated Android Support Libraries

In this big move I also took a big risk on deciding to make the break away from defaulting to version 23.3.0 of the Android Support Libraries in a few of my plugins. These libraries are now almost 3 years old and it is simply time to update them to the latest and greatest 25.3.1. Since you can update them now in Xamarin.Forms applications it is time! I even show you how to do it in this small Snack Pack episode of The Xamarin Show

It should be known that I don’t use Support libraries unless I absolutely have to, but if you are using Permissions, Media, Share, or Geolocator then you are going to have to update. Here is what you need to know:

Before you install or update your NuGets, ensure you have Android SDK for API 25 installed. You can watch my video on The Xamarin Show or simply click Tools->Android SDK Manager, deselect everything, and then select Android SDK 25, that is all you will need. Next, you need to go into your Android project settings and under General/Build make sure you select Android 7.0 and then go into your Manifest and set the Target to 25 too!

If you don’t do this you will see an error when trying to install the Android NuGet that you aren’t targeting the correct version of Android. That is what this error means. Go update!

Can I Haz NuGets?

As of the time of writing this article each and every Plugin for Xamarin that I have created now has a pre-release version available that introduces these changes. Over the next two weeks I will be transitioning all of them to the stable branch after a bit more testing and feedback from you!

Let’s take the Connectivity Plugin (my most popular plugin), which checks for connectivity and event changes. There is no code that is laid down and you are encouraged to use the singleton of CrossConnectivity.Current.IsConnected, but that would be an issue in a unit test project or installed into something else that it isn’t supported. Unless we structure our code a bit differently, like this:

This code is structured pretty well actually, and how I would encourage you to use Plugins, which is to just have a property that returns the single, or returns it from your Dependency Service/IoC. If we need to unit test this puppy all we need to do is change that get property to a get and set property and make it static so we can set it in our unit tests.

Now, all we need to do is simply create a mock that implements IConnectivity and then set it in our unit tests.

There you have it, you can install any plugin into any unit test project, but it may or may not have an implementation… and really you don’t want to rely on the implementation in the unit test project as you want full control. You can roll your own mocking framework or use one that is available. Just think of it as an interface.

Update!

This is now easier than ever with my Store Review Plugin! Just a single line of code and you are good to go!

Original blog post

This is pretty simple to do for iOS and Android by launching a specific URL scheme. To do this, we will use two differnt plugins:

• Share Plugin: to open browser
• Device Info: to detect OS and versions

For iOS you will need to decide what URL you want to use based on the OS versions you support as each have different URLs:

* **Lower than iOS 7:** ``` itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/viewContentsUserReviews?type=Purple+Software&id=YOUR_APP_ID ```

• iOS 7:

itms-apps://itunes.apple.com/app/idYOUR_APP_ID

• iOS 8 or later:

itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/viewContentsUserReviews?id=YOUR_APP_ID&onlyLatestVersion=true&pageNumber=0&sortOrdering=1&type=Purple+Software

I only target iOS 8 and later so I will use that item. All you need to do is replace the “YOUR_APP_ID” with your actual APP ID from your iTunes connect page.

Update! Recently Apple updated the store to simply append on action=write-review onto the end such as:

var url = $"itms-apps://itunes.apple.com/app/id{appId}?action=write-review";

From the looks of it this works all the way back to iOS 8.

For Android, you will need the URL of your app on Google Play:

https://play.google.com/store/apps/details?id=YOUR_APP_ID

The Code! Let’s do this

It is actually really simple now:

var url = string.Empty;
var appId = string.Empty;

if(CrossDeviceInfo.Current.Platform == Platform.iOS)
{
    appId = "your_id";
    url = $"itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/viewContentsUserReviews?id={appId}&onlyLatestVersion=true&pageNumber=0&sortOrdering=1&type=Purple+Software"
}
else if(CrossDeviceInfo.Current.Platform == Platform.Android)
{
    appId = "your_id";
    url = $"https://play.google.com/store/apps/details?id={appId}"
}

if(string.IsNullOrWhiteSpace(url))
  return;

await CrossShare.Current.OpenBrowser(url, new BrowserOptions
{
    UseSafariWebViewController = false
);}

Boom, there you have it! The app store for both iOS and Android will open up and you are good to go.

Enjoy!

Here is the easiest example of taking a photo and displaying it in a Xamarin.Forms image.

takePhoto.Clicked += async (sender, args) =>
{
    await CrossMedia.Current.Initialize();

    var file = await CrossMedia.Current.TakePhotoAsync(new StoreCameraMediaOptions
    {
        Directory = "Sample",
        Name = "test.jpg"
    });

    if (file == null)
        return;

    image.Source = ImageSource.FromStream(() =>
    {
        var stream = file.GetStream();
        file.Dispose();
        return stream;
    });
};

Improvements

With this release I really focused on performance, memory optimizations, and adding new features that developers have been asking for. The top of the list has been Image Resizing when taking and picking photos. Now, all you need to do is set the PhotoSize in the Media Options:

PhotoSize = PhotoSize.Medium

This will shrink it in half, or you can simply specify a custom resize ratio:

PhotoSize = PhotoSize.Custom, CustomPhotoSize = 90

Better yet, I have also added a new way of compressing the image quality by just setting another parameter when taking or picking a photo:

CompressionQuality = 92

These can really help when displaying photos to users and when you don’t want a huge 2400x4600 photo saved locally. However, you may want to have the original photo saved to the users gallery, and the Media Plugin has you covered! Simply set:

SaveToAlbum = true

And what do you know the original photo will be saved to the camera roll on each device!

There are a bunch of other new features like specifying cropping on iOS and UWP, new permissions support for iOS 10 and Android N (new fancy File Providers), and even overlay support for iOS:

Optimizations

I have spent a lot of time on optimizing the code especially for Android. This means that photos will be automatically rotated based on Exif information, bitmaps are only loaded into memory when needed for continuous photo taking, and a plethora of other bug fixes that have been reported on the GitHub page. This release also has a nice update to the new Permissions Plugin that you can now get your hands on that has some awesome new features.

I am also really excited for all of the new documentation that I wrote up for this release, documenting just about every feature that I could and even including a lot of nice sample apps in the tests folders to check out.

What’s Next

I would  love to reach a new 3.0 release with some new optimizations including custom photo resizing to a max width and height, but would also love to hear what you want, or is it finally everything that you want :) Let me know on the GitHub Page.

A community effort to abstract away common APIs across iOS, Android, and Windows and package them up into small bitesize NuGet packages giving all developers a way to access these native APIs from shared code. In the last years (or so) since we started our original Plugins push nearly 100+ plugins have been created and are out there on NuGet and we have put together a hand currated list to browse through.

On my front I have created and worked on nearly 15 plugins that have gone through a lot of changes over the last year with nearly 100 GitHub issues squashed and plenty of updates along the way. Today, I am happy to announce updates to all of my plugins and some substantial changes that you will find when updating, that I am calling Plugins for Xamarin!

New Plugins!

That is right! In the last few weeks I have worked on a few new plugins and also with some amazing developers to update their plugins to align with the Plugins theming:

• Compass: Easily access compass heading 0-360 degrees.
• Local Notifications: Easily show and schedule local notifications.
• Permissions: Check and request runtime permissions.
• Share: Easily share text or open a browser.

Updated Plugins

Each and every plugin has been updated with new features, platforms, and yes some breaking changes, which you can read about a bit later on.

Here is a list of what I personally have created and updated:

• Battery Status: Get battery level, how it is getting charged, and get notified when it changes.
• Connectivity: See if device is connected to the internet and through what connection type.
• Contacts: Currently in Beta to gather and query contacts
• Device Information: Base information about each device such as OS and version.
• Extended Maps: Launch navigation directions in default map app on each OS
• Geolocator: Easy way of querying GPS location
• Media: Take or pick photos/videos
• Settings: Fully cross platform settings for your application.
• Text To Speech: Turn your text into a vocal symphony on mobile devices.
• Vibrate: Make that device rumble!

All of the new and updated plugins have a lot of awesome updates that aim to shorten development time for creating mobile apps. Here are a few enhancements that you will find.

Android Runtime Permissions

Last week I blogged about my new Permissions Plugin, which I beleive is one of my finest pieces of work when it comes to plugins, that solves the problem of checking and request runtime permissons from shared code (all asynce). This plugin was actually created so I could integrate it deeply into all of my other plugins. So now, if any plugin requires an Android runtime permission it will handle automatically requesting it for you, or you can using the Permission plugin to prompt when necessary. This incldes Contacts, Geoloator, and Media are all updated and ready to go.

Windows 10 UWP Support!

Windows 10 hasn’t been out long and Windows 10 Mobile is finally hitting some devices, but demand for plugin support has been high especially with the release of Xamarin.Forms 2.0 and its UWP preview. I am happy to announce that each and every one of my plugins that I have listed have been update with full Windows 10 UWP support in addition to Windows 8.1 RT support!

Lessons Learned

You will notice that all of the udpated plugins are officially 2.0.0! Yes that means there was a major number bump and that is because in the last year I have learned a lot about how developers are using the plugins and how they should have been structured from the beginning.

Don’t require Xamarin.Forms

This might have been the biggest mistakes when I setup the Plugins Templates was that I had the idea that Plugins could be used specifically only with Xamarin.Forms and not with traditional iOS, Android, and Windows apps. This is fine for controls or a specific framework that needs to deeply integrate with Xamarin.Forms, but not for Plugins. Plugins should simply NEVER require Xamarin.Forms. There are easy ways to access the Application Conetxt, ViewControllers, and I even released an amazing Current Activity plugin to get the current Activity in Android!

I have worked already with a few developers to update their plugins to remove the Xamarin.Forms restrictions and open them up to everyone. While it is a breaking change, it is for the best and I encourage everyone to follow suite if you have created a plugin or ping me and I will help out :)

Unified Namespaces

I was so close to perfection when I setup the templates for plugins that you could bring in a plugin and then type out “CrossFEATURE_NAME” to get access to it. However, there was one missign piece, which was that the namespaces for each plugin were completely different. I originally thought that this was a good idea, however talking with Mike James he said wouldn’t it be nice to type in “using Plugin.” and see all the plugins come up. He is right! So I made this change to each and every plugin I had access to :) This means that yes, I have broke all the plugins, but I promise never to do it again, and it is an simple change. I have also update the templates to reflect this.

Required Permissions by Default

This is a very small one, but in general I used to have a readme file with each plugin (still do for some) that told you which permissions you need to set for the different platforms. Little did I know that if a permission is required I should just set it and I can do so from the plugin itself. This means any plugin that requires an Android permission will automatically add itself to your Android Manifest :)

Get The Plugins!

So go forth and update the plugins now that you areaware of the changes as they have all been pushed to NuGet. Or start using some plugins and browse all of Plugins for Xamarin and Windows. In addition, I worked with the Xamarin University team to open up my Guest Lecture on plugins to be FREE for everyone!

Get Involved

If you are a library creator I urge you to take a look at all of the changes I have made to my plugins and make similar updates to really enhance the entire Xamarin development ecosystem. I have updated the Plugins for Xamarin templates with a lot of these changes already and would love to start highlighting even more amazing plugins, so please email or tweet at me about the plugins you have created.

Permissions! Blarg!

As an Android developer I have felt pretty spoiled over the last few years when it came to getting access to an API that required a permission. Simply check a checkbox in the project setting and any of the 130+ permissions were mine to have! The user installed my app and automatically granted me every permission my little heart desired. I took a look at what those poor iOS developers (and myself) had to implement in their apps to request a permission, get a callback, and then handle revoking of permissions from users! That looked like no fun at all. Well, Android developers had it too good for too long and now with the release of Android Marshmallow users are back in control with the introduction of Runtime Permissions, and I honestly think it is for the better. However, this means for developers we now have to go off and check permissions on multiple platforms, with different APIs, and no shared code. 

First, let’s take a look at what we would have to do for both iOS and Android to get access to grab the users location.

iOS:

1. Add NSLocationWhenInUseUsageDescription or  NSLocationAlwaysUsageDescription to info.plist.

2. Create new CLLocatonManager

3. Check we have the permission

4. Request correct permission if needed

5. Register for callbacks when authorization changes

Here is what it would look like:

void RequestLocationPermission()
{

    var locationManager = new CLLocationManager();

    EventHandler authCallback = null;

    authCallback = (sender, e) =>
        {
            if(e.Status == CLAuthorizationStatus.NotDetermined)
                return;

            locationManager.AuthorizationChanged -= authCallback;
            //do stuff here
        };

    locationManager.AuthorizationChanged += authCallback;

    var info = NSBundle.MainBundle.InfoDictionary;
    if (info.ContainsKey(new NSString("NSLocationWhenInUseUsageDescription")))
        locationManager.RequestWhenInUseAuthorization();
    else if (info.ContainsKey(new NSString("NSLocationAlwaysUsageDescription")))
        locationManager.RequestAlwaysAuthorization();
    else
        throw new UnauthorizedAccessException("On iOS 8.0 and higher you must set either NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription in your Info.plist file to enable Authorization Requests for Location updates!");
}

Android:

1. Add correct permissions to AndroidManifest
2. Check permissions on API 23+
3. Check if need to show rationale (user revoked or denied)
4. Request permissions
5. Do this every single time before you make a call!

Here is what that would look like:

async Task GetLocationCompatAsync()
{
  const string permission = Manifest.Permission.AccessFineLocation;
  if (ContextCompat.CheckSelfPermission(this, permission) == (int)Permission.Granted)
  {
    await GetLocationAsync();
    return;
  }
if (ActivityCompat.ShouldShowRequestPermissionRationale(this, permission))
{
//Explain to the user why we need to read the location
Snackbar.Make(layout, "Location access is required to show coffee shops nearby.", Snackbar.LengthIndefinite)
.SetAction("OK", v => ActivityCompat.RequestPermissions(this, PermissionsLocation, RequestLocationId))
.Show();
return;

}

The Problem

It is pretty clear that this code is pretty tedious to write and it has to be done in the actual iOS or Android projects, which is a complete bummer. While we have been forced to write this code for years, I say NO MORE! Last week I set out on a goal of creating my next Plugins for Xamarin to solve Permissions once and for all. Here was the goal:

1. Simple Cross-platform Async API that should:

2. CheckPermisssion - Simply check the permission

3. ShouldShowRationale - Tell us if the user revoked access on Android

4. RequestPermissions - Any amount that you would like!

5. Work on a wide array of iOS and Android permissions that require runtime checks

Today, I am pleased to introduce my latest Plugin that does just this, Permissions Plugin for Xamarin! This will not only simplify permissions on a per platform basis, but also from shared code such as Xamarin.Forms. More importantly though it will enable Library creators to deeply integrate with the SDKs without having to worry about writing all the permission code. Did I mention it is all async??!?!?! 

Permissions I Handle

The nice thing is that there are just 9 “permission groups”  (about 30+ permissions) on Android that have to be checked and about the same on iOS currently. Here is a full listing of everything the library can do:

1.   Calendar (Android: Calendar, iOS: Events)

2.   Camera (Android: Camera, iOS: Camera Roll & Camera)

3.   Contacts (Android: Contacts, iOS: AddressBook)

4.   Location (Android: Location, iOS: CoreLocation (Always/WhenInUse))

5.   Microphone (Android: Microphone, iOS: Microphone)

6.   Phone (Android: Phone, iOS: Nothing)

7.   Photos (Android: Nothing, iOS: Photos)

8.   Reminders(Android: Nothing, iOS: Reminders)

9.   Sensors (Android: Body Sensors, iOS: CoreMotion)

10.   Sms (Android: Sms, iOS: Nothing)

11.   Storage (Android: External Storage, iOS: Nothing)

Implementation

All in all I have to say that iOS permission requesting is pretty straight forward. You just have to go in aware that each library has its own way of handling permissions, different enums, and different callbacks to handle. If you read through the documentation for each of these APIs you will see that they are pretty identical except that you have different types of status: AVAuthorizationStatus, ABAuthorizationStatus, EKAuthorizationStatus, CLAuthorizationStatus, and more! Each of these actually have a common type though of Granted, Denied, Restricted, or Unknown. I decided copy most of these when returning a PermissionStatus to you:

1. Denied

2. Disabled (feature is disabled, such as locatio)

3. Granted

4. Restricted

5. Unknown

To hand the fact that there is a mixture of Async calls to check the status of these permissions and no way to actually request them async I simply used a TaskCompletionSource on every single call such as:

Task RequestPhotosPermission()
{
    if (PhotosPermissionStatus == PermissionStatus.Granted)
        return Task.FromResult(PermissionStatus.Granted);

    var tcs = new TaskCompletionSource();

    PHPhotoLibrary.RequestAuthorization(status =>
        {
            switch(status)
            {
                case PHAuthorizationStatus.Authorized:
                    tcs.SetResult(PermissionStatus.Granted);
                    break;
                case PHAuthorizationStatus.Denied:
                    tcs.SetResult(PermissionStatus.Denied);
                    break;
                case PHAuthorizationStatus.Restricted:
                    tcs.SetResult(PermissionStatus.Restricted);
                    break;
                default:
                    tcs.SetResult(PermissionStatus.Unknown);
                    break;
            }
        });

    return tcs.Task;
}

Android on the other hand is a bit more tricky. To check a permission this can be done on the activity or the application context, which is what I will use if you are trying this on a background service.

To request a permission you actually need an Activity and then you have to actually override a method on the activity to handle the request. This is obviously an issue because I am writing a library and can’t access the Activity you are on. Well, that used to be the case until I created the CurrentActivity plugin! Enabling you, me, or any library creator to get access to the current activity! 

This means a new MainApplication.cs file will get installed when you install the plugin, so be sure to read all about that! Now that I have the Activity the next issue to overcome is that fact that the API I created takes in my enum of a permission group, but Android requires you request all of the Manifest permissions you have specified for that group. This means that yes you will still need to add the permissions to your manifest, but I do a reverse lookup to see what you have listed in the AndroidManifest and those are what I request! What!!!! Amazing! I know! However, there is one small caveat here, which is whatever Activity you are requesting from you will have to notify my library when the call is returned by simply adding the following lines of code:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Permission[] grantResults)
{
PermissionsImplementation.Current.OnRequestPermissionsAsyncResult(requestCode, permissions, grantResults);
}

If you are supporting more than iOS/Android and have a bunch of Windows apps, do not fear as I added in dummy implementations for all flavors of Windows and .NET so permissions will return true.

In Action

Finally I get to just show you the code! It is actually super straight forward. Let’s say you want to request the location using the Geolocator library (although it does check permissions in the upcoming version 2.0.0).  Here are the calls in a PCL (Xamarin.Forms app hence the DisplayAlerts):

try
{
    var status = await CrossPermissions.Current.CheckPermissionStatusAsync(Permission.Location);
    if (status != PermissionStatus.Granted)
    {
        if(await CrossPermissions.Current.ShouldShowRequestPermissionRationaleAsync(Permission.Location))
        {
            await DisplayAlert("Need location", "Gunna need that location", "OK");
        }

        var results = await CrossPermissions.Current.RequestPermissionsAsync(new[] {Permission.Location});
        status = results[Permission.Location];
    }

    if (status == PermissionStatus.Granted)
    {
        var results = await CrossGeolocator.Current.GetPositionAsync(10000);
        LabelGeolocation.Text = "Lat: " + results.Latitude + " Long: " + results.Longitude;
    }
    else if(status != PermissionStatus.Unknown)
    {
        await DisplayAlert("Location Denied", "Can not continue, try again.", "OK");
    }
}
catch (Exception ex)
{

    LabelGeolocation.Text = "Error: " + ex;
}

Grab the NuGet & Code

Last week I pushed all the code up to GitHub and made the NuGet packages available for all. I will be integrating the Permissions plugin into all of my other Plugins that require permission checking. I also recorded a Motz Codes Live with a full walkthrough.

Given this Settings Class:

public static class Settings
{

    private static ISettings AppSettings
    {
        get
        {
            return CrossSettings.Current;
        }
    }

    const string CountKey = "count";
    private static readonly int CountDefault = 0;

    public static int Count
    {
        get { return AppSettings.GetValueOrDefault(CountKey, CountDefault); }
        set { AppSettings.AddOrUpdateValue(CountKey, value); }
    }
}

Approach 1: Essentially you need to create a view model with a public property that you wish to data bind to and then call into settings from there and raise a property changed notification if the value changed. Your Settings.cs can stay the same but you will need to create the viewmodel such as:

public class MyViewModel : INotifyPropertyChanged
{

    public int Count
    {
        get { return Settings.Count; }
        set
        {
            if (Settings.Count == value)
                return;

            Settings.Count = value;
            OnPropertyChanged();
        }

    }

    private Command increase;
    public Command IncreaseCommand
    {
        get
        {
            return increase ?? (increase = new Command(() => Count++));
        }
    }

    public event PropertyChangedEventHandler PropertyChanged;

    public void OnPropertyChanged([CallerMemberName]string name = "")
    {
        var changed = PropertyChanged;
        if (changed == null)
            return;
        changed(this, new PropertyChangedEventArgs(name));
    }

}

Then you XAML will look like this inside your Content page:

<StackLayout Padding="25">
 <Button Text="Increase" Command="{Binding IncreaseCommand}"/>
 <Label Text="{Binding Count, StringFormat='The count is {0:F0}'}"/>
</StackLayout>

Make sure you set the BindingContext in the xaml.cs of the page:

public partial class MyPage : ContentPage
{
    public MyPage()
    {
        InitializeComponent();
        BindingContext = new MyViewModel();
    }
}

This actually isn’t too much code to actually implement as your ViewModel would have a BaseViewModel that implements INotifyPropertyChanged, so really you are just adding in

public int Count
{
    get { return Settings.Count; }
    set
    {
        if (Settings.Count == value)
            return;

        Settings.Count = value;
        OnPropertyChanged();
    }
}

Approach 2: More magical way

However, using the powers of C# and knowing how Databinding works you could first create a BaseViewModel that everything will use:

public class BaseViewModel : INotifyPropertyChanged
{
    public Settings Settings
    {
        get { return Settings.Current; }
    }
    public event PropertyChangedEventHandler PropertyChanged;

    public void OnPropertyChanged([CallerMemberName]string name = "")
    {
        var changed = PropertyChanged;
        if (changed == null)
            return;
        changed(this, new PropertyChangedEventArgs(name));
    }
}

Notice my reference to Settings.Current, we will need to implement that now as a singleton, but we will use our BaseViewModel so we don’t have to re-implement INotifyPropertyChanged:

public class Settings : BaseViewModel
{
    static ISettings AppSettings
    {
        get
        {
            return CrossSettings.Current;
        }
    }

    static Settings settings;
    public static Settings Current
    {
        get { return settings ?? (settings = new Settings()); }
    }

    const string CountKey = "count";
    static readonly int CountDefault = 0;

    public int Count
    {
        get
        {
            return AppSettings.GetValueOrDefault(CountKey, CountDefault);
        }
        set
        {
            if (AppSettings.AddOrUpdateValue(CountKey, value))
                OnPropertyChanged();

        }
    }
}

Now of course we will still want to create a unique ViewModel that our XAML view will bind to:

public class MyViewModel : BaseViewModel
{
    private Command increase;
    public Command IncreaseCommand
    {
        get
        {
            return increase ?? (increase = new Command(() => Settings.Count++));
        }
    }
}

Notice that we are now inheriting from BaseViewModel, which means our command can actually just increment Settings.Count! But now we must adjust our Xaml just a bit as to what we are actually data binding to for our label:

<StackLayout Padding="25">
 <Button Text="Increase" Command="{Binding IncreaseCommand}"/>
 <Label BindingContext="{Binding Settings}" Text="{Binding Count, StringFormat='The count is {0:F0}'}"/>
</StackLayout>

Notice I am setting the BindingContext to our Settings, which is in our BaseViewModel for the Label, this must be done because that is where it is located now. And there you have it.

Material Design First

I immediately knew I wanted to use AppCompat and leverage material design as much as I could. I followed my own blog post on how to integrate Support v7 into my app and re-used all of the styles and colors xml. This was pretty tedious to setup and made me question why there aren’t project templates for these…. aka I know what I am doing this weekend :) 

Next was choosing my material palette and integrating different assets. I immediately went to http://www.materialpalette.com/, which is an amazing resource to help you put some colors together for your app. Then I headed over to the Android Asset Studio, every Android developers #1 bookmark, to generate a few icons for the app. If you are looking for some inspiration be sure to check out http://www.materialup.com for awesome material designs.

Tight Code Challenge

Monday night couldn’t have ended better. I got to sit down at my favorite restaurant, Thai Tom, to indulge in a Pad Thai Chicken with one my best friends Frank Krueger. I told Frank about Coffee Filter and my current UI design with Google Maps Lite and I could tell ideas were igniting in his brilliant mind. He enhanced my currenty UI idea with a new enhancement of flipping through coffee locations with a map hiding behind them. The UI would mostly be informational with nice large fonts telling me where to go get coffee. However, what Frank said next was very interesting, which was that he challenging me to write Coffee Filter in as little lines of code as possible. That meant no big MVVM framework, not over architected, just go go go. 

I took this challenge mostly to heart and didn’t introduce any data binding or IPropertyChanged notifications. I still separated out my Models and View Models into a nice re-usable section, but just didn’t add any framework into the mix. The entire app is actually around 650 lines of code including using statements and comments, which to me is very impressive.

Plugins for Xamarin

The reason for nice tight code was actually because of plugins. Plugins abstract away a bunch of cross platform functionality, which is where most of the code actually lives, so I didn’t have to write it. When I started writing plugins for Xamarin a while back I didn’t know how often I would actually use my own, but I found immediate use of three:

• Connectivity: Check my network state before querying any data.
• Geolocator: Gave me immediate access to my location.
• External Maps: Easy way of launching maps to navigate.

Get the App & the Code

My favorite part of Android development is being able to package up an app and have it on Google Play within two hours. This means that yes, Coffee Filter is available right now: https://play.google.com/store/apps/details?id=com.refractored.coffeefilter. Of course you know I love open source, so you can grab the code for Coffee Filter on GitHub: https://github.com/jamesmontemagno/Coffee-Filter. It even includes some brand new Xamarin.UITests that can be run on a simulator or Test Cloud, which is pretty awesome. I am not done yet with Coffee Filter though as I will be adding more details to each coffee shop, refactoring, taking feedback, fixing bugs, and of course leveraging my shared code with iOS.