In this article

Getting Started with the Xamarin Workbooks SDK

03/30/2017

4 minutes to read

Contributors

In this article

This document provides a quick guide to getting started with developing
integrations for Xamarin Workbooks. Much of this will work with the stable
Xamarin Workbooks, but loading integrations via NuGet packages is only
supported in Workbooks 1.3, in the alpha channel at the time of writing.

General Overview

Xamarin Workbooks integrations are small libraries that use the
Xamarin.Workbooks.Integrations NuGet SDK to integrate with the Xamarin
Workbooks and Inspector agents to provide enhanced experiences.

There are 3 major steps to getting started with developing an
integration—we'll outline them here.

Creating the Integration Project

Integration libraries are best developed as multiplatform libraries. Because you
want to provide the best integration on all the available agents, past and
future, you'll want to choose a broadly supported set of libraries. We recommend
using the "Portable Library" template for the broadest support:

You'll want to delete the empty class that's created for you as part of the
project—you won't be needing it for this. Once you've done these steps,
you're ready to begin building your integration.

Building an Integration

We'll build a simple integration. We really love the color green, so we'll
add the color green as a representation to each object. First, create a new
class called SampleIntegration, and make it implement our
IAgentIntegration interface:

We're returning a Color, a pre-built representation type in our SDK.
You'll notice that the return type here is an IEnumerable<object>—one
representation provider may return many representations for an object! All
representation providers are called for every object, so it's important to not
make any assumptions about what objects are being passed to you.

The final step is to actually register our provider with the agent and tell
Workbooks where to find our integration type. To register the provider, add this
code to the IntegrateWith method in the SampleIntegration class we created
earlier:

Setting the integration type is done via an assembly-wide attribute. You can put
this in your AssemblyInfo.cs, or in the same class as your integration type for
convenience:

[assembly: AgentIntegration (typeof (SampleIntegration))]

During development, you may find it more convenient to
use AddProvider overloads on RepresentationManager that allow
you to register a simple callback to provide representations inside a workbook,
and then move that code into your RepresentationProvider implementation once
you're finished. An example for rendering an OxyPlotPlotModel
might look like this:

These APIs give you a quick way to get up and running, but we would not
recommend shipping an entire integration only using them—they provide very
little control over how your types are processed by the client.

With the representation registered, your integration is ready to ship!

Shipping your integration

To ship your integration, you'll need to add it to a NuGet package.
You can ship it with your existing library's NuGet, or if you're creating a
new package, you can use this template .nuspec file as a starting point.
You'll need to fill out the sections relevant to your integration. The most
important part is that all of the files for your integration must be in a
xamarin.interactive directory at the root of the package. This enables us
to easily find all the relevant files for your integration, regardless of
whether you use an existing package or create a new one.

Once you've created the .nuspec file, you can pack your NuGet like so:

nuget pack MyIntegration.nuspec

and then publish it to NuGet. Once it's there, you'll be able to
reference it from any workbook and see it in action. In the screenshot below,
we've packaged the sample integration that we built in this document and
installed the NuGet package in a workbook:

Notice that you don't see any #r directives or anything to initialize the
integration—Workbooks has taken care of all of that for you behind the scenes!

Next Steps

Check out our other documentation for more information about the
moving pieces that make up the SDK, and our sample integrations for
additional things you can do from your integration, like providing custom
JavaScript that is run in the Workbooks client.

Feedback

We'd love to hear your thoughts. Choose the type you'd like to provide: