ASP .NET Core

Utilizando o NHibernate em uma aplicação ASP.NET Core

Neste artigo falaremos sobre o NHibernate no ASP.NET Core.

Persistir informações é um requisito básico de quase todos os sistemas. Não importando o tamanho da aplicação, ela necessitará armazenar dados. Às vezes será necessário lidar com apenas um pequeno grupo de tabelas, em outros cenários será necessário trabalhar com um grande e complexo banco de dados.

Quanto mais complexo for o banco, mais robusta deve ser a camada de acesso da aplicação. Felizmente existem frameworks ORM que auxiliam neste processo. No .NET Core, duas soluções se destacam quando se trata de lidar com uma complexa base de dados: Entity Core e NHibernate.

Como já abordei o Entity Core aqui antes, hoje falarei do NHibernate.

NHibernate

O NHibernate é um porte para .NET do framework Hibernate do Java, que é uns dos mais antigos e respeitados ORMs. Assim como o framework que o originou, o NHibernate é um projeto open-source maduro e utilizado em uma infinidade de projetos, principalmente projetos corporativos.

Isso ocorre porque possui uma grande gama de recursos: suporte nativos a vários banco de dados, várias estratégias de geração de ID, cache de segundo nível, entre outras coisas. E por possuir muitos recursos, a sua configuração não é tão simples quando o Entity Core, mas fornece mais opções de customização.

Para conhecê-lo na prática, vamos a um exemplo de CRUD simples.

Criando a aplicação

Neste artigo criarei uma aplicação ASP.NET Core MVC:

dotnet new mvc -n AspNetCoreNHibernate

Nela, adicione o pacote do NHibernate:

dotnet add package NHibernate

Da biblioteca Fluent NHibernate:

dotnet add package FluentNHibernate

E o conector do SQLite (que será o banco deste exemplo):

dotnet add package System.Data.SQLite

Agora podemos começar a configuração do NHibernate.

Criando e mapeando a entidade

No NHibernate é necessário definir a entidade de domínio, uma classe POCO:

public class Product
{
    public virtual int Id { get; set; }
    public virtual string Name { get; set; }
    public virtual int Quantity { get; set; }
    public virtual double Price { get; set; }
}

É importante que todas as propriedades desta entidade sejam virtual.

Para que o NHibernate reconheça a entidade, é necessário mapeá-la. O padrão da biblioteca é um mapeamento por arquivo XML, mas graças ao FluentNHibernate, isso pode ser feito via código:

public class ProductMap: ClassMapping<Product>
{
    public ProductMap()
    {
        Id(x => x.Id, x =>
        {
            x.Generator(Generators.Increment);
            x.Type(NHibernateUtil.Int64);
            x.Column("Id");
        });

        Property(b => b.Name, x =>
        {
            x.Length(520);
            x.Type(NHibernateUtil.String);
            x.NotNullable(true);
        });

        Property(b => b.Quantity, x =>
        {
            x.Type(NHibernateUtil.Int32);
            x.NotNullable(true);
        });

        Property(b => b.Price, x =>
        {
            x.Type(NHibernateUtil.Double);
            x.Scale(2);
            x.Precision(15);
            x.NotNullable(true);
        });

        Table("Products");
    }
}

Com a classe mapeada, podemos registrar o NHibernate nos serviços da nossa aplicação.

Configurando o serviço do NHibernate

Seguindo o padrão do ASP.NET Core, criarei uma extensão para o nosso serviço:

public static class NHibernateExtensions
{
    public static IServiceCollection AddNHibernate(
        this IServiceCollection services, 
        string connectionString)
    {
        var mapper = new ModelMapper();
        mapper.AddMappings(typeof(NHibernateExtensions).Assembly.ExportedTypes);
        HbmMapping entityMapping = mapper.CompileMappingForAllExplicitlyAddedEntities();

        var configuration = new Configuration();
        configuration.DataBaseIntegration(c =>
        {
            c.Dialect<SQLiteDialect>();
            c.ConnectionString = connectionString;
            c.KeywordsAutoImport = Hbm2DDLKeyWords.AutoQuote;
            c.SchemaAction = SchemaAutoAction.Update;
            c.LogFormattedSql = true;
            c.LogSqlInConsole = true;
        });
        configuration.AddMapping(entityMapping);

        var sessionFactory = configuration.BuildSessionFactory();

        services.AddSingleton(sessionFactory);
        services.AddScoped(factory => sessionFactory.OpenSession());

        return services;
    }
}

Note que é indicado que as classes de domínio estão mapeadas em classes da aplicação. Também definimos as configurações de conexão e por fim, é criado a sessão.

C# (C Sharp) Avançado
Curso de C# (C Sharp) Avançado
CONHEÇA O CURSO

Esta sessão é adicionada no escopo, para que a conexão com o banco de dados não fique sempre “aberta”. O banco será acessado por um objeto sessão e ao adicioná-la no escopo, ele só será criado quando for utilizado.

Por fim é necessário chamar o método AddNHibernate em ConfigureServices da classe Startup:

public void ConfigureServices(IServiceCollection services)
{
    services.AddNHibernate(Configuration.GetConnectionString("SQLiteConnection"));
    services.AddControllersWithViews();
}

Com essas configurações já podemos acessar o banco de dados. Mas para este projeto criarei e implementarei o padrão repository.

Criando o repositório da aplicação

O nosso repositório será composto de uma interface:

public interface IRepository<T>
{
    Task Add(T item);
    Task Remove(long id);
    Task Update(T item);
    Task<T> FindByID(long id);
    IEnumerable<T> FindAll();
}

E sua implementação:

public class ProductRepository : IRepository<Product>
{
    private ISession _session;
    public ProductRepository(ISession session) => _session = session;
    public async Task Add(Product item)
    {
        ITransaction transaction = null;
        try
        {
            transaction = _session.BeginTransaction();
            await _session.SaveAsync(item);
            await transaction.CommitAsync();
        }
        catch(Exception ex)
        {
            Console.WriteLine(ex);
            await transaction?.RollbackAsync();
        }
        finally
        {
            transaction?.Dispose();
        }
    }

    public IEnumerable<Product> FindAll() => 
                    _session.Query<Product>().ToList();

    public async Task<Product> FindByID(long id) => 
                    await _session.GetAsync<Product>(id);

    public async Task Remove(long id)
    {
        ITransaction transaction = null;
        try
        {
            transaction = _session.BeginTransaction();
            var item = await _session.GetAsync<Product>(id);
            await _session.DeleteAsync(item);
            await transaction.CommitAsync();
        }
        catch(Exception ex)
        {
            Console.WriteLine(ex);
            await transaction?.RollbackAsync();
        }
        finally
        {
            transaction?.Dispose();
        }
    }

    public async Task Update(Product item)
    {
        ITransaction transaction = null;
        try
        {
            transaction = _session.BeginTransaction();
            await _session.UpdateAsync(item);
            await transaction.CommitAsync();
        }
        catch(Exception ex)
        {
            Console.WriteLine(ex);
            await transaction?.RollbackAsync();
        }
        finally
        {
            transaction?.Dispose();
        }
    }
}

Note que nas operações que realizam alterações no banco, é criada uma transação:

transaction = _session.BeginTransaction();
await _session.SaveAsync(item);
await transaction.CommitAsync();

Isso não é necessário, mas é recomendado que seja implementado. Assim, caso ocorra um erro durante a alteração, é possível voltar o banco para o estado anterior a transação:

await transaction?.RollbackAsync();

Para finalizarmos, é necessário criar o controller.

Criando controller da aplicação

O nosso controller será um controller CRUD padrão:

public class ProductController : Controller
{
    private readonly ProductRepository productRepository;

    public ProductController(NHibernate.ISession session) => 
                        productRepository = new ProductRepository(session);

    // GET: Products
    public ActionResult Index()
    {
        return View(productRepository.FindAll().ToList());
    }

    // GET: Products/Details/5
    public async Task<ActionResult> Details(long? id)
    {
        if (id == null)
        {
            return StatusCode(StatusCodes.Status404NotFound);
        }
        Product product = await productRepository.FindByID(id.Value);
        if (product == null)
        {
            return StatusCode(StatusCodes.Status404NotFound);
        }
        return View(product);
    }

    // GET: Products/Create
    public ActionResult Create()
    {
        return View();
    }

    // POST: Products/Create
    [HttpPost]
    [ValidateAntiForgeryToken]
    public async Task<ActionResult> Create(
                    [Bind("Id,Name,Quantity,Price")]
                    Product product)
    {
        if (ModelState.IsValid)
        {
            await productRepository.Add(product);
            return RedirectToAction("Index");
        }

        return View(product);
    }

    // GET: Products/Edit/5
    public async Task<ActionResult> Edit(long? id)
    {
        if (id == null)
        {
            return StatusCode(StatusCodes.Status400BadRequest);
        }
        Product product = await productRepository.FindByID(id.Value);
        if (product == null)
        {
            return StatusCode(StatusCodes.Status404NotFound);
        }
        return View(product);
    }

    // POST: Products/Edit/5
    [HttpPost]
    [ValidateAntiForgeryToken]
    public async Task<ActionResult> Edit(
                [Bind("Id,Name,Quantity,Price")]
                Product product)
    {
        if (ModelState.IsValid)
        {
            await productRepository.Update(product);
            return RedirectToAction("Index");
        }
        return View(product);
    }

    // GET: Products/Delete/5
    public async Task<ActionResult> Delete(long? id)
    {
        if (id == null)
        {
            return StatusCode(StatusCodes.Status400BadRequest);
        }
        Product product = await productRepository.FindByID(id.Value);
        if (product == null)
        {
            return StatusCode(StatusCodes.Status404NotFound);
        }
        return View(product);
    }

    // POST: Products/Delete/5
    [HttpPost, ActionName("Delete")]
    [ValidateAntiForgeryToken]
    public async Task<ActionResult> DeleteConfirmed(long id)
    {
        await productRepository.Remove(id);
        return RedirectToAction("Index");
    }
}

Antes de ver o sistema funcionando é necessário criar as views para as actions acima. Você pode vê-la no repositório do projeto.

Com isso, ao executá-lo, veremos que está tudo certo:

Página index mostrando a listagem de produtos

Conclusão

O NHibernate é uma ótima solução para aplicações que precisam lidar com bancos de dados complexos ou que não sejam suportado pelo Entity Core. Com vários anos de estrada é um framework popular e estável, que pode ser utilizado em qualquer projeto sem medo.

Então quando for criar o seu projeto, não deixe de dar uma olhada neste framework.

Você pode ver o código completo do projeto no meu Github.

O que é o ASP.NET Core?

O ASP.NET Core é uma versão do ASP.NET para a plataforma .NET Core. Só que antes de conhecê-lo precisamos voltar um pouco no tempo.

Em 2002, no lançamento da versão 1.0 do .NET Framework, a Microsoft lançou com esta plataforma o ASP.NET, como um sucessor da tecnologia ASP ( Active Server Pages).

Por se tratar de uma extensão do .NET Framework, assim como ele, no início o ASP.NET possuía poucos recursos. Suportava todas as linguagens de programação compatíveis com a plataforma .NET, mas ainda era muito limitado.

