Creare applicazioni console con Spectre.Console

Come developer, spesso ci troviamo a interagire con il terminal e con le varie applicazioni pensate per essere sfruttate via CLI. Per alcuni è un piacere, per altri è un incubo, ma a qualsiasi categoria apparteniate, nessuno può sopportare applicazioni console che non abbiano un’interfaccia (grafica e funzionale) chiara. Se state pensando a git avete perfettamente capito ciò a cui mi riferisco…

In questo articolo scopriremo come creare applicazioni console che siano belle, funzionali e che si integrino perfettamente con tutto l’ecosistema dotnet.

Vi presento Spectre.Console!

Spectre.Console

Spectre.Console è un pacchetto NuGet che permette di creare delle vere e proprie applicazioni invocabili da terminale, complete di tutto ciò che possiate immaginare utile, chiavi in mano!

Questa libreria open source è formata da due progetti complementari fra loro:

– Spectre.Console che mette a disposizione tutta una serie di widgets (tabelle, alberi, grafici…) e di utilities per stilizzare l’aspetto grafico

– Spectre.Cli ovvero l’infrastruttura che permette di progettare l’esperienza di utilizzo complessiva dell’applicazione (args parsing e la loro specifica, alberatura dei comandi…). Questo scheletro è pensato anche per integrarsi con i vari framework di logging e di dependency injection, offrendo, quindi, la massima flessibilità.

Impariamo a conoscere questo progetto creando insieme una semplicissima applicazione di esempio.

(L’applicazione di esempio completa è disponibile a questo link).

Cosa andremo a costruire

Per iniziare a intravedere le potenzialità di Spectre.Console, costruiremo una semplice console application che mostri il meteo (si, lo so, poca fantasia) per una data località.

Scaffold

Creiamo una console application e installiamo un po’ di dipendenze:

dotnet new console -o SpectreExample.Weather

dotnet add package Spectre.Cli
dotnet add package Microsoft.Extensions.Hosting

Apriamo il .csproj e andiamo a modificarlo

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <!-- new project! why not? -->
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <WarningsAsErrors>nullable</WarningsAsErrors>
    <LangVersion>latest</LangVersion> 
  </PropertyGroup>

  <!-- ... -->

</Project>

Scheletro del primo Command

Il primo e più importante Command che andremo a scrivere è, appunto, quello che fornirà il meteo.

Creiamo un file Commands/ForecastCommand.cs

internal class ForecastCommand : AsyncCommand<ForecastCommand.Settings>
{
  public override async Task<int> ExecuteAsync(CommandContext context, Settings settings)
  {
    throw new NotImplementedException();
  }

  internal sealed class Settings : CommandSettings
  {
    public Settings(string location) => Location = location;

    [CommandArgument(0, "<location>")]
    [Description("The place where you want to know the forecast for")]
    public string Location { get; }
  }
}

Abbiamo definito un command con i suoi Settings. In generale, i parametri di un’applicazione console (prendiamo ad esempio dotnet new) sono di due tipi:

1. Options – ovvero parametri il cui valore è preceduto da un identificatore, ad esempio dotnet new –output [valore] oppure con uno shorthand dotnet new -o [valore]

2. Arguments – parametri che sono specificati senza identificatore, ad esempio dotnet new [valore]

Nel nostro ForecastCommand abbiamo definito un solo parametro di tipo Argument tramite l’attributo [CommandArgument(0, “<location>”)] che specifica:

– La posizione 0, ovvero è il primo Argument

– Il nome, ovvero ‘location’

– L’obbligatorietà, perché il nome è racchiuso fra ‘<>’

Abbiamo, inoltre, aggiunto una descrizione che comparirà nell’help della nostra applicazione.

Boilerplate

Per integrare Spectre.Cli con il ServicesContainer di Microsoft, è necessario scrivere un po’ di boilerplate.

Creiamo una cartella Infrastructure e aggiungiamoci

internal sealed class TypeResolver : ITypeResolver
{
  private readonly IServiceProvider _provider;

  public TypeResolver(IServiceProvider provider) => _provider = provider;

  public object? Resolve(Type? type)
  {
    if (type == null)
    {
      return null;
    }

