Artigo
12/09/2016

Connect(); 2016

Volume 31 - Número 12

Xamarin Workbooks – O Futuro (Interativo) dos Documentos Técnicos

Antigamente, os livros técnicos impressos eram o principal meio para aprender novas linguagens de programação e SDKs. Atualmente, você encontrará uma infinidade de conteúdos online, de documentação sobre produtos a blogs de desenvolvedores, de Stack Overflow ao GitHub, e de podcasts ao YouTube – até mesmo aulas online da Xamarin University.

Porém, ainda podem existir barreiras para a aprendizagem: Configurar o novo IDE no qual você deseja começar a programar, compreender o assistente Arquivo | Novo Projeto e todas as suas opções, digitar ou copiar o código de exemplo em um projeto novo ou existente para experimentar e, até mesmo navegar pela estrutura de solução existente, pode ser muito confuso para os não iniciados. Os desenvolvedores que mudaram do Visual Basic para o Eclipse e o Xcode sabem como essas experiências podem ser diferentes.

Roslyn – o serviço de compilador .NET de software livre da Microsoft – facilita novas experiências que amenizam esses problemas removendo a necessidade da interface IDE. Experiências de aprendizagem, como a Gistlyn (bit.ly/2d00D7b) e o novo tutorial C# da Microsoft (bit.ly/28WyuvW), imergem o desenvolvedor em documentação e códigos, sem sobrecarregá-lo com soluções e projetos. Estas novas ferramentas tornam a aprendizagem mais simples e interativa.

Apresentando o Xamarin Workbooks

O Xamarin Workbooks traz este novo conceito de documentação interativa e codificação ativa para o desenvolvimento de aplicativos móveis e para área de trabalho. Em conjunção com simuladores de dispositivos, o Workbooks oferece a você a mesma experiência imersiva que as ferramentas online mencionadas anteriormente, mas fornece a capacidade adicional de aprender e experimentar com todos os SDKs para Android, iOS, Mac e Windows Presentation Foundation (WPF):

Aprender a desenvolver o aplicativo Xamarin Mobile se torna um processo interativo e exploratório. Em vez de apenas ler os documentos, o Workbooks permite que você crie códigos de forma interativa e teste recursos nativos de aplicativos móveis.
É possível explorar APIs online – incluindo os serviços do Microsoft Azure – sem o inconveniente de ter que iniciar um aplicativo de exemplo e navegar por um labirinto de arquivos de origem. Como você está usando as mesmas ferramentas com as quais seus aplicativos móveis são escritos, o código que você está usando pode ser copiado do Workbooks para seus projetos do aplicativo Xamarin.
Escrever seus próprios Workbooks é fácil, seja para testar uma ideia ou criar seu próprio curso para ensinar outras pessoas. Em vez de criar seu centésimo Arquivo | Novo Projeto para tentar algo novo, você obtém uma maneira mais rápida e fácil de experimentar. Como um bônus adicional, você pode interagir com a interface do usuário no simulador e explorar a árvore visual na exibição do inspetor.

Introdução

O que é exatamente o Workbooks? Resumindo: É uma documentação ativa e interativa para plataformas móveis e para área de trabalho. Você pode baixar o aplicativo do Workbooks para Mac e Windows em bit.ly/2ejXBj8. Para Android e iOS, você deve ter o Xamarin e as plataformas e simuladores SDKs instalados em seu sistema.

Os arquivos Workbooks são essencialmente arquivos Markdown com cabeçalho YAML; eles contêm texto formatado e código C# isolado. O arquivo de extensão é “.workbook.” Você pode escrever um workbook com qualquer editor de texto, mas o aplicativo Xamarin Workbooks inclui a capacidade de criar e editar workbooks para que você não precise aprender o formato subjacente. Aqui estão algumas fontes Markdown de exemplo:

---
uti: com.xamarin.workbook
platform: iOS
---
# My First Workbook
Simple C# assignment will render the resulting object as a string.
```csharp
var greeting = "Hello, MSDN"
```

