Xamarin Workbooks SDK 시작Getting Started with the Xamarin Workbooks SDK

이 문서에서는 Xamarin Workbooks에 대 한 통합 개발을 시작 하는 방법에 대 한 간략 한 가이드를 제공 합니다.This document provides a quick guide to getting started with developing integrations for Xamarin Workbooks. 이 중 대부분은 안정적인 Xamarin Workbooks에서 작동 하지만 NuGet 패키지를 통해 통합을 로드 하는 것은 작성 시 알파 채널의 통합 문서 1.3 에서만 지원 됩니다.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 통합은 Xamarin.Workbooks.Integrations NuGet SDK를 사용 하 여 향상 된 환경을 제공 하기 위해 Xamarin Workbooks 및 검사자 에이전트와 통합 하는 작은 라이브러리입니다.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:

이식 가능한 라이브러리 템플릿Mac용 Visual StudioPortable Library Template Visual Studio for Mac

라이브러리 프로젝트를 만든 후에는 NuGet 패키지 관리자를 통해 Xamarin.Workbooks.Integration NuGet 라이브러리에 대 한 참조를 추가 합니다.Once you create the library project, add a reference to our Xamarin.Workbooks.Integration NuGet library via the NuGet Package Manager.

프로젝트의 일부로 생성 된 빈 클래스를 삭제 하는 것이 좋습니다 .이에 대해서는 필요 하지 않습니다.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. 먼저 SampleIntegration이라는 새 클래스를 만들고 IAgentIntegration 인터페이스를 구현 하도록 설정 합니다.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)
    {
    }
}

원하는 것은 녹색 인 모든 개체에 대 한 표현을 추가 하는 것입니다.What we want to do is add a representation for every object that is a green color. 표시 공급자를 사용 하 여이 작업을 수행 합니다.We'll do this using a representation provider. 공급자는 RepresentationProvider 클래스에서 상속 합니다. 즉, ProvideRepresentations를 재정의 하기만 하면 됩니다.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);
    }
}

SDK에서 미리 작성 된 표현 유형인 Color을 반환 하 고 있습니다.We're returning a Color, a pre-built representation type in our SDK. 여기에서 반환 형식은 IEnumerable<object>—하나는 개체에 대 한 여러 표현을 반환할 수 있는 것입니다.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. 공급자를 등록 하려면 앞에서 만든 SampleIntegration 클래스의 IntegrateWith 메서드에이 코드를 추가 합니다.To register the provider, add this code to the IntegrateWith method in the SampleIntegration class we created earlier:

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

통합 유형 설정은 어셈블리 차원의 특성을 통해 수행 됩니다.Setting the integration type is done via an assembly-wide attribute. 이를 AssemblyInfo.cs에 배치 하거나 편의를 위해 통합 형식과 동일한 클래스에 넣을 수 있습니다.You can put this in your AssemblyInfo.cs, or in the same class as your integration type for convenience:

[assembly: AgentIntegration (typeof (SampleIntegration))]

개발 하는 동안 AddProvider 오버 RepresentationManager 로드를 사용 하 여 통합 문서 내에 표시를 제공 하는 간단한 콜백을 등록 한 다음 완료 되 면 해당 코드를 RepresentationProvider 구현으로 이동 하는 것이 더 편리할 수 있습니다.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. OxyPlot PlotModel를 렌더링 하기 위한 예제는 다음과 같습니다.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)));

참고

이러한 Api를 사용 하면 신속 하 게 시작 하 고 실행할 수는 있지만, 클라이언트에서 형식을 처리 하는 방법을 거의 제어 하지 않는—를 사용 하 여 전체 통합을 제공 하지 않는 것이 좋습니다.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

통합을 제공 하려면 NuGet 패키지에 추가 해야 합니다.To ship your integration, you'll need to add it to a NuGet package. 기존 라이브러리의 NuGet과 함께 제공 하거나 새 패키지를 만드는 경우이 nuspec 파일을 시작 점으로 사용할 수 있습니다.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. 가장 중요 한 부분은 통합에 대 한 모든 파일이 패키지 루트의 xamarin.interactive 디렉터리에 있어야 한다는 것입니다.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.

<?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>

Nuspec 파일을 만들었으면 다음과 같이 NuGet을 압축할 수 있습니다.Once you've created the .nuspec file, you can pack your NuGet like so:

nuget pack MyIntegration.nuspec

그런 다음 NuGet에 게시 합니다.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. 아래 스크린샷에서는이 문서에서 빌드하고 NuGet 패키지를 통합 문서에 설치한 샘플 통합을 패키지 했습니다.In the screenshot below, we've packaged the sample integration that we built in this document and installed the NuGet package in a workbook:

통합을 초기화 하는 데 #r 지시문 또는 모든 것이 표시 되지 않습니다. 통합 문서에서 모든 작업을 내부적으로 처리 합니다.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

SDK를 구성 하는 이동 방법에 대 한 자세한 내용 및 통합 문서 클라이언트에서 실행 되는 사용자 지정 JavaScript를 제공 하는 것과 같이 통합에서 수행할 수 있는 추가 작업에 대 한 샘플 통합 은 다른 설명서를 확인 하세요.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.