Amazon Web Services (AWS) - RDS - Fundamentos
Curso de Amazon Web Services (AWS) - RDS - Fundamentos
CONHEÇA O CURSO

Replicando o desenvolvimento Desktop na web

No seu lançamento, o ASP.NET trouxe o modelo de aplicação Web Forms (ASP.NET Web Forms), cujo objetivo era replicar o desenvolvimento Desktop em uma aplicação web.

Em 2002, o desenvolvimento Desktop possuía ferramentas como Delphi e Visual Basic, que permitiam que uma tela fosse criada com o arrastar de controles. Desta forma, o desenvolvedor não precisava se preocupar com a codificação dos componentes da interface, apenas com a lógica de negócios.

Replicando isso na web, o ASP.NET Web Forms permitia que os desenvolvedores criassem interfaces web arrastando componentes. O ASP.NET se encarregaria de criar o HTML, CSS e JavaScript da página, e o desenvolvedor poderia focar na lógica de negócio da aplicação.

Olhando em retrospecto, na época esta foi uma boa solução, pois ajudou os desenvolvedores Desktop migrarem para o desenvolvimento web. Entretanto, o HTML gerado pelo ASP.NET tinha pouca legibilidade, hoje seria considerado um código muito poluído, por isso ao logo do tempo o Web Forms entrou em desuso e hoje está descontinuado.

Padrões de projetos vem ao resgate

Para melhorar a qualidade das aplicações ASP.NET, em 2009 foi lançado o modelo de aplicação MVC (ASP.NET MVC), cujo objetivo era aplicar o padrão de projetos MVC. Neste tipo de aplicação, os componentes são separados em três camadas lógicas:

  • Model (camada de negócio);
  • View (camada de apresentação);
  • Controller (camada de controle).

Um model representa o estado de um aspeto particular da aplicação. O controller lida com as interações e alterações do model para refletir o estado da aplicação e passa essas informações para a view. A view recebe as informações do controller e as exibe para o usuário.

Não possuindo mais o recurso de arrastar componentes para criar as páginas, mas isoladas na camada view, o ASP.NET MVC permitia que um desenvolvedor front-end pudesse focar na criação das páginas, enquanto outro lidasse com a lógica de negócio das camadas model e controller.

A constante busca pela evolução

Buscando uma evolução constante, ao longo do tempo foram lançados vários recursos ao ASP.NET, como: Web API, que permite criar APIs; Razor, uma template engine; ASP.NET AJAX, que facilita a adição de Ajax em aplicações ASP.NET; entre outros.

Nesta procura por evolução, a Microsoft notou que a comunidade poderia ajudá-la, assim, em 2012 decidiu abrir o código fonte do ASP.NET (entre outros produtos). E trabalhando em conjunto com a comunidade nas atualizações do ASP.NET, notou que a plataforma necessitava de muitas modificações que não poderiam ser aplicadas na versão existente, assim nasceu o ASP.NET Core.

C# (C Sharp) Intermediário
Curso de C# (C Sharp) Intermediário
CONHEÇA O CURSO

Então surge o ASP.NET Core

Sucessor do ASP.NET, o ASP.NET Core é um framework open-source, multiplataforma, criado pela Microsoft e a comunidade. Leve, rápido e modular, funciona em conjunto com o .NET Core.

Lançado em 2016, mesmo sendo um sucessor do ASP.NET, o ASP.NET Core foi criado totalmente do zero, para que não precisasse se preocupar com código legado permitindo assim seguir o padrão de desenvolvimento web moderno.

Assim como outras plataformas, o ASP.NET Core é totalmente modular, recursos podem ser adicionados via pacotes Nuget. O que permitiu que a plataforma fosse mais performática que seu antecessor. Além disso, não necessita de uma IDE específica, todo desenvolvimento pode ser feito via linha de comando. O que permite que uma aplicação criada em uma plataforma possa ser movida para outra, sem a perda de nenhum recurso ou funcionalidade.

Devido a todo seu poder, caso necessite criar uma aplicação web, não deixe de dar uma olhada no ASP.NET Core.

Mediator Pattern com MediatR no ASP.NET Core

Para facilitar o desenvolvimento, a manutenção e manter o código limpo e legível, grandes aplicações procuram seguir princípios SOLID, padrões de projetos e outras recomendações de boas práticas, como a desacoplação dos objetos. Neste grupo de recomendações, vem ganhando espaço a adoção do Mediator Pattern, que no ASP.NET pode ser facilmente implementado com a biblioteca MediatR, como veremos neste artigo.

C# (C Sharp) - Introdução ao ASP.NET Core
Curso de C# (C Sharp) - Introdução ao ASP.NET Core
CONHEÇA O CURSO

O que é Mediator Pattern?

Mediator é um padrão de projetos comportamental especificado pela GoF, que na sua definição formal é descrito como:

Um objeto que encapsula a forma como um conjunto de objetos interage. O Mediator promove o acoplamento fraco ao evitar que os objetos se refiram uns aos outros explicitamente e permite variar suas interações independentemente.

Em outras palavras podemos dizer que o Mediator Pattern gerencia as interações de diferentes objetos. Através de uma classe mediadora, centraliza todas as interações entre os objetos, visando diminuir o acoplamento e a dependência entre eles. Desta forma, neste padrão, os objetos não conversam diretamente entre eles, toda comunicação precisa passar pela classe mediadora.

Podemos ilustrar seu funcionamento com a imagem abaixo:

Representação Gráfica do Mediator Pattern. Há setas apontando e saindo do objeto Mediator para representar a comunicação.

Se um objeto, por exemplo, Objeto A, quiser se comunicar com outro, Objeto C, terá que passar pelo Mediator. Com isso, cada objeto pode focar apenas na sua responsabilidade e não precisa conhecer a estrutura do outro para realizar a comunicação. Se Objeto C for modificado, Objeto A não precisa tomar conhecimento disso, ou seja, cada objeto trabalha de forma independente e isolada.

Entretanto, se houver um grande fluxo de comunicação entre os objetos, o objeto mediador pode se tornar um gargalo para a aplicação. Para resolver isso, a solução comum é implementar o CQRS (Command Query Responsibility Segregation), em tradução livre, Segregação de Responsabilidade de Comando e Consulta.

CQRS vem ao resgate

O Command Query Responsibility Segregation, ou CQRS, é um padrão de projeto que separa as operações de leitura e escrita da base de dados em dois modelos: queries e commands. Os commands são responsáveis pelas ações que realizam alguma alteração na base de dados. Geralmente operações assíncronas que não retornam nenhum dado.

Já as queries são responsáveis pelas consultas, retornando objetos DTOs (Data Transfer Object) para que seja isolada do domínio.

Por gerarem o maior fluxo de informações da aplicação, as consultas podem ser otimizadas através de um serviço específico, como um servidor de cache. Do lado dos commands, o Mediator pode ser utilizado para gerenciar a comunicação dos objetos.

É por causa disso que a biblioteca MediatR implementa conceitos do CQRS, porém não vou me aprofundar nele, já que não é objetivo desse artigo.

O MediatR entra em cena

O MediatR é uma biblioteca open source criada por Jimmy Bogard, o mesmo criador da biblioteca AutoMapper. O seu objetivo é facilitar a implementação do Mediator Pattern em aplicações .NET. Com ela não precisamos nos preocupar com a criação da classe mediadora, pois já são fornecidas interfaces que facilitam a implementação do fluxo de comunicação entre os objetos.

Colocando a mão na massa

Agora que conhecemos os conceitos por trás da biblioteca MediatR, vamos para um exemplo de implementação em um projeto. Será o projeto de uma API simples com um CRUD de pessoas.

A primeira coisa a ser feita é a criação do projeto:

dotnet new webapi -n MediatRSample

Em seguida, iremos adicionar a biblioteca:

dotnet add package MediatR

Para uma aplicação ASP.NET Core, também é necessário instalar o pacote de injeção de dependência:

dotnet add package MediatR.Extensions.Microsoft.DependencyInjection

Com o projeto criado e as dependências adicionadas, vamos adicionar algumas pastas nele, para que o nosso código fique mais organizado. O projeto ficará com a seguinte estrutura:

Onde dentro da pasta Application, temos as pastas:

  • Commands: Onde serão definidos os objetos DTOs que representam uma ação a ser executada;
  • EventHandlers: Onde serão definidos objetos responsáveis por receber uma notificação gerada pelos Handlers;
  • Handlers: Onde serão definidos objetos responsáveis por receber as ações definidas pelos Commands;
  • Models: Onde serão definidas as entidades utilizadas pela aplicação;
  • Notifications: Onde serão definidos os objetos DTOs que representam notificações.

    Vamos implementar as classes dessas pastas.

C# (C Sharp) - ASP.NET MVC
Curso de C# (C Sharp) - ASP.NET MVC
CONHEÇA O CURSO

Especificando a classe domínio e o repositório da aplicação

Antes de implementar os objetos que farão uso da biblioteca MediatR, é necessário especificar a nossa classe de domínio, o model Pessoa:

public class Pessoa
{
    public int Id { get; set; }
    public string Nome { get; set; }
    public int Idade { get; set; }
    public char Sexo { get; set; }
}

Esta classe contém todas as propriedades que necessitamos para representar um objeto pessoa na nossa aplicação. Os commands que iremos definir serão baseados nela.

Por se tratar de um exemplo simples, esta aplicação não fará uso de um banco de dados, mas possuirá uma interface IRepository:

public interface IRepository<T>
{
    Task<IEnumerable<T>> GetAll();

    Task<T> Get(int id);

    Task Add(T item);

    Task Edit(T item);

    Task Delete(int id);
}

E uma classe repositório que salva os dados em uma coleção estática:

public class PessoaRepository : IRepository<Pessoa>
{
    private static Dictionary<int, Pessoa> pessoas = new Dictionary<int, Pessoa>();

    public async Task<IEnumerable<Pessoa>> GetAll(){
        return await Task.Run(() => pessoas.Values.ToList());
    }

    public async Task<Pessoa> Get(int id){
        return await Task.Run(() => pessoas.GetValueOrDefault(id));
    }

    public async Task Add(Pessoa pessoa){
        await Task.Run(() => pessoas.Add(pessoa.Id, pessoa));
    }

    public async Task Edit(Pessoa pessoa){
        await Task.Run(() =>
        {
            pessoas.Remove(pessoa.Id);
            pessoas.Add(pessoa.Id, pessoa);
        });
    }

    public async Task Delete(int id){
        await Task.Run(() => pessoas.Remove(id));
    }
}

Implementando o padrão Command

Para gerenciar as interações dos objetos, a biblioteca MediatR implementa o padrão Command. Este padrão específica um objeto que encapsula toda informação necessária para executar uma ação posterior.

É neste ponto que a biblioteca faz uso do CQRS, como explicado anteriormente. Como vimos, no CQRS as operações são separadas em queries e commands. A parte dos commands é uma aplicação do padrão Command, que na implementação do MediatR é composta de dois objetos: Command e Command Handler.

Os objetos Command definem solicitações que irão alterar o estado dos dados e que o sistema precisa realizar. Por ser imperativo e se tratar de uma ação que será executada apenas uma vez (por solicitação) é recomendado que esses objetos sejam nomeados com o verbo no imperativo: “cadastra”, “altera”, etc. Também se recomenda a adição de um tipo, e.g., CadastraPessoaCommand, AlteraPessoaCommand, etc.

