Documentações interativas com Try .NET


Acredito que, em algum momento, você já precisou criar um tutorial em C# para demonstrar algo para seu time ou até mesmo para que seus clientes entendessem os recursos do seu produto. Para esses casos, provavelmente, você escreveu as instruções e criou um projeto com o código em questão para conseguir repassar o conhecimento.

Escrever e executar um trecho de código diretamente no navegador já se tornou algo comum para algumas tecnologias do nosso dia a dia. Imagine, então, entender e descobrir o output de um código sem precisar colocar no seu projeto?

É aí que entra o Try .NET como uma maneira fácil de criar documentações com snippets que sejam possíveis de executar em nossas máquinas por meio de uma página da web ou de um arquivo markdown interativo.

Basicamente, criamos um markdown vinculado a um trecho de código em um projeto existente. O leitor do Try .NET pode então executar esse código de dentro do navegador.

Essa execução se dá com a utilização de ‘Blazor’ e ‘Web Assembly’ no client-side para projetos ‘.NET Core’.

 

Fato Interessante

O Try .NET é um projeto open source criado pela Microsoft e liderado pela Senior Program Manager Maria Naggaga! Vamos contribuir para a comunidade 🙂

 

Vamos lá

Para criar um projeto, você vai precisar:

  • .NET Core SDK;
  • dotnet try Global Tool;
  • editor de sua escolha. 🙂

Para instalar o Try .NET, execute o seguinte comando

dotnet tool install --global dotnet-try 

Obs.: Suporta o .NET Core 2.1 e 3.0!

Feito isso, podemos seguir por dois caminhos: começar do zero ou iniciar a partir de uma demo que o Try .NET disponibiliza.

Caso queira utilizar a demo, execute:

dotnet try demo

Neste post, vamos começar um projeto do zero para entendermos melhor como tudo funciona. Bora!?

 

Começando do zero

Vamos criar um Console Application simples:

dotnet new console -o {nomeDoProjeto}

Com o projeto criado, adicione um markdown ‘README.md’ com algum conteúdo, pois moldaremos nossa documentação mais à frente.

#Primeiros passos com Try .NET

 

Para visualizar o que acabamos de criar, execute o seguinte comando:

dotnet try

O código será compilado e o navegador será aberto com o nosso markdown renderizado.

 

Legal, tudo funcionando! Agora, alteraremos nosso ‘Program.cs’ para imprimir um texto.

using System;

namespace TryDotNet_FirstSteps
{
    class Program
    {
        static void Main(string[] args)
        {
            var twitter = "@LetticiaNicoli";
            Console.WriteLine($"Follow me: {twitter}!");
        }
    }
}

Se você rodar o ‘dotnet try’ novamente, o markdown estará igual ao da execução anterior! Então, como fazemos para que seja possível executar esse trecho de código no nosso README.md?

É bem simples: no nosso código, adicionaremos uma ‘#region’ para o código que queremos exibir e, consequentemente, possibilitar a edição:

#region FollowMeExample
    var twitter = "@LetticiaNicoli";
    Console.WriteLine($"Follow me: {twitter}!");
#endregion FollowMeExample

E no ‘README.md’ adicionamos um bloco vazio, conforme o padrão a seguir:

´´´cs --region {nomeDaRegion} --source-file {arquivoCS} --project {arquivoCSPROJ}

´´´

 

  • ‘cs’: informa para o renderer do markdown que o bloco é um código C#.
  • ‘region’: é por meio desse parâmetro que o Try .NET entende que todo o código contido na region deve ser renderizado no markdown.
  • ‘source-file’: informa qual arquivo contém a region.
  • ‘project’: informa que o projeto precisa ser compilado e executado.

Para nosso exemplo, temos:

´´´cs --region FollowMeExample --source-file .\Program.cs --project .\TryDotNet_FirstSteps.csproj
´´´

 

Um detalhe relevante é que podemos optar por passar apenas o parâmetro ‘cs’ e, dentro do bloco, inserir o código desejado.

´´´cs
Console.WriteLine($"Hello World"); 
´´´

 

Executaremos novamente o dotnet try!

Agora, conseguimos executar e alterar o trecho de código à vontade dentro do nosso markdown. Fala sério, isso é muito legal! Mas ainda pode melhorar: note que, quando editamos o código, temos IntelliSense, ctrl + space, autocomplete.

Se você realizar alguma alteração que faça com que o código deixe de compilar, conseguimos visualizar os erros de compilação com número da linha (baseado no código que você está visualizando no navegador, e não no arquivo .cs original).

Um ponto que vale ressaltar é que o Try .NET suporta packages. Adicione normalmente um package ao seu projeto e use em seu código. 

Trouxe dois exemplos:

 

Newtonsoft.Json

static void JsonExample()
{
    #region JsonExample
    var times = new { text = "Now", time = DateTime.Now };
    var json = JsonConvert.SerializeObject(times);

    Console.WriteLine(json);
    #endregion JsonExample
}

 

Serilog

static void SerilogExample()
{
    #region SerilogExample
    Log.Logger = new LoggerConfiguration()
                        .WriteTo.Console()
                        .CreateLogger();

    Log.Information("Ah, there you are!");
    #endregion SerilogExample
}

Obs.: não se esqueça de adicionar o bloco de código no README.md para conseguir visualizar!

Quando executarmos esses códigos no navegador, ele usará normalmente o package do ‘Newtonsoft.Json’ e do ‘Serilog’. Assim como dito anteriormente, aqui também temos IntelliSense completo no editor para esses pacotes.

 

Verifique se está tudo certo

O Try .NET disponibilizou, via linha de comando, um compilador para sua documentação, como um ‘linter’ que temos em algumas tecnologias.

dotnet try verify

Com esse comando, garantimos que cada snippet de código está funcionando conforme o esperado, pois ele detecta erros de markdown e compilação.

No exemplo a seguir, removi um ‘;’ do código.

Foi dado OK para o markdown, porém houve falha para a compilação.

Obs.: caso o comando anterior não funcione, tente ‘dotnet try verify .’ como workaround, pois uma issue foi aberta recentemente para que o verify não exija um diretório como argumento.

Deixarei alguns sites de referência que já estão utilizando o Try .NET.

Hoje você consegue iniciar um tutorial de C# pelo site da Microsoft sem precisar ter uma máquina configurada. Clique aqui para conferir!

Algumas documentações do .NET também já estão possibilitando a execução de código pelo navegador: um exemplo é o System.DateTime. Veja aqui!

O ‘Noda Time’ começou a colocar alguns snippets para validarmos! Como exemplo a seguir:

Se quiser conferir pelo site, clique aqui!

O projeto criado neste post está disponível no meu Github  🙂


Autor:

Microsoft MVP, Xamarin Certified Mobile Developer, MTAC e Organizadora do High5Devs. Adepta às boas práticas ágeis e novas tecnologias busca compartilhar seus conhecimentos na área para empoderar mais e mais pessoas.