    return _provider.GetService(type);
  }
}

internal sealed class TypeRegistrar : ITypeRegistrar
{
  private readonly IServiceCollection _provider;

  public TypeRegistrar(IServiceCollection provider) => _provider = provider;

  public ITypeResolver Build() => new TypeResolver(_provider.BuildServiceProvider());

  public void Register(Type service, Type implementation) =>
    _provider.AddSingleton(service, implementation);

  public void RegisterInstance(Type service, object implementation) =>
    _provider.AddSingleton(service, implementation);

  public void RegisterLazy(Type service, Func<object> factory) =>
    _provider.AddSingleton(service, _ => factory());
}

Vogliamo, inoltre, poterci interfacciare con il GenericHost sempre di Microsoft; creiamo, quindi, qualche extension method sempre in Infrastructure.

public static class HostingExtensions
{
  public static IServiceCollection AddSpectre<TDefaultCommand>(
    this IServiceCollection services,
    Action<IConfigurator>? configurator = null
  )
    where TDefaultCommand : class, ICommand
  {
    var app = new CommandApp<TDefaultCommand>(new TypeRegistrar(services));
    if (configurator != null)
    {
      app.Configure(configurator);
    }

    services.AddSingleton<ICommandApp>(app);

    return services;
  }

  public static async Task<int> RunSpectre(this IHost host, string[] args)
  {
    if (host is null)
    {
      throw new ArgumentNullException(nameof(host));
    }

    var app = host.Services.GetService<ICommandApp>();
    if (app == null)
    {
      throw new InvalidOperationException("Command application has not been configured.");
    }

    try
    {
      return await app.RunAsync(args);
    }
    catch (Exception ex)
    {
      AnsiConsole.WriteException(ex, ExceptionFormats.ShortenEverything);
      return -99;
    }
  }
}

Collegare i fili

Siamo ora pronti a scrivere il nostro Program.cs mettendo insieme i vari pezzi!

// Program.cs

var builder = Host.CreateDefaultBuilder();
builder.ConfigureLogging(
  (context, loggingBuilder) =>
  {
    // da non fare in un applicazione reale!
    // in questo esempio ci serve solo per disabilitare il logging in Console
    if (context.HostingEnvironment.IsProduction())
    {
      loggingBuilder.ClearProviders();
    }
  }
);

builder.ConfigureServices(
  (context, services) =>
  {
    services.AddSpectre<ForecastCommand>(
      config =>
      {
        config.SetApplicationName("wth");

        if (context.HostingEnvironment.IsDevelopment())
        {
          config.PropagateExceptions();
          config.ValidateExamples();
        }
      }
    );
  }
);

var host = builder.Build();

return await host.RunSpectre(args);

Lanciando l’applicazione con dotnet run — Firenze, Spectre eseguirà il ForecastCommand (al momento non implementato):

Error: The method or operation is not implemented.

Se non passiamo l’Argument ‘Firenze’, chiamando semplicemente dotnet run, otteniamo correttamente un errore:

Error: Missing required argument 'location'.

Spectre ha creato anche l’help per noi, invocabile con dotnet run — -h

USAGE:
    wth <location> [OPTIONS]

ARGUMENTS:
    <location>    The place where you want to know the forecast for

OPTIONS:
    -h, --help    Prints help information

Chiamare le Api per il meteo

Il meteo verrà fornito dal servizio OpenWeatherMap. Registratevi e create una Api key.

Tutto il codice necessario per chiamare queste Api lo trovate a questo link.

Dopodiché, aggiungete il pacchetto Refit:

dotnet add package Refit.HttpClientFactory

e aggiornate il Program.cs:

builder.ConfigureServices(
  (context, services) =>
  {
    services.AddRefitClient<IOpenWeatherApiClient>()
                .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.openweathermap.org/data/2.5"));

    // spectre stuff
  }
);

Implementare ForecastCommand

Iniziamo modificando ForecastCommand come segue:

internal class ForecastCommand : AsyncCommand<ForecastCommand.Settings>
{
  private static readonly TextInfo TextInfo = CultureInfo.CurrentCulture.TextInfo;
  private readonly IOpenWeatherApiClient _weatherApiClient;