A Figura 1 mostra o workbook resultante antes e depois da execução.

Figura 1 - Execução antes e depois do MyFirst.workbook

Células de código executáveis têm um plano de fundo cinza e usam a mesma experiência de edição que o Visual Studio Code. Funcionalidades como destaque de sintaxe, conclusão de código, erros de compilação e atalhos de teclado têm suporte nele.

Ao clicar dentro de uma célula de código para destacá-la, um conjunto de botões de ação aparecem abaixo dela (como mostrado na Figura 1). Pressione o botão Reproduzir (seta dentro do círculo, na extremidade à esquerda) para executar essa célula de código (e todos os códigos anteriores). Você também pode executar todo o workbook de uma vez no menu Executar.

Assim que a execução do código é concluída, uma célula de resultado é exibida abaixo da célula de código. Você pode editar qualquer parte da célula de código, para alterar como ela é executada ou para experimentá-la com a API, e pressionar Reproduzir para executá-la novamente. (E novamente. É assim que os desenvolvedores aprendem com o Workbooks – lendo a documentação, executando e modificando o código de exemplo ao longo do processo.)

A célula de resultado contém uma representação da última referência de objeto na célula de código. Por padrão, é usada a representação da cadeia de caracteres do objeto, mas o Workbooks dá suporte a uma série de visualizadores adicionais para ajudá-lo a explorar os resultados. Use o menu pequeno ao lado do resultado para escolher uma das visualizações disponíveis, incluindo:

C#: Uma cadeia de caracteres de escape para o C# (por exemplo, novas linhas codificadas como “\n”).

Texto sem formatação: Um valor de cadeia de caracteres sem escape (por exemplo, linhas novas são renderizadas como texto multilinha).

Membros do objeto: Renderiza uma lista completa das propriedades do objeto em uma tabela. Gráficos de objeto cíclicos e grandes são avaliados por demanda, para que eles não diminuam o ritmo de sua codificação, mas estão disponíveis para serem explorados se necessário, tal como um depurador de tempo de execução.

Enumerável: Expande automaticamente uma coleção para que você possa explorar cada item. Somente os 10 primeiros elementos são inicialmente exibidos, mas você pode explorar mais clicando no botão Continuar Enumerando.

Cor: Uma pequena amostra de cor é exibida, junto com as representações Hexa ou RGB de seu valor.

Local: Os objetos que representam uma localização de latitude/longitude são mostrados no mapa (somente para Mac).

Imagem: Classes de exibição de imagem válidas podem mostrar a imagem em linha no workbook.

Exceção: Destaca as mensagens de exceção na célula de resultado.

Html: Os autores do Workbooks podem usar o método AsHtml em suas células de código para fazer com que a célula de resultado renderize uma cadeia de caracteres como HTML.

A Figura 2 mostra o Workbook dos Visualizadores, incluindo exemplos de algumas dessas opções.

Figura 2 - Opções de Visualização

Até o momento, vimos apenas o Workbooks exibindo seus resultados em linha, mas eles são ainda mais interessantes quando exploram APIs móveis nativas com o Xamarin por meio de simuladores de dispositivo móvel.

Aprendendo sobre o Xamarin com o Workbooks

Quando você se sentir familiarizado para executar células de código e interpretar os resultados, visite developer.xamarin.com/workbooks e baixe o Workbooks para saber mais sobre Android, iOS e Xamarin.Forms. As APIs de plataforma nativa estão disponíveis no Workbooks para tarefas tão simples quanto adicionar um rótulo à tela, até renderizar conteúdo em 3D correspondente a toque.

Ao criar ou abrir um workbook iOS, Android ou Xamarin.Forms, um simulador de dispositivo móvel inicializará (workbooks do Mac ou do Windows Presentation Foundation [WPF] só iniciam uma janela vazia). Esses simuladores externos (ou janelas) executam um aplicativo agente que se comunica com o workbook – você verá uma mensagem de status quando o agente estiver iniciando. Quando o agente estiver em execução, o Xamarin Workbooks estará pronto para ser explorado.

