Xamarin.iOS – API Doc with a Xamarin Workbook and Nuget

In this lesson

  • Import a Namespace
  • Add a Nuget Package to Workbook
  • Interact with a web API


Tap on time to skip ahead


Hello there C# hipsters. In this lesson, I’m going to cover the Xamarin Workbook functionality with the new Xamarin Inspector tool and how it can be used for documentation purposes.


Earlier, I downloaded this Workbook from one of my emails. As you can see the file size of a Workbook is extremely low so this makes for a very nice format to pass around, either on Dropbox, email or just to post online. With that said, let’s open up this Workbook. Right now there’s a few bugs with the Xamarin Inspector, so to open up this Workbook what you want to do is go File, Open and then navigate to the document and double click it like so.


Much like we saw in the previous lesson, it takes a few minutes because it has to create a connection with our iOS simulator here on the right. Once the document is loaded, we can see that we have some really nice formatting here. The Xamarin Workbooks support Markdown so we get different heading sizes that we can use. For example, I can select the whole thing and I can specify what type of heading level I want it to be. I can obviously add things like my author information as well as any notes about particular code.


To actually take this Workbook from just yet another text document to something that’s actually useful, what we need to do is we need to execute each line of code. I’m going to put my cursor at the end of this using statement. This imports system.net into our run time. From here, I’m going to also instantiate our WebClient. Then, I’m going to set its base address, which, this is basically just a directory that I have on our Rendr servers.


The next thing I want to do is demonstrate how I might want to get a list of breweries from this API. I want to use the WebClient to download a string or text from Brewery.json. Now, if I enter after the semicolon, you’ll see we get this big, long JSON string of content. This is all well and good but it’s almost easier to just load this URL in a browser and see it formatted there. What we can do inside Xamarin Workbooks, is we can actually take this JSON and convert it into something useful like a class instance. To do this, we’ll want to use the very popular Newtonsoft Json Nuget package. We can add this package by going up to File -> Add Package, then we’ll get our typically Nuget explorer. I can type in Json.net and it will give me a list of Nuget packages. I’ve already added this package to this Workbook but I still need to invoke that reference by putting my cursor at the end of the line and hitting return.


The next thing you’ll notice is that we get to define a class called Brewery. Something that you might notice that’s a bit different than if you were coding in a traditional environment, is that we have to use the full namespace path for any sort of attributes we’re using. For those of you that might not be familiar with the Newtonsoft Json.net library, we can specify that, “Hey, you’ll want to use the JSON property with the name of address and apply it to this property.”


For example, in this API, all the property names are lowercase. But in C# we like our properties to be upper case. This is a handy attribute that allows us to handle that conversion explicitly. After starting this class, I can put my cursor at the last curly brace and hit return which should in turn create this class and register it with our run time.


I also want to go ahead and say that we’re using Newtonsoft JSON so we can load that simply into our run time. Then I’m going to go ahead and I’m going to convert this JSON string into a list of breweries. Again, to invoke it, I put my cursor after the semicolon and hit return.


From here, we can see we’ve had nine breweries deserialized. If I want to see if everything got mapped correctly, I can say breweries 1 and it will give me the second item in our list. We can see that address was parsed correctly as well as description and email. If I so choose, I can change our index, hit return and have it updated just to make sure multiple items were parsed.


In real life, things are going to change. We can also change our Workbook to match any sort of API change. Let’s go ahead and add an extra property here for website URLs. I’m going to say web URL, like that, then I’m going to copy our JSON property name like this. I’m going to put my cursor after the last curly brace to update our run time. Then, I’m going to re-parse our JSON. Now, I’m going to take another look at the fourth brewery. We’ll see that we’re now able to easily parse the web URL into our model. As you can see, the Xamarin Workbooks functionality is extremely useful for documenting APIs as well as demonstrating to people how they might interact with different libraries or SDKs.

Additional Info

Register to get access to additional resources and info.