  // dependency injection grazie al boilerplate scritto in precedenza
  public ForecastCommand(IOpenWeatherApiClient weatherApiClient)
  {
    _weatherApiClient = weatherApiClient;
  }

  public override async Task<int> ExecuteAsync(CommandContext context, Settings settings)
  {
    // chiamata alle API di OpenWeatherMap
    var response = await _weatherApiClient.GetWeatherForecastAsync("LA_VOSTRA_API_KEY", settings.Location);
    // le API ritornano una previsione ogni 3 ore per 5 giorni.
    // semplicemente ne prendiamo una sola occorennza per ogni giorno e ignoriamo quella per il giorno corrente
    var forecasts = OneWeatherForEachDay(response).Skip(1).OrderBy(x => x.Date);

    // questi 2 metodi sono quelli che andremo a implementare insieme
    var title = Title(response.City);
    var forecastPanels = forecasts.Select(CreateForecastPanel);

    // scrittura sulla console dei Widget creati in precedenza
    AnsiConsole.Write(title);
    AnsiConsole.WriteLine();
    // Columns è un helper per renderizzare una collezione di Widget in modo colonnare
    AnsiConsole.Write(new Columns(forecastPanels).Collapse());

    return 0;
  }

  private static Rule Title(City city)
  {
    throw new NotImplementedException();
  }

  private static Panel CreateForecastPanel(Forecast forecast)
  {
    throw new NotImplementedException();
  }

  private static IEnumerable<Forecast> OneWeatherForEachDay(WeatherForecastResponse res) =>
    res.List.GroupBy(x => x.Date.Date).Select(x => x.First());

  private static string WindDirection(int deg) => deg switch
  {
    > 0 and < 90    => "N/E",
    > 90 and < 180  => "S/E",
    > 180 and < 270 => "S/O",
    > 270           => "N/O",
    0               => "N",
    90              => "E",
    180             => "S",
    270             => "O",
    _               => throw new ArgumentOutOfRangeException(nameof(deg), deg, null)
  };

  internal sealed class Settings : CommandSettings
  {
    public Settings(string location)
    {
      Location = location;
    }

    [CommandArgument(0, "<location>")]
    [Description("The place where you want to know the forecast for")]
    public string Location { get; }
  }
}

Vediamo come sia attiva la Dependency Injection grazie al glue code scritto in precedenza. Vediamo anche Spectre.Console all’opera tramite la classe statica AnsiConsole usata per scrivere sulla console i Widgets che andiamo ad implementare.

Title widget

Vogliamo creare una cosiddetta Rule che mostri il titolo e la località per cui stiamo richiedendo il meteo.

Implementiamo il metodo Title():

private static Rule Title(City city)
{
  return new Rule($"[orange1 underline]Previsione a 5 giorni per [bold]{city.Name}, {city.Country}[/][/]")
          .RuleStyle("deepskyblue1")
          .LeftAligned();
}

Iniziamo creando una Rule e dandogli un titolo: usiamo una speciale sintassi per specificare lo stile di questo testo; in pratica, lo stile scritto fra parentesi quadre, ad esempio [orange1 underline], viene applicato fino a quando questo viene chiuso con [/].

Infine con un Api fluent, andiamo a specificare anche lo stile della Rule stessa, in questo caso il colore e la posizione del titolo all’interno della Rule.

ForecastPanel widget

Creiamo ora un Panel, che non è altro che un contenitore per altri Widgets.

Implementiamo il metodo CreateForecastPanel():

private static Panel CreateForecastPanel(Forecast forecast)
{
  var infoTable = CreateInfoTable(forecast);

  return new Panel(infoTable)
          .BorderColor(Color.Grey53)
          .Header($"[white underline bold]{TextInfo.ToTitleCase(forecast.Date.ToString("dddd dd"))}[/]")
          .HeaderAlignment(Justify.Center)
          .RoundedBorder();
}

In pratica stiamo creando un Panel a cui stiamo applicando:

– un contenuto, che in questo caso è un widget Table

– un header specificandone il testo, lo stile tramite la sintassi che abbiamo introdotto precedentemente e la sua posizione

– dei bordi stondati con relativo colore

Il contenuto informativo è, quindi, rappresentato da una tabella con una sola colonna:

