DEV Community: Silvair L. Soares

Reforma Tributária - Novos Eventos de apuração do IBS e da CBS

Silvair L. Soares — Thu, 28 Aug 2025 11:59:22 +0000

Entendendo os novos Eventos de Apuração do IBS e da CBS

Os Eventos de Apuração do Imposto sobre Bens e Serviços (IBS) e da Contribuição Social sobre Bens e Serviços (CBS) são conceitos novos e fundamentais na reforma tributária brasileira.

Criados pela Nota Técnica 2025.002-RTC, os schemas XML para a geração desses eventos foram disponibilizados para download e podem ser acessados aqui. Esses eventos são essenciais para que a Secretaria da Receita Federal (RFB) e as Secretarias de Fazenda Estaduais e Municipais possam apurar e fiscalizar o Imposto sobre o Valor Adicionado (IVA), que no Brasil será um IVA dual: o IBS (subnacional (Estados, Distrito Federal e Municípios)) e a CBS (federal).

Quando gerar cada evento?

Estes novos eventos representam momentos-chave no ciclo de vida de uma nota fiscal, indicando a intenção de quem a emite ou de quem a recebe. São eles:

Código	Evento	Autor	Descrição	Momento de Geração
112110	Informação de efetivo pagamento integral para liberar crédito presumido do adquirente	Emitente	Informa o pagamento integral da nota fiscal para que o destinatário possa utilizar um crédito presumido.	No momento do recebimento do pagamento integral da nota fiscal.
112120	Importação em ALC/ZFM não convertida em isenção	Emitente	Indica que uma operação de importação, que seria isenta em ZFM ou ALC, não obteve a isenção.	Quando a ausência de isenção é constatada.
112130	Perecimento, perda, roubo ou furto durante o transporte contratado pelo fornecedor	Emitente	Registra que a mercadoria foi perdida, roubada ou danificada durante o transporte sob responsabilidade do fornecedor.	Quando o sinistro (perecimento, perda, roubo ou furto) é identificado.
112140	Fornecimento não realizado com pagamento antecipado	Emitente	Sinaliza que um produto ou serviço, que já havia sido pago, não foi entregue.	No momento da constatação de que o fornecimento não ocorrerá.
211110	Solicitação de Apropriação de crédito presumido	Destinatário	Manifesta a intenção de usar o crédito presumido liberado pelo fornecedor.	Quando o destinatário decide se apropriar do crédito, após a confirmação do pagamento integral.
211120	Destinação de item para consumo pessoal	Emitente/Destinatário	Comunica que um item foi retirado de circulação comercial para uso pessoal.	Quando a destinação do item para consumo pessoal é realizada.
211124	Perecimento, perda, roubo ou furto durante o transporte contratado pelo adquirente	Destinatário	Registra que a mercadoria foi perdida, roubada ou danificada durante o transporte sob responsabilidade do adquirente.	Quando o sinistro é identificado.
211128	Aceite de débito na apuração por emissão de nota de crédito	Destinatário	Indica que o destinatário concorda com um débito em sua apuração de impostos, devido a uma nota de crédito.	Quando o destinatário aceita o débito.
211130	Imobilização de Item	Destinatário	Sinaliza que um item adquirido será classificado como ativo imobilizado (fixo) da empresa.	No momento da decisão de imobilizar o item.
211140	Solicitação de Apropriação de Crédito de Combustível	Destinatário	Pede a apropriação de crédito sobre a compra de combustíveis, que possui regras específicas.	No momento em que o destinatário solicita o crédito.
211150	Solicitação de Apropriação de Crédito para bens e serviços que dependem de atividade do adquirente	Destinatário	Pede a apropriação de crédito sobre bens e serviços que dependem de uma atividade específica do adquirente para serem válidos.	No momento em que a atividade que habilita o crédito é concluída.
212110	Manifestação sobre Pedido de Transferência de Crédito de IBS em Operações de Sucessão	Sucessora	A empresa sucessora se manifesta sobre a transferência de crédito de IBS da empresa sucedida.	No momento da manifestação sobre o pedido de transferência.
212120	Manifestação sobre Pedido de Transferência de Crédito de CBS em Operações de Sucessão	Sucessora	A empresa sucessora se manifesta sobre a transferência de crédito de CBS da empresa sucedida.	No momento da manifestação sobre o pedido de transferência.
412120	Manifestação do Fisco sobre Pedido de Transferência de Crédito de IBS em Operações de Sucessão	Fisco	O Fisco autoriza ou nega a transferência de crédito de IBS entre as empresas.	Após a análise do pedido de transferência.
412130	Manifestação do Fisco sobre Pedido de Transferência de Crédito de CBS em Operações de Sucessão	Fisco	O Fisco autoriza ou nega a transferência de crédito de CBS entre as empresas.	Após a análise do pedido de transferência.
110001	Cancelamento de Evento	Idem ao Autor do Evento que está sendo cancelado	Cancela qualquer evento anterior, por exemplo, o cancelamento de uma solicitação de apropriação de crédito.	Quando a necessidade de cancelar um evento anterior é identificada.

O Papel crucial dos Novos Eventos de Apuração no período de transição (2026)

A implementação dos novos eventos de apuração do IBS e da CBS é mais do que uma mera formalidade. Ela se torna uma condição indispensável para que as empresas possam usufruir de um benefício fiscal significativo.

Conforme a Nota Técnica 2025.002, a correta e pontual geração desses eventos é a chave para a dispensa total do recolhimento do IBS e da CBS sobre os fatos geradores que ocorrerem em 2026. A legislação é clara: Se as obrigações acessórias, que incluem a emissão desses eventos, não forem cumpridas integralmente, o contribuinte perderá o direito a esse benefício e terá que recolher os impostos normalmente.

Em essência, a Receita Federal está usando esses eventos como uma ferramenta de rastreabilidade e controle. Ao registrar cada passo da apuração, o contribuinte não apenas cumpre uma exigência legal, mas também colabora para a transparência do novo modelo tributário. O não cumprimento dessa obrigação pode resultar em uma dupla penalidade: a perda do benefício e a cobrança dos tributos devidos. Por isso, a partir de janeiro de 2026, uma gestão precisa e rigorosa desses eventos será vital para a saúde financeira e a conformidade das empresas.

Um detalhe importante sobre estes novos eventos:

Diferente dos eventos atuais da NF-e (Cancelamento, Carta de Correção, Manifestação do Destinatário, Ator Interessado na NF-e - Transportador, etc) que são processados por webservices de cada estado, os novos Eventos de Apuração do IBS e da CBS serão autorizados diretamente na SVRS – SEFAZ VIRTUAL DO RIO GRANDE DO SUL. As URLs de produção e homologação podem ser encontradas no Portal Nacional da NFe, na aba Serviços, Relação de Serviços Web.

Veja mais detalhes sobre a implementação destes eventos neste link.

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – Parte 3

Silvair L. Soares — Fri, 07 Mar 2025 11:54:33 +0000

Após a conclusão da etapa 2, onde configuramos os nossos projetos para gerar a documentação automaticamente, utilizando o NSwag, a terceira e última etapa desta série de artigos, será a implementação de uma funcionalidade que nos auxiliará a depurar nossas APIs, principalmente, quando ocorrerem falhas durante o processamento de alguma requisição.

Esta funcionalidade é extremamente importante para nos auxiliar a entender o fluxo das requisições, nos dando uma noção geral do funcionamento do sistema. Além de nos auxiliar a identificar ocorrências de erros em qualquer nível da requisição.

Como explicado na parte 1 desta série de artigos, utilizaremos uma implementação do OpenTracing chamada OpenTracing API for .NET. Além da Jaeger UI para gerenciamento da interface gráfica onde analisaremos as requisições.

Para isto, vamos executar os seguintes passos:

1. Instalando o OpenTracing API for .NET, a Jaeger UI e criando o configurador do OpenTracing

Acesse o menu Tools ⇒ Nuget Package Manager ⇒ Package Manager Console;
Na janela do console, no campo Default Project, selecione o projeto Erp.Shared;

Digite o comando Install-Package Jaeger, pressione Enter e aguarde a instalação.

Digite o comando Install-Package OpenTracing.Contrib.NetCore, pressione Enter e aguarde a instalação.

Como o projeto Api.Erp.Shared está referenciado em todos os demais projetos, instalaremos as dependências, apenas neste projeto.

A seguir, criaremos um método de extensão para configurar o OpenTracing. Portanto, crie o seguinte arquivo no diretório Extensions do projeto Api.Erp.Shared:

…\Api.Erp\Api.Erp.Shared\Extensions\DistributedTracing.cs

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using OpenTracing.Util;
using Jaeger;
using System.Reflection;
using Jaeger.Samplers;
using OpenTracing;

namespace Api.Erp.Shared.Extensions
{
    /// <summary>
    /// Configuração do OpenTracing
    /// </summary>
    public static class DistributedTracing
    {
        /// <summary>
        /// Método de extensão da "IServiceCollection" para configuração do OpenTracing
        /// </summary>
        /// <param name="services"></param>
        public static void ConfigureOpenTracing(this IServiceCollection services)
        {
            services.AddSingleton<ITracer>(serviceProvider =>
            {
                string serviceName = Assembly.GetEntryAssembly().GetName().Name;

                ILoggerFactory loggerFactory = serviceProvider.GetRequiredService<ILoggerFactory>();

                ISampler sampler = new ConstSampler(sample: true);

                ITracer tracer = new Tracer.Builder(serviceName)
                    .WithLoggerFactory(loggerFactory)
                    .WithSampler(sampler)
                    .Build();

                GlobalTracer.Register(tracer);

                return tracer;
            });
            services.AddOpenTracing();
        }
    }
}

2. Habilitando o OpenTracing no projeto Api.Erp.Clientes

Acesse o arquivo Startup.cs do projeto Api.Erp.Clientes e faça as seguintes alterações:

public class Startup
{
    …
    public void ConfigureServices(IServiceCollection services)
    {
        // Habilita as ferramentas de instrumentação do OpenTracing
        services.ConfigureOpenTracing();
    …
    }
}

3. Habilitando o OpenTracing no projeto Api.Erp.Comercial

Acesse o arquivo Startup.cs do projeto Api.Erp.Comercial e faça as seguintes alterações:

public class Startup
{
    …
    public void ConfigureServices(IServiceCollection services)
    {
        // Habilita as ferramentas de instrumentação do OpenTracing
        services.ConfigureOpenTracing();
    …
    }
}

4. Habilitando o OpenTracing no projeto Api.Erp.Fiscal

Acesse o arquivo Startup.cs do projeto Api.Erp.Fiscal e faça as seguintes alterações:

…
public class Startup
{
    …
    public void ConfigureServices(IServiceCollection services)
    {
        // Habilita as ferramentas de instrumentação do OpenTracing
        services.ConfigureOpenTracing();
    …
    }
}

Isto é tudo o que precisamos fazer para gerar os logs de nossas APIs. Porém, diferentemente do Swagger, a interface gráfica para acompanhamento das transações, não é gerada dentro de nosso projeto, mas através do seguinte projeto OpenSource chamado Jaeger UI.

Faça o download dos arquivos binários neste link. Extraia os arquivos para algum local em seu computador.

A pasta extraída conterá os seguintes arquivos:

Acesse o caminho do diretório no prompt de comando e digite o comando:

jaeger-all-in-one.exe

Execute o projeto das APIs e depois acesse o seguinte caminho no browser:

http://localhost:16686/

Esta é a interface gráfica do Jaeger.

Para termos um exemplo real de rastreamento, acione o endpoit que retorna todas as notas fiscais emitidas:

Retorne para a interface gráfica do Jaeger UI. Selecione o valor Api.Erp.Fiscal no campo Service e clique no botão Find Traces.

Selecione o primeiro log capturado e veja todo o detalhamento desta requisição:

São exibidas informações importantíssimas, como o tempo total da requisição e qual etapa foi executada por cada microsserviço.

Ao expandir um item da árvore, você poderá ver os detalhes de cada requisição:

Um outro recurso importantíssimo do Jaeger UI é a geração de um diagrama que detalha a arquitetura geral do sistema. Para visualizar este recurso, clique no link System Architecture, e acesse a aba DAG.

Para a requisição que nos retornou os dados de todas as notas fiscais do sistema, podemos conferir através do Jaeger UI, que a Api.Erp.Fiscal fez duas requisições para a Api.Erp.Comercial, que por sua vez fez outras duas requisições para a Api.Erp.Clientes:

Com isto concluímos a terceira e última etapa da nossa série de artigos.

Espero que esta série de artigos tenha sido útil para ajudar-lhe a minimizar algumas das dores do processo de adoção da arquitetura de microsserviços.

Comentários serão sempre muito bem vindos. Compartilhe comigo sua experiência na adoção deste padrão arquitetural cada vez mais adotado.

Obtenha o código completo da solução até o presente momento neste repositório do GitHub.

Links para a série completa:

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – (Parte 1) Construindo o projeto

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – (Parte 2) Incluindo documentação com o Swagger

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços (Parte 3) – Implementando rastreamento distribuído

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – Parte 2

Silvair L. Soares — Thu, 06 Mar 2025 20:48:50 +0000

Após a conclusão da etapa 1, onde criamos todos os projetos e configuramos a execução do sistema, as funcionalidades básicas de nossas APIs estão todas funcionando perfeitamente.

Ao pressionar a tecla F5 para executar os projetos da nossa solução, veremos as seguintes janelas serem abertas no browser:

Embora os serviços prometidos estejam funcionando, as informações destas páginas não são nada expressivas para o consumidor de nossas APIs.

O que faremos a seguir é habilitar a documentação automática utilizando o NSwag.

Para isto, vamos executar os seguintes passos:

1. Instalando o NSwag e criando o configurador do Swagger

Acesse o menu Tools ⇒ Nuget Package Manager ⇒ Package Manager Console;
Na janela do console, no campo Default Project, selecione o projeto Erp.Shared;
Digite o comando Install-Package NSwag.AspNetCore, pressione Enter e aguarde a instalação.

Como o projeto Api.Erp.Shared está referenciado em todos os demais projetos, instalaremos o NSwag apenas neste projeto.

A seguir, criaremos dois métodos de extensão para configurar o swagger.

Crie o seguinte arquivo no diretório Extensions do projeto Api.Erp.Shared:

…Api.Erp\Api.Erp.Shared\Extensions\SwaggerConfig.cs

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using System.Reflection;

namespace Api.Erp.Shared.Extensions
{
    public static class SwaggerConfig
    {
        public static void ConfigureSwaggerDoc(this IServiceCollection services, string description)
        {
            services.AddOpenApiDocument(config =>
            {
                config.Version = "v1";
                config.AllowReferencesWithProperties = true; //Habilita a geração de exemplos para propriedades aninhadas
                config.Title = "Documentação da API: " + Assembly.GetEntryAssembly().GetName().Name;
                config.Description = description;
            });
        }

        public static void ConfigureSwaggerUI(this IApplicationBuilder app)
        {
            // Ativa o middleware para veicular o Swagger gerado como um terminal JSON.
            app.UseOpenApi();

            // Registra o gerador Swagger e os middlewares Swagger UI
            app.UseSwaggerUi3(config => config.TransformToExternalPath = (internalUiRoute, request) =>
            {
                config.Path = "/swagger";
                if (internalUiRoute.StartsWith("/") == true && internalUiRoute.StartsWith(request.PathBase) == false)
                {
                    return request.PathBase + internalUiRoute;
                }
                else
                {
                    return internalUiRoute;
                }
            });
        }
    }
}

2. Habilitando o Swagger no projeto Api.Erp.Clientes

Acesse o arquivo Startup.cs do projeto Api.Erp.Clientes e faça as seguintes alterações:

using Api.Erp.Shared.Extensions;
    public class Startup
    {
…
        public void ConfigureServices(IServiceCollection services)
        {
…
            //Habilita o Swagger
            string description = "**API para gerenciamento dos clientes do sistema Api.Erp**";
            services.ConfigureSwaggerDoc(description);
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
…
            // Ativa a Swagger-ui
            app.ConfigureSwaggerUI();
…
        }
    }

3. Habilitando o Swagger no projeto Api.Erp.Comercial

Acesse o arquivo Startup.cs do projeto Api.Erp.Comercial e faça as seguintes alterações:

using Api.Erp.Shared.Extensions;
    public class Startup
    {
…
        public void ConfigureServices(IServiceCollection services)
        {
…
            //Habilita o Swagger
            string description = "**API para gerenciamento das vendas do sistema Api.Erp**";
            services.ConfigureSwaggerDoc(description);
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
…
            // Ativa a Swagger-ui
            app.ConfigureSwaggerUI();
…
        }
    }

4. Habilitando o Swagger no projeto Api.Erp.Fiscal

Acesse o arquivo Startup.cs do projeto Api.Erp.Fiscal e faça as seguintes alterações:

using Api.Erp.Shared.Extensions;
    public class Startup
    {
…
        public void ConfigureServices(IServiceCollection services)
        {
…
            //Habilita o Swagger
            string description = "**API para gerenciamento das notas fiscais do sistema Api.Erp**";
            services.ConfigureSwaggerDoc(description);
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
…
            // Ativa a Swagger-ui
            app.ConfigureSwaggerUI();
…
        }
    }

A partir deste momento, ao executarmos o nossas APIs (F5), caso acessemos a rota \swagger, as páginas de documentação já serão exibidas.

Nestas páginas, é possível testar todos os endpoints, clicando no botão Try it out e depois no botão Execute.

Abrindo a rota do Swagger automaticamente

Você deve ter notado, que ao executar os projetos, ainda está sendo necessário digitar a rota que exibe a documentação do Swagger (\swagger), este processo pode ser automatizado.

Esta ação, também poderia ser feito via configuração nas propriedades do projeto. Porém, faremos de uma forma um pouco mais simples e não baseada em configuração. Siga os seguintes passos:

Crie um arquivo chamado DocsController.cs, na pasta Controller de cada um dos projetos, com os respectivos conteúdos:

…\Api.Erp\Api.Erp.Clientes\Controllers\DocsController.cs

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Api.Erp.Clientes.Controllers
{
    /// <summary>
    /// Controller para exibir a documentação da API de Clientes
    /// </summary>
    [Route("")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public class DocsController : Controller
    {
        [Route(""), HttpGet]
        [AllowAnonymous]
        public IActionResult Swagger()
        {
            return Redirect("~/swagger");
        }
    }
}

…\Api.Erp\Api.Erp.Comercial\Controllers\DocsController.cs

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Api.Erp.Comercial.Controllers
{
    /// <summary>
    /// Controller para exibir a documentação da API Comercial
    /// </summary>
    [Route("")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public class DocsController : Controller
    {
        [Route(""), HttpGet]
        [AllowAnonymous]
        public IActionResult Swagger()
        {
            return Redirect("~/swagger");
        }
    }
}

…\Api.Erp\Api.Erp.Fiscal\Controllers\DocsController.cs

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Api.Erp.Fiscal.Controllers
{
    /// <summary>
    /// Controller para exibir a documentação da API Fiscal
    /// </summary>
    [Route("")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public class DocsController : Controller
    {
        [Route(""), HttpGet]
        [AllowAnonymous]
        public IActionResult Swagger()
        {
            return Redirect("~/swagger");
        }
    }
}

Agora, ao executar a solution (F5), as páginas do swagger serão carregadas automaticamente para todas as APIs, sem a necessidade de acionar a rota \swagger.

6. Melhorando os exemplos de dados gerados do Swagger

Ao examinarmos a documentação de cada endpoint, podemos verificar no campo “Example Value”, um exemplo de dados que poderiam ser submetidos para a API, porém os valor atribuídos à cada propriedade, não são sempre sugestivos para o usuário.

Veja por exemplo o JSON atribuído ao método POST da API que gerencia as notas fiscais:

Podemos melhorar estes exemplos, com a anotação JsonSchemaExtensionData da classe NJsonSchema.Annotations.JsonSchemaExtensionDataAttribute.

Vamos alterar as nossas classes, incluindo exemplos de dados mais eficientes, incluindo também a tag com um texto explicativo para o usuário (internos ou externos) de nossas APIs.

Faça as seguintes alterações nos respectivos arquivos:

…Api.Erp\Api.Erp.Shared\ViewModels\ClienteVM.cs

using NJsonSchema.Annotations;
using System;

namespace Api.Erp.Shared.ViewModels
{
    /// <summary>
    /// Informações para o cadastro do cliente
    /// </summary>
    public class ClienteVM
    {
        /// <summary>
        /// Id do cliente no Banco de Dados
        /// </summary>
        [JsonSchemaExtensionData("example", "15")]
        public string id { get; set; }

        /// <summary>
        /// Nome do cliente
        /// </summary>
        [JsonSchemaExtensionData("example", "Nome do cliente")]
        public string nome { get; set; }

        /// <summary>
        /// Email do cliente
        /// </summary>
        [JsonSchemaExtensionData("example", "emaildocliente@provedor.com.br")]
        public string email { get; set; }
    }
}

…Api.Erp\Api.Erp.Shared\ViewModels\NotaFiscalVmInput.cs

using NJsonSchema.Annotations;

namespace Api.Erp.Shared.ViewModels
{    
    /// <summary>
    /// Informações para geração de uma nova nota fiscal
    /// </summary>
    public class NotaFiscalVmInput
    {
        /// <summary>
        /// Id na Nota Fiscal no Banco de Dados
        /// </summary>
        [JsonSchemaExtensionData("example", "31")]
        public string id { get; set; }

        /// <summary>
        /// Id da venda que será a origem da Nota Fiscal
        /// </summary>
        [JsonSchemaExtensionData("example", "2")]
        public string idVenda { get; set; }

        /// <summary>
        /// Valor total do ICMS. Formato 00000.00
        /// </summary>
        [JsonSchemaExtensionData("example", 1500.90)]
        public decimal valorTotalICMS { get; set; }

        /// <summary>
        /// Valor total da nota fiscal
        /// </summary>
        [JsonSchemaExtensionData("example", 1500.00)]
        public decimal valorTotalNotaFiscal { get; set; }
    }
}

…Api.Erp\Api.Erp.Shared\ViewModels\NotaFiscalVmOutput.cs

namespace Api.Erp.Shared.ViewModels
{
    /// <summary>
    /// Informações da nota fiscal
    /// </summary>
    public class NotaFiscalVmOutput
    {
        /// <summary>
        /// Id na Nota Fiscal no Banco de Dados
        /// </summary>
        public string id { get; set; }

        /// <summary>
        /// Referência para a venda que originou a nota fiscal
        /// </summary>
        public VendaVmOutput Venda { get; set; }

        /// <summary>
        /// Valor total do ICMS
        /// </summary>
        public decimal valorTotalICMS { get; set; }

        /// <summary>
        /// Valor total da nota fiscal
        /// </summary>
        public decimal valorTotalNotaFiscal { get; set; }
    }
}

…Api.Erp\Api.Erp.Shared\ViewModels\VendaVmInput.cs

using NJsonSchema.Annotations;

namespace Api.Erp.Shared.ViewModels
{
    /// <summary>
    /// Informações para geração de uma nova venda
    /// </summary>
    public class VendaVmInput
    {
        /// <summary>
        /// Id na venda no banco de dados
        /// </summary>
        [JsonSchemaExtensionData("example", "3")]
        public string id { get; set; }

        /// <summary>
        /// Id do cliente da venda
        /// </summary>
        [JsonSchemaExtensionData("example", "10")]
        public string idCliente { get; set; }

        /// <summary>
        /// Valor total da venda. Formato 00000.00
        /// </summary>
        [JsonSchemaExtensionData("example", 890.50)]
        public decimal valorTotal { get; set; }
    }
}

…Api.Erp\Api.Erp.Shared\ViewModels\VendaVmOutput.cs

namespace Api.Erp.Shared.ViewModels
{
    /// <summary>
    /// Informações da venda
    /// </summary>
    public class VendaVmOutput
    {
        /// <summary>
        /// Id na venda no banco de dados
        /// </summary>
        public string id { get; set; }

        /// <summary>
        /// Referência para o cliente, para o qual foi executada a venda
        /// </summary>
        public ClienteVM cliente { get; set; }

        /// <summary>
        /// Valor total da venda
        /// </summary>
        public decimal valorTotal { get; set; }
    }
}

As informações incluídas na anotação [JsonSchemaExtensionData("example", "value")] serão utilizadas para a geração dos exemplos de dados na interface do Swagger, porém, para aproveitar as informações incluídas na tag summary, precisamos configurar os nossos projetos para gerar o arquivo XML da documentação (XML Documentation file). Uma maneira muito simples de fazer isso, é editar os arquivos de nossos projetos (extensão .csproj) e incluir as instruções:

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
       <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
       <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

Portanto, dê um clique duplo em cada um dos arquivos de cada projeto (.csproj) e deixe-os da seguinte forma:

…Api.Erp\Api.Erp.Clientes\Api.Erp.Clientes.csproj

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\Api.Erp.Shared\Api.Erp.Shared.csproj" />
  </ItemGroup>

</Project>

…Api.Erp\Api.Erp.Comercial\Api.Erp.Comercial.csproj

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\Api.Erp.Shared\Api.Erp.Shared.csproj" />
  </ItemGroup>

</Project>

…Api.Erp\Api.Erp.Fiscal\Api.Erp.Fiscal.csproj

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\Api.Erp.Shared\Api.Erp.Shared.csproj" />
  </ItemGroup>

</Project>

…Api.Erp\Api.Erp.Shared\Api.Erp.Shared.csproj

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NSwag.AspNetCore" Version="13.3.0" />
  </ItemGroup>

</Project>

Ao executarmos nossas APIs, agora teremos uma riqueza muito maior de detalhes, com instruções precisas para os usuários.

Veja novamente o exemplo do endpoit utilizado para criar uma nova nota fiscal, após as modificações:

Com isto concluímos a parte 2 desta série de artigos.

Obtenha o código completo da solução até o presente momento neste repositório do GitHub.

Links para a série completa:

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – (Parte 1) Construindo o projeto

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – (Parte 2) Incluindo documentação com o Swagger

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços (Parte 3) – Implementando rastreamento distribuído

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – Parte 1

Silvair L. Soares — Thu, 06 Mar 2025 20:03:34 +0000

Com a crescente adoção da arquitetura de microsserviços, inúmeras vantagens são agregadas à rotina dos desenvolvedores de software. Estas vantagens contribuem para a qualidade final dos produtos de software construídos.

No entanto, algumas complexidades são, inevitavelmente acrescentadas.

Vantagens	Desvantagens
Processo de implantação independente	Maior complexidade operacional
Possibilidade de diversidade tecnológica	Necessidade de construir documentação para diversos microssistemas
Feedbacks mais rápidos	Maior dificuldade para encontrar pontos de falhas
Facilidade o processo de entrega contínua	Custo de serialização e desserialização

Estas, são apenas algumas das vantagens e desvantagens deste padrão arquitetural. A intenção desta série de artigos, é te auxiliar a mitigar uma parte desta complexidade.

O que você irá aprender nesta série de artigos?
1.1. Documentação automática das Web APIs
1.2. Depuração e rastreamento de falhas
2. Projeto de exemplo
2.1. Criando os projetos
2.1.1. Criando o projeto Api.Erp.Shared
2.1.1.1. Repositório de dados
2.1.1.2. Serviços HTTP
2.1.1.3. Referenciando o projeto Api.Erp.Shared nos demais projetos
2.1.2. Criando funcionalidades no projeto Api.Erp.Clientes
2.1.3. Criando funcionalidades no projeto Api.Erp.Comercial
2.1.4. Criando funcionalidades no projeto Api.Erp.Fiscal
2.1.5. Configurando a execução dos projetos
2.1.5.1. Configurando o projeto Api.Erp.Clientes
2.1.5.2. Configurando o projeto Api.Erp.Comercial
2.1.5.3. Configurando o projeto Api.Erp.Fiscal
2.1.6. Configurações gerais

1. O que você irá aprender nesta série de artigos?

Enquanto desenvolvemos nossos sistemas utilizando a arquitetura tradicional, também conhecida como arquitetura monolítica, geralmente, não nos preocupamos com alguns fatores, que, à medida que a solução cresce, necessitam de uma atenção especial, são eles:

1.1. Documentação automática das Web APIs

Conforme ganhamos experiência na atividade de desenvolvimento de software, veremos o quão difícil é manter uma documentação clara, objetiva e o mais importante, perfeitamente sincronizada com as inúmeras funcionalidades que criamos diariamente, ou as funcionalidades alteradas, à medida que os requisitos do sistema vão sendo atualizados.

Em um momento ou outro, devido a prazos apertados ou outros fatores que fogem do nosso controle, algum tópico da documentação não estará mais de acordo com a funcionalidade documentada, a partir deste ponto, caso não seja possível atualizar esta parte da documentação, a documentação como um todo não fará mais sentido, pois perdeu a sincronia com a solução. O esforço e o investimento para manter o sincronismo será cada vez maior, pois será difícil ter certeza de que todos os tópicos da documentação estão atualizados.

Este não é um problema exclusivo da arquitetura baseada em microsserviços, porém quando trabalhamos com a arquitetura monolítica, toda a nossa API é disponibilizada em uma única unidade de software, em uma única url (endereço da web), onde serão disponibilizados todos os endpoints que entregam as funcionalidades desenvolvidas. Isto por si só, já torna mais fácil para um membro novo da equipe, ter um entendimento geral do funcionamento do software. Além de ser mais fácil também, para o consumidor externo de nossa API, encontrar em um só local toda a lista de serviços disponíveis.

Atenção: É uma prática recomendada, a adoção do padrão de Gateway de API, para o fornecimento centralizado de funcionalidades de nossas APIs em um único endereço da web, por mais que a implementação esteja distribuída em vários microsserviços, porém este assunto não é tema deste artigo. Sobre isto, você poderá aprender mais aqui.Atenção: É uma prática recomendada, a adoção do padrão de Gateway de API, para o fornecimento centralizado de funcionalidades de nossas APIs em um único endereço da web, por mais que a implementação esteja distribuída em vários microsserviços, porém este assunto não é tema deste artigo. Sobre isto, você poderá aprender mais aqui.

À medida que avançamos na adoção da arquitetura de microsserviços, as funcionalidades de nossa API não serão mais entregues em um único endereço da web, mas em vários. Com isto, torna-se necessário que desenvolvamos uma documentação específica, focada no assunto de cada microsserviço, para cada componente de software que agregamos à nossa solução. Com a adoção dos microsserviços, não deveremos mais construir uma única base de documentação, mas uma para cada componente novo de software que for construído.

Felizmente, temos disponíveis para nos auxiliar na documentação de nossas APIs, uma especificação amplamente utilizada e consolidada, chamada OpenAPI Specification, originalmente conhecida como Swagger Specification.

Com poucas linhas de código e algumas configurações, teremos uma documentação dinâmica e viva, que, além de explicitar todas as funcionalidades de cada Web API, ainda nos permite testar todas as funcionalidades da API, em uma interface gráfica interativa, gerada automaticamente, à medida que criamos novos endpoints em nossa solução.

Temos ainda, a opção de utilizar parte dos comentários incluídos no código fonte como parte desta documentação. Explicarei este assunto mais à frente nesta série de artigos.

Para a nosso projeto de demonstração, utilizaremos a seguinte implementação da especificação OpenAPI para projetos .NET:

NSwag ⇒ Cadeia de ferramentas Swagger/OpenAPI para .NET, ASP.NET Core e TypeScript. Existe outra implementação, amplamente utilizada e igualmente difundida, chamada Swashbuckle. Você pode fazer um comparativo entre estas implementações e escolher a que fizer mais sentido para o seu contexto. Porém para efeito prático, neste artigo, utilizaremos o NSwag.

1.2. Depuração e rastreamento de falhas

Enquanto sua Web API é um monólito, ou seja, construído com apenas um componente de software (1 – Solution ⇒ 1 – Project), basta executar o projeto em uma janela do seu IDE, incluir os breakpoints e iniciar a depuração linha a linha, à procura da falha.

Porém, quando iniciamos a migração para a arquitetura de microsserviços, nossa solução começa a ser fragmentada (granularidade), à medida que novos componentes (microsserviços) são acrescentados. Este aumento do número de componentes em si, não é um problema, mas indiretamente, começa a tornar a depuração e descoberta de erros cada vez mais difícil.

Antes, na arquitetura monolítica, existia apenas uma unidade de software potencialmente, causadora de problemas. Mas com a adoção da arquitetura de microsserviços, temos um leque cada vez maior de possíveis pontos de falhas.

Abrir uma instância do IDE para depurar um projeto, procurando as falhas? Ok. Agora tente acessar 05, 10 ou 15 instâncias do seu IDE, cada uma com um projeto diferente e constate na prática que não é uma prática sustentável.

Felizmente, nem tudo está perdido. Existe um conjunto de práticas e ferramentas, as quais, nos auxiliam neste processo de depuração descentralizado, também conhecido como distributed tracing (rastreamento distribuído).

Neste artigo, abordaremos uma possível solução deste cenário, utilizando as seguintes especificações/ferramentas:

OpenTracing ⇒ Trata-se de uma especificação de API, estruturas e bibliotecas que implementaram a especificação e documentação para o projeto. O OpenTracing permite que os desenvolvedores adicionem instrumentação ao código do aplicativo usando APIs que não os bloqueiam em nenhum produto ou fornecedor em particular;

OpenTracing API for .NET ⇒ Implementação da especificação do OpenTracing para C# (.NET);

Jaeger UI ⇒ Interface gráfica para visualização dos eventos registrados pelo OpenTracing API for .NET.

2. Projeto de exemplo

Para demonstrar a utilização das técnicas e ferramentas apresentadas anteriormente neste artigo, construiremos um grupo de Web APIs para gerenciamento de um sistema ERP. Constituído do seguinte conjunto de Web APIs em .NET Core:

2.1. Criando os projetos

Para a criação dos projetos, utilizarei o Microsoft Visual Studio 2019.

Dentro do Visual Studio, clique no menu File ⇒ New Project:

Selecione a opção ASP.NET Core Web Application e clique em Next.

Dê o nome do primeiro projeto de Api.Erp.Clientes e o nome Api.Erp para a solution. Clique no botão Create.

Selecione o template API e clique no botão Create, para finalizar a criação da solution e do primeiro projeto.

A seguinte tela será exibida, com o primeiro projeto criado:

Clique com o botão direito no ícone da solution, selecione a opção Add ⇒ New Project. Selecione novamente a opção ASP.NET Core Web Application e clique em Next. Desta vez, dê o nome Api.Erp.Comercial para o novo projeto, clique em Next, e utilize novamente o template API.

Repita o passo anterior, porém desta vez, criando um novo projeto chamado Api.Erp.Fiscal.

No final destes passos, teremos uma solution com três projetos:

Exclua os arquivos WeatherForecast.cs e WeatherForecastController.cs de cada um dos três projetos criados. Pois são apenas demonstrações do template API criados automaticamente pelo Visual Studio.

2.1.1. Criando o projeto Api.Erp.Shared

Adicione um novo projeto chamado Api.Erp.Shared do tipo Class Library (.NET Core).

A função deste projeto, é armazenar conteúdos que serão comuns a todos os demais projetos. Uma boa prática para centralização de funcionalidades, evitando replicação de código desnecessária.

Após criar o projeto Api.Erp.Shared, delete o arquivo Class1.cs.

Atenção: Como a nossa intenção aqui é simplesmente demostrar a criação de documentação automática com o NSwag e posteriormente habilitar o OpenTracing para monitoramento de nossas APIs, as deixaremos o mais simples possível. Portanto, não se atenha aos detalhes de implementação de cada uma delas bem como aspectos relacionados a boas práticas de arquitetura de software.

Clique com o botão direito no projeto Api.Erp.Shared, selecione Add ⇒ New Folder e digite o nome ViewModels para o diretório.

No diretório *…Api.Erp\Api.Erp.Shared\ViewModels* crie os seguintes arquivos:

1 – …Api.Erp\Api.Erp.Shared\ViewModels\ClienteVM.cs

namespace Api.Erp.Shared.ViewModels
{
    public class ClienteVM
    {
        public string id { get; set; }
        public string nome { get; set; }
        public string email { get; set; }
    }
}

2 – …Api.Erp\Api.Erp.Shared\ViewModels\VendaVMInput.cs

namespace Api.Erp.Shared.ViewModels
{
    public class VendaVmInput
    {
        public string id { get; set; }
        public string idCliente { get; set; }
        public decimal valorTotal { get; set; }
    }
}

3 – …Api.Erp\Api.Erp.Shared\ViewModels\VendaVMOutput.cs

namespace Api.Erp.Shared.ViewModels
{
    public class VendaVmOutput
    {
        public string id { get; set; }
        public ClienteVM cliente { get; set; }
        public decimal valorTotal { get; set; }
    }
}

4 – …Api.Erp\Api.Erp.Shared\ViewModels\NotaFiscalVmInput.cs

namespace Api.Erp.Shared.ViewModels
{
    public class NotaFiscalVmInput
    {
        public string id { get; set; }
        public string idVenda { get; set; }
        public decimal valorTotalICMS { get; set; }
        public decimal valorTotalNotaFiscal { get; set; }
    }
}

5 – …Api.Erp\Api.Erp.Shared\ViewModels\NotaFiscalVmOutput.cs

namespace Api.Erp.Shared.ViewModels
{
    public class NotaFiscalVmOutput
    {
        public string id { get; set; }
        public VendaVmOutput Venda { get; set; }
        public decimal valorTotalICMS { get; set; }
        public decimal valorTotalNotaFiscal { get; set; }
    }
}

Estas são as view models que utilizaremos para a construção de nossas APIs. Como todos os projetos irão utilizá-las, este é o motivo de estas serem criadas no projeto Api.Erp.Shared.

2.1.1.1. Repositório de dados

Ainda no projeto Api.Erp.Shared, criaremos o nosso repositório de dados.

Como a intenção aqui é apenas demonstrar as funcionalidades de nossa API, não utilizaremos conexão com nenhum banco de dados. Em vez disso, persistiremos nossas informações em variáveis estáticas.

Crie o seguinte arquivo, do diretório Repository do projeto Api.Erp.Shared:

…Api.Erp\Api.Erp\Api.Erp.Shared\Repository\BaseRepository.cs

using Api.Erp.Shared.ViewModels;
using System.Collections.Generic;

namespace Api.Erp.Shared.Repository
{
    public static class BaseRepository
    {
        static BaseRepository()
        {
            CriarDadosModelo();
        }

        private static void CriarDadosModelo()
        {
            // Na primeira execução, inclui alguns clientes para teste
            if (RepositorioClientes == null)
            {
                RepositorioClientes = new List<ClienteVM>();
                ClienteVM cliente1 = new ClienteVM();
                cliente1.id = "10";
                cliente1.nome = "Silvair Leite Soares";
                cliente1.email = "silvairsoares@outlook.com";
                RepositorioClientes.Add(cliente1);

                ClienteVM cliente2 = new ClienteVM();
                cliente2.id = "11";
                cliente2.nome = "José da Silva Sobrinho";
                cliente2.email = "josesobrinho@outlook.com";
                RepositorioClientes.Add(cliente2);
            }

            // Na primeira execução, inclui algumas vendas para teste
            if (RepositorioVendas == null)
            {
                RepositorioVendas = new List<VendaVmInput>();
                VendaVmInput venda1 = new VendaVmInput();
                venda1.id = "1";
                venda1.idCliente = "10";
                venda1.valorTotal = 100;
                RepositorioVendas.Add(venda1);

                VendaVmInput venda2 = new VendaVmInput();
                venda2.id = "2";
                venda2.idCliente = "11";
                venda2.valorTotal = 1500;
                RepositorioVendas.Add(venda2);
            }

            // Na primeira execução, inclui algumas notas fiscais para teste
            if (RepositorioNotasFiscais == null)
            {
                RepositorioNotasFiscais = new List<NotaFiscalVmInput>();
                NotaFiscalVmInput notafiscal1 = new NotaFiscalVmInput();
                notafiscal1.id = "20";
                notafiscal1.idVenda = "1";
                notafiscal1.valorTotalICMS = 100;
                notafiscal1.valorTotalNotaFiscal = 110;
                RepositorioNotasFiscais.Add(notafiscal1);

                NotaFiscalVmInput notafiscal2 = new NotaFiscalVmInput();
                notafiscal2.id = "30";
                notafiscal2.idVenda = "2";
                notafiscal2.valorTotalICMS = 800;
                notafiscal2.valorTotalNotaFiscal = 100;
                RepositorioNotasFiscais.Add(notafiscal2);
            }
        }

        // Variável para persistência temporária de clientes, somente para demonstração
        public static ICollection<ClienteVM> RepositorioClientes;

        // Variável para persistência temporária de vendas, somente para demonstração
        public static ICollection<VendaVmInput> RepositorioVendas;

        // Variável para persistência temporária de notas fiscais, somente para demonstração
        public static ICollection<NotaFiscalVmInput> RepositorioNotasFiscais;
    }
}

2.1.1.2. Serviços HTTP

Criaremos agora, no projeto Api.Erp.Shared, alguns serviços http que serão responsáveis pela comunicação REST entre os microsserviços.

Crie os seguintes arquivos, do diretório Http do projeto Api.Erp.Shared:

1 – …Api.Erp\Api.Erp\Api.Erp.Shared\Http\RequestHttp.cs

Este será um serviço genérico, utilizado para efetuar requisições http GET, entre os microserviços.

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace Api.Erp.Shared.Http
{
    public static class RequestHttp
    {
        public static async Task<string> Request(string url)
        {
            HttpClient client = new HttpClient();

            client.BaseAddress = new Uri(url);
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

            var response = await client.GetStringAsync(url);
            return response;
        }
    }
}

2 – …Api.Erp\Api.Erp\Api.Erp.Shared\Http\ClienteServices.cs

Este será o serviço http que pesquisará um cliente específico por id, na Api.Erp.Clientes.

using Api.Erp.Shared.ViewModels;
using System.Text.Json;
using System.Threading.Tasks;

namespace Api.Erp.Shared.Http
{
    public static class ClienteServices
    {
        public static async Task<ClienteVM> PesquisarPorId(string id)
        {
            // Rota que retorna um cliente pelo id pesquisado
            var url = "http://localhost:5000/api/cliente/" + id;

            // Executa a requisição http
            var response = await RequestHttp.Request(url);

            // Converte o JSON retornado pela api em um objeto do tipo ClienteVM
            ClienteVM cliente = JsonSerializer.Deserialize<ClienteVM>(response);
            return cliente;
        }
    }
}

3 – …Api.Erp\Api.Erp\Api.Erp.Shared\Http\FiscalServices.cs

Este será o serviço http que receberá um resumo de uma nota fiscal, obterá os dados da venda, na Api.Erp.Comercial. E retornará a nota fiscal completa, contendo os dados da venda, juntamente com os dados do cliente da venda (Nota Fiscal ⇒ Venda ⇒ Cliente)

using Api.Erp.Shared.ViewModels;
using System.Text.Json;
using System.Threading.Tasks;

namespace Api.Erp.Shared.Http
{
    public static class FiscalServices
    {
        public static async Task<NotaFiscalVmOutput> ObterNotaFiscalCompleta(NotaFiscalVmInput notafiscal)
        {
            // Pesquisa a venda da notafiscal na Api.Erp.Comercial
            VendaVmOutput vendaDaNotaFiscal = await PesquisarVendaPorId(notafiscal.idVenda);

            // Cria um objeto com os dados completos da notafiscal, para retornar para o usuário
            NotaFiscalVmOutput notafiscalCompleta = new NotaFiscalVmOutput();
            notafiscalCompleta.id = notafiscal.id;
            notafiscalCompleta.Venda = vendaDaNotaFiscal;
            notafiscalCompleta.valorTotalICMS = notafiscal.valorTotalICMS;
            notafiscalCompleta.valorTotalNotaFiscal = notafiscal.valorTotalNotaFiscal;

            return notafiscalCompleta;
        }

        private static async Task<VendaVmOutput> PesquisarVendaPorId(string id)
        {
            // Rota que retorna uma venda pelo id pesquisado
            var url = "http://localhost:5003/api/venda/" + id;

            // Executa a requisição http de forma assíncrona
            var response = await RequestHttp.Request(url);

            // Converte o JSON retornado pela api em um objeto do tipo VendaVmOutput
            VendaVmOutput venda = JsonSerializer.Deserialize<VendaVmOutput>(response);
            return venda;
        }
    }
}

4 – …Api.Erp\Api.Erp\Api.Erp.Shared\Http\ComercialServices.cs

Este será o serviço http que fará todas as operações relacionadas às vendas, registradas na Api.Erp.Comercial.

using Api.Erp.Shared.Repository;
using Api.Erp.Shared.ViewModels;
using System;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;

namespace Api.Erp.Shared.Http
{
    public static class ComercialServices
    {
        public static async Task<VendaVmOutput> PesquisarPorId(string id)
        {
            // Rota que retorna uma venda pelo id pesquisado
            var url = "http://localhost:5003/api/venda/" + id;

            // Executa a requisição http de forma assíncrona
            var response = await RequestHttp.Request(url);

            // Converte o JSON retornado pela api em um objeto do tipo VendaVmInput
            VendaVmInput venda = JsonSerializer.Deserialize<VendaVmInput>(response);

            return await ObterVendaCompleta(venda);
        }

        public static async Task<VendaVmOutput> ObterVendaCompleta(VendaVmInput venda)
        {
            // Pesquisa o cliente da venda na Api.Erp.Clientes
            ClienteVM clienteDaVenda = await ClienteServices.PesquisarPorId(venda.idCliente);

            // Cria um objeto com os dados completos da venda, para retornar para o usuário
            VendaVmOutput vendaCompleta = new VendaVmOutput();
            vendaCompleta.id = venda.id;
            vendaCompleta.cliente = clienteDaVenda;
            vendaCompleta.valorTotal = venda.valorTotal;

            return vendaCompleta;
        }

        public static async Task<VendaVmOutput> ObterVendaCompletaPorId(string id)
        {
            // Obtem os dados da venda, salvos no repositório de vendas
            var venda = BaseRepository.RepositorioVendas.Where(cli => cli.id == id).FirstOrDefault();

            return await ObterVendaCompleta(venda);
        }
    }
}

2.1.1.3. Referenciando o projeto Api.Erp.Shared nos demais projetos

O próximo passo é referenciar o projeto Api.Erp.Shared nos os demais projetos. Para isso, clique com o botão direito na opção Depencencies de cada um dos projetos (Api.Erp.Clientes, Api.Erp.Comercial e Api.Erp.Fiscal), selecione a opção Add Projects Reference…, acesse a aba Projects, marque o projeto Api.Erp.Shared e clique em OK.

Lembre-se de repetir este processo em todos os projetos (Api.Erp.Clientes, Api.Erp.Comercial e Api.Erp.Fiscal).

2.1.2. Criando funcionalidades no projeto Api.Erp.Clientes

Crie o seguinte arquivo no projeto Api.Erp.Clientes:

…\Api.Erp\Api.Erp.Clientes\Controllers\ClienteController.cs

Este será o controller que processará todas as requisições do Api.Erp.Clientes.

using Api.Erp.Shared.Repository;
using Api.Erp.Shared.ViewModels;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;

namespace Api.Erp.Clientes.Controllers
{
    [Route("api/cliente/")]
    public class ClienteController : Controller
    {
        [HttpPost]
        public ClienteVM Add([FromBody] ClienteVM DadosCliente)
        {
            BaseRepository.RepositorioClientes.Add(DadosCliente);
            return DadosCliente;
        }

        [HttpGet("{id}")]
        public ClienteVM GetClienteById(string id)
        {
            var cliente = BaseRepository.RepositorioClientes.Where(cli => cli.id == id).FirstOrDefault();
            return cliente;
        }

        [HttpGet]
        public ICollection<ClienteVM> GetAllClientes()
        {
            return BaseRepository.RepositorioClientes;
        }

        [HttpDelete("{id}")]
        public object Deletar(string id)
        {
            var cliente = BaseRepository.RepositorioClientes.Where(cli => cli.id == id).FirstOrDefault();
            if (BaseRepository.RepositorioClientes.Remove(cliente))
            {
                return new
                {
                    resultado = "Cliente: " + id + " excluido com sucesso!"
                };
            }
            else
            {
                return new
                {
                    resultado = "Erro ao excluir o cliente " + id
                };
            }
        }
    }
}

2.1.3. Criando funcionalidades no projeto Api.Erp.Comercial

Crie o seguinte arquivo no projeto Api.Erp.Comercial:

…\Api.Erp\Api.Erp.Comercial\Controllers\VendaController.cs

Este será o controller que processará todas as requisições do Api.Erp.Comercial.

using Api.Erp.Shared.Http;
using Api.Erp.Shared.Repository;
using Api.Erp.Shared.ViewModels;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Api.Erp.Comercial.Controllers
{
    [Route("api/venda/")]
    public class VendaController : Controller
    {
        [HttpPost]
        public async Task<VendaVmOutput> Add([FromBody] VendaVmInput DadosVenda)
        {
            BaseRepository.RepositorioVendas.Add(DadosVenda);
            return await ComercialServices.ObterVendaCompleta(DadosVenda);
        }

        [HttpGet("{id}")]
        public async Task<VendaVmOutput> GetVendaById(string id)
        {
            // Obtem os dados da venda, salvos no repositório de vendas
            var venda = BaseRepository.RepositorioVendas.Where(cli => cli.id == id).FirstOrDefault();
            VendaVmOutput vendaCompleta = await ComercialServices.ObterVendaCompleta(venda);

            return vendaCompleta;
        }

        [HttpGet]
        public async Task<ICollection<VendaVmOutput>> GetAllVendas()
        {
            ICollection<VendaVmOutput> vendasCompletas = new List<VendaVmOutput>();

            foreach (var item in BaseRepository.RepositorioVendas)
            {
                vendasCompletas.Add(await ComercialServices.ObterVendaCompleta(item));
            }

            return vendasCompletas;
        }

        [HttpDelete("{id}")]
        public object Deletar(string id)
        {
            var venda = BaseRepository.RepositorioVendas.Where(cli => cli.id == id).FirstOrDefault();
            if (BaseRepository.RepositorioVendas.Remove(venda))
            {
                return new
                {
                    resultado = "Venda: " + id + " excluida com sucesso!"
                };
            }
            else
            {
                return new
                {
                    resultado = "Erro ao excluir o venda " + id
                };
            }
        }
    }
}

2.1.4. Criando funcionalidades no projeto Api.Erp.Fiscal

Crie o seguinte arquivo no projeto Api.Erp.Fiscal:

…\Api.Erp\Api.Erp.Fiscal\Controllers\NotaFiscalController.cs

Este será o controller que processará todas as requisições do Api.Erp.Fiscal.

using Api.Erp.Shared.Http;
using Api.Erp.Shared.Repository;
using Api.Erp.Shared.ViewModels;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Api.Erp.Fiscal.Controllers
{
    [Route("api/notafiscal/")]
    public class NotaFiscalController : Controller
    {
        [HttpPost]
        public async Task<NotaFiscalVmOutput> Add([FromBody] NotaFiscalVmInput DadosNotaFiscal)
        {
            BaseRepository.RepositorioNotasFiscais.Add(DadosNotaFiscal);
            return await FiscalServices.ObterNotaFiscalCompleta(DadosNotaFiscal);
        }

        [HttpGet("{id}")]
        public async Task<NotaFiscalVmOutput> GetNotaFiscalById(string id)
        {
            // Obtem os dados da notafiscal, salvos no repositório de notas fiscais
            var notafiscal = BaseRepository.RepositorioNotasFiscais.Where(cli => cli.id == id).FirstOrDefault();
            NotaFiscalVmOutput notafiscalCompleta = await FiscalServices.ObterNotaFiscalCompleta(notafiscal);

            return notafiscalCompleta;
        }

        [HttpGet]
        public async Task<ICollection<NotaFiscalVmOutput>> GetAllNotaFiscais()
        {
            ICollection<NotaFiscalVmOutput> notafiscaisCompletas = new List<NotaFiscalVmOutput>();

            foreach (var item in BaseRepository.RepositorioNotasFiscais)
            {
                notafiscaisCompletas.Add(await FiscalServices.ObterNotaFiscalCompleta(item));
            }

            return notafiscaisCompletas;
        }

        [HttpDelete("{id}")]
        public object Deletar(string id)
        {
            var notafiscal = BaseRepository.RepositorioNotasFiscais.Where(cli => cli.id == id).FirstOrDefault();
            if (BaseRepository.RepositorioNotasFiscais.Remove(notafiscal))
            {
                return new
                {
                    resultado = "Nota fiscal: " + id + " excluida com sucesso!"
                };
            }
            else
            {
                return new
                {
                    resultado = "Erro ao excluir a nota fiscal " + id
                };
            }
        }
    }
}

2.1.5. Configurando a execução dos projetos

Vamos fazer algumas configurações para a execução de nossos projetos.

2.1.5.1. Configurando o projeto Api.Erp.Clientes

Clique com o botão direito no projeto Api.Erp.Clientes, selecione a opção Properties, na janela de propriedades do projeto, na aba Debug, altere o valor dos seguintes campos respectivamente:

Profile: Api.Erp.Clientes
Launch: Project
Launch browser:
App URL: https://localhost:5001;http://localhost:5000

2.1.5.2. Configurando o projeto Api.Erp.Comercial

Clique com o botão direito no projeto Api.Erp.Comercial, selecione a opção Properties, na janela de propriedades do projeto, na aba Debug, altere o valor dos seguintes campos respectivamente:

Profile: Api.Erp.Comercial
Launch: Project
Launch browser:
**App URL: https://localhost:5002;http://localhost:5003

2.1.5.3. Configurando o projeto Api.Erp.Fiscal

Clique com o botão direito no projeto Api.Erp.Fiscal, selecione a opção Properties, na janela de propriedades do projeto, na aba Debug, altere o valor dos seguintes campos respectivamente:

Profile: Api.Erp.Fiscal
Launch: Project
Launch browser:
App URL: https://localhost:5004;http://localhost:5005

2.1.6. Configurações gerais

No método Configure do arquivo Startup.cs de cada um dos projetos (Api.Erp.Clientes, Api.Erp.Comercial e Api.Erp.Fiscal), comente a seguinte instrução:

app.UseHttpsRedirection();

Clique com o botão direito na solution Api.Erp, selecione Properties, acesse a aba Common Properties ⇒ Startup Project, desabilite a opção Current selection, habilite Multiple startup projects:. Na coluna Action, selecione a opção Start, para as 3 APIs (Api.Erp.Clientes, Api.Erp.Comercial e Api.Erp.Fiscal).

Com isto, concluímos a primeira etapa do nosso artigo. Fizemos uma apresentação dos problemas e criamos a nossa aplicação, com as APIs para exemplo.

Para ver todas as APIs em execução, basta pressionar a tecla F5.

Enquanto não habilitamos o Swagger em nossas APIs, você poderá utilizar o Postman para testar todos os serviços das APIs. Baixe a coleção com as requisições do postman aqui.

Obtenha o código completo da solução até o presente momento neste repositório do GitHub.

Links para a série completa:

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – (Parte 1) Construindo o projeto

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços – (Parte 2) Incluindo documentação com o Swagger

Criando Web APIs modernas, autônomas e rastreáveis com .Net Core utilizando arquitetura de microsserviços (Parte 3) – Implementando rastreamento distribuído

Criando métodos HTTP PATCH, usando o AutoMapper

Silvair L. Soares — Fri, 09 Aug 2024 20:56:55 +0000

Protocolo HTTP

O protocolo HTTP (HyperText Transfer Protocol) é a base da comunicação na web, definindo como os clientes (navegadores, aplicativos) se comunicam com os servidores para solicitar e receber dados. Uma parte fundamental desse protocolo são os métodos HTTP, que indicam a ação que se deseja realizar sobre um recurso.

Métodos HTTP

Métodos HTTP, são um conjunto de convenções definidas pelo protocolo HTTP, através dos quais, usuários de um serviço web podem solicitar à um servidor web, que uma ação específica seja executada.

Os métodos HTTP mais comuns

GET: Utilizado para obter ou recuperar dados de um recurso específico. É o método mais simples e idempotente (pode ser repetido várias vezes sem alterar o resultado).
POST: Empregado para criar novos recursos. É frequentemente utilizado para enviar dados para um servidor, como em formulários.
PUT: Serve para atualizar um recurso completamente. Substitui a representação atual do recurso por uma nova.
DELETE: Usado para excluir um recurso.
PATCH: Similar ao PUT, mas permite atualizar apenas partes específicas de um recurso.
HEAD: Retorna apenas os cabeçalhos da resposta, sem o corpo. É útil para verificar o status de um recurso sem baixar todo o conteúdo.

Neste artigo, apresentarei uma proposta de implementação de um endpoint HTTP PATCH.

Este tipo de serviço, apresenta algumas nuances um pouco diferentes e até desafiadoras, em comparação aos demais métodos HTTP.

Serviços que atendem requisições do tipo PATCH, geralmente exigem que apenas a parte do recurso a ser modificado seja enviada, o que pode tornar a operação do lado do cliente um pouco mais complexa, pois o payload a ser enviado se torna dinâmico.

Para lidar com esta complexidade, foi criado RFC 6902 chamado JSON Patch, o qual define um padrão para transmissão das informações que devem ser modificadas do lado do servidor.

O JSON Patch oferece ao usuário ações como inclusão, exclusão, substituição, etc de apenas uma parte do recurso armazenado no servidor.

Veja neste artigo, como configurar a implementação oficial para .Net.

Ao longo deste artigo, vamos construir uma API para gestão de Pessoas.

Tendo como exemplo, o seguinte conjunto de classes em C#:

public class Endereco
{
    public string? Rua { get; set; }
    public string? Complemento { get; set; }
}

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

Uma requisição utilizando JSON Patch, que tenha interesse em modificar uma parte do recurso que tenha sido salvo com o tipo Pessoa, definido anteriormente, seria algo como:

[
  {
    "path": "/nome",
    "op": "replace",
    "value": "Silvair Leite Soares - Nome alterado via jsonpatch"
  },
  {
    "path": "/endereco/rua",
    "op": "replace",
    "value": "Rua do endereço alterada"
  }
]

A implementação do serviço que recebe este payload, seria algo como:

Endpoint que executa a atualização via JsonPath:

using HttpPatchWithAutoMapper.Domain.Pessoas;
using HttpPatchWithAutoMapper.Domain.Pessoas.ViewModels;
using Microsoft.AspNetCore.JsonPatch;
using Microsoft.AspNetCore.Mvc;

namespace HttpPatchWithAutoMapper.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PessoasController : ControllerBase
    {
        private readonly IPessoasServices _pessoasServices;

        public PessoasController(IPessoasServices pessoasServices)
        {
            _pessoasServices = pessoasServices;
        }        

        /// <summary>
        /// Atualiza parcialmente uma pessoa usando JSON Patch
        /// </summary>
        /// <returns></returns>
        [HttpPatch("api/pessoas/JsonPatch/")]
        public async Task<Pessoa> UpdateJsonPatch(string id, [FromBody] JsonPatchDocument<Pessoa> pessoa)
        {
            return await _pessoasServices.UpdateJsonPatch(id, pessoa);
        }
    }
}

Demonstração de uma requisição:

curl -X 'PATCH' \
  'https://localhost:7281/Pessoas/api/pessoas/JsonPatch?id=d892792b-a7ac-481e-b0af-5adc62d51ce4' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "path": "/nome",
    "op": "replace",
    "value": "Silvair Leite Soares - Nome alterado via jsonpatch"
  },
  {
    "path": "/endereco/rua",
    "op": "replace",
    "value": "Rua do endereço alterado"
  }
]'

Implementação do serviço que executa a atualização via JsonPath:

using AutoMapper;
using HttpPatchWithAutoMapper.Domain.Pessoas.ViewModels;
using Microsoft.AspNetCore.JsonPatch;
using Microsoft.AspNetCore.JsonPatch.Exceptions;
using Microsoft.AspNetCore.Mvc;

namespace HttpPatchWithAutoMapper.Domain.Pessoas
{
    public class PessoasServices : IPessoasServices
    {
        private static ICollection<Pessoa> pessoas = new List<Pessoa>();

        public async Task<Pessoa> UpdateJsonPatch(string id, [FromBody] JsonPatchDocument<Pessoa> pessoa)
        {
            var pessoaSalva = pessoas.FirstOrDefault(p => p.Id == id);
            if (pessoaSalva == null)
            {
                throw new ArgumentException("Pessoa não encontrada");
            }

            try
            {
                // Aqui é o local em que os comandos definidos no objeto 'pessoa' 
                // são aplicados, atualizando o objeto 'pessoaSalva'
                pessoa.ApplyTo(pessoaSalva);

                return pessoaSalva;
            }
            catch (JsonPatchException ex)
            {
                throw ex;
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
}

Esta implementação funciona bem, porém o processo de geração do payload de atualização do lado do cliente, se torna extremamente complexo. Pois precisamos criar uma operação para cada propriedade que o usuário deseja alterar. Dessa forma, o payload para atualização dos recursos do servidor, tende a ficar cada vez maior e mais complexo

[
    { "op": "replace", "path": "/a/b/c", "value": "novo valor" },
    { "op": "replace", "path": "/a/b/c", "value": "C" },
     ...
]

Na imagem abaixo, um exemplo de requisição no Swagger, que altera o nome e a rua do endereço da pessoa com o id "d892792b-a7ac-481e-b0af-5adc62d51ce4".

É um payload bem verboso para executar pequenas alterações. Além de obrigamos que o cliente de nossa API entenda o padrão definido na RFC 6902.

Neste ponto o AutoMapper pode contribuir bastante. Utilizando-o, podemos criar um endpoint que recebe o mesmo payload usado para fazer uma inclusão (HTTP POST) ou atualização completa (HTTP PUT):

{
  "id": "d892792b-a7ac-481e-b0af-5adc62d51ce4",
  "nome": "Silvair Leite Soares",
  "idade": "40",
  "endereco": {
    "rua": "Nome da rua da pessoa",
    "complemento": "Complemento do endereço"
  }
}

De forma que as propriedades que forem omitidas (com valor igual à null), permanecerão inalteradas no repositório de dados.

{
    "id": "d892792b-a7ac-481e-b0af-5adc62d51ce4",
    "nome": "Silvair Leite Soares - Nome alterado via jsonpatch",
    "idade": null,
    "endereco": {
    "rua": "Nome da rua da pessoa",
    "complemento": null
  }
}

Vamos à implementação.

O primeiro passo é incluir a referência ao pacote nuget do AutoMapper no projeto. Para isso execute o comando:

dotnet add package AutoMapper --version 13.0.1

Endpoint que executa a atualização via AutoMapper:

using HttpPatchWithAutoMapper.Domain.Pessoas;
using HttpPatchWithAutoMapper.Domain.Pessoas.ViewModels;
using Microsoft.AspNetCore.JsonPatch;
using Microsoft.AspNetCore.Mvc;

namespace HttpPatchWithAutoMapper.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PessoasController : ControllerBase
    {
        private readonly IPessoasServices _pessoasServices;

        public PessoasController(IPessoasServices pessoasServices)
        {
            _pessoasServices = pessoasServices;
        }        

        /// <summary>
        /// Atualiza parcialmente uma pessoa usando o AutoMapper
        /// </summary>
        /// <returns></returns>
        [HttpPatch("api/pessoas/AutoMapper")]
        public async Task<Pessoa> UpdateAutoMapper([FromBody] Pessoa pessoa)
        {
            return await _pessoasServices.UpdateAutoMapper(pessoa);
        }
    }
}

Implementação do serviço que executa a atualização via AutoMapper:

using AutoMapper;
using HttpPatchWithAutoMapper.Domain.Pessoas.ViewModels;
using Microsoft.AspNetCore.JsonPatch;
using Microsoft.AspNetCore.JsonPatch.Exceptions;
using Microsoft.AspNetCore.Mvc;

namespace HttpPatchWithAutoMapper.Domain.Pessoas
{
    public class PessoasServices : IPessoasServices
    {
        private static ICollection<Pessoa> pessoas = new List<Pessoa>();

public Task<Pessoa> UpdateAutoMapper(Pessoa pessoa)
{
    var existingPessoa = pessoas.FirstOrDefault(p => p.Id == pessoa.Id);
    if (existingPessoa == null)
    {
        throw new ArgumentException("Pessoa não encontrada");
    }

    // Configuração do AutoMapper
    var configAutoMapper = new MapperConfiguration(cfg =>
    {
        cfg.CreateMap<Pessoa, Pessoa>()
            .ForAllMembers(opt => opt.Condition((src, dest, srcMember) => srcMember != null));

        cfg.CreateMap<Endereco, Endereco>()
            .ForAllMembers(opt => opt.Condition((src, dest, srcMember) => srcMember != null));                
    });

    // Inclui configuração de mapeamento personalizada, para copiar apenas itens não nulos
    var mapper = configAutoMapper.CreateMapper();

    // Faz o merge das informações salvas no repositório, 
    // com as propriedades não nulas enviadas pelo usuário da API
    mapper.Map(pessoa, existingPessoa);

    return Task.FromResult(existingPessoa);
}

    }    
}

Precisamos configurar cada uma das propriedades de tipos complexos (Pessoa e Endereco), que deveremos copiar apenas as propriedades não nulas, ou seja, as propriedades que o usuário da API enviou na requisição.

Esta instrução é a responsável por definir esta condição no AutoMapper:

.ForAllMembers(opt => opt.Condition((src, dest, srcMember) => srcMember != null));

Para atualizar apenas algumas propriedades do recurso que foi anteriormente incluido no repositório de dados, poderemos enviar requisições simples assim:

{
    "id": "d892792b-a7ac-481e-b0af-5adc62d51ce4",
    "nome": "Silvair Leite Soares - Nome alterado via AutoMapper",
    "idade": null, // <-Esta propriedade permanecerá inalterada
    "endereco": {
        "rua": "Nome da rua da pessoa alterada via AutoMapper",
        "complemento": null // <-Esta propriedade permanecerá inalterada
  }
}

curl -X 'PATCH' \
  'https://localhost:7281/Pessoas/api/pessoas/AutoMapper' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "d892792b-a7ac-481e-b0af-5adc62d51ce4",
    "nome": "Silvair Leite Soares - Nome alterado via AutoMapper",
    "idade": null,
    "endereco": {
    "rua": "Nome da rua da pessoa alterada via AutoMapper",
    "complemento": null
  }
}'

Na imagem abaixo, um exemplo de requisição no Swagger, que altera o nome e a rua do endereço da pessoa com o id "d892792b-a7ac-481e-b0af-5adc62d51ce4".

Esta proposta exige um pouco mais de configuração, mas em contrapartida simplifica absurdamente a operação por parte do cliente da API. Já que o payload exigido pelos métodos POST, PUT e PATCH, serão os mesmos.

Veja aqui o código completo do projeto no GitHub.

Usando o chat do Bing como um aliado para escrever testes de software

Silvair L. Soares — Thu, 04 May 2023 16:17:26 +0000

Imagem gerada com a ferramenta Criador de Imagens do Bing.

A criação de testes é uma parte crucial do processo de desenvolvimento de software. Pois garante que o software funcione corretamente e atenda às expectativas dos usuários.

No entanto, um desafio enfrentado pelos desenvolvedores é obter dados falsos e aleatórios para serem usados nestes testes. Dados falsos são necessários para simular cenários realistas e garantir que o software seja capaz de lidar com diferentes situações.

Para auxiliar na geração de dados falsos para os testes, existe uma excelente biblioteca chamada Bogus, disponível nesse repositório do Nuget.

Esta biblioteca auxilia na geração de instâncias de dados fakes, de acordo com as classes do seu projeto.

Um pequeno exemplo:

 public class NotaFiscal

    public long Id { get; set; }
    public int Operacao { get; set; }
    public string TipoEmissao { get; set; }
    public string ModeloDocumento { get; set; }
    public string Situacao { get; set; }
    public int Serie { get; set; }
    public int Numero { get; set; }
    public DateTime DataEmissao { get; set; }
    public DateTime DataEntradaSaida { get; set; } 
}

Para gerar uma instância fake da classe NotaFiscal, poderíamos fazer o seguinte código usando o Bogus:

using Bogus;

namespace Exemplo
{
    public class NotaFiscalFaker : Faker<NotaFiscal>
    {
        public NotaFiscalFaker()
        {
            RuleFor(n => n.Id, f => f.Random.Long(1));
            RuleFor(n => n.Operacao, f => f.Random.Int(1));
            RuleFor(n => n.TipoEmissao, f => f.Random.String2(10));
            RuleFor(n => n.ModeloDocumento, f => f.Random.String2(10));
            RuleFor(n => n.Situacao, f => f.Random.String2(10));
            RuleFor(n => n.Serie, f => f.Random.Int(1));
            RuleFor(n => n.Numero, f => f.Random.Int(1));
            RuleFor(n => n.DataEmissao, f=>f.Date.Recent());
            RuleFor(n=>n.DataEntradaSaida,f=>f.Date.Recent());
        }
    }
}

Você pode usar esse builder da seguinte maneira:

var faker = new NotaFiscalFaker();
var fakeNotaFiscal = faker.Generate();

Com este pequeno exemplo, dá pra perceber que o Bogus, é uma mão-na-roda. Mas imagine um cenário em que tenhamos centenas de classes de dados extensas, daria um trabalhão, gerar um builder para cada uma dessas classes. Manter esses builders, à medida que estas classes vão sendo evoluídas, também dará um trabalho extra.

O Chat do novo Bing, pode nos ajudar com este trabalho braçal e maçante.

Abaixo, descrevo minha conversa com o Chat do Bing, e mostro o excelente resultado que ele me deu, durante a geração de builders, para as seguintes classes em c#:

NotaFiscal:

public class NotaFiscal
{
    public long Id { get; set; }

    /// <summary> 
    /// IND_OPER - Indicador do tipo de operação:
    /// 
    /// <para>0 - Entrada</para> 
    /// <para>1 - Saída</para> 
    /// </summary> 
    public int Operacao { get; set; }

    /// <summary> 
    /// IND_EMIT - Indicador do emitente do documento fiscal:
    /// 
    /// <para>0 - Emissão própria</para> 
    /// <para>1 - Terceiros</para> 
    /// </summary> 
    public string TipoEmissao { get; set; }

    public NotaFiscalProdutoNaturezaOperacao NaturezaOperacao { get; set; }

    public Participante Participante { get; set; }

    public string ModeloDocumento { get; set; }

    public string Situacao { get; set; }

    public int Serie { get; set; }

    public int Numero { get; set; }

    public string Chave { get; set; }

    public DateTime DataEmissao { get; set; }

    public DateTime DataEntradaSaida { get; set; }

    public decimal ValorTotal { get; set; }

    public int TipoPagamento { get; set; }

    public decimal ValorDesconto { get; set; }

    public decimal ValorAbatimento { get; set; }

    public decimal ValorMercadorias { get; set; }

    public int TipoTransporte { get; set; }

    public decimal ValorFrete { get; set; }

    public decimal ValorSeguro { get; set; }

    public decimal ValorDespesas { get; set; }

    public decimal ICMS_BC { get; set; }

    public decimal ICMS_Aliquota { get; set; }

    public decimal ICMS_Valor { get; set; }

    public decimal ICMS_ST_BC_Valor { get; set; }

    public decimal ICMS_ST_Retido_Valor { get; set; }

    public decimal IPI_Valor { get; set; }

    public decimal PIS_Valor { get; set; }

    public decimal PIS_ST_Valor { get; set; }

    public decimal COFINS_Valor { get; set; }

    public decimal COFINS_ST_Valor { get; set; }

    public List<NotaFiscalProduto> Produtos { get; set; }

}

Participante:

public class Participante
{
    public long Id { get; set; }
    public string Codigo { get; set; }
    public string Nome { get; set; }
    public string Cod_Pais { get; set; }
    public string CNPJ { get; set; }
    public string CPF { get; set; }
    public string IE { get; set; }
    public string SUFRAMA { get; set; }
    public string EnderecoCod_Mun { get; set; }
    public string EnderecoLogradouro { get; set; }
    public string EnderecoNumero { get; set; }
    public string EnderecoComplemento { get; set; }
    public string EnderecoBairro { get; set; }
}

Produto:

public class Produto
{
    public long Id { get; set; }
    public string Codigo { get; set; }
    public string Descricao { get; set; }
    public NotaFiscalProdutoUnidade Unidade { get; set; }
    public int Origem { get; set; }
    public string NCM { get; set; }
    public string CEST { get; set; }
    public decimal ICMS_Aliquota { get; set; }
}

NotaFiscalProduto:

public class NotaFiscalProduto
{
    public long NotaFiscalId { get; set; }
    public int Numero { get; set; }
    public Produto Produto { get; set; }
    public decimal Quantidade { get; set; }
    public decimal ValorTotal { get; set; }
    public decimal Desconto { get; set; }
    public int Movimentado { get; set; }
    public string ICMS_CST { get; set; }
    public string CFOP { get; set; }
    public decimal ICMS_BC { get; set; }
    public decimal ICMS_Aliquota { get; set; }
    public decimal ICMS_Valor { get; set; }
    public decimal ICMS_ST_BC { get; set; }
    public decimal ICMS_ST_Aliquota { get; set; }
    public decimal ICMS_ST_Valor { get; set; }
    public int IPI_Apuracao { get; set; }
    public string IPI_CST { get; set; }
    public string IPI_Enquadramento { get; set; }
    public decimal IPI_BC { get; set; }
    public decimal IPI_Aliquota { get; set; }
    public decimal IPI_Valor { get; set; }
    public string PIS_CST { get; set; }
    public decimal PIS_BC { get; set; }
    public decimal PIS_Aliquota { get; set; }
    public decimal PIS_BC_Quantidade { get; set; }
    public decimal PIS_Aliquota_Reais { get; set; }
    public decimal PIS_Valor { get; set; }
    public string COFINS_CST { get; set; }
    public decimal COFINS_BC { get; set; }
    public decimal COFINS_Aliquota { get; set; }
    public decimal COFINS_BC_Quantidade { get; set; }
    public decimal COFINS_Aliquota_Reais { get; set; }
    public decimal COFINS_Valor { get; set; }
    public string ContaContabil { get; set; }
    public decimal ValorAbatimento { get; set; }
}

NotaFiscalProdutoUnidade:

public class NotaFiscalProdutoUnidade
{
    public long Id { get; set; }
    public string Codigo { get; set; }
    public string Simbolo { get; set; }
}

NotaFiscalProdutoNaturezaOperacao:

public class NotaFiscalProdutoNaturezaOperacao
{
    public long Id { get; set; }
    public string Codigo { get; set; }
    public string Descricao { get; set; }
}

Abaixo, a transcrição da minha conversa com o chat do Bing:

Meu prompt:

1 - Usando a biblioteca Bogus para .Net, gere um builder para criar instâncias fakes da classe "NotaFiscalProdutoNaturezaOperacao".

Resposta do Chat:

Então segui, com os seguintes prompts:

2 - Usando a biblioteca Bogus para .Net, gere um builder para criar instâncias fakes da classe "NotaFiscalProdutoUnidade".

3 - Usando a biblioteca Bogus para .Net, gere um builder para criar instâncias fakes da classe "NotaFiscalProduto".

4 - Usando a biblioteca Bogus para .Net, gere um builder para criar instâncias fakes da classe "Produto".

5 - Usando a biblioteca Bogus para .Net, gere um builder para criar instâncias fakes da classe "Participante".

Neste momento, algo interessante ocorreu: Eu esqueci de informar para o chat do Bing, a definição da classe Participante:

6 - Usando a biblioteca Bogus para .Net, gere um builder para criar instâncias fakes da classe "NotaFiscal".

Em alguns minutos, consegui criar os builders para todo o modelo de dados da API:

Obtendo como resultado as seguintes classes:

NotaFiscalProdutoNaturezaOperacaoFaker

public class NotaFiscalProdutoNaturezaOperacaoFaker : Faker<NotaFiscalProdutoNaturezaOperacao>
{
    public NotaFiscalProdutoNaturezaOperacaoFaker()
    {
        RuleFor(n => n.Id, f => f.Random.Long(1));
        RuleFor(n => n.Codigo, f => f.Random.String2(10));
        RuleFor(n => n.Descricao, f => f.Lorem.Sentence());
    }
}

NotaFiscalProdutoUnidadeFaker

public class NotaFiscalProdutoUnidadeFaker : Faker<NotaFiscalProdutoUnidade>
{
    public NotaFiscalProdutoUnidadeFaker()
    {
        RuleFor(n => n.Id, f => f.Random.Long(1));
        RuleFor(n => n.Codigo, f => f.Random.String2(10));
        RuleFor(n => n.Simbolo, f => f.Random.String2(3));
    }
}

NotaFiscalProdutoFaker

public NotaFiscalProdutoFaker()
{
    RuleFor(n => n.NotaFiscalId, f => f.Random.Long(1));
    RuleFor(n => n.Numero, f => f.Random.Int(1));
    RuleFor(n => n.Produto, f => new ProdutoFaker().Generate());
    RuleFor(n => n.Quantidade, f => f.Random.Decimal(1));
    RuleFor(n => n.ValorTotal, f => f.Random.Decimal(1));
    RuleFor(n => n.Desconto, f => f.Random.Decimal(1));
    RuleFor(n => n.Movimentado, f => f.Random.Int(1));
    RuleFor(n => n.ICMS_CST, f => f.Random.String2(10));
    RuleFor(n => n.CFOP, f => f.Random.String2(10));
    RuleFor(n => n.ICMS_BC, f => f.Random.Decimal(1));
    RuleFor(n => n.ICMS_Aliquota, f => f.Random.Decimal(1));
    RuleFor(n => n.ICMS_Valor, f => f.Random.Decimal(1));
    RuleFor(n => n.ICMS_ST_BC, f => f.Random.Decimal(1));
    RuleFor(n => n.ICMS_ST_Aliquota, f => f.Random.Decimal(1));
    RuleFor(n => n.ICMS_ST_Valor, f => f.Random.Decimal(1));
    RuleFor(n => n.IPI_Apuracao, f => f.Random.Int(1));
    RuleFor(n => n.IPI_CST, f => f.Random.String2(10));
    RuleFor(n => n.IPI_Enquadramento, f => f.Random.String2(10));
    RuleFor(n => n.IPI_BC, f => f.Random.Decimal(1));
    RuleFor(n => n.IPI_Aliquota, f => f.Random.Decimal(1));
    RuleFor(n => n.IPI_Valor, f => f.Random.Decimal(1));
    RuleFor(n => n.PIS_CST, f => f.Random.String2(10));
    RuleFor(n => n.PIS_BC, f => f.Random.Decimal(1));
    RuleFor(n => n.PIS_Aliquota, f => f.Random.Decimal(1));
    RuleFor(n => n.PIS_BC_Quantidade, f => f.Random.Decimal(1));
    RuleFor(n => n.PIS_Aliquota_Reais, f => f.Random.Decimal(1));
    RuleFor(n => n.PIS_Valor, f => f.Random.Decimal(1));
    RuleFor(n => n.COFINS_CST, f => f.Random.String2(10));
    RuleFor(n => n.COFINS_BC, f => f.Random.Decimal(1));
    RuleFor(n => n.COFINS_Aliquota, f => f.Random.Decimal(1));
    RuleFor(n => n.COFINS_BC_Quantidade, f => f.Random.Decimal(1));
    RuleFor(n => n.COFINS_Aliquota_Reais, f => f.Random.Decimal(1));
    RuleFor(n => n.COFINS_Valor, f => f.Random.Decimal(1));
}

ProdutoFaker

public class ProdutoFaker : Faker<Produto>
{
    public ProdutoFaker()
    {
        RuleFor(n => n.Id, f => f.Random.Long(1));
        RuleFor(n => n.Codigo, f => f.Random.String2(10));
        RuleFor(n => n.Descricao, f => f.Lorem.Sentence());
        RuleFor(n => n.Unidade, f => new NotaFiscalProdutoUnidadeFaker().Generate());
        RuleFor(n => n.Origem, f => f.Random.Int(1));
        RuleFor(n => n.NCM, f => f.Random.String2(10));
        RuleFor(n => n.CEST, f => f.Random.String2(10));
        RuleFor(n => n.ICMS_Aliquota, f => f.Random.Decimal(1));
    }
}

ParticipanteFaker

public class ParticipanteFaker : Faker<Participante>
{
    public ParticipanteFaker()
    {
        RuleFor(n => n.Id, f => f.Random.Long(1));
        RuleFor(n => n.Codigo, f => f.Random.String2(10));
        RuleFor(n => n.Nome, f => f.Name.FullName());
        RuleFor(n => n.Cod_Pais, f => f.Address.CountryCode());
        RuleFor(n => n.CNPJ, f => f.Company.Cnpj());
        RuleFor(n => n.CPF, f => f.Person.Cpf());
        RuleFor(n => n.IE, f => f.Random.String2(10));
        RuleFor(n => n.SUFRAMA, f => f.Random.String2(10));
        RuleFor(n => n.EnderecoCod_Mun, f => f.Random.String2(10));
        RuleFor(n => n.EnderecoLogradouro, f => f.Address.StreetName());
        RuleFor(n => n.EnderecoNumero, f => f.Address.BuildingNumber());
        RuleFor(n => n.EnderecoComplemento, f => f.Address.SecondaryAddress());
        RuleFor(n => n.EnderecoBairro, f => f.Address.County());
    }
}

NotaFiscalFaker

public class NotaFiscalFaker : Faker<NotaFiscal>
{
    public NotaFiscalFaker()
    {
        RuleFor(n => n.Id, f => f.Random.Long(1));
        RuleFor(n => n.Operacao, f => f.PickRandom(new int[] { 0, 1 }));
        RuleFor(n => n.TipoEmissao, f => f.PickRandom(new string[] { "0", "1" }));
        RuleFor(n => n.NaturezaOperacao, f => new NotaFiscalProdutoNaturezaOperacaoFaker().Generate());
        RuleFor(n => n.Participante, f => new ParticipanteFaker().Generate());
        RuleFor(n => n.ModeloDocumento, f => f.Random.String2(10));
        RuleFor(n => n.Situacao, f => f.Random.String2(10));
        RuleFor(n => n.Serie, f => f.Random.Int(1));
        RuleFor(n => n.Numero, f => f.Random.Int(1));
        RuleFor(n => n.Chave, f => f.Random.String2(10));
        RuleFor(n => n.DataEmissao, f => f.Date.Recent());
        RuleFor(n => n.DataEntradaSaida, f => f.Date.Recent());
        RuleFor(n => n.ValorTotal, f => f.Random.Decimal(1));
        RuleFor(n => n.TipoPagamento, f => f.Random.Int(1));
        RuleFor(n => n.ValorDesconto, f => f.Random.Decimal(1));
        RuleFor(n => n.ValorAbatimento, f => f.Random.Decimal(1));
        RuleFor(n => n.ValorMercadorias, f => f.Random.Decimal(1));
        RuleFor(n => n.TipoTransporte, f => f.Random.Int(1));
        RuleFor(n => n.ValorFrete, f => f.Random.Decimal(1));
        RuleFor(n => n.ValorSeguro, f => f.Random.Decimal(1));
        RuleFor(n => n.ValorDespesas, f => f.Random.Decimal(1));
        RuleFor(n => n.ICMS_BC, f => f.Random.Decimal(1));
        RuleFor(n => n.ICMS_Aliquota, f => f.Random.Decimal(1));
        RuleFor(n => n.ICMS_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.ICMS_ST_BC_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.ICMS_ST_Retido_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.IPI_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.PIS_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.PIS_ST_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.COFINS_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.COFINS_ST_Valor, f => f.Random.Decimal(1));
        RuleFor(n => n.Produtos, f => new NotaFiscalProdutoFaker().Generate(f.Random.Int(5)));
    }
}

Repare que ele entendeu os comentários das propriedades da classe NotaFiscal:

/// <summary> 
/// IND_OPER - Indicador do tipo de operação:
/// 
/// <para>0 - Entrada</para> 
/// <para>1 - Saída</para> 
/// </summary> 
public int Operacao { get; set; }

/// <summary> 
/// IND_EMIT - Indicador do emitente do documento fiscal:
/// 
/// <para>0 - Emissão própria</para> 
/// <para>1 - Terceiros</para> 
/// </summary> 
public string TipoEmissao { get; set; }

Fazendo a personalização dos valores que podem ser incluidos nestas propridades:

RuleFor(n => n.Operacao, f => f.PickRandom(new int[] { 0, 1 }));

RuleFor(n => n.TipoEmissao, f => f.PickRandom(new string[] { "0", "1" }));

Com estas classes geradas, ao escrever os testes unitários, ou até os testes de integração, sempre que precisar de uma instância com dados totalmente randômicos destas classes, tudo que tenho a fazer é invocar os builders, assim:

var faker = new NotaFiscalProdutoNaturezaOperacaoFaker();
var fakeNotaFiscalProdutoNaturezaOperacao = faker.Generate();

var faker = new NotaFiscalProdutoNaturezaOperacaoFaker();
var fakeNotaFiscalProdutoNaturezaOperacao = faker.Generate();

var faker = new NotaFiscalProdutoUnidadeFaker();
var fakeNotaFiscalProdutoUnidade = faker.Generate();

var faker = new NotaFiscalProdutoFaker();
var fakeNotaFiscalProduto = faker.Generate();

var faker = new ProdutoFaker();
var fakeProduto = faker.Generate();

var faker = new ParticipanteFaker();
var fakeParticipante = faker.Generate();

var faker = new NotaFiscalFaker();
var fakeNotaFiscal = faker.Generate();

Não é objetivo deste artigo, mostrar como criar os testes, o objetivo aqui foi somente mostrar como as inteligências artificiais, podem nos ajudar a fazer o trabalho chato e altamente suscetível à erros, de forma automática. Tudo que você precisa fazer é fornecer um contexto e caprichar nos prompts.

Validando o schema de arquivos XML com .Net e C#

Silvair L. Soares — Fri, 13 Aug 2021 15:05:06 +0000

Embora muitas pessoas possam torcer o nariz ao ouvirem termos como: Webservices, SOAP, XML, schema, XSD, WSDL, etc. São tecnologias que teremos que lidar em algum momento da nossa vida profissional.

Protocolos e padrões mais leves como REST, gRPC, GraphQL, etc, estão cada vez mais se popularizando, mas existem grandes projetos (sem previsão de migração), consolidados que utilizam o protocolo SOAP para troca de informações entre sistemas.

No Brasil, dois grandes exemplos são a Nota Fiscal Eletrônica - NF-e e o Web Service de Rastreamento dos Correios.

O que vamos aprender neste artigo?
1. Entender os fundamentos do protocolo SOAP
2. Criar um serviço genérico para validar qualquer arquivo XML, com diferentes schemas
3. Criar uma API REST em .Net para fazer a validação de arquivos XML

1. O protocolo SOAP

Se existe um requisito comum, para a maioria das aplicações corporativas, é a integração entre diferentes sistemas. Nenhum software é (ou não deveria ser) uma ilha!

Se este for o seu caso, inevitavelmente em algum momento você precisará consumir algum serviço remoto, implementado por terceiros, durante o ciclo de vida operacional do seu sistema.

O protocolo SOAP - Simple Object Access Protocol (em português, Protocolo Simples de Acesso à Objeto) possibilita que esta tarefa seja executada de forma bastante eficiente.

SOAP utiliza o protocolo HTTP para transportar os dados. E devido ao fato de utilizar um protocolo padrão, permite que sistemas construídos com diferentes linguagens de programação e sendo executados em diferentes sistemas operacionais, troquem informações de forma transparente.

Além disso, permite que o produtor destes serviços remotos, defina o formato da entrada de dados que será aceito, utilizando para isto os XML Schema - XML Schema Definition (em português, Definição de Esquema XML).

São arquivos com a extensão .xsd, com os seguintes tipos de conteúdo:

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:complexType name="TEndereco">
        <xsd:sequence>
            <xsd:element name="logradouro" type="xsd:string"/>
            <xsd:element name="complemento" type="xsd:string"/>
            <xsd:element name="bairro" type="xsd:string"/>
            <xsd:element name="CEP">
                <xsd:simpleType>
                    <xsd:restriction base="xsd:string">
                        <xsd:maxLength value = "9"/>
                        <xsd:minLength value = "9"/>
                    </xsd:restriction>
                </xsd:simpleType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

No exemplo acima, foi definido uma entrada de endereços, chamada de TEndereco, contendo os campos: Logradouro, Numero, Complemento, Bairro e CEP, cada um com a sua respectiva regra de preenchimento. Através deste modelo, poderemos utilizar o tipo TEndereco em outros tipos de dados:

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:include schemaLocation="TEndereco.xsd"/>
    <xsd:element name="pessoa">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="nome">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value = "20"/>
                            <xsd:minLength value = "2"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>
                <xsd:element name="sobrenome">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value = "20"/>
                            <xsd:minLength value = "2"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>
                <xsd:element name="endereco" minOccurs="1" maxOccurs="1" type="TEndereco"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

No exemplo acima, o tipo TEndereco foi utilizado no tipo TPessoa. Desta forma, é possível definir todas as regras do tipo de entrada aceito pelo webservice SOAP.

Dica!
Para quem trabalha com orientação a objetos, os schemas seriam as classes, já os arquivos XML que transportam os dados, seriam uma instância desta classe, ou um objeto instanciado.

Esta foi apenas uma pequena introdução ao protocolo SOAP, como não é objetivo deste artigo aprofundar neste tema, deixo aqui a fonte oficial de informações, para quem pretende entender de forma mais ampla, este vasto conteúdo:
https://www.w3.org/TR/soap/

2. Criando um serviço genérico para validar qualquer schema de diferentes tipos de XML

2.1. Ambiente necessário

Visual Studio Code (https://code.visualstudio.com/Download)
.Net 5.0 SDK (https://dotnet.microsoft.com/download/dotnet/thank-you/sdk-5.0.400-windows-x64-installer)

Vamos criar uma API simples, que receberá uma string que representa um arquivo XML, validará o schema e caso econtre alguma inconsistência, retornará uma mensagem detalhando todos os problemas encontrados.

Para a criação da WEB API, após a instalação do .Net 5.0 SDK, temos disponível uma poderosa ferramenta de linha de comando que nos ajudará inclusive com a criação do projeto.

Abra um diretório qualquer do seu computador, clique na barra de endereços, digite o comando CMD e tecle ENTER.

Ao fazer isto, o prompt de comando do Windows, abrirá o respectivo diretório automaticamente:

Digite o comando dotnet new webapi --name web.api.xml.schema.validation e tecle ENTER.

Após alguns segundos, teremos um projeto do tipo WEB API, criado e totalmente funcional.

Para acessá-lo no Visual Studio Code, navegue para o diretório do projeto no prompt de comando, digite code . e tecle e ENTER.

A tela do Visual Studio Code será aberta automaticamente, com o projeto previamente criado, já carregado:

Na primeira execução, o Visual Studio Code identificará a linguagem na qual o projeto está sendo desenvolvido e perguntará se deseja incluir a extensão para o C#, permita que ele faça a instalação, clicando no botão Install.

Para executar o projeto de teste, basta acessar o terminal do Visual Studio Code (CTRL + ‘) e digitar o comando: dotnet run.

A partir deste momento, basta acessar o endereço: https://localhost:5001/swagger no browser para ver a API sendo executada.

É incrível como é fácil criar e executar uma API no .Net né!

A seguir, criaremos um serviço injetável (injeção de dependência) que será utilizando no controller responsável por receber e validar o arquivo xml.

Crie o diretório Services na raiz do projeto, com os seguintes subdiretórios: ServiceInterfaces e Services.
Crie o arquivo IXMLValidationService.cs no diretório \Services\XMLValidation\ServiceInterfaces, com o seguinte conteúdo:

namespace web.api.xml.schema.validation.Services.InterfacesServicos
{
    public interface IXMLValidationService
    {        
        string XMLValidate(string XML);
    }
}

Agora vamos criar uma classe que implementará o método XMLValidate definido na interface IXMLValidationService:

Crie o arquivo XMLValidationService.cs no diretório \Services\XMLValidation\Services, com o seguinte conteúdo:

using web.api.xml.schema.validation.Services.InterfacesServicos;

namespace web.api.xml.schema.validation.Services.Servicos
{
    public class XMLValidationService: IXMLValidationService
    {        

    }
}

Neste momento, o Visual Studio Code exibirá um erro, pois não estamos ainda, implementando o XMLValidate definido na interface IXMLValidationService:

Para resolver este problema, posicione o mouse sobre o ícone da lâmpada amarela no início da linha 5 e clique na opção Implementar a interface:

A assinatura do método será criada automaticamente:

using web.api.xml.schema.validation.Services.InterfacesServicos;

namespace web.api.xml.schema.validation.Services.Servicos
{
    public class XMLValidationService : IXMLValidationService
    {
        public string XMLValidate(string XML)
        {
            throw new System.NotImplementedException();
        }
    }
}

Agora vamos dar início ao processo de validação do schema de fato.
Para isto, crie o subdiretório Schemas dentro do diretório \Services\XMLValidation.

Crie no diretório \Schemas os seguintes arquivos com seus respectivos conteúdos:

Arquivo: TEndereco.xsd
Conteúdo:

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:complexType name="TEndereco">
        <xsd:sequence>
            <xsd:element name="logradouro" type="xsd:string"/>
            <xsd:element name="complemento" type="xsd:string"/>
            <xsd:element name="bairro" type="xsd:string"/>
            <xsd:element name="CEP">
                <xsd:simpleType>
                    <xsd:restriction base="xsd:string">
                        <xsd:maxLength value="9"/>
                        <xsd:minLength value="9"/>
                    </xsd:restriction>
                </xsd:simpleType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>

Arquivo: TPessoa.xsd
Conteúdo:

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:include schemaLocation="TEndereco.xsd"/>
    <xsd:element name="pessoa">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="nome">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value = "20"/>
                            <xsd:minLength value = "2"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>
                <xsd:element name="sobrenome">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:maxLength value = "20"/>
                            <xsd:minLength value = "2"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>
                <xsd:element name="endereco" minOccurs="1" maxOccurs="1" type="TEndereco"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

Estes arquivos são o schemas que validarão o conteúdo do arquivo xml recebido pela nossa WEB API.

O nosso método XMLValidate, contém um parâmetro do tipo string que será utilizada para criar um objeto do tipo System.Xml.XmlDocument.

Faça a seguinte modificação no método XMLValidate da classe XMLValidationService:

using System.Xml;
using web.api.xml.schema.validation.Services.InterfacesServicos;

namespace web.api.xml.schema.validation.Services.Servicos
{
    public class XMLValidationService : IXMLValidationService
    {
        public string XMLValidate(string XML)
        {
            XmlDocument document = new XmlDocument();            
            try
            {
                document.Load(XML);
            }
            catch (System.Exception ex)
            {                
                throw new System.Exception("Houve um erro ao gerar um documento XML com os dados recebidos. " + ex.Message);
            }

            return "";      
        }
    }
}

Com isto, teremos um serviço que recebe uma string que representa um documento XML, tenta instanciar um XmlDocument e retorna uma exceção, caso o XML esteja com uma má formação.

Lembre-se, o que validaremos é um schema do XML e para isto, o conteúdo XML deverá no mínimo ser um XML bem formado.

Para criar o mecanismo de validação, utilizaremos o Validate(ValidationEventHandler validationEventHandler) do namespace System.Xml.XmlDocument.

Portanto, faça as seguintes modificações na classe XMLValidationService:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Xml;
using System.Xml.Schema;
using web.api.xml.schema.validation.Services.InterfacesServicos;

namespace web.api.xml.schema.validation.Services.Servicos
{
    public class XMLValidationService : IXMLValidationService
    {
        private static readonly ICollection<string> falhas = new List<String>();

        public string XMLValidate(string XML)
        {
            XmlDocument document = new XmlDocument();
            try
            {
                document.LoadXml(XML);
                string falhas = ValidarXmlPessoa(document);

                if (falhas.Count() > 0)
                    return falhas;
                else
                    return "Arquivo validado com sucesso!";

            }
            catch (Exception ex)
            {
                throw new Exception("Houve um erro ao gerar um documento XML com os dados recebidos. " + ex.Message);
            }
        }

        /// <summary>
        /// Executa a validação de schema do XML do tipo "TPessoa", com base nos arquivos .xsd
        /// </summary>
        private string ValidarXmlPessoa(XmlDocument dados)
        {
            string retorno = "";
            // Inclui os schemas XSD para validação do documento do tipo "TPessoa" e suas dependências
            ICollection<string> XSDFiles = new List<String>();
            try
            {                
                XSDFiles.Add(@"Services\XMLValidation\Schemas\TPessoa.xsd");
                XSDFiles.Add(@"Services\XMLValidation\Schemas\TEndereco.xsd");
            }
            catch (Exception ex)
            {
                throw ex;
            }

            // Aciona o método genérico de validações de schemas, mas que neste contexto, estará validando apenas os tipos "TEndereco" e "TPessoa"
            List<string> validacao = ValidarDocumentoXML(dados, XSDFiles).ToList();

            if (validacao.Count > 0)
            {
                retorno = "Ocorreram os seguintes erros na validação:\n";
                foreach (var item in validacao)
                {
                    retorno += item;
                }
            }
            return retorno;
        }

        /// <summary>
        /// Este é um método genérico, que serve para validar qualquer o schema de qualquer tipo de arquivo xml
        /// </summary>
        private static ICollection<string> ValidarDocumentoXML(XmlDocument doc, ICollection<string> XSDFiles)
        {
            // Limpa a lista de falhas de schema
            falhas.Clear();
            try
            {
                // Adiciona todos os arquivos .xsd ao fluxo de validação
                foreach (var item in XSDFiles)
                {
                    doc.Schemas.Add(null, item);
                }
            }
            catch (System.Exception ex)
            {
                throw new Exception("Houve um erro ao incluir os arquivos XSD para validar o arquivo XML.\n" + ex.Message);
            }
            try
            {
                // Delegate responsável por manipular os erros ocorridos: ValidationCallBack()
                doc.Validate(ValidationCallBack);
            }
            catch (XmlSchemaValidationException ex)
            {
                throw new Exception("Houve um erro executar a validação do documento XML. " + ex.Message);
            }

            return falhas;
        }

        /// <summary> 
        /// Manipulador de erros do xml
        /// Sua finalidade é obter as mensagens de erro (disparadas pelo método "ValidarDocumentoXML") e as incluir a variável "falhas"
        /// </summary> 
        private static void ValidationCallBack(object sender, ValidationEventArgs args)
        {
            // Podem ser gerados dois tipos de falhas ("XmlSeverityType"), portanto, a estrutura abaixo, separa os erros entre "Alerta (Warning)" ou "Erros (Error)"
            if (args.Severity == XmlSeverityType.Warning)
            {
                falhas.Add("Alerta: " + TraduzMensagensDeErro(args.Message) + " (Caminho: " + ObtemCaminho(args) + ")");
            }
            else if (args.Severity == XmlSeverityType.Error)
            {
                falhas.Add("Erro: " + TraduzMensagensDeErro(args.Message) + " (Caminho: " + ObtemCaminho(args) + ")");
            }
        }

        /// <summary>
        /// Durante a validação do schema de um arquivo xml, este método auxilia na obtenção do caminho completo da tag que causou algum problema de validação
        /// </summary>
        private static string ObtemCaminho(ValidationEventArgs args)
        {
            // Captura a referência para a tag que causou o problema (falha de schema)
            XmlSchemaValidationException ex = (XmlSchemaValidationException)args.Exception;
            object sourceObject = ex.SourceObject;

            if (sourceObject.GetType() == typeof(XmlElement))
            {
                XmlElement tagProblema = (XmlElement)(sourceObject);
                return GetCaminhoTagXML(tagProblema.ParentNode) + "/" + tagProblema.Name;
            }
            else
            {
                return "";
            }
        }

        /// <summary>
        /// Devolve o caminho completo de um elemento de um documento XML, no padrão: "\elemento_raiz\elemento2\elemento3\..."
        /// </summary>
        private static string GetCaminhoTagXML(XmlNode args)
        {
            var node = args.ParentNode;
            if (args.ParentNode == null)
            {
                return "";
            }
            else if (args.ParentNode.NodeType == XmlNodeType.Element)
            {
                // Elemento atual é um nó com mais itens
                // Chama o próprio método recursivamente, para obter toda a árvore da tag atual
                return GetCaminhoTagXML(node) + @"/" + args.Name;
            }
            return "";
        }

        /// <summary>
        /// Altera o texto das mensagens de validação do schema, de inglês para português
        /// </summary>
        private static string TraduzMensagensDeErro(string mensagem)
        {
            mensagem = mensagem.Replace("The value of the 'Algorithm' attribute does not equal its fixed value.", "O valor do atributo 'Algorithm' não é igual ao seu valor fixo.");
            mensagem = mensagem.Replace("The '", "O elemento '");
            mensagem = mensagem.Replace("element is invalid", "é inválido");
            mensagem = mensagem.Replace("The value", "O valor");
            mensagem = mensagem.Replace("is invalid according to its datatype", "é inválido de acordo com o seu tipo de dados");
            mensagem = mensagem.Replace("The Pattern constraint failed.", "");
            mensagem = mensagem.Replace("The actual length is less than the MinLength value", "O comprimento real é menor que o valor MinLength");
            mensagem = mensagem.Replace(" in namespace 'http://www.w3.org/2000/09/xmldsig#'.", "");
            mensagem = mensagem.Replace("The element", "O elemento");
            mensagem = mensagem.Replace("has invalid child element", "tem um elemento filho inválido");
            mensagem = mensagem.Replace("List of possible elements expected:", "Lista de possíveis elementos esperados:");
            mensagem = mensagem.Replace("The Enumeration constraint failed.", "");
            mensagem = mensagem.Replace("http://www.w3.org/2000/09/xmldsig#:", "");
            mensagem = mensagem.Replace("http://www.w3.org/2001/XMLSchema:", "");
            mensagem = mensagem.Replace("The input is not a valid Base-64 string as it contains a non-base 64 character, more than two padding characters, or an illegal character among the padding characters.", "A entrada não é uma string Base-64 válida, pois contém um caractere não base 64, mais de dois caracteres de preenchimento ou um caractere ilegal entre os caracteres de preenchimento.");
            mensagem = mensagem.Replace("The required attribute", "O atributo obrigatório");
            mensagem = mensagem.Replace("is missing", "está ausente");
            mensagem = mensagem.Replace("has incomplete content", "tem conteúdo incompleto");
            mensagem = mensagem.Replace("as well as", "bem como");
            return mensagem;
        }
    }
}

Como a classe ficou um pouco extensa, utilizei comentários em pontos específicos para explicar cada detalhe que está sendo executado.

Após estas modificações, temos o serviço para validação de XML completamente funcional, para utilizarmos, basta injetá-lo no controller, faremos isto através de uma configuração no método ConfigureServices da classe Startup.

Mas primeiro, vamos incluir uma referência em nosso arquivo web.api.xml.schema.validation.csproj para o pacote Microsoft.AspNetCore.Mvc.NewtonsoftJson, que nos auxiliará a trabalhar com arquivos XML nos controllers da API.

Edite o conteúdo do arquivo web.api.xml.schema.validation.csproj incluindo a linha:

<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="5.0.3" />

Deixando-o da seguinte forma:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <TargetFramework>net5.0</TargetFramework>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3"/>
        <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="5.0.3"/>
    </ItemGroup>
</Project>

Após adicionar a referência para a biblioteca de serialização NewtonSoft edite o conteúdo do arquivo Startup.cs, deixando-o da seguinte forma:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;
using Newtonsoft.Json.Serialization;
using web.api.xml.schema.validation.Services.InterfacesServicos;
using web.api.xml.schema.validation.Services.Servicos;

namespace web.api.xml.schema.validation
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // Configurações da injeção de dependência do serviço validador de documentos XML
            services.AddScoped(typeof(IXMLValidationService), typeof(XMLValidationService));

            services.AddControllers();
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "web.api.xml.schema.validation", Version = "v1" });
            });

            //Inclusão do framework de serialização NewtonSoft
            services.AddControllers().AddNewtonsoftJson();

            //Ajuste para permitir receber conteudos do tipo XML nos controllers da API
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_3_0)
                .AddNewtonsoftJson
                    (options => { }).AddXmlSerializerFormatters()
              .AddXmlDataContractSerializerFormatters();

        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UseSwagger();
                app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "web.api.xml.schema.validation v1"));
            }

            app.UseHttpsRedirection();
            app.UseRouting();
            app.UseAuthorization();

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

3. Criando o endpoint para receber os arquivos XML

A próxima e última etapa, será a criação do controller que receberá a string do XML e irá submetê-la à validação, por meio do serviço XMLValidationService.

Crie no diretório \Controllers o arquivo XMLValidationController.cs com o seguinte conteúdo:

using System.ComponentModel;
using Microsoft.AspNetCore.Mvc;
using web.api.xml.schema.validation.Services.InterfacesServicos;

[Description("Validação de XML")]
public class XMLValidationController : Controller
{
    //Interface do serviço que valida o arquivo XML e será injetado automaticamente em tempo de execução
    private readonly IXMLValidationService _XMLValidationService;

    public XMLValidationController(IXMLValidationService XMLValidationService)
    {
        _XMLValidationService = XMLValidationService;
    }

    [HttpPost("api/validarxml/")]
    public string Validar([FromBody] string strDocumento)
    {
        return _XMLValidationService.XMLValidate(strDocumento);
    }
}

Todo o código da aplicação está pronto. Agora, ao executar nossa WEB API e navegar para o endereço: https://localhost:5001/swagger, teremos acesso ao novo endpoint XMLValidation conforme mostra a imagem a seguir:

Ao clicar no botão Try it out podemos testar o nosso mecanismo de validação, usando o seguinte payload:

"<?xml version='1.0' encoding='UTF-8'?>
<pessoa>
    <nome>Silvair</nome>
    <sobrenome>Leite Soares</sobrenome>
    <endereco>
        <logradouro>Rua Goia</logradouro>
        <complemento>Quadra e lote qualquer</complemento>
        <bairro>Setor Gentil Meirelles</bairro>
        <CEP>74575-200</CEP>
    </endereco>
</pessoa>"

O schema será validado com sucesso, veja na imagem a seguir:

Mas se você fizer qualquer modificação no payload, de forma que o contrato (arquivos .xsd) seja quebrado, a API retornará todos os detalhes dos problemas ocorridos. Veja a seguir:

"<?xml version='1.0' encoding='UTF-8'?>
<pessoa>
    <nome>Silvair</nome>
    <sobrenome/>
    <endereco>
        <logradouro>Rua Goia</logradouro>
        <complemento>Quadra e lote qualquer</complemento>
        <bairro>Setor Gentil Meirelles</bairro>
        <ElementoNaoPrevisto>Texto qualquer</ElementoNaoPrevisto>
        <CEP>74575-200</CEP>
    </endereco>
</pessoa>"

Omiti intencionalmente o conteúdo da tag sobrenome e inclui um elemento não previsto na tag endereco, veja o resultado:

Com este passo, concluímos o nosso projeto de teste. Lembrando que, por mais que estejamos validando os tipos "pessoa" e "endereco" durante este artigo, o serviço que construímos servirá para validar qualquer tipo de schema XML. Bastando para isso, incluir os respectivos arquivos .xsd no diretório \Schemas e fazer algumas pequenas modificações, como por exemplo, criar um endpoint específico para cada tipo de arquivo XML a ser validado.

Todo o código construído durante o projeto está disponível no seguinte repositório do GitHub: https://github.com/silvairsoares/web.api.xml.schema.validation

Referências:

MACORATTI, José Carlos. XML - Validando um Documento XML com um Schema (C#). Disponível em: http://www.macoratti.net/11/10/c_vxml1.htm. Acesso em: 13 de ago. de 2021.