Conforme você lê e executa cada célula de código, o aplicativo no simulador muda para refletir cada nova parte do código. Se tiver curiosidade sobre como isso funciona, edite o código e execute-o novamente. A Figura 3 mostra um exemplo simples de UITableView do iOS, e a Figura 4 mostra-a em execução no simulador.

Figura 3 - XamariniOS.workbook

---
uti: com.xamarin.workbook
platform: iOS
packages:
- id: Newtonsoft.Json
  version: 9.0.1
---
# iOS UITableView
This example uses **Json.NET** and `WebClient` to download a file *monkeydata.json* that is used to bind to the iOS UITableView.
```csharp
#r "Newtonsoft.Json"
#load "json_monkey.csx"
```
To add a UITableView control to the screen, instantiate an instance, set the bounds, and add to the `RootViewController`. You can experiment with changing the `Frame`.
```csharp
var tableView = new UITableView();
tableView.Frame = UIScreen.MainScreen.Bounds;
RootViewController.View.AddSubview(tableView);
```
Wiring up a data source (like a generic list of `Monkey` objects) to a table requires a `UITableViewSource`. This class converts the data into `UITableViewCell` classes to be rendered.
```csharp
public class MySource : UITableViewSource
{
  string identifier = "mycell";
  public List<Monkey> Data {get;set;} = new List<Monkey>(); // C# 6
  public override nint RowsInSection (UITableView tableview, nint section)
  {
    return Data.Count;
  }
  public override UITableViewCell GetCell (UITableView tableView,
    NSIndexPath indexPath)
  {
    // First, get or create a cell
    UITableViewCell cell = tableView.DequeueReusableCell (identifier);
    if (cell == null)
    { cell = new UITableViewCell (UITableViewCellStyle.Subtitle, identifier); }
    // Then, get the data and set the UI
    cell.TextLabel.Text = Data[indexPath.Row].Name;
    cell.DetailTextLabel.Text = Data[indexPath.Row].Location;
    return cell;
  }
}
```
To display the data in the table, create the source object, assign the Monkey object list, then assign it to the table
```csharp
var source = new MySource(); // Create the class
source.Data = monkeys;       // Assign the list of strings
tableView.Source = source;   // Give it to the table view
tableView.ReloadData();      // and show on the screen
```

Figura 4 - Workbooks e Simulador iOS

O Workbooks também pode exibir uma vista expandida da hierarquia da interface do usuário a ser explorada. Você pode selecionar itens no simulador, na renderização 3D ou na lista de árvore visual, e exibir as propriedades deles em um preenchimento. Para acessar no Mac, selecione Exibir | Inspetor Visual. No Windows, os preenchimentos são encaixados, prontos para serem acessados a qualquer momento. Para voltar para o código e a documentação, use o item de menu Exibir | Workbook.

Explorando APIs

O Workbooks também é ótimo para explorar outras APIs, como as fornecidas pelos pacotes NuGet ou pontos de extremidade REST. Um exemplo que combina os dois é um workbook que se conecta ao Azure EasyTables, usando o back-end tryappservice.azure.com gratuito.

A fonte completa do workbook é mostrada na Figura 5, incluindo os pacotes NuGet necessários; e o código-fonte completo para salvar e recuperar dados de um Azure EasyTable é mostrado em execução na Figura 6.

Figura 5 - Azure-TryAppService.workbook

---
uti: com.xamarin.workbook
platform: WPF
packages:
- id: Microsoft.Bcl
  version: 1.1.10
- id: Newtonsoft.Json
  version: 9.0.1
- id: Microsoft.Net.Http
  version: 2.2.29
- id: Microsoft.Azure.Mobile.Client
  version: 3.0.1