private static Table CreateInfoTable(Forecast forecast)
{
  var infoTable = new Table()
                  .SimpleBorder()
                  .BorderColor(Color.Grey53)
                  .Collapse();
  
  infoTable.AddColumn($"[bold orange1]{TextInfo.ToTitleCase(forecast.Weather[0].Description)}[/]");
  
  infoTable.AddRow(
    $"Temperatura [red]{forecast.Main.Temp:F0}°C[/], Percepita [deepskyblue1]{forecast.Main.FeelsLike:F0}°C[/]"
  );
  infoTable.AddRow($"Probabilità di precipitazioni {forecast.PrecipitationProbability:p0}");
  infoTable.AddRow($"Nuvolosità {forecast.Clouds.All}%");
  infoTable.AddRow($"Pressione {forecast.Main.Pressure} hPa");
  infoTable.AddRow($"Umidità {forecast.Main.Humidity}%");
  infoTable.AddRow($"Vento {forecast.Wind.Speed} m/s, {WindDirection(forecast.Wind.Deg)}");

  return infoTable;
}

Anche in questo caso specifichiamo lo stile della tabella e poi la costruiamo in modo dichiarativo, usando anche qui la sintassi [] per lo stile del testo.

Aggiungere un secondo command

A questo punto la nostra applicazione console di esempio è completa e funzionante. Tuttavia, al momento, la vostra personale Api key di OpenWeatherMap è scritta in chiaro all’interno di ForecastCommand. Possiamo sfruttare questa “falla” per mostrare come aggiungere un ulteriore command all’applicazione.

Per prima cosa creiamo un servizio che si occupi di salvare la chiave su un file e, successivamente, di recuperarla.

internal static class ApiKeyService
{
    private static readonly string UserDirectory = Environment.GetFolderPath(
        Environment.SpecialFolder.UserProfile,
        Environment.SpecialFolderOption.DoNotVerify
    );

    private static readonly string SettingsFolder = Path.Join(UserDirectory, ".wth");

    // la chiave sarà salvata all'interno della cartella del vostro profilo utente nel file .wth/api_key.txt
    private static readonly string SettingsFilePath = Path.Join(SettingsFolder, "api_key.txt");

    public static Task SaveApiKey(string apiKey)
    {
        if (!Directory.Exists(SettingsFolder))
        {
            Directory.CreateDirectory(SettingsFolder);
        }

        return File.WriteAllTextAsync(SettingsFilePath, apiKey);
    }

    public static async Task<string?> GetApiKey()
    {
        try
        {
            return await File.ReadAllTextAsync(SettingsFilePath);
        }
        catch (DirectoryNotFoundException)
        {
            return null;
        }
    }
}

Questo servizio è banale e assolutamente non adatto per essere usato in un’applicazione reale, ma per il risultato che vogliamo ottenere è più che sufficiente.

Creiamo AddKeyCommand.cs sotto la cartella Commands, che non farà altro che prendere in input la chiave e chiamare il servizio di salvataggio su file:

internal class AddKeyCommand : AsyncCommand<AddKeyCommand.Settings>
{
    public override async Task<int> ExecuteAsync(CommandContext context, Settings settings)
    {
        await ApiKeyService.SaveApiKey(settings.ApiKey);
        return 0;
    }

    internal sealed class Settings : CommandSettings
    {
        public Settings(string apiKey)
        {
            ApiKey = apiKey;
        }

        [CommandArgument(0, "<ApiKey>")]
        [Description("Your OpenWeatherMap ApiKey")]
        public string ApiKey { get; }
    }
}

Registriamo il command nel Program.cs:

services.AddSpectre<ForecastCommand>(
  config =>
  {
    /*...*/

    config.AddCommand<AddKeyCommand>("add-key")
          .WithDescription("Save your personal OpenWeatherMap ApiKey");
  }
);

Richiamando l’help con dotnet run — -h, possiamo vedere come il nuovo command sia stato correttamente registrato:

USAGE:
    wth <location> [OPTIONS]
ARGUMENTS:
    <location>    The place where do you want to know the forecast                                                              
OPTIONS:
    -h, --help    Prints help information