Já os objetos Command Handler serão responsáveis por executar as ações definidas pelos objetos Command. É aqui que ficará centralizado grande parte da lógica da aplicação.

Vamos iniciar a nossa implementação deste padrão definindo as classes Command:

public class CadastraPessoaCommand : IRequest<string>
{
    public string Nome { get; set; }
    public int Idade { get; set; }
    public char Sexo { get; set; }
}
public class AlteraPessoaCommand : IRequest<string>
{
    public int Id { get; set; }
    public string Nome { get; set; }
    public int Idade { get; set; }
    public char Sexo { get; set; }
}
public class ExcluiPessoaCommand : IRequest<string>
{
    public int Id { get; set; }
}

Note que essas são classes POCO simples, que contém apenas os atributos necessários para executar a ação especificada. Todas implementam a interface IRequest da biblioteca MediatR.

Nesta interface genérica se especifica o tipo de dado que será retornado quando o command for processado. Também é atráves do uso desta interface que será possível vincular os commands com as classes Command Handlers. É desta forma que a biblioteca saberá qual objeto deve ser invocado quando uma solicitação for gerada.

As boas práticas recomendam que para cada objeto Command haja um objeto Command Handler, entretanto seria possível implementar um objeto Command Handler para lidar com todos os commands definidos na aplicação.

Para este exemplo vou seguir as boas práticas, então a aplicação conterá as três classes abaixo:

public class CadastraPessoaCommandHandler : IRequestHandler<CadastraPessoaCommand, string>
{
    private readonly IMediator _mediator;
    private readonly IRepository<Pessoa> _repository;
    public CadastraPessoaCommandHandler(IMediator mediator, IRepository<Pessoa> repository)
    {
        this._mediator = mediator;
        this._repository = repository;
    }

    public async Task<string> Handle(CadastraPessoaCommand request, CancellationToken cancellationToken)
    {
        var pessoa = new Pessoa { Nome = request.Nome, Idade = request.Idade, Sexo = request.Sexo };

        try {
            pessoa = await _repository.Add(pessoa);

            await _mediator.Publish(new PessoaCriadaNotification { Id = pessoa.Id, Nome = pessoa.Nome, Idade = pessoa.Idade, Sexo = pessoa.Sexo});

            return await Task.FromResult("Pessoa criada com sucesso");
        } catch(Exception ex) {
            await _mediator.Publish(new PessoaCriadaNotification { Id = pessoa.Id, Nome = pessoa.Nome, Idade = pessoa.Idade, Sexo = pessoa.Sexo });
            await _mediator.Publish(new ErroNotification { Excecao = ex.Message, PilhaErro = ex.StackTrace });
            return await Task.FromResult("Ocorreu um erro no momento da criação");
        }

    }
}
public class AlteraPessoaCommandHandler : IRequestHandler<AlteraPessoaCommand, string>
{
    private readonly IMediator _mediator;
    private readonly IRepository<Pessoa> _repository;
    public AlteraPessoaCommandHandler(IMediator mediator, IRepository<Pessoa> repository)
    {
        this._mediator = mediator;
        this._repository = repository;
    }

    public async Task<string> Handle(AlteraPessoaCommand request, CancellationToken cancellationToken)
    {
        var pessoa = new Pessoa { Id = request.Id, Nome = request.Nome, Idade = request.Idade, Sexo = request.Sexo };

        try {
            await _repository.Edit(pessoa);

            await _mediator.Publish(new PessoaAlteradaNotification { Id = pessoa.Id, Nome = pessoa.Nome, Idade = pessoa.Idade, Sexo = pessoa.Sexo, IsEfetivado = true});

            return await Task.FromResult("Pessoa alterada com sucesso");
        } catch(Exception ex) {
            await _mediator.Publish(new PessoaAlteradaNotification { Id = pessoa.Id, Nome = pessoa.Nome, Idade = pessoa.Idade, Sexo = pessoa.Sexo, IsEfetivado = false});
            await _mediator.Publish(new ErroNotification { Excecao = ex.Message, PilhaErro = ex.StackTrace });
            return await Task.FromResult("Ocorreu um erro no momento da alteração");
        }

    }
}
namespace MediatRSample.Application.Handlers
{
    public class ExcluiPessoaCommandHandler : IRequestHandler<ExcluiPessoaCommand, string>
    {
        private readonly IMediator _mediator;
        private readonly IRepository<Pessoa> _repository;
        public ExcluiPessoaCommandHandler(IMediator mediator, IRepository<Pessoa> repository)
        {
            this._mediator = mediator;
            this._repository = repository;
        }

        public async Task<string> Handle(ExcluiPessoaCommand request, CancellationToken cancellationToken)
        {
            try {
                await _repository.Delete(request.Id);

                await _mediator.Publish(new PessoaExcluidaNotification { Id = request.Id, IsEfetivado = true});

                return await Task.FromResult("Pessoa excluída com sucesso");
            } catch(Exception ex) {
                await _mediator.Publish(new PessoaExcluidaNotification { Id = request.Id, IsEfetivado = false });
                await _mediator.Publish(new ErroNotification { Excecao = ex.Message, PilhaErro = ex.StackTrace });
                return await Task.FromResult("Ocorreu um erro no momento da exclusão");
            }

        }
    }
}

Note que todos os command handlers implementam a interface IRequestHandler, nesta interface é especificado uma classe command e o tipo de retorno. Quando esta classe command gerar uma solicitação, o MediatR irá invocar o command handler, chamando o método Handler.

É no método Handler que definimos as instruções que devem ser realizadas para aplicar a solicitação definida pelo command.

Após a solicitação ser atendida, é possível utilizar o método Publish() para emitir uma notificação para todo sistema. Onde o MediatR irá procurar por uma a classe que tenha implementado a interface INotificationHandler<tipo da notificacao> e invocar o método Handler() para processar aquela notificação, como veremos a seguir.

Implementando notificações

Na sua essência as solicitações command não retornam nenhuma informação, assim para ser informado que a solicitação foi finalizada com sucesso, ou não, pode ser implementada notificações.

Como vimos no tópico anterior, no método Handler de uma classe Command Handler, pode ser invocado o método Publish(), passando por parâmetro um objeto notificação. Todos os Event Handlers que estiverem “ouvindo” notificações do tipo do objeto “publicado” serão notificados e poderão processá-lo.

Assim, para implementar as notificações inicialmente é necessário definir os objetos notificação:

public class PessoaCriadaNotification : INotification
{
    public int Id { get; set; }
    public string Nome { get; set; }
    public int Idade { get; set; }
    public char Sexo { get; set; }
}
public class PessoaAlteradaNotification : INotification
{
    public int Id { get; set; }
    public string Nome { get; set; }
    public int Idade { get; set; }
    public char Sexo { get; set; }
    public bool IsEfetivado { get; set; }
}
public class PessoaExcluidaNotification : INotification
{
    public int Id { get; set; }
    public bool IsEfetivado { get; set; }
}
public class ErroNotification : INotification
{
    public string Excecao { get; set; }
    public string PilhaErro { get; set; }
}

Como as classes Commands, as notificações são classes POCO que contêm apenas os dados necessários para processar a informação. Para que a biblioteca reconheça o objeto dessas classes como uma notificação é importante que elas implementem a interface INotification.

Já a nossa classe Notification Handler irá “escutar” todas as notificações, pois todas serão apenas registradas no console:

public class LogEventHandler :
                            INotificationHandler<PessoaCriadaNotification>,
                            INotificationHandler<PessoaAlteradaNotification>,
                            INotificationHandler<PessoaExcluidaNotification>,
                            INotificationHandler<ErroNotification>
{
    public Task Handle(PessoaCriadaNotification notification, CancellationToken cancellationToken)
    {
        return Task.Run(() =>
        {
            Console.WriteLine($"CRIACAO: '{notification.Id} - {notification.Nome} - {notification.Idade} - {notification.Sexo}'");
        });
    }

    public Task Handle(PessoaAlteradaNotification notification, CancellationToken cancellationToken)
    {
        return Task.Run(() =>
        {
            Console.WriteLine($"ALTERACAO: '{notification.Id} - {notification.Nome} - {notification.Idade} - {notification.Sexo} - {notification.IsEfetivado}'");
        });
    }

    public Task Handle(PessoaExcluidaNotification notification, CancellationToken cancellationToken)
    {
        return Task.Run(() =>
        {
            Console.WriteLine($"EXCLUSAO: '{notification.Id} - {notification.IsEfetivado}'");
        });
    }

    public Task Handle(ErroNotification notification, CancellationToken cancellationToken)
    {
        return Task.Run(() =>
        {
            Console.WriteLine($"ERRO: '{notification.Excecao} \n {notification.PilhaErro}'");
        });
    }
}

A aplicação poderia definir quantas classes Notification Handlers forem necessárias. Por exemplo, além da classe acima poderia haver uma classe que enviaria um e-mail para o usuário informando que uma pessoa foi cadastrada. Outra que avisaria a equipe de suporte que um erro foi gerado.

Caso uma notificação seja “ouvida” por mais de um Notification Handlers, todos serão invocados quando a notificação for gerada.

Controller e configuração MediatR

Agora que os objetos do MediatR estão criados, podemos definir o nosso controller:

[ApiController]
[Route("[controller]")]
public class PessoaController : ControllerBase
{

    private readonly IMediator _mediator;
    private readonly IRepository<Pessoa> _repository;

