Introducción a los libros de Xamarin SDKGetting Started with the Xamarin Workbooks SDK

Este documento proporciona a una guía rápida introducción al desarrollo de aplicaciones integradas para Xamarin Workbooks.This document provides a quick guide to getting started with developing integrations for Xamarin Workbooks. Gran parte de esto funcionará con los libros de Xamarin estable, pero cargando integraciones a través de paquetes de NuGet solo se admite en los libros 1.3, en el canal alfa en el momento de escribir.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.

Información generalGeneral Overview

Integraciones de Xamarin Workbooks son pequeñas bibliotecas que utilizan el [ Xamarin.Workbooks.Integrations NuGet] nuget SDK para integrar con el Inspector y Workbooks de Xamarin agentes para proporcionar experiencias mejoradas.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.

Hay 3 pasos principales para empezar a desarrollar una integración, que le resumimos aquí.There are 3 major steps to getting started with developing an integration—we'll outline them here.

Crear el proyecto de integraciónCreating the Integration Project

Bibliotecas de integración se desarrollan mejor como bibliotecas multiplataforma.Integration libraries are best developed as multiplatform libraries. Dado que desea proporcionar la mejor integración en todos los agentes disponibles, pasado y futuro, desea elegir un conjunto de bibliotecas ampliamente compatible.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. Se recomienda usar la plantilla "Biblioteca Portable" para el soporte más amplio:We recommend using the "Portable Library" template for the broadest support:

Plantilla de biblioteca Portable Visual Studio para MacPortable Library Template Visual Studio for Mac

Una vez creado el proyecto de biblioteca, agregue una referencia a nuestro Xamarin.Workbooks.Integration biblioteca NuGet a través del Administrador de paquetes de NuGet.Once you create the library project, add a reference to our Xamarin.Workbooks.Integration NuGet library via the NuGet Package Manager.

Desea eliminar la clase vacía que se crea automáticamente como parte del proyecto, no va a necesitar, para esto.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. Una vez que haya realizado estos pasos, está listo para empezar a crear la integración.Once you've done these steps, you're ready to begin building your integration.

Creación de una integraciónBuilding an Integration

Vamos a crear una integración sencilla.We'll build a simple integration. Realmente amamos el color verde, así que agregaremos el color verde como una representación de cada objeto.We really love the color green, so we'll add the color green as a representation to each object. En primer lugar, cree una nueva clase denominada SampleIntegrationy conviértalo en implementar nuestro [ IAgentIntegration ] integration-type interfaz:First, create a new class called SampleIntegration, and make it implement our IAgentIntegration interface:

using Xamarin.Interactive;

public class SampleIntegration : IAgentIntegration
{
    public void IntegrateWith (IAgent agent)
    {
    }
}

Lo que queremos hacer es agregar un representación para cada objeto que es un color verde.What we want to do is add a representation for every object that is a green color. Haremos esto con un proveedor de representación.We'll do this using a representation provider. Proveedores de heredan de la [ RepresentationProvider ] reppr clase — para nuestra, nos basta con reemplazar [ ProvideRepresentations ] prrep:Providers inherit from the RepresentationProvider class—for ours, we just need to override ProvideRepresentations:

using Xamarin.Interactive.Representations;

class SampleRepresentationProvider : RepresentationProvider
{
    public override IEnumerable<object> ProvideRepresentations (object obj)
    {
        // This corresponds to Pantone 2250 XGC, our favorite color.
        yield return new Color (0.0, 0.702, 0.4314);
    }
}

Devuelve un [ Color ] color, una compilada previamente el tipo de representación en nuestro SDK.We're returning a Color, a pre-built representation type in our SDK. Observará que el tipo de valor devuelto es un IEnumerable<object> —un proveedor de representación puede devolver varias representaciones de un objeto.You'll notice that the return type here is an IEnumerable<object>—one representation provider may return many representations for an object! Todos los proveedores de representación se denominan para cada objeto, por lo que es importante no realizar ninguna suposición acerca de los objetos que se pasen a usted.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.