COMMANDS:
    add-key <ApiKey>    Save your personal OpenWeatherMap ApiKey

ed è quindi possibile invocarlo con dotnet run — add-key “LA_VOSTRA_API_KEY”.

Salvata la vostra chiave, passiamo ad aggiornare ForecastCommand in modo che la recuperi dal file:

internal class ForecastCommand : AsyncCommand<ForecastCommand.Settings>
{
  /*...*/

  public override async Task<int> ExecuteAsync(CommandContext context, Settings settings)
  {
    var apiKey = await ApiKeyService.GetApiKey();
    if (apiKey is null)
    {
      AnsiConsole.MarkupLine(
        "[red][bold]No ApiKey configured![/] Please run the 'wth add-key <ApiKey>' command.[/]"
      );
      return -99;
    }

    var response = await _weatherApiClient.GetWeatherForecastAsync(apiKey, settings.Location);
    var forecasts = OneWeatherForEachDay(response).Skip(1).OrderBy(x => x.Date);

    var title = Title(response.City);
    var forecastPanels = forecasts.Select(CreateForecastPanel);

    AnsiConsole.Write(title);
    AnsiConsole.WriteLine();
    AnsiConsole.Write(new Columns(forecastPanels).Collapse());

    return 0;
  }

  /*...*/
}

Dotnet tool

Finora abbiamo invocato la nostra applicazione console tramite dotnet run perché eravamo in fase di sviluppo. Possiamo trasformare la nostra applicazione console in un dotnet tool che ci permetterà di:

– interagire con l’applicazione usando un nome custom, nel nostro esempio wth

– pacchettizzarla ed eventualmente distribuirla tramite NuGet

– installarla e quindi averla disponibile nelle nostre shell

Iniziamo con l’aggiungere queste poche direttive al .csproj:

<PropertyGroup>
  <PackAsTool>true</PackAsTool>
  <ToolCommandName>wth</ToolCommandName>
  <PackageOutputPath>./nupkg</PackageOutputPath>
</PropertyGroup>

e concludiamo creando il pacchetto con

dotnet pack -c Release

il cui risultato sarà il file ./nupkg/SpectreExample.Weather.1.0.0.nupkg.

In caso volessimo distribuire la nostra applicazione pubblicamente, la potremmo caricare su https://www.nuget.org e quindi sarebbe disponibile per essere installata usando il comando dotnet tool install. Per questo esempio, installeremo il tool direttamente dalla cartella locale ./nupkg senza bisogno di caricare niente su NuGet.

Installazione

dotnet tool install --global --add-source ./nupkg SpectreExample.Weather

Il parametro –global indica di installare la nostra applicazione come tool globale, ovvero lo aggiunge alla variabile di ambiente PATH.

Il parametro –add-source, invece, indica al CLI di dotnet di aggiungere temporaneamente la cartella ./nupkg come sorgente locale alla lista di quelle di NuGet.

L’output ci mostra sia il nome con cui possiamo invocare il tool (ovvero wth), sia la versione installata:

You can invoke the tool using the following command: wth

Tool 'spectreexample.weather' (version '1.0.0') was successfully installed.

Siamo finalmente pronti a usare la nostra applicazione meteo come una vera CLI application!

wth Londra

Conclusioni; potenzialità estetiche e di infrastruttura

Costruendo un esempio, abbiamo visto le potenzialità della libreria Spectre.Console sia in termini di widget e stile sia in termini di infrastruttura. La semplicità della sintassi per applicare lo stile, la quantità di widget disponibili, l’esperienza d’uso pensata nei minimi dettagli, ma soprattutto la completezza di tutte le funzionalità offerte dalla libreria ne fanno un coltellino svizzero da portare sempre nel nostro zaino da sviluppatori.

Cerchiamo di dare un po’ d’amore alle spesso bistrattate applicazioni console …e non provate mai a scrivere un tool con interfaccia ispirata a git!

Appendice: esempio di disinstallazione

Cancellate la cartella .wth presente nella cartella del vostro profilo ed eseguite

dotnet tool uninstall --global SpectreExample.Weather

Creare applicazioni console complesse (e belle) in C# con Spectre.Console

Categorie

Giuneco Tech