    public PessoaController(IMediator mediator, IRepository<Pessoa> repository)
    {
        this._mediator = mediator;
        this._repository = repository;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        return Ok(await _repository.GetAll());
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> Get(int id)
    {
        return Ok(await _repository.Get(id));
    }

    [HttpPost]
    public async Task<IActionResult> Post(CadastraPessoaCommand command)
    {
        var response = await _mediator.Send(command);
        return Ok(response);
    }

    [HttpPut]
    public async Task<IActionResult> Put(AlteraPessoaCommand command)
    {
        var response = await _mediator.Send(command);
        return Ok(response);
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> Delete(int id)
    {
        var obj = new ExcluiPessoaCommand { Id = id };
        var result = await _mediator.Send(obj);
        return Ok(result);
    }
}

Note que neste controller estamos “injetando” a interface IMediator, isso foi feito para que seja possível enviar as solicitações dos nossos objetos command com o método Send que esta interface disponibiliza:

var response = await _mediator.Send(command);

Neste contexto, o IMediator será a classe mediadora que através do método Send chama os command handlers que definimos, com base no objeto passado.

Por fim, é necessário adicionar o MediatR como serviço da nossa aplicação no método ConfigureServices da classe Startup:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddMediatR(typeof(Startup));
    services.AddSingleton<IRepository<Pessoa>, PessoaRepository>();
}

Também repare que estamos registrando a nossa classe repositório para que ela seja “injetada” no nosso controller e nas classes Command Handlers.

E a mágica acontece

Com a nossa aplicação definida, podemos iniciá-la e testar os endpoints. Note que ao executar uma solicitação:

Tela no Postman, mostrando o exemplo de uma requisição POST para o endpoint "https://localhost:5001/pessoa"

Ela será registrada no console:

Print do terminal do Visual Studio Code mostrando o texto: "CRIACAO: '1 - Carlos - 21 - M'"

Todas as solicitações que realizam alguma alteração nos dados serão registradas:

Print do terminal do Visual Studio Code mostrando logs do endpoint

Você pode ver o código completo da aplicação no repositório dela no meu Github.

C# (C Sharp) - APIs REST com ASP.NET Web API
Curso de C# (C Sharp) - APIs REST com ASP.NET Web API
CONHEÇA O CURSO

No episódio de hoje aprendemos…

Mesmo com o exemplo simples demonstrado neste artigo, é possível notar que o Mediator Pattern nos ajuda a manter os objetos do sistema totalmente isolados e independentes, cada um possuindo apenas a sua responsabilidade.

Com a biblioteca MediatR a implementação deste padrão em uma aplicação ASP.NET Core é facilitada. Mas é importante frisar que este o Mediator não deve ser utilizado em qualquer projeto, dependendo do caso, a “sobrecarga ” necessária para implementá-lo não compensará os benefícios que fornece.

Então como He-Man diria, utilize com sabedoria.

Publicando uma aplicação ASP.NET Core no Heroku

No desenvolvimento de uma aplicação web pode ser necessário a sua publicação para testes, ou mesmo, para apresentar algo para um futuro usuário. Durante os estudos, também é muito comum o desejo de publicar a aplicação web que está sendo criada.

Por não ser algo definitivo, o desenvolvedor pode não desejar (ou não poder) pagar por uma hospedagem para publicar a aplicação web que está desenvolvendo. Infelizmente não existem muitas opções de hospedagem gratuita. Dos que existem, sempre há alguma limitação.

Um dos serviços que mais se destacam neste requisito é o Heroku.

Google Cloud - App Engine
Curso de Google Cloud - App Engine
CONHEÇA O CURSO

Heroku

O Heroku é uma platform as a service (PaaS) que permite que desenvolvedores criem, executem e publiquem aplicações na nuvem, sendo que a sua versão mais básica é grátis. Mesmo nesta versão, ele fornece uma URL, o que permite testar a aplicação sem necessitar de um domínio.

Entretanto, nativamente o Heroku fornece suporte apenas as linguagens JavaScript (via Node), Ruby, Java, PHP, Python, Go, Scala e Clojure. É possível executar outras linguagens via Buildpacks, que são scripts criados pela comunidade.

Contudo, esses buildpacks podem possuir limitações que impedem o seu uso na sua aplicação. Algo simples, para uma linguagem nativa, como a publicação de uma aplicação Django, pode ser complexo com o uso de um buildpack criado pela comunidade.

Felizmente, o Heroku também permite a publicação de uma imagem Docker, o que elimina praticamente todos os limites que um buildpack possa ter.

Assim, por não fornecer suporte nativo ao ASP.NET Core, neste artigo veremos como publicar este tipo de aplicação na plataforma via container do Docker.

Preparando a casa

Para acompanhar este artigo é importante que tenha o Docker instalado na sua máquina. Há versões dele para todos os sistemas operacionais. Também é importante que tenha uma conta no Heroku e o seu utilitário de linha comando configurado na máquina. O Fagner (instrutor aqui da Treinaweb) explicou como isso pode ser feito no seu artigo sobre a publicação de uma aplicação Django.

Por fim, mas não menos importante, a aplicação utilizada neste artigo será a API a criada com o framework Carter que mostrei anteriormente.

PHP - Testes unitários com PHPUnit
Curso de PHP - Testes unitários com PHPUnit
CONHEÇA O CURSO

Containeralizando” a aplicação ASP.NET Core

A primeira coisa que temos que fazer na aplicação é adicioná-la a um container Docker, para isso, deve ser adicionado ao projeto o arquivo Dockerfile. Será neste arquivo que definiremos como o nosso container será criado.

Também é recomendado que seja criado na aplicação um arquivo .dockerignore. Assim como o .gitignore, neste arquivo são definidos diretórios e arquivos que o docker deve ignorar. Para esta aplicação, o conteúdo do .dockerignore será:

**/.dockerignore
**/.git
**/.gitignore
**/.vs
**/.vscode
**/*.*proj.user
**/bin
**/obj

Já o Dockerfile conterá:

FROM mcr.microsoft.com/dotnet/core/aspnet:3.1 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/core/sdk:3.1 AS build
WORKDIR /src
COPY . .
RUN dotnet restore 
RUN dotnet build --no-restore -c Release -o /app

FROM build AS publish
RUN dotnet publish --no-restore -c Release -o /app

FROM base AS final
WORKDIR /app
COPY --from=publish /app .
# Padrão de container ASP.NET
# ENTRYPOINT ["dotnet", "CarterAPI.dll"]
# Opção utilizada pelo Heroku
CMD ASPNETCORE_URLS=http://*:$PORT dotnet CarterAPI.dll

Um arquivo Dockerfile é como um script. Este em questão implementa multi-stage, o que significa que é definido um passo para cada processo definido no script. Assim, se um passo falhar, não é necessário refazer os passos que já foram concluídos.

Acima, inicialmente se obtém a imagem de runtime do ASP.NET Core, na imagem do SDK as bibliotecas da aplicação são obtidas e ela é compilada. Caso não ocorra nenhum erro, a aplicação é publicada e por fim, ela é iniciada.

Geralmente quando uma aplicação ASP.NET Core é adicionada em um container, ela é iniciada com o comando:

ENTRYPOINT ["dotnet", "CarterAPI.dll"]

Mas o Heroku recomenda que a aplicação seja iniciada com o comando:

CMD ASPNETCORE_URLS=http://*:$PORT dotnet CarterAPI.dll

Isso ocorre porque o processo web do Heroku “escuta” as requisições HTTP na porta $PORT, que não necessariamente é a porta 80. A porta que ele utilizará é atribuído a variável de ambiente $PORT, assim antes de iniciar a aplicação, a porta utilizada pela aplicação é alterada para ser a mesma esperada pelo Heroku.

Agora está tudo pronto e podemos criar uma imagem da nossa aplicação. Para isso, utilizamos o comando abaixo:

docker build -t carter-api .

Lembrando que este comando deve ser executado pelo terminal no mesmo nível do arquivo Dockerfile, ou seja, na raiz da aplicação.

Pronto, com a imagem do projeto criado, podemos publicá-la no Heroku.

Publicando a aplicação no Heroku

Após se registrar no site, no dashboard crie um novo projeto:

O nome do projeto irá definir a URL da aplicação, que seguirá o padrão <nome-aplicacao>.herokuapp.com.

Voltando a aplicação, acesse pelo terminal a pasta da sua aplicação e nela execute o comando:

heroku container:push web -a carter-api

Note que no parâmetro -a é informado o nome da aplicação definida no Heroku. Com isso, uma imagem Docker será gerada e enviada para o registro do Heroku:

Como é apresentado no final deste comando, para que a aplicação seja disponibilizada é necessário executar o comando container:release:

heroku container:release web -a carter-api

Que irá apenas “liberar” a aplicação:

Agora é possível acessá-la na url <nome-aplicacao>.herokuapp.com:

Até o Swagger está disponível:

Simples não é?

C# (C Sharp) - APIs REST com ASP.NET Web API
Curso de C# (C Sharp) - APIs REST com ASP.NET Web API
CONHEÇA O CURSO

Para tudo e além…

O processo que utilizamos aqui é bem simples e por fazer uso de um container Docker, isso nos permite publicar qualquer tipo de aplicação web que funciona em container. Isso vale desde aplicações de linguagens suportadas nativamente pelo Heroku, mas que utilize outra versão da linguagem, até aplicações que ainda nem existem atualmente.

Uma aplicação web de uma nova linguagem que suporte Docker, poderia ser publicada utilizando este mesmo processo, sem problemas.

Então é isso. Você pode obter os códigos da aplicação demostrada aqui no meu Github.

Criando um Chat com ASP.NET Core SignalR

No artigo passado, abordei aplicações em tempo real com a biblioteca SignalR, onde demonstrei seu uso em uma streaming API.

Como citei no artigo, um uso muito comum desta biblioteca é na criação de chats. Para conhecer mais recursos dela, vamos criar este tipo de aplicação.

Começando pelo começo

Antes de mais nada, criaremos uma aplicação web:

dotnet new web -n ChatSignalR

E nela, iremos criar um Hub:

namespace ChatSignalR.Hubs
{
    public class ChatHub: Hub
    {
        public async Task SendMessage(string usuario, string mensagem)
        {
            await Clients.All.SendAsync("ReceiveMessage", usuario, mensagem);
        }
    }
}

Note que para esta aplicação o Hub possui um método. Será para este método que o cliente enviará mensagens. Assim que a mensagem for recebida, o Hub a enviará para todos os clientes.

Esta será a dinâmica do nosso chat. Um chat aberto, onde todos os usuários conectados receberão todas as mensagens dos demais usuários.

Na parte do servidor, por fim, é necessário habilitar o SignalR e registrar o hub na classe Startup:

public class Startup
{
    public void ConfigureServices(IServiceCollection services) => services.AddSignalR();

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        app.UseDefaultFiles(); 
        app.UseStaticFiles();

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapHub<ChatHub>("/chat");
        });
    }
}

Criando o cliente:

O nosso cliente será uma página web simples, que conterá um campo para o usuário informar seu nome e uma mensagem:

<!DOCTYPE html>
<html>
<head>
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='IE=edge'>
    <title>Mensagens</title>
    <meta name='viewport' content='width=device-width, initial-scale=1'>
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css" >
</head>
<body>
    <div class="container col-6">
        <div class="form-group">
            <label for="usuario">Usuário</label>
            <input type="text" id="usuario" class="form-control"/>
        </div>
        <div class="form-group">
            <label for="mensagem">Mensagem</label>
            <textarea class="form-control" id="mensagem" rows="2"></textarea>
        </div>
        <input type="button" class="btn btn-primary" id="send" value="Enviar Mensagem" />
    </div>
    <div class="row">
        <div class="col-12">
            <hr />
        </div>
    </div>
    <div class="container col-6">
        <ul class="list-group" id="messagesList"></ul>
    </div>
    <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js"></script>
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js"></script>
    <script src='https://cdnjs.cloudflare.com/ajax/libs/aspnet-signalr/1.1.4/signalr.min.js'></script>
    <script src='main.js'></script>
</body>
</html>

Na parte do JavaScript, conectaremos ao Hub do servidor e definiremos o envio e recebimento de mensagens:

"use strict";

var connection = new signalR.HubConnectionBuilder().withUrl("/chat").build();
$("#send").disabled = true;

connection.on("ReceiveMessage", function (user, message) {
    var msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
    var li = $("<li></li>").text(user + ": " + msg);
    li.addClass("list-group-item");
    $("#messagesList").append(li);
});

connection.start().then(function () {
    $("#send").disabled = false;
}).catch(function (err) {
    return console.error(err.toString());
});

$("#send").on("click", function (event) {
    var user = $("#usuario").val();
    var message = $("#mensagem").val();
    connection.invoke("SendMessage", user, message).catch(function (err) {
        return console.error(err.toString());
    });
    event.preventDefault();
});

Note que quando uma mensagem for recebida, ela é exibida em uma lista:

connection.on("ReceiveMessage", function (user, message) {
    var msg = message.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
    var li = $("<li></li>").text(user + ": " + msg);
    li.addClass("list-group-item");
    $("#messagesList").append(li);
});

E no envio é indicado o método definido no Hub:

$("#send").on("click", function (event) {
    var user = $("#usuario").val();
    var message = $("#mensagem").val();
    connection.invoke("SendMessage", user, message).catch(function (err) {
        return console.error(err.toString());
    });
    event.preventDefault();
});
C# (C Sharp) - APIs REST com ASP.NET Web API
Curso de C# (C Sharp) - APIs REST com ASP.NET Web API
CONHEÇA O CURSO

1,2, 3…. Testando

Agora, ao executar a aplicação e abrir várias abas, note que todos os usuários irão receber as mensagens que forem enviadas:

Simples, não é?

Você pode obter o código da aplicação demonstrado neste artigo no meu Github.

Trabalhando com a template engine Liquid no ASP.NET Core

Quando pensamos em template engine para o ASP.NET, a primeira coisa que vem a mente é o Razor. É uma unanimidade o quanto esta template engine é poderosa e, graças ao suporte constante da Microsoft, sempre recebe novos recursos, como os Razor Componentes. Também tem o fato que ela está integrada ao ASP.NET Core, o que facilita o seu uso. Mas ela não é a única opção de template engine para o ASP.NET Core.

Neste quesito se destaca a biblioteca Fluid, que adiciona ao ASP.NET Core suporte a template engine Liquid.

F# (F Sharp) - Fundamentos
Curso de F# (F Sharp) - Fundamentos
CONHEÇA O CURSO

Liquid

Liquid é uma template engine open source criada pela empresa Shopify para ser utilizado na criação de temas do seu CMS (sistema de gerenciamento de conteúdo). Possuindo uma sintaxe simples, ele facilita a definição de templates principalmente para quem não está habituado com programação.

Criada em 2006, com o tempo esta template engine passou a ser adotada por outras soluções, principalmente sistemas CMS, como o Orchard Core, que é um framework CMS para ASP.NET Core.

Criando a aplicação que utilizará o Liquid

Diferente do Razor, o Liquid pode ser implementado até em um projeto console (para fazer isso com o Razor é necessário utilizar alguma biblioteca de terceiro). Mas para este artigo, trabalharemos com um projeto web e veremos como substituir o Razor pelo Liquid.

Desta forma, inicialmente iremos criar uma aplicação web vazia:

dotnet new web -n SimpleWebLiquid

Em seguida, adicione no projeto a referência da biblioteca Fluid:

dotnet add package Fluid.MvcViewEngine

Por fim, habilite o Fluid no método ConfigureServices da classe Startup:

public void ConfigureServices(IServiceCollection services) => services.AddMvc().AddFluid();

Como criamos uma aplicação web vazia, também é importante adicionar as rotas dos controllers no método Configure desta classe:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Pessoa}/{action=Index}/{id?}");
    });
}

Acima é definido como controller padrão Pessoa, pois o criaremos a seguir.

Definindo o modelo e controller do exemplo

Para exemplificar o uso do Liquid, será definido no projeto um model Pessoa:

public class Pessoa
{
    public int Id { get; set; }
    public string Nome { get; set; }
}

Um repositório simples para ele:

public class PessoaRepository
{
    private static Dictionary<int, Pessoa> pessoas = new Dictionary<int, Pessoa>();

    public List<Pessoa> GetAll(){
        return pessoas.Values.ToList();
    }

    public void Add(Pessoa pessoa){
        pessoa.Id = pessoas.Count + 1;
        pessoas.Add(pessoa.Id, pessoa);
    }
}

E por fim, o controller:

public class PessoaController: Controller
{
    public readonly PessoaRepository repository;

    public PessoaController() => repository = new PessoaRepository();

    public IActionResult Index()
    {
        var pessoas = repository.GetAll();

        return View(pessoas);
    }

    public IActionResult Create() => View();

    [HttpPost]
    public IActionResult Create([FromForm] Pessoa pessoa)
    {
        repository.Add(pessoa);
        return RedirectToAction(nameof(Index));
    }
}

Note que este controller não diferente muito de um controller definido quando estamos trabalhando com o Razor. A diferença é em relação ao não uso do validador contra ataques XSRF/CSRF (mesmo sem o Razor, isso pode ser configurado na classe Startup, mas não faz parte do escopo deste artigo) e a definição da anotação [FromForm] no parâmetro da nossa action Create. Como não iremos trabalhar com modelos fortemente tipados nos templates, também não é possível validar os dados do modelo. Isso teria que ser feito “manualmente”.

Criando os templates Liquid

Assim como ocorre com o uso do Razor, o controller também irá procurar pelos templates Liquid das actions dentro de uma pasta com seu nome em Views. Assim, no projeto, crie esta estrutura de pastas:

+-- Views
|   +-- Pessoa

A biblioteca Fluid segue algumas conversões do Razor. Caso haja um arquivo chamado _ViewStart na pasta, ele será o primeiro arquivo carregado. Assim, dentro de Views crie um arquivo chamado _ViewStart.liquid e adicione o conteúdo abaixo:

{% layout '_Layout' %}

A tag {% layout [template] %} é utilizada para definir o template padrão utilizado nas views da pasta atual e todas as subpastas, funcionando como uma “master page”.

Acima, estamos indicando como template um arquivo chamado _Layout, assim o crie dentro da pasta atual (não se esqueça da extensão .liquid) e adicione o conteúdo abaixo:

<html>
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>{{ ViewData['Title'] }}</title>
        <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css">
    </head>
    <body>
        <header>
            <nav class="navbar navbar-expand-sm nnavbar-light bg-white border-bottom box-shadow mb-3">
                <div class="container">
                    Exemplo de Liquid
                </div>
            </nav>
        </header>
        <div class="container">
            <main role="main" class="pb-3">
            {% renderbody %}
            </main>
        </div>  

        <footer class="border-top footer text-muted">
            <div class="container">
                © 2020 - Treinaweb
            </div>
        </footer>
        <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js"></script>
        <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js"></script>
        <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js"></script>
    </body>
</html>

No código acima é importante frisar a tag {% renderbody %}. Ela indica o ponto onde o conteúdo das views será renderizado na template. Funcionando como o @RenderBody() do Razor.

Também note o trecho de exibição do título:

<title>{{ ViewData['Title'] }}</title>

Nele estamos utilizando duas chaves. Estas chaves são utilizadas para indicar objetos que devem ser renderizados. Desta forma, quando este template for processado o conteúdo de ViewData['Title'] será exibido no HTML gerado.

Com o nosso template definido, podemos criar dentro da pasta Pessoa, a view de listagem (Index.liquid):

<p>
    <a href="/Pessoa/Create">Adicionar pessoa</a>
</p>

<table class="table">
    <thead>
        <tr>
            <th>
                Id
            </th>
            <th>
                Nome
            </th>
        </tr>
    </thead>
    <tbody>
    {% for p in Model %}
        <tr>
            <td>
                {{ p.Id }}
            </td>
            <td>
                {{ p.Nome }}
            </td>
        </tr>
    {% endfor %}
    </tbody>
</table>

E de cadastrado (Create.liquid):

<div class="row">
    <div class="col-md-4">
        <form action="/Pessoa/Create" method="post">
            <div class="form-group">
                <label for="Nome" class="control-label"></label>
                <input name="Nome" id="Nome class="form-control" />
            </div>
            <div class="form-group">
                <input type="submit" value="Salvar" class="btn btn-primary" />
            </div>
        </form>
    </div>
</div>

<div>
    <a href="/Pessoa/Index">Voltar para listagem</a>
</div>

Na view Index, note que estamos utilizando um laço for:

{% for p in Model %}

Este laço percorre um objeto Model. Para que o template reconheça a estrutura deste model, é necessário que ele seja registrado no construtor da classe Startup:

static Startup() => TemplateContext.GlobalMemberAccessStrategy.Register<Pessoa>();

Pronto, agora podemos testar a nossa aplicação.

Windows Server 2016 - Internet Information Services
Curso de Windows Server 2016 - Internet Information Services
CONHEÇA O CURSO

A mágica acontecendo

Ao executar a aplicação e acessá-la, nos é exibido a tela de listagem:

Também podemos adicionar algumas pessoas:

E notaremos que o nosso template Liquid está funcionando corretamente:

liquid_3

Devo migrar todas as minhas aplicações para o Liquid?

O suporte do Liquid ao ASP.NET não significa que você deve utilizá-lo em todas as suas aplicações. Como dito no início, o Razor é uma poderosa ferramenta, que não deve ser substituída sem necessidade.

O Liquid é uma template engine mais acessível para pessoas com pouco conhecimento em programação. Então quando estiver trabalhando em um projeto onde as pessoas que irão lidar com as templates possuem esta característica, você deve dar uma olhada nesta template engine.

Você pode ver o código completo da aplicação demonstrada neste artigo no meu Github.

ASP.NET Core – Criando uma Streaming API

Quando falamos de streaming de dados, a primeira coisa que vem a cabeça são streaming mídia: áudio e mídia. Mas em algumas situações, pode ser necessário a implementação de streaming de dados textuais.

Utilizado para a entrega de dados em tempo real, o streaming de dados em uma API é uma técnica utilizada principalmente por redes sociais, como Twitter e Facebook.

No .NET Core este tipo de recurso pode ser implementado via SignalR, mas neste artigo exemplificaremos isso utilizando a estrutura tradicional do ASP.NET Core. Futuramente abordarei o uso do SignalR.

C# (C Sharp) - APIs REST com ASP.NET Web API
Curso de C# (C Sharp) - APIs REST com ASP.NET Web API
CONHEÇA O CURSO

Criando uma Web API Simples

Para exemplificar a API Streaming, inicialmente iremos criar uma API simples:

dotnet new web -n ApiSimples

Que conterá apenas um model:

namespace ApiSimples.Models
{
    public class Item
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }

        public override string ToString() => $"{Id} - {Name} - {IsComplete}";
    }
}

E um controller:

namespace ApiSimples.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TodoController : ControllerBase
    {
        private static List<Item> _itens = new List<Item>();

        [HttpGet]
        public ActionResult<List<Item>> Get() => _itens;

        [HttpPost]
        public async Task<ActionResult<Item>> Post([FromBody] Item value)
        {
            if(value == null)
                return BadRequest();

            if(value.Id == 0)
            {
                var max = _itens.Max(i => i.Id);
                value.Id = max+1;
            }

            _itens.Add(value);
            return value;
        }

        [HttpPut("{id}")]
        public async Task<ActionResult<Item>> Put(long id, [FromBody] Item value)
        {
            var item = _itens.SingleOrDefault(i => i.Id == id);
            if(item != null)
            {
                _itens.Remove(item);
                value.Id = id;
                _itens.Add(value);
                return item;
            }

            return BadRequest();
        }

        [HttpDelete("{id}")]
        public async Task<ActionResult> Delete(long id)
        {
            var item = _itens.SingleOrDefault(i => i.Id == id);
            if(item != null)
            {
                _itens.Remove(item);
                return Ok(new { Description = "Item removed" });
            }

            return BadRequest();
        }
    }
}