El último paso es registrar el proveedor con el agente realmente e indican dónde encontrar el tipo de integración de los libros.The final step is to actually register our provider with the agent and tell Workbooks where to find our integration type. Para registrar el proveedor, agregue este código a la IntegrateWith método en el SampleIntegration clase que creamos anteriormente:To register the provider, add this code to the IntegrateWith method in the SampleIntegration class we created earlier:

agent.RepresentationManager.AddProvider (new SampleRepresentationProvider ());

Establecer el tipo de integración se realiza a través de un atributo de todo el ensamblado.Setting the integration type is done via an assembly-wide attribute. Se puede colocar en su AssemblyInfo.cs o en la misma clase que el tipo de integración para su comodidad:You can put this in your AssemblyInfo.cs, or in the same class as your integration type for convenience:

[assembly: AgentIntegration (typeof (SampleIntegration))]

Durante el desarrollo, le resultará más conveniente usar [ AddProvider sobrecargas] addprovider en RepresentationManager que le permiten registrar una devolución de llamada simple para proporcionar representaciones dentro de un libro, y, a continuación, pasar ese código en su RepresentationProvider implementación una vez que haya terminado.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. Un ejemplo para representar un [ OxyPlot ] oxyplot PlotModel podría tener este aspecto:An example for rendering an OxyPlot PlotModel might look like this:

InteractiveAgent.RepresentationManager.AddProvider<PlotModel> (
  plotModel => Image (new SvgExporter {
      Width = 300,
      Height = 250
    }.ExportToString (plotModel)));

Nota

Estas API ofrecen una forma rápida de empezar a trabajar, pero no lo recomendaría una integración completa de envío solo con ellos—proporcionan un control muy preciso sobre cómo se procesan los tipos por el cliente.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.

Con la representación registrada, la integración está lista para enviar.With the representation registered, your integration is ready to ship!

La integración de envíoShipping your integration

Para enviar la integración, deberá agregarlo a un paquete de NuGet.To ship your integration, you'll need to add it to a NuGet package. Se pueden enviar con NuGet de la biblioteca existente, o si va a crear un nuevo paquete, puede usar este archivo .nuspec de plantilla como punto de partida.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. Deberá rellenar las secciones relevantes para su integración.You'll need to fill out the sections relevant to your integration. La parte más importante es que todos los archivos para la integración deben estar en un xamarin.interactive directorio en la raíz del paquete.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. Esto nos permite encontrar fácilmente todos los archivos pertinentes para la integración, independientemente de si un paquete existente o crear uno nuevo.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.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
      <id>$YourNuGetPackage$</id>
      <version>$YourVersion$</version>
      <authors>$YourNameHere$</authors>
      <projectUrl>$YourProjectPage$</projectUrl>
      <description>A short description of your library.</description>
    </metadata>
    <files>
      <file src="Path\To\Your\Integration.dll" target="xamarin.interactive" />
    </files>
</package>

Una vez que haya creado el archivo .nuspec, puede empaquetar su NuGet así:Once you've created the .nuspec file, you can pack your NuGet like so:

nuget pack MyIntegration.nuspec

y, a continuación, publicarlo en NuGet.and then publish it to NuGet. Una vez allí, podrá hacer referencia a él desde cualquier libro y verlo en acción.Once it's there, you'll be able to reference it from any workbook and see it in action. En la siguiente captura de pantalla, tenemos los paquetes de la integración de ejemplo que hemos compilado en este documento y había instalado el paquete de NuGet en un libro:In the screenshot below, we've packaged the sample integration that we built in this document and installed the NuGet package in a workbook:

Tenga en cuenta que no ve ningún #r directivas ni nada para inicializar la integración: los libros se ha ocupado de todo eso por usted en segundo plano.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!

Pasos siguientesNext Steps

Consulte otra documentación para obtener más información acerca de las piezas móviles que componen el SDK, y nuestro integraciones de ejemplo para aspectos adicionales que puede hacer desde la integración, como proporcionar código JavaScript personalizado que se ejecuta en el cliente de los libros.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.