---
# Azure TryAppService
Two NuGets - **Microsoft.Azure.Mobile.Client** & Newtonsoft.Json - have been added:
```csharp
#r "Newtonsoft.Json"
#r "Microsoft.WindowsAzure.Mobile"
#r "Microsoft.WindowsAzure.Mobile.Ext"
```
This `TodoItem` class matches the one configured in the TryAppService back end.
```csharp
using Newtonsoft.Json;
using Microsoft.WindowsAzure.MobileServices;
public class TodoItem
{
  [JsonProperty(PropertyName = "id")]
  public string ID {get;set;}
  [JsonProperty(PropertyName = "text")]
  public string Name {get;set;}
  [JsonProperty(PropertyName = "complete")]
  public bool Done {get;set;}
  [Version]
  public string Version { get; set; }
  public override string ToString() {
    return $"{Name} is " + (Done?"done":"not done");
  }
}
```
Sign up at [tryappservice.azure.com](https://tryappservice.azure.com/ "Try Azure for free!") **Mobile App > TodoList**. Replace the URL with *your* temporary, generated endpoint URL:
```csharp
var mobileService = new MobileServiceClient (
  "https://da0cfa57-0ee0-4-231-b9ee.azurewebsites.net/");
  // Replace this with your own
var table = mobileService.GetTable<TodoItem> ();
```
The following code creates a new `TodoItem` class, inserts it into the table on the server, and retrieves the list from the server:
```csharp
var rememberTo = new TodoItem {Name="buy apples"};
await table.InsertAsync (rememberTo);
List<TodoItem> todos = await table.Take (10).ToListAsync ();
```

Figura 6 - Usando o Azure TryAppService de forma interativa

É claro que há muito mais coisas para mostrar sobre o Azure – este exemplo só começa a demonstrar como o Workbooks pode ser aplicado à ideia de ensinar uma API.

Escrevendo seu próprio Workbooks

Apesar de você poder escrever workbooks no Markdown, a maneira mais fácil de criar os seus é dentro do próprio aplicativo do Workbooks. Escolha o item de menu Arquivo | Novo, em seguida, escolha a plataforma: iOS e Android podem ser criados tanto no macOS quanto no Windows. Os workbooks de Mac e WPF só podem ser criados no MacOS ou no Windows, respectivamente.

O Workbooks é composto por três tipos de elementos: células de texto, células de código e células de resultado. Um workbook recém-criado contém uma única célula de código, na qual você pode digitar e executar o código C# imediatamente.

As células podem ser adicionadas e excluídas usando botões de ação que aparecem abaixo de uma célula quando ela tem foco. Existem três botões (visíveis na Figura 1):

Mais (+) – Adiciona uma nova célula de código.
Aspas duplas (") – Adiciona uma nova célula de texto.
Excluir (x) – Exclui a célula anterior.

Todas as células de código em um workbook são executadas no mesmo contexto para que as variáveis e classes criadas em uma célula de código fiquem disponíveis nas células de código subsequentes.

O texto pode ser formatado selecionando-o e usando a barra de formatação mostrada na Figura 7. As opções incluem negrito, itálico, adição de links, formato de código, assim como listas com marcadores, listas numeradas e blockquotes. Também existem seis níveis de título e a capacidade de inserir imagens ou uma régua horizontal.

Figura 7 - Formatação de texto

As células de código têm suporte para realce de palavra-chave C# e preenchimento automático de membro e assinatura/substituição. Os erros são indicados por um sublinhado vermelho e a mensagem de erro é exibida ao passar a seta do mouse sobre o sublinhado.

Cada plataforma tem seu próprio mecanismo para acessar a interface de usuário, da seguinte forma:

Android: Compilar workbooks que usam o simulador significa que você precisa de uma maneira de referenciar a interface do usuário a partir das células de código. Para Android, use o código a seguir para obter uma referência para a Atividade que está sendo usada pelo simulador:

var mainActivity = StartedActivities.First();
var label = new Android.Widget.TextView(mainActivity) {
  Text = "Hello, Workbooks",
  TextSize = 36
};
mainActivity.SetContentView(label);

iOS: os workbooks do iOS expõem o RootViewController do simulador para que você possa criar a interface do usuário adicionando subexibições, como mostrado aqui:

var label = new UIKit.UILabel(new CGRect(10,10,300,50)) {
  Text = "Hello, Workbooks",
  Font = UIFont.SystemFontOfSize(36)
};
RootViewController.Add(label);

WPF: É possível adicionar controles à janela do aplicativo nos workbooks WPF configurando a propriedade Conteúdo em System.Windows.Application.Current.MainWindow, por exemplo:

var label = new System.Windows.Controls.Label {
  Text = "Hello, Workbooks",
  FontSize = 36
};
System.Windows.Application.Current.MainWindow.
  Content = label;

O Workbooks também inclui recursos para ajudá-lo a criar cenários de código mais sofisticados, para que você possa:

Referenciar namespaces adicionais: Por padrão, somente um conjunto limitado de namespaces estão disponíveis em cada workbook. Alguns deles, como o System.Xml, precisam de uma cláusula using no início da célula de código antes de serem usados (tal como em um arquivo C# comum).

Adicionar pacotes NuGet: Use o item de menu Arquivo | Adicionar Pacote para adicionar pacotes NuGet a um workbook, e verifique se os conjuntos estão referenciados usando a seguinte sintaxe:

#r "Microsoft.WindowsAzure.Mobile"

Os conjuntos referenciados desta forma ainda precisam da instrução using apropriada em uma célula de código (conforme exibido na Figura 6).

Inclui códigos adicionais: exemplos mais complexos podem exigir muitos códigos, o que só tumultuaria o workbook se estivesse exibido em linha. Arquivos de código externos podem ser referenciados por um workbook com a seguinte sintaxe:

#load "my-extra-code.csx"

Use arquivos externos para criar classes de suporte, elementos de interface do usuário, classes Model e ViewModel ou outros objetos necessários para o workbook funcionar, mas que não são necessários para a documentação (e que provavelmente não precisarão ser modificados pelo usuário). O workbook na Figura 3 mostra onde alguns códigos de dados configurados são adicionados com um arquivo externo para manter as instruções fáceis de ler.

Obter ajuda: Digite help na última linha em qualquer célula de código para rapidamente exibir os métodos de conveniência disponíveis no workbook.

Conclusão

O Xamarin Workbooks é atualmente a maneira mais rápida de aprender a desenvolver aplicativos móveis. Você pode aprender mais sobre as plataformas móveis nativas e explorar as APIs online. Também é fácil criar seus próprios workbooks personalizados para seu blog, curso de treinamento ou outra finalidade. O Workbooks pode incluir pacotes NuGet e pode referenciar namespaces adicionais, assim como todos os SDKs Android, iOS, macOS e WPF.

Visite developer.xamarin.com/workbooks para começar. O Xamarin está disponível gratuitamente como parte do Visual Studio Community Edition (e também no Mac), e o aplicativo Workbooks também é gratuito para baixar e usar.

Craig Dunn é gerente de programas para a documentação Xamarin na Microsoft. Encontre-o no Twitter: @conceptdev ou no LinkedIn em linkedin.com/in/conceptdev.

Agradecemos aos seguintes especialistas técnicos da Microsoft pela revisão deste artigo: Aaron Bockover e David Britch
David Britch trabalha no grupo de documentação Xamarin na Microsoft. Ele é autor de uma série de publicações sobre desenvolvimento de software incluindo livros, documentação de diretrizes, implementações de referência, whitepapers, vídeos e cursos de treinamento dirigidos por instrutores.

Aaron Bockover é chefe da equipe de inspeção da Xamarin Workbooks na Microsoft. Ele é um fã de .NET e Mono desde o lançamento do Mono e adora possibilitar que outras pessoas tirem o máximo de proveito das linguagens C# e .NET, assim como as inúmeras plataformas abordadas atualmente.