À frente este controller será modificado com adição do streaming.

Não se esqueça de adicionar o suporte para o controller em Startup:

public class Startup
{
    public void ConfigureServices(IServiceCollection services) => services.AddControllers();

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Adicionando o streaming de dados

No ASP.NET Core, ao acessar uma rota, a solicitação é processada e o seu resultado retornado para o usuário. Ao definir um streaming de dados, a solicitação se manterá em um processamento contínuo, retornando dados de um evento, enquanto a conexão se mantiver ativa.

Por não seguir o comportamento padrão, o streaming não pode retornar um objeto ActionResult, que é o tipo de retorno mais comum. Assim, a primeira coisa a ser feita é definir um ActionResult customizado:

public class StreamResult : IActionResult
{
    private readonly CancellationToken _requestAborted;
    private readonly Action<Stream, CancellationToken> _onStreaming;

    public StreamResult(Action<Stream, CancellationToken> onStreaming, CancellationToken requestAborted)
    {
        _requestAborted = requestAborted;
        _onStreaming = onStreaming;
    } 

    public Task ExecuteResultAsync(ActionContext context)
    {
        var stream = context.HttpContext.Response.Body;
        context.HttpContext.Response.GetTypedHeaders().ContentType = new MediaTypeHeaderValue("text/event-stream");
        _onStreaming(stream, _requestAborted);
        return Task.CompletedTask;
    }
}

Note que esta classe implementa a interface IActionResult. Assim, ela poderá ser utilizada no lugar de ActionResult.

O ponto mais importante dela é a definição do callback onStreaming, que é recebido por parâmetro:

public StreamResult(Action<Stream, CancellationToken> onStreaming, CancellationToken requestAborted)
{
  _requestAborted = requestAborted;
  _onStreaming = onStreaming;
} 

Este callback será utilizado para salvar os clients que estiverem “ouvindo” o streaming. E o CancellationToken será utilizado para finalizar o streaming caso a solicitação seja interrompida/cancelada.

Voltando ao controller, é necessário definir uma coleção para salvar os clients:

private static ConcurrentBag<StreamWriter> _clients = new ConcurrentBag<StreamWriter>();

Esta coleção precisa ser thread-safe, por isso que foi utilizada uma coleção do namespace System.Collections.Concurrent.

Agora é possível definir o endpoint do streaming de dados:

[HttpGet]
[Route("streaming")]
public IActionResult Streaming()
{
    return new StreamResult(
        (stream, cancelToken) => {
            var wait = cancelToken.WaitHandle;
            var client = new StreamWriter(stream);
            _clients.Add(client);

            wait.WaitOne();

            StreamWriter ignore;
            _clients.TryTake(out ignore);
        }, 
        HttpContext.RequestAborted);
}

Note que na função callback da classe StreamResult estamos adicionando o client na coleção e aguarda-se que a solicitação seja cancelada. Com isso, ao acessar o endpoint, a solicitação se manterá ativa.

No momento já temos um streaming de dados, mas nada está sendo enviado para os clients. Para isso, definiremos um método que irá percorrê-los e escreverá dados no stream:

private async Task WriteOnStream(Item data, string action)
{
    foreach (var client in _clients)
    {
        string jsonData = string.Format("{0}\n", JsonSerializer.Serialize(new { data, action }));
        await client.WriteAsync(jsonData);
        await client.FlushAsync();
    }
}

Os dados escritos, serão as ações do nosso controller:

public async Task<ActionResult<Item>> Post([FromBody] Item value)
{
    if(value == null)
        return BadRequest();

    if(value.Id == 0)
    {
        var max = _itens.Max(i => i.Id);
        value.Id = max+1;
    }

    _itens.Add(value);

    await WriteOnStream(value, "Item added");

    return value;
}

[HttpPut("{id}")]
public async Task<ActionResult<Item>> Put(long id, [FromBody] Item value)
{
    var item = _itens.SingleOrDefault(i => i.Id == id);
    if(item != null)
    {
        _itens.Remove(item);
        value.Id = id;
        _itens.Add(value);

        await WriteOnStream(value, "Item updated");

        return item;
    }

    return BadRequest();
}

[HttpDelete("{id}")]
public async Task<ActionResult> Delete(long id)
{
    var item = _itens.SingleOrDefault(i => i.Id == id);
    if(item != null)
    {
        _itens.Remove(item);
        await WriteOnStream(item, "Item removed");
        return Ok(new { Description = "Item removed" });
    }

    return BadRequest();
}

Pronto, o nosso streaming de dados já está completo.

F# (F Sharp) - Fundamentos
Curso de F# (F Sharp) - Fundamentos
CONHEÇA O CURSO

123 Testando…

Para testar a API, inicialmente é necessário acessar o endpoint do streaming de dados:

Note que o navegador indicará que a página está sendo carregada. Este é o comportamento padrão. Ao enviar uma solicitação para o controller, ela será mostrada nesta página:

A página sempre mostrará que está sendo carregada, mas todas as ações que forem geradas do nosso controller serão exibidas nela.

Simples, não é? Você pode ver esta aplicação completa no meu Github.

No próximo artigo mostrarei como obter isso utilizando o SignalR.

Criando uma API RESTful com o Carter e .NET Core

No início deste ano comentei o quanto o ASP.NET Web API é quase uma unanimidade na criação de APIs no .NET, mas que haviam outras opções, tão boas quanto ele.

No artigo em questão abordei a criação de uma API com o framework NancyFX. E ao longo deste ano ganhou destaque outro framework para criação de APIs, que podemos chamar de um derivado do Nancy, o Carter.

C# (C Sharp) - APIs REST com ASP.NET Web API
Curso de C# (C Sharp) - APIs REST com ASP.NET Web API
CONHEÇA O CURSO

Carter

O Carter foi criado por Jonathan Channon, e é mantido por ele e a Carter Community, seguindo a mesma filosofia do Nancy (onde o Jonathan Channon também contribui), facilitar a vida do desenvolvedor.

Implementado como uma extensão do ASP.NET Core, o Carter permite que o código seja mais direto, elegante e agradável. Seu principal objetivo é facilitar a definição das rotas e controllers.

Para compreendê-lo, vamos ver um exemplo simples de API.

Criando a aplicação para utilizar o Carter

O Carter pode ser adicionado em qualquer tipo de aplicação ASP.NET Core, mesmo uma aplicação existente. Caso queria trabalhar apenas com este framework é necessário criar uma aplicação web vazia:

dotnet new web -n CarterAPI

E adicionar o pacote carter:

dotnet add package carter

Em seguida ele deve ser configurado na classe Startup:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddCarter();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints => endpoints.MapCarter());
    }
}

Também é possível instalar o CarterTemplate:

dotnet new -i CarterTemplate

Com isso, é possível criar a aplicação utilizando este template:

dotnet new Carter -n CarterAPI

Nesta opção a aplicação é criada com o Carter configurado e um módulo definido. Como não optamos por esta opção, vamos criar o módulo na nossa aplicação.

Criando um módulo

Assim como no Nancy, no Carter os endpoints devem ser definidos em módulos. Um módulo nada mais é que uma classe que herde a classe CarterModule. Esta classe pode ser definida em qualquer ponto da aplicação. O importante é que seja pública, por exemplo:

using Carter;

namespace CarterAPI.Modules
{
    public class HomeModule : CarterModule
    {
        public HomeModule()
        {
            Get("/", (req, res) => res.WriteAsync("Hello from Carter!"));
        }
    }
}

Como é possível supor, acima estamos definindo uma solicitação GET, que será invocada quando o usuário acessar a rota /. Ao executar a aplicação, teremos o resultado:

Para cada verbo do HTTP há um método disponível:

  • Delete = DELETE;
  • Get = GET;
  • Head = HEAD;
  • Options = OPTIONS;
  • Post = POST;
  • Put = PUT;
  • Patch = PATCH.

Criando o CRUD

Para exemplificar uma API REST completa, vamos definir os métodos CRUD.

Inicialmente defina uma entidade:

public class Pessoa
{
    public int Id { get; set; }
    public string Nome { get; set; }
    public int Idade { get; set; }
}

E um repositório:

public class PessoaRepository
{
    private static Dictionary<int, Pessoa> pessoas = new Dictionary<int, Pessoa>();

    public List<Pessoa> GetAll(){
        return pessoas.Values.ToList();
    }

    public Pessoa Get(int id){
        return pessoas.GetValueOrDefault(id);
    }

    public void Add(Pessoa pessoa){
        pessoas.Add(pessoa.Id, pessoa);
    }

    public void Edit(Pessoa pessoa){
        pessoas.Remove(pessoa.Id);
        pessoas.Add(pessoa.Id, pessoa);
    }

    public void Delete(int id){
        pessoas.Remove(id);
    }
}

Por fim, podemos definir os endpoints:

public class PessoaModule : CarterModule
{
    public readonly PessoaRepository repository;
    public PessoaModule()
    {
        repository = new PessoaRepository();
        Get("/pessoa/", (req, res) => {
            var pessoas = repository.GetAll();
            return res.AsJson(pessoas);
        });
        Get("/pessoa/{id:int}", (req, res) =>
        {
            var id = req.RouteValues.As<int>("id");
            var pessoa = repository.Get(id);
            return res.Negotiate(pessoa);
        });
        Post("/pessoa/", async (req, res) =>
        {
            var pessoa = await req.Bind<Pessoa>();

            repository.Add(pessoa);
            res.StatusCode = 201;
            await res.Negotiate(pessoa);
            return;
        });
        Put("/pessoa/{id:int}", async (req, res) =>
        {
            var pessoa = await req.Bind<Pessoa>();

            pessoa.Id = req.RouteValues.As<int>("id");

            repository.Edit(pessoa);

            res.StatusCode = 204;
            return;
        });
        Delete("/pessoa/{id:int}", (req, res) =>
        {
            var id = req.RouteValues.As<int>("id");
            repository.Delete(id);
            res.StatusCode = 204;
            return Task.CompletedTask;
        });
    }
}

Nestes endpoints podemos notar algumas particularidades do framework, como o fato dos parâmetros da URL definem um tipo de dado:

Get("/pessoa/{id:int}", (req, res) =>

Isso permite que o valor seja validado no momento que a solicitação está sendo processada. Este valor é obtido através do método do RouteValues:

var id = req.RouteValues.As<int>("id");

Já os dados passados no corpo da solicitação serão obtidos através do Bind:

var pessoa = await req.Bind<Pessoa>();

Podemos testar este endpoint pelo Postman, mas outro recurso do Carter é a geração do JSON definido pelo OpenAPI, que abordei no meu artigo sobre o Swagger.

OpenAPI

O JSON do OpenAPI criado pelo Carter pode ser acessado pela URL /openapi, mas infelizmente ele não configura os endpoints automaticamente. Cada endpoint precisa ser configurado em uma classe que herde RouteMetaData.

Para os endpoints deste artigo, defini as classes abaixo:

public class GetPessoa : RouteMetaData
{
    public override string Tag { get; } = "Pessoa";
    public override string Description { get; } = "Retorna uma lista de pessoas";

    public override RouteMetaDataResponse[] Responses { get; } =
    {
        new RouteMetaDataResponse
        {
            Code = 200,
            Description = $"Uma lista de Pessoas",
            Response = typeof(IEnumerable<Pessoa>)
        }
    };

    public override string OperationId { get; } = "Pessoa_GetPessoa";
}
public class GetPessoaById: RouteMetaData
{
    public override string Tag { get; } = "Pessoa";
    public override string Description { get; } = "Obtém pessoa pelo id";

    public override RouteMetaDataResponse[] Responses { get; } =
    {
        new RouteMetaDataResponse
        {
            Code = 200, 
            Description = $"Uma Pessooa",
            Response = typeof(Pessoa)
        },
        new RouteMetaDataResponse
        {
            Code = 404,
            Description = $"Pessoa não encontrada"
        }
    };

    public override string OperationId { get; } = "Pessoa_GetPessoaById";
}
public class PostPessoa: RouteMetaData
{
    public override string Tag { get; } = "Pessoa";
    public override string Description { get; } = "Adiciona uma pessoa";

    public override RouteMetaDataRequest[] Requests { get; } =
    {
        new RouteMetaDataRequest
        {
            Request = typeof(Pessoa),
        }
    };

    public override RouteMetaDataResponse[] Responses { get; } = 
    { 
        new RouteMetaDataResponse 
        { 
            Code = 204, 
            Description = "Pessoa adicionada" 
        }
    };
    public override string OperationId { get; } = "Pessoa_PostPessoa";
}
public class PutPessoa: RouteMetaData
{
    public override string Tag { get; } = "Pessoa";
    public override string Description { get; } = "Atualiza uma pessoa";

    public override RouteMetaDataRequest[] Requests { get; } =
    {
        new RouteMetaDataRequest
        {
            Request = typeof(Pessoa),
        }
    };

    public override RouteMetaDataResponse[] Responses { get; } = 
    { 
        new RouteMetaDataResponse 
        { 
            Code = 204, 
            Description = "Pessoa atualizada" 
        }
    };
    public override string OperationId { get; } = "Pessoa_PutPessoa";
}
public class DeletePessoa: RouteMetaData
{
    public override string Tag { get; } = "Pessoa";
    public override string Description { get; } = "Exclui uma pessoa";

    public override RouteMetaDataResponse[] Responses { get; } = 
    { 
        new RouteMetaDataResponse 
        { 
            Code = 204, 
            Description = "Exclui Pessoa" 
        }
    };

    public override string OperationId { get; } = "Pessoa_DeletePessoa";
}

Agora é necessário definir esses meta dados em cada endpoint:

public class PessoaModule : CarterModule
{
    public readonly PessoaRepository repository;
    public PessoaModule()
    {
        repository = new PessoaRepository();
        Get<GetPessoa>("/pessoa/", (req, res) => {
            var pessoas = repository.GetAll();
            return res.AsJson(pessoas);
        });
        Get<GetPessoaById>("/pessoa/{id:int}", (req, res) =>
        {
            var id = req.RouteValues.As<int>("id");
            var pessoa = repository.Get(id);
            if(pessoa == null)
            {
                res.StatusCode = 404;
                return Task.CompletedTask;
            }
            return res.Negotiate(pessoa);
        });
        Post<PostPessoa>("/pessoa/", async (req, res) =>
        {
            var pessoa = await req.Bind<Pessoa>();

            repository.Add(pessoa);
            Console.WriteLine(pessoa);
            res.StatusCode = 201;
            await res.Negotiate(pessoa);
            return;
        });
        Put<PutPessoa>("/pessoa/{id:int}", async (req, res) =>
        {
            var pessoa = await req.Bind<Pessoa>();

            pessoa.Id = req.RouteValues.As<int>("id");

            repository.Edit(pessoa);

            res.StatusCode = 204;
            return;
        });
        Delete<DeletePessoa>("/pessoa/{id:int}", (req, res) =>
        {
            var id = req.RouteValues.As<int>("id");
            repository.Delete(id);
            res.StatusCode = 204;
            return Task.CompletedTask;
        });
    }
}

Note que eles são especificados no método do endpoint:

Get<GetPessoa>("/pessoa/", (req, res) => {

Ao defini-los e acessar /openapi, será retornado o JSON:

Para visualizarmos em uma interface gráfica, é possível adicionar o SwaggerUi da biblioteca Swashbuckle:

dotnet add package Swashbuckle.AspNetCore.SwaggerUi --version 5.0.0-rc4

Configurá-lo no projeto:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();

    app.UseSwaggerUI(opt =>
    {
        opt.RoutePrefix = "openapi/ui";
        opt.SwaggerEndpoint("/openapi", "Carter OpenAPI Sample");
    });

    app.UseEndpoints(endpoints => endpoints.MapCarter());
}

Desta forma, ao acessar a URL /openapi/ui teremos acesso a interface gráfica:

E por ela é possível testar todos os endpoints.

C# (C Sharp) - APIs REST com ASP.NET Web API
Curso de C# (C Sharp) - APIs REST com ASP.NET Web API
CONHEÇA O CURSO

Conclusão

Devido a sua simplicidade e grande gama de recursos o Carter é um framework que merece ser acompanhado. Caso tenha se interessado por ele, recomendo que dê uma olhada no seu repositório.

Infelizmente no momento ele não possui nenhuma documentação detalhada.

Você pode obter os códigos da aplicação demonstrada neste artigo, no meu Github.

Verificando a integridade da aplicação ASP.NET Core com Health Checks

Alguns artigos passados falei sobre as ferramentas de linha de comando que permitem diagnosticar uma aplicação no .NET Core 3.0. Por serem ferramentas de linha de comando, elas requerem acesso a máquina onde a aplicação está instalada. Infelizmente em muitos cenários algo assim não é possível, mas o monitoramento do status da aplicação não deixa de ser importante nesses casos.

Se tratando de aplicações ASP.NET, antigamente o comum era criar um endpoint que retornasse o estado da aplicação ou menos nada era definido. Mas com a adoção cada vez maior de microsserviços e a criação de aplicações para um ambiente distribuído, implementar a verificação da integridade da aplicação se tornou algo essencial.

C# (C Sharp) Básico
Curso de C# (C Sharp) Básico
CONHEÇA O CURSO

Felizmente, a partir da versão 2.2 do ASP.NET Core, foi introduzido os Health Checks que facilitam este trabalho.

Conhecendo os Health Checks

Health check é um middleware que fornece um endpoint que retorna o status da aplicação. Na sua versão básica, a aplicação é considerada saudável caso retorne o código 200 (OK) para uma solicitação web. Mas também são fornecidas bibliotecas que nos permite verificar o status de serviços utilizados pela aplicação, como: banco de dados, sistema de mensageria, cache, logging, serviços externos ou mesmo a criação de um health check customizado.

Aplicação que terá a integridade verificada

Para exemplificar o uso do health check, vou utilizar uma aplicação ASP.NET Core Web API simples, que já foi mostrada no artigo sobre a documentação de uma ASP.NET Core Web API com o Swagger, que você pode ver no meu Github.

Adicionando o Health Check na aplicação

Agora que já temos a aplicação, já podemos ativar o health check nela. Para isso, basta adicionar o service no método ConfigureServices da classe Startup e indicar a URL dele no método Configure:

public void ConfigureServices(IServiceCollection services)
{
    //....
    services.AddHealthChecks();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    //...

    //Ativa o HealthChecks
    app.UseHealthChecks("/status");
    //...
}

Agora, ao executar a aplicação e acessar a URL /status será exibido se ela está saudável ou não:

Como está sendo testado apenas se ela responde a uma requisição, a aplicação é considerada saudável.

Integridade do banco de dados

Existem várias formas de testar a integridade do banco de dados. É fornecido uma gama de pacotes que nos permite testar a integridade do banco de acordo com o SGBD:

  • SQL Server: AspNetCore.HealthChecks.SqlServer;
  • MySQL: AspNetCore.HealthChecks.MySql;
  • PostgreSQL: AspNetCore.HealthChecks.Npgsql;
  • SQLite: AspNetCore.HealthChecks.SqLite;
  • Oracle: AspNetCore.HealthChecks.Oracle;
  • MongoDb: AspNetCore.HealthChecks.MongoDb.

Caso esteja trabalhando com o Entity Framework, também há o pacote Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore, que será o que utilizaremos na aplicação:

dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Com isso, basta adicionar a classe DbContext, que o estado da conexão com o banco será verificada:

public void ConfigureServices(IServiceCollection services)
{
    //...
    services.AddHealthChecks()
            .AddDbContextCheck<TodoContext>();
}

Se o banco estiver saudável, o resultado não será alterado:

Caso haja algum problema com a conexão com o banco, a aplicação não será considerada saudável:

Alterando as informações exibidas

No momento, somos informados apenas se a aplicação está ou não saudável. Para uma aplicação pequena, isso pode ser útil, mas imagine uma aplicação que verifica vários serviços? Apenas com esta informação não conseguiremos saber qual serviço não está funcionando corretamente.

Para obter esses dados, podemos customizar as informações de saída do health check, definindo um delegate na opção ResponseWriter:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    //...

    //Ativa o HealthChecks
    app.UseHealthChecks("/status", new HealthCheckOptions()
    {
        // WriteResponse é um delegate que permite alterar a saída.
        ResponseWriter = (httpContext, result) => {
            httpContext.Response.ContentType = "application/json";

            var json = new JObject(
                new JProperty("status", result.Status.ToString()),
                new JProperty("results", new JObject(result.Entries.Select(pair =>
                    new JProperty(pair.Key, new JObject(
                        new JProperty("status", pair.Value.Status.ToString()),
                        new JProperty("description", pair.Value.Description),
                        new JProperty("data", new JObject(pair.Value.Data.Select(
                            p => new JProperty(p.Key, p.Value))))))))));
            return httpContext.Response.WriteAsync(json.ToString(Formatting.Indented));
        }
    });
    //...
}

Com isso, obteremos a causa do problema da aplicação:

Criando health checks customizados

Existe uma grande gama de health checks definidos, mas em algumas situações, pode ser necessário definir um customizado. Para isso, é necessário definir uma classe que implemente a interface IHealthCheck e definir no método CheckHealthAsync qual tipo de verificação ele fará:

public class SelfHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        return Task.FromResult(new HealthCheckResult(
            HealthStatus.Healthy,
            description: "API up!"));
    }
}

Acima é definido um health check simples, que apenas indica que a API está funcionando.

C# (C Sharp) Intermediário
Curso de C# (C Sharp) Intermediário
CONHEÇA O CURSO

Agora é necessário adicioná-lo ao serviço com o método AddCheck:

public void ConfigureServices(IServiceCollection services)
{
    //...
    services.AddHealthChecks()
            .AddDbContextCheck<TodoContext>()
            .AddCheck<SelfHealthCheck>("Self");
}

Também pode ser definido um método de extensão:

public static class HealthCheckBuilderExtensions
{
    public static IHealthChecksBuilder AddSelfCheck(this IHealthChecksBuilder builder, string name, HealthStatus? failureStatus = null, IEnumerable<string> tags = null)
    {
        // Register a check of type SelfHealthCheck
        builder.AddCheck<SelfHealthCheck>(name, failureStatus ?? HealthStatus.Degraded, tags);

        return builder;
    }
}

E utilizá-lo para registrar o health check:

public void ConfigureServices(IServiceCollection services)
{
    //...
    services.AddHealthChecks()
            .AddDbContextCheck<TodoContext>()
            .AddSelfCheck("Self");
}

Ao acessar a aplicação, ele também será mostrado:

Adicionando uma interface

No momento o resultado do status da aplicação é um JSON, mas existe um pacote que nos permite visualizar as informações em uma interface gráfica. Para isso, adicione na aplicação os pacotes AspNetCore.HealthChecks.UI e AspnetCore.HealthChecks.UI.Client:

dotnet add package AspNetCore.HealthChecks.UI
dotnet add package AspnetCore.HealthChecks.UI.Client

Em seguida é necessário habilitar o Health Checks UI nos métodos ConfigureServices e Configure da classe Startup:

public void ConfigureServices(IServiceCollection services)
{
    //....
    services.AddHealthChecks()
            .AddDbContextCheck<TodoContext>()
            .AddSelfCheck("Self");

    services.AddHealthChecksUI();
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    //...

    //Ativa o HealthChecks
    app.UseHealthChecks("/status", new HealthCheckOptions()
    {
        // WriteResponse is a delegate used to write the response.
        ResponseWriter = (httpContext, result) => {
            httpContext.Response.ContentType = "application/json";

            var json = new JObject(
                new JProperty("status", result.Status.ToString()),
                new JProperty("results", new JObject(result.Entries.Select(pair =>
                    new JProperty(pair.Key, new JObject(
                        new JProperty("status", pair.Value.Status.ToString()),
                        new JProperty("description", pair.Value.Description),
                        new JProperty("data", new JObject(pair.Value.Data.Select(
                            p => new JProperty(p.Key, p.Value))))))))));
            return httpContext.Response.WriteAsync(json.ToString(Formatting.Indented));
        }
    });

    //Ativa o HealthChecks utilizado pelo HealthCheckUI
    app.UseHealthChecks("/status-api", new HealthCheckOptions()
    {
        Predicate = _ => true,
        ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
    });

    app.UseHealthChecksUI(opt => {
        opt.UIPath = "/status-dashboard";
    });

    //...
}

Além de habilitar o Health Checks UI note que também é definido um novo endpoint para o health check, configurado para o delegate UIResponseWriter.WriteHealthCheckUIResponse. Este é um delegate criado pelo Health Checks UI, e configura um arquivo JSON que será lido pela biblioteca.

Para que ele seja lido, é necessário especificá-lo no arquivo appsettings.json:

{
  "HealthChecks-UI": {
    "HealthChecks": [
      {
        "Name": "Status-API",
        "Uri": "https://localhost:5001/status-api"
      }
    ]
  }
}

Com isso, ao executar a aplicação e acessar a URL /status-dashboard a interface será exibida:

Por hoje é isso 🙂

C# (C Sharp) Avançado
Curso de C# (C Sharp) Avançado
CONHEÇA O CURSO

Lembrando que você pode ver o código da aplicação no Github.

.NET Core 3.0 – Criando tarefas de segundo plano com Worker Service

Quando se pensa em uma aplicação ASP.NET Core, provavelmente irá pensar em uma aplicação MVC, Web API ou Razor. Mas um detalhe pouco conhecido é que também é possível criar tarefas de segundo plano com o ASP.NET Core, através do conceito de generic hosts. Na versão 3.0 do .NET Core, este tipo de aplicação foi definida em um novo template chamado Worker Service, facilitando assim a criação das tarefas de segundo plano e dando mais destaque para este recurso.

O conceito de generic host foi introduzido na versão 2.1 do .NET Core e trata-se de uma aplicação ASP.NET Core que não processa requisições HTTP. O objetivo deste tipo de aplicação é remover o pipeline HTTP enquanto mantém os demais recursos de uma aplicação ASP.NET Core, como configuração, injeção de dependência e logging. Permitindo assim a criação de aplicações que precisam ser executadas em segundo plano, como serviços de mensagens.

C# (C Sharp) Básico
Curso de C# (C Sharp) Básico
CONHEÇA O CURSO

Criando uma aplicação Worker Service

Para criar uma aplicação Worker Service é necessário ter instalado o .NET Core 3.0, que no momento da criação deste artigo está no preview 7. Caso esteja utilizando o Visual Studio, este tipo de aplicação está disponível a partir da versão 2019.

Como estou utilizando o Visual Studio Code, vou criar a aplicação pela linha de comando com o código abaixo:

dotnet new worker -n WorkerSample

No Visual Studio 2019 você pode encontrar o template desta aplicação dentro dos subtemplates do ASP.NET Core.

Na classe Program, podemos notar que é criado um servidor web:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
                services.AddHostedService<Worker>();
            });
}

Que define um serviço, a classe Worker, que veremos a seguir.

Definindo a tarefa

A classe responsável por executar a tarefa em segundo plano é a classe Worker:

public class Worker : BackgroundService
{
    private readonly ILogger<Worker> _logger;

    public Worker(ILogger<Worker> logger)
    {
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
            await Task.Delay(1000, stoppingToken);
        }
    }
}

Note que o construtor recebe uma instância de Logger. Podemos utilizar esta instância para notificar o usuário do estado do serviço. Já no método ExecuteAsync é onde a tarefa de segundo plano é executada.

Note que ela é executada enquanto o serviço não for cancelado.

Para este artigo iremos modificar apenas o método ExecuteAsync, adicionando informações sobre o estado do serviço:

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    _logger.LogInformation("O serviço está iniciando.");

    stoppingToken.Register(() => _logger.LogInformation("Tarefa de segundo plano está parando."));

    while (!stoppingToken.IsCancellationRequested)
    {
        _logger.LogInformation("Executando tarefa: {time}", DateTimeOffset.Now);
        await Task.Delay(10000, stoppingToken);
    }

    _logger.LogInformation("O serviço está parando.");
}

Ao executar a aplicação temos o resultado abaixo:

No momento ela ainda não está sendo executada como serviço, vamos configurá-la para isso.

C# (C Sharp) Intermediário
Curso de C# (C Sharp) Intermediário
CONHEÇA O CURSO

Configurando a tarefa como serviço para ser executada em segundo plano

Para executar a aplicação como serviço, é necessário adicionar o pacote “Microsoft.Extensions.Hosting.WindowsServices” na aplicação:

dotnet add package Microsoft.Extensions.Hosting.WindowsServices

Ao adicioná-lo podemos chamar o método UseWindowsService():

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .UseWindowsService()
        .ConfigureServices((hostContext, services) =>
        {
            services.AddHostedService<Worker>();
        });

Este método verifica se a aplicação está executando como serviço e faz as configurações necessárias de acordo deste contexto. Ela também configura a aplicação para utilizar o ServiceBaseLifetime, que auxilia no controle do ciclo de vida da aplicação enquanto ela é executada como serviço. Isso sobrescreve o padrão ConsoleLifetime.

Publicando o serviço

Com o ServiceBaseLifetime configurado, podemos publicar a nossa aplicação:

dotnet publish -c Release

O comando acima irá publicar a aplicação de acordo com o ambiente de desenvolvimento. Você também pode publicar a aplicação para um sistema específico com a opção -r:

dotnet publish -c Release -r <RID>

“ significa Runtime Identifier (RID) e na documentação você pode ver as opções disponíveis.

Instalando o serviço no Windows

Com a aplicação publicada, ela pode ser instalada como serviço no Windows com o utilitário sc:

sc create workersample binPath=C:\Programs\Services\WorkerSample.exe

Instalando o serviço no Mac OS X

No caso do Mac OS X, os serviços são conhecimentos como daemon. Para definir o nosso serviço neste sistema como um daemon, é necessário possuir o .NET Core instalado na máquina e definir um script:

#!bin/bash
#Start WorkerSample if not running
if [ “$(ps -ef | grep -v grep | grep WorkerSample | wc -l)” -le 0 ]
then
 dotnet /usr/local/services/WorkerSample.dll
 echo "WorkerSampler Started"
else
 echo "WorkerSample Already Running"
fi

Dê para este script permissão de execução:

chmod +x ~/scripts/startup/startup.sh

Os daemons neste sistema operacional são definidos na pasta /Library/LaunchDaemons/, onde deve ser configurado em um arquivo XML com a extensão .plist (não faz parte do escopo deste artigo explicar as configurações deste arquivo, você pode conhecê-las na documentação do launchd).

No nosso caso, o arquivo terá o conteúdo abaixo:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:</string>
    </dict>
    <key>Label</key>
    <string>br.com.treinaweb.workersample</string>
    <key>Program</key>
    <string>/Users/admin/scripts/startup/startup.sh</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
    <key>LaunchOnlyOnce</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/startup.stdout</string>
    <key>StandardErrorPath</key>
    <string>/tmp/startup.stderr</string>
    <key>UserName</key>
    <string>admin</string>
    <key>GroupName</key>
    <string>admin</string>
    <key>InitGroups</key>
    <true/>
  </dict>
</plist>

Com isso, para iniciar o daemon basta carregar o arquivo .plist, que acabamos de definir:

sudo launchctl load -w /Library/LaunchDaemons/br.com.treinaweb.workersample.plist

Instalando o daemon no Linux

Assim como no Mac OS X, no Linux os serviços são conhecidos como daemon e nesta plataforma também é necessário possuir o .NET Core instalado na máquina. Fora isso, cada distribuição pode definir uma forma de criação de daemon, aqui vou explicar a criação utilizando o systemd.

No systemd o serviço é definido em um arquivo .service salvo em /etc/systemd/system e que no exemplo deste artigo conterá o conteúdo o abaixo:

[Unit]
Description=Dotnet Core Demo service

[Service]  
ExecStart=/bin/dotnet/dotnet WorkerSample.dll
WorkingDirectory=/usr/local/services
User=dotnetuser  
Group=dotnetuser  
Restart=on-failure  
SyslogIdentifier=dotnet-sample-service  
PrivateTmp=true  

[Install]  
WantedBy=multi-user.target  

Após isso, basta habilitar o daemon:

systemctl enable worker-sample.service 

Que ele poderá ser iniciado:

systemctl start dotnet-sample-service.service

Obs: Infelizmente no Mac OS X e Linux, a aplicação não sabe quando está sendo parada, algo que ocorre no Windows, quando ela é executada como serviço.

C# (C Sharp) Avançado
Curso de C# (C Sharp) Avançado
CONHEÇA O CURSO

O Worker Service é bom?

O template Worker Service é uma boa adição para o .NET Core, pois isso pode tornar os generic hosts cada vez mais populares. Permitindo que as pessoas consigam utilizar os recursos do ASP.NET Core em uma aplicação console.

E com o tempo, espero que melhore o suporte da aplicação como daemon em ambientes Unix.

© 2004 - 2019 TreinaWeb Tecnologia LTDA - CNPJ: 06.156.637/0001-58 Av. Paulista, 1765, Conj 71 e 72 - Bela Vista - São Paulo - SP - 01311-200