Emiliano Montesdeoca

Blazor do zero: Capítulo 3 — Componentes que escalam

Mon, 01 Jun 2026 00:00:00 +0000

Bem-vindo ao Capítulo 3 de Blazor do zero. Se você não leu o Capítulo 2, leia primeiro para já ter o projeto base pronto.

No Capítulo 2 fizemos a aplicação rodar. Neste capítulo vamos deixá-la sustentável.

Projetos Blazor ficam bagunçados rápido quando cada página vira um .razor gigante. Componentes são a forma de evitar isso: trazem consistência, reutilização e limites claros entre partes da interface.

O que um componente Blazor realmente é

Um componente é um arquivo .razor que pode:

Renderizar markup
Manter estado local
Receber dados via parâmetros
Emitir eventos para o componente pai
Renderizar conteúdo filho

Em execução, o Blazor trata cada componente como uma pequena máquina de estado. Quando o estado muda, ele renderiza novamente e aplica um diff no DOM.

Por isso você deve desenhar entradas limpas e comportamento previsível.

Passo 1: Comece com um componente focado

Crie Components/Common/SectionHeader.razor:

<header class="section-header">
 <h2>@Title</h2>
 @if (!string.IsNullOrWhiteSpace(Subtitle))
 {
 <p>@Subtitle</p>
 }
</header>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public string? Subtitle { get; set; }
}

Use em Components/Pages/Home.razor:

@page "/"

<PageTitle>Blazor do zero</PageTitle>

<SectionHeader
 Title="Blazor do zero"
 Subtitle="O capítulo 3 é sobre componentes." />

É um exemplo simples, mas introduz a ideia central: os parâmetros devem explicar o componente.

Passo 2: Use parâmetros para deixar o comportamento explícito

Vamos criar um botão reutilizável.

Components/Common/AppButton.razor:

<button class="app-button @VariantCssClass" @onclick="OnClick">
 @Text
</button>

@code {
 [Parameter] public string Text { get; set; } = "Button";
 [Parameter] public string Variant { get; set; } = "primary";
 [Parameter] public EventCallback OnClick { get; set; }

 private string VariantCssClass => Variant.ToLowerInvariant() switch
 {
 "secondary" => "app-button--secondary",
 "danger" => "app-button--danger",
 _ => "app-button--primary"
 };
}

Uso:

@code {
 private int _savedCount;

 private void Save()
 {
 _savedCount++;
 }
}

<AppButton Text="Save" Variant="primary" OnClick="Save" />
<p>Salvo @_savedCount vezes.</p>

O ponto principal é o contrato:

Parâmetros pequenos e claros
Nomes explícitos, sem comportamento “mágico”
Defaults seguros

Passo 3: Use `RenderFragment` para composição

RenderFragment permite que o componente pai injete blocos de UI no filho.

Crie Components/Common/Card.razor:

<article class="card">
 <header class="card__header">@Title</header>
 <section class="card__body">
 @ChildContent
 </section>
</article>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public RenderFragment? ChildContent { get; set; }
}

Uso:

<Card Title="Roadmap">
 <ul>
 <li>Componentes</li>
 <li>Data binding</li>
 <li>Routing</li>
 </ul>
</Card>

Esse padrão evita repetir o mesmo markup de estrutura em várias páginas.

Passo 4: Prefira composição em vez de páginas gigantes

Se a página crescer demais, separe por responsabilidade:

ProfileSummary para o bloco principal
ProfileStats para métricas
ProfileActivityList para atividades recentes

Assim a página vira orquestração e não um bloco monolítico.

Passo 5: Equilibre markup e lógica

Para componentes simples, @code inline funciona bem.

Para componentes maiores, mova lógica para code-behind:

UserCard.razor
UserCard.razor.cs

Isso melhora a leitura do markup e da lógica C#.

Passo 6: Estrutura de pastas prática

Uma organização que costuma escalar bem:

Components/Pages/ -> páginas roteáveis
Components/Layout/ -> shell e navegação
Components/Common/ -> blocos genéricos compartilhados
Components/Features/<FeatureName>/ -> componentes de cada feature

Erros comuns no início com Blazor

Passar parâmetros demais em vez de usar um view model dedicado
Colocar regra de negócio dentro de componentes de página
Criar um “componente Deus” com centenas de linhas
Repetir padrões de markup em vez de extrair peças reutilizáveis

Próximo capítulo

No Capítulo 4 vamos focar em data binding e eventos: @bind, tratamento de eventos, tradeoffs do two-way binding e padrões para manter estado previsível.

Blazor do Zero: Capítulo 2 — A tua primeira app Blazor

Thu, 14 May 2026 00:00:00 +0000

Bem-vindo ao Capítulo 2 de Blazor do Zero. Se perdeste o Capítulo 1, lê primeiro para manter o contexto dos modelos de renderização.

Neste capítulo vamos criar uma nova app Blazor, executá-la localmente e perceber o papel dos ficheiros principais.

Passo 1: Criar o projeto

No terminal:

dotnet new blazor -o BlazorFromScratch
cd BlazorFromScratch

Isto cria uma Blazor Web App em .NET 9 com a estrutura padrão.

Se a tua ferramenta pedir um modelo de interatividade, começa por Interactive Server. É o modo mais simples para aprender.

Passo 2: Executar localmente

Inicia a app:

dotnet watch

Depois abre o URL mostrado no terminal (normalmente https://localhost:5xxx). Deves ver a app padrão com as páginas Home, Counter e Weather.

Se isto funcionar, o ambiente está pronto.

Passo 3: Entender a estrutura do projeto

Estes são os ficheiros e pastas mais importantes no início:

Program.cs — regista serviços e configura o pipeline HTTP.
Components/App.razor — componente raiz da aplicação.
Components/Routes.razor — mapeamento de rotas.
Components/Pages/ — páginas com rota como Home e Counter.
Components/Layout/ — layout partilhado (MainLayout.razor, menu).
wwwroot/ — recursos estáticos (CSS, imagens, favicon).
appsettings.json — valores de configuração.

Não te preocupes em dominar tudo já. Nesta fase, basta saber onde vive a UI e onde o arranque é configurado.

Passo 4: Fazer a primeira alteração

Abre Components/Pages/Home.razor e substitui o conteúdo por:

@page "/"

<PageTitle>Blazor do Zero</PageTitle>

<h1>Blazor do Zero</h1>
<p>O Capítulo 2 está a correr localmente.</p>

Guarda e atualiza o browser. Com dotnet watch, a app deve atualizar de imediato.

Esta alteração simples confirma o ciclo completo: editar -> compilar -> renderizar.

Passo 5: Ler o Program.cs uma vez

Não precisas memorizar, mas deves reconhecer estas linhas:

AddRazorComponents() ativa componentes Razor.
AddInteractiveServerComponents() ativa componentes interativos no servidor.
MapRazorComponents<App>() mapeia o componente raiz para endpoints.

Estas linhas mostram como a app arranca e quais capacidades de renderização estão ativas.

Problemas comuns

Se algo falhar, normalmente é um destes pontos:

SDK antigo: corre dotnet --version e confirma .NET 9.
Certificado HTTPS: corre dotnet dev-certs https --trust.
Conflito de portas: termina processos dotnet antigos e volta a correr.

Próximo capítulo

No Capítulo 3 vamos aprofundar componentes: parâmetros, composição e organização de UI reutilizável.

Blazor do Zero: Capítulo 1 — O que é Blazor?

Fri, 08 May 2026 00:00:00 +0000

Bem-vindo ao Capítulo 1 de Blazor do Zero. Se perdeu o post de introdução onde explico o propósito desta série e a quem se destina, comece por lá — é curto.

Neste capítulo vamos responder à pergunta fundamental: o que é Blazor? Parece simples, mas a resposta tem várias camadas — especialmente porque “Blazor” passou a ter significados ligeiramente diferentes ao longo dos anos. No final deste post saberá o que é Blazor, como se encaixa no ecossistema .NET, quais são os diferentes modelos de renderização e por que razão poderá — ou não — escolhê-lo em vez de um framework JavaScript.

Um breve historial

O Blazor começou como um projeto experimental de Steve Sanderson na Microsoft por volta de 2017. A ideia era provocadora: executar C# no navegador usando WebAssembly, eliminando completamente a necessidade de JavaScript. Era uma prova de conceito, e o nome era uma mistura deliberada de Blazer e Razor — o motor de templates sobre o qual o Blazor viria a ser construído.

O experimento gerou entusiasmo suficiente para que a Microsoft o levasse a sério. O Blazor foi lançado como parte do ASP.NET Core 3.0 em setembro de 2019, primeiro como Blazor Server — um modelo que executa o seu código C# no servidor e usa uma conexão SignalR em tempo real para enviar atualizações de interface ao navegador. Blazor WebAssembly seguiu em maio de 2020 como parte do ASP.NET Core 3.1, trazendo execução verdadeiramente do lado do cliente ao framework.

O .NET 6 e 7 refinaram a experiência do desenvolvedor. Depois, o .NET 8, lançado em novembro de 2023, repensou fundamentalmente o modelo de renderização com o que a Microsoft chamou de UI web full-stack. Renderização estática do lado do servidor, streaming rendering, servidor interativo, WebAssembly interativo e um novo modo Auto viviam todos sob o mesmo teto num único projeto. O .NET 9 construiu sobre esta base e eliminou as arestas.

É aqui que estamos hoje.

O que o Blazor realmente é

No seu núcleo, o Blazor é um framework de UI baseado em componentes para .NET. Constrói a sua interface a partir de componentes — peças autocontidas de C# e marcação HTML que podem manter estado, responder a eventos e compor-se em estruturas maiores. Se trabalhou com React ou Vue, esse modelo mental vai parecer familiar. A diferença fundamental é que em vez de JavaScript, escreve C#.

Os componentes em Blazor são escritos em ficheiros .razor. Um ficheiro .razor mistura marcação HTML com código C# usando a sintaxe Razor que pode já conhecer das views do ASP.NET MVC. Aqui está como fica um componente simples:

@page "/counter"

<h1>Contador</h1>
<p>Contagem atual: @currentCount</p>
<button @onclick="IncrementCount">Clique aqui</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

Não há JavaScript à vista. A diretiva @onclick associa o clique do botão a um método C#. A expressão @currentCount renderiza o valor atual. Quando o estado muda, o Blazor determina o que atualizar no DOM.

Esse é o núcleo. Tudo o resto — routing, injeção de dependências, formulários, chamadas HTTP — é construído sobre este modelo de componentes.

Os modelos de renderização

É aqui que reside muita confusão, por isso sejamos precisos. “Blazor” hoje refere-se a uma família de modos de renderização, não a um único modelo de implantação. Compreender a diferença importa porque afeta a performance, os requisitos de infraestrutura e o que os seus componentes podem ou não fazer.

SSR Estático

O modo mais simples. Os seus componentes Razor renderizam no servidor para HTML e esse HTML é enviado ao navegador. Não há conexão persistente, sem WebAssembly e sem interatividade do lado do cliente por padrão. É essencialmente o que o Razor Pages faz, mas usando o modelo de componentes.

Use para páginas com muito conteúdo, landing pages, qualquer coisa que não precise de interatividade em tempo real.

Servidor Interativo

O código do seu componente corre no servidor. Uma conexão WebSocket SignalR é estabelecida entre o navegador e o servidor. Quando clica num botão ou escreve num campo, o evento viaja pelo WebSocket até ao servidor, o seu C# executa, o diff é calculado e as atualizações do DOM são enviadas de volta ao navegador.

Vantagens: Acesso total aos recursos do servidor (bases de dados, sistema de ficheiros, segredos). Carregamento inicial rápido. Tamanho de download reduzido. Funciona em navegadores sem suporte a WebAssembly.

Desvantagens: Cada interação do utilizador requer uma viagem de ida e volta ao servidor, o que adiciona latência. Os recursos do servidor escalam com o número de conexões ativas. A app degrada se a conexão cair.

Use para aplicações empresariais, ferramentas internas, apps onde o acesso a dados do servidor importa mais do que a capacidade offline.

WebAssembly Interativo

O runtime .NET é descarregado para o navegador e a sua app corre completamente no cliente. Após o download inicial, a app funciona completamente offline e cada interação é imediata — sem viagens ao servidor para lógica de interface.

Vantagens: Execução verdadeiramente do lado do cliente. Funciona offline. Carga do servidor reduzida após a app estar carregada.

Desvantagens: Download inicial maior (runtime .NET + a sua app). Primeiro carregamento mais lento. Precisa de uma API para aceder a dados do servidor.

Use para apps com capacidade offline, ferramentas que precisam de reatividade imediata, cenários onde o processamento do servidor não é necessário para a interface.

Modo Auto

Introduzido no .NET 8. A app começa no modo Servidor Interativo (carregamento inicial rápido, sem esperar pelo download do WebAssembly). Assim que os ficheiros WebAssembly tiverem sido descarregados em segundo plano, as visitas subsequentes mudam automaticamente para o modo WebAssembly.

Isto dá-lhe o carregamento inicial rápido do modo Servidor e eventualmente a execução completa do lado do cliente do WebAssembly. É o modelo mais complexo de compreender, mas é um padrão prático para muitas apps.

Misturar modos na mesma app

No .NET 8 e posteriores, não está limitado a um único modo de renderização para toda a app. Uma landing page pode ser SSR Estático; o dashboard autenticado pode ser Servidor Interativo; um widget de visualização de dados pode ser WebAssembly Interativo. O framework gere as transições.

Nesta série começaremos com o Servidor Interativo por ser o mais simples de colocar a funcionar e ter o modelo mental mais direto. Exploraremos os outros modos à medida que avançamos.

Como o Blazor se compara com frameworks JavaScript

Se desenvolveu com React, Angular ou Vue, esta é provavelmente a comparação que lhe interessa.

As semelhanças são reais. O modelo de componentes do Blazor é deliberadamente semelhante ao do React. Tem props (Parâmetros no Blazor), estado local (campos no bloco @code), hooks de ciclo de vida e o mesmo padrão de comunicação dados para baixo / eventos para cima. Se conhece React, vai sentir-se em casa em poucas horas.

A diferença fundamental é a linguagem. No Blazor escreve C#. A sua lógica de negócio, regras de validação e modelos de dados podem todos ser partilhados entre o seu frontend Blazor e o seu backend ASP.NET Core. Sem duplicar uma classe User em TypeScript quando já a tem em C#.

A lacuna do ecossistema é real mas está a fechar. O ecossistema npm é enorme. O ecossistema NuGet para componentes de UI é menor, embora tenha crescido substancialmente. Para uma biblioteca de gráficos específica ou um widget de drag-and-drop, o JavaScript ainda tem mais opções. Mas para a maioria das aplicações empresariais, o que está disponível no mundo .NET é mais do que suficiente.

A interoperabilidade JavaScript existe quando precisa dela. O Blazor permite chamar JavaScript a partir de C# e C# a partir de JavaScript. Para APIs do navegador sem wrapper .NET, ou quando quer usar uma biblioteca JS existente, o interop está disponível. Adiciona uma camada mas não é doloroso.

A resposta honesta: se a sua equipa é totalmente de developers JavaScript a construir um produto público onde SEO, performance e o ecossistema npm são críticos, fique com JavaScript. Se a sua equipa é de developers .NET, se está a construir aplicações internas ou empresariais, ou se a partilha de código entre frontend e backend lhe importa, o Blazor é uma escolha convincente.

O que precisa para acompanhar a série

Para o resto desta série vai precisar de:

.NET 9 SDK — descarregue em dot.net
Um IDE — Visual Studio 2022 (a edição Community é gratuita), VS Code com a extensão C# Dev Kit, ou JetBrains Rider
Conforto básico com C# — classes, propriedades, interfaces, async/await

Só isso. Sem Node, sem npm, sem webpack.

A seguir

No Capítulo 2 vamos montar a sua primeira app Blazor, percorrer a estrutura do projeto e garantir que consegue executá-la localmente. No final terá uma app a funcionar e uma imagem clara do que cada ficheiro está a fazer.

Até lá.

Blazor do Zero: Uma Nova Série

Mon, 04 May 2026 00:00:00 +0000

Há algum tempo que escrevo sobre Blazor — ciclos de vida de componentes, CSS isolado, modelos de interatividade, autenticação. Esses posts foram úteis individualmente, mas sempre senti que faltava uma base. Eles assumem que você já sabe o que é Blazor, por que ele existe e como se encaixa no ecossistema .NET mais amplo. Nem todo mundo sabe isso, e isso é completamente normal.

Por isso, estou começando algo novo: Blazor do Zero. Uma série de verdade, construída desde os fundamentos, pensada para desenvolvedores que querem realmente entender o que estão construindo — não apenas copiar e colar até funcionar.

Para Quem É Esta Série

Esta série é para você se:

Você é um desenvolvedor .NET que já ouviu falar em Blazor mas nunca teve o tempo ou o ponto de partida certo para se aprofundar.
Você já experimentou Blazor, fez funcionar, mas sente que está adivinhando por que as coisas funcionam.
Você vem do mundo JavaScript/React/Angular e quer entender como é a resposta da Microsoft para o frontend moderno.
Você quer um recurso único e coerente em vez de documentação espalhada e posts de blog dispersos.

Você não precisa ser um desenvolvedor sênior. Você precisa, sim, se sentir confortável com os fundamentos do C# — classes, interfaces, async/await. Se você consegue escrever uma API CRUD simples em ASP.NET Core, você está pronto.

O Que Vamos Abordar

Aqui está um roteiro aproximado do que tenho planejado. Alguns tópicos se expandirão em vários posts conforme necessário:

O que é Blazor? — Modelos de hospedagem, histórico, comparação com o desenvolvimento web tradicional
Seu primeiro app Blazor — Scaffolding, estrutura do projeto, execução local
Componentes — O bloco fundamental de qualquer interface em Blazor
Data binding e eventos — Tornando sua interface reativa
Comunicação entre componentes — Parâmetros, EventCallbacks, valores em cascata
Roteamento e navegação — Como o Blazor lida com URLs e transições de página
Injeção de dependência — Serviços, escopos e o contêiner DI no Blazor
Formulários e validação — EditForm, DataAnnotations, validadores personalizados
HTTP e dados externos — Chamando APIs a partir do seu app Blazor
Autenticação e autorização — Protegendo seu app da forma correta
Interop com JavaScript — Quando você precisa acessar o navegador diretamente
Desempenho e otimização — Virtualização, lazy loading, estratégias de renderização
Testando componentes Blazor — bUnit e como é um bom teste
Deploy — Publicando no Azure, IIS e hosts estáticos

Esta lista vai evoluir. Alguns tópicos se dividirão em vários posts; outros podem ser fundidos. Vou atualizar este post à medida que a série avança e adicionar links para cada entrada conforme forem publicadas.

Por Que Uma Série, Por Que Agora

O Blazor amadureceu muito. Com o .NET 8 e 9, o modelo de renderização foi significativamente reformulado — SSR estático, streaming rendering, Server interativo, WebAssembly interativo e o modo Auto convivem agora sob o mesmo teto. É um framework genuinamente interessante e capaz, mas o salto em complexidade torna a experiência inicial bastante desorientadora.

Quero construir um recurso que te encontre onde você está e te guie por tudo de forma sistemática. Não é um substituto para a documentação oficial — ela é boa e você deve lê-la — mas um companheiro que explica o por quê por trás do o quê.

Como Acompanhar a Série

Cada post da série será suficientemente independente para ser lido sozinho, mas eles também vão se apoiar mutuamente. Se você está começando do zero, recomendo seguir a ordem. Se você está entrando para preencher uma lacuna específica, tudo bem também — vou linkar posts de pré-requisito onde for relevante.

O código de cada post estará disponível no GitHub. Vou compartilhar os links ao longo do caminho.

Até o próximo post.

Tipos de união C#: Uniões discriminadas estão finalmente chegando

Wed, 01 Apr 2026 00:00:00 +0000

Se você escreve C# há algum tempo, há uma boa chance de você ter se deparado com um obstáculo ao tentar modelar algo que pode ser “uma entre várias coisas”. Talvez você precisasse de um método para retornar um valor de sucesso ou um erro. Talvez você estivesse construindo um sistema de pagamento que lida com cartões de crédito, transferências bancárias e carteiras digitais – cada uma com dados totalmente diferentes. Ou talvez você apenas olhou para F# ou Rust e pensou: “Por que não posso ter isso em C#?”

A espera está quase no fim. Sindicatos discriminados estão chegando ao C#.

Este tem sido um dos recursos linguísticos mais solicitados há anos, com discussões na comunidade que remontam a 2017 e antes. A equipe de design da linguagem C# está trabalhando em uma proposta que introduz uma palavra-chave union para definir hierarquias de tipo fechado com correspondência exaustiva de padrões. Neste post, quero explicar o que são os sindicatos discriminados, por que eles são tão importantes, como os falsificamos até agora e como realmente é a sintaxe proposta - com exemplos de código reais para cada um.

Uma observação rápida antes de começarmos: no momento em que este livro foi escrito, o recurso de tipos de união ainda estava em fase de proposta e visualização. A sintaxe e o comportamento que descrevo aqui baseiam-se nos documentos de design mais recentes disponíveis publicamente e nas discussões da equipe de design da linguagem C#. As coisas podem mudar antes do lançamento final. Serei claro sobre o que está confirmado versus o que ainda está em discussão.

O que são sindicatos discriminados?

Em sua essência, uma união discriminada (às vezes chamada de “união marcada” ou “tipo de soma”) é um tipo que pode conter um de um conjunto fixo de valores possíveis, onde cada variante pode transportar dados diferentes. A parte “discriminada” significa que o tempo de execução sempre sabe qual variante é – há uma tag que a identifica.

Pense nisso como um enum, mas onde cada membro pode carregar sua própria carga de dados.

Se você já usou outras linguagens, provavelmente já viu esse conceito antes:

F# teve sindicatos discriminados desde o primeiro dia:

type Shape =
 | Circle of radius: float
 | Rectangle of width: float * height: float
 | Triangle of base: float * height: float

Rust usa enum para a mesma ideia:

enum Shape {
 Circle { radius: f64 },
 Rectangle { width: f64, height: f64 },
 Triangle { base: f64, height: f64 },
}

TypeScript consegue algo semelhante com uniões marcadas:

type Shape =
 | { kind: "circle"; radius: number }
 | { kind: "rectangle"; width: number; height: number }
 | { kind: "triangle"; base: number; height: number };

Em todos esses casos, o compilador conhece todas as variantes possíveis e pode garantir que você lide com todas elas. Esse é o superpoder: verificação de exaustividade. Se você adicionar uma nova variante, o compilador informará onde você esqueceu de manipulá-la.

C# nunca teve uma maneira de primeira classe de expressar isso. Até agora.

Como simulamos sindicatos hoje

Ao longo dos anos, a comunidade C# apresentou diversas soluções alternativas, cada uma com suas próprias vantagens e desvantagens. Deixe-me examinar as abordagens mais comuns.

Registros abstratos com herança

A solução alternativa mais idiomática no C# moderno é usar registros abstratos com tipos derivados selados:

public abstract record Shape
{
 public sealed record Circle(double Radius) : Shape;
 public sealed record Rectangle(double Width, double Height) : Shape;
 public sealed record Triangle(double Base, double Height) : Shape;

 private Shape() { } // Prevent external inheritance
}

Isso funciona razoavelmente bem. Você obtém imutabilidade, igualdade de valores e pode usar correspondência de padrões:

double Area(Shape shape) => shape switch
{
 Shape.Circle c => Math.PI * c.Radius * c.Radius,
 Shape.Rectangle r => r.Width * r.Height,
 Shape.Triangle t => 0.5 * t.Base * t.Height,
 _ => throw new InvalidOperationException("Unknown shape")
};
```Mas existem desvantagens significativas. O compilador não sabe que a hierarquia está fechada, então você sempre precisa daquele braço de descarte `_` ou receberá um aviso. Se você adicionar uma nova variante, o compilador não informará sobre todos os lugares em que você se esqueceu de manipulá-la — o descarte a engole silenciosamente. Isso anula completamente o propósito.

### A Biblioteca OneOf

Outra abordagem popular é o pacote [OneOf](https://github.com/mcintyre321/OneOf) NuGet:

```csharp
public OneOf<Success<Order>, NotFound, ValidationError> ProcessOrder(OrderRequest request)
{
 // ...
}

// Usage
var result = ProcessOrder(request);
result.Switch(
 success => Console.WriteLine($"Order {success.Value.Id} processed"),
 notFound => Console.WriteLine("Order not found"),
 error => Console.WriteLine($"Validation failed: {error.Message}")
);

OneOf fornece verificação exaustiva em tempo de compilação por meio de seus parâmetros de tipo genérico, o que é ótimo. Mas depende da correspondência posicional (primeiro tipo, segundo tipo, etc.), as assinaturas genéricas tornam-se difíceis de manejar rapidamente e não se integram à correspondência de padrões da linguagem. É um hack inteligente, mas ainda é um hack.

Enum manual + padrão de dados

Alguns desenvolvedores seguem o caminho clássico com uma tag enum e um contêiner de dados:

public enum PaymentType { CreditCard, BankTransfer, DigitalWallet }

public class Payment
{
 public PaymentType Type { get; init; }
 public CreditCardInfo? CreditCard { get; init; }
 public BankTransferInfo? BankTransfer { get; init; }
 public DigitalWalletInfo? DigitalWallet { get; init; }
}

Isto é frágil. Nada impede você de definir Type como CreditCard, mas preencher a propriedade BankTransfer. O compilador não pode ajudá-lo e você acaba com erros de tempo de execução e verificações de nulos em todos os lugares. É a abordagem “stringly-typed” para modelagem de tipos e não é escalonável.

Todas essas abordagens compartilham um problema fundamental: elas estão lutando contra a linguagem em vez de trabalhar com ela. O compilador não consegue raciocinar sobre o conjunto fechado de possibilidades, então você perde a propriedade mais valiosa das uniões discriminadas — a verificação exaustiva.

A proposta C#: a palavra-chave `union`

A proposta da equipe da linguagem C# introduz uma palavra-chave union dedicada que define um conjunto fechado de membros nomeados, cada um carregando dados opcionalmente. Aqui está a sintaxe básica conforme proposta:

union Shape
{
 Circle(double Radius),
 Rectangle(double Width, double Height),
 Triangle(double Base, double Height)
}

É isso. Limpo, conciso e imediatamente legível. Cada membro dentro da união define uma variante distinta com seus próprios dados. O compilador sabe que Shape só pode ser uma dessas três coisas.

Nos bastidores, o compilador gera uma hierarquia de tipos selada — semelhante ao que você escreveria à mão com registros abstratos, mas com total consciência do compilador sobre a natureza fechada do tipo. Isso significa que o compilador pode impor exaustividade na correspondência de padrões, que é o principal benefício.

Membros somente de valor

Os membros do sindicato não precisam transportar dados. Você pode misturar membros que transportam dados com membros de valor simples:

union Option<T>
{
 Some(T Value),
 None
}

Este é o tipo clássico Option/Maybe que os programadores funcionais vêm pedindo em C# há anos. None não carrega dados — é apenas uma tag.

Uniões Genéricas

Como você pode ver no exemplo Option<T> acima, os sindicatos apoiam os genéricos. Aqui está um exemplo mais envolvente:

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

Isso abre todo um estilo de tratamento de erros que não depende de exceções para casos de falha esperados – algo que tem sido uma prática padrão em Rust e em linguagens funcionais há anos.

Uniões com Métodos

A proposta também permite que os sindicatos tenham métodos, propriedades computadas e implementem interfaces, assim como qualquer outro tipo:```csharp union Shape { Circle(double Radius), Rectangle(double Width, double Height), Triangle(double Base, double Height);

public double Area => this switch
{
Circle(var r) => Math.PI * r * r,
Rectangle(var w, var h) => w * h,
Triangle(var b, var h) => 0.5 * b * h
};
public double Perimeter => this switch
{
Circle(var r) => 2 * Math.PI * r,
Rectangle(var w, var h) => 2 * (w + h),
Triangle(var b, var h) => b + h + Math.Sqrt(b * b + h * h)
};

}


Observe como a expressão `switch` dentro de `Area` e `Perimeter` não precisa de um braço padrão. O compilador sabe que a união é exaustiva — existem apenas três variantes e todas as três são tratadas. Se você adicionar uma quarta variante posteriormente, o compilador sinalizará todos os `switch` que não lidam com ela.

## Integração de correspondência de padrões

A correspondência de padrões tem evoluído em C# desde a versão 7.0, e os tipos de união são projetados para serem cidadãos de primeira classe desse sistema.

### Expressões de troca exaustivas

O recurso mais impactante é a verificação exaustiva dos switches. Com uniões, o compilador **conhece** todos os casos possíveis:

```csharp
string Describe(Shape shape) => shape switch
{
 Circle(var r) => $"A circle with radius {r}",
 Rectangle(var w, var h) => $"A {w}x{h} rectangle",
 Triangle(var b, var h) => $"A triangle with base {b} and height {h}"
};

Sem braço de descarte. Não _ => throw new NotImplementedException(). Se você esquecer um caso, o compilador emitirá um erro, não um aviso. Esta é uma melhoria fundamental na segurança.

Correspondência de padrões aninhados

As uniões são compostas naturalmente com padrões aninhados:

union Expr
{
 Literal(double Value),
 Add(Expr Left, Expr Right),
 Multiply(Expr Left, Expr Right),
 Negate(Expr Inner)
}

double Evaluate(Expr expr) => expr switch
{
 Literal(var v) => v,
 Add(var left, var right) => Evaluate(left) + Evaluate(right),
 Multiply(var left, var right) => Evaluate(left) * Evaluate(right),
 Negate(var inner) => -Evaluate(inner)
};

Esse tipo de estrutura de dados recursiva é extremamente comum em compiladores, interpretadores, mecanismos de regras e modelagem matemática. Hoje, em C#, você precisaria de uma hierarquia de classes profunda e do padrão de visitante. Com os sindicatos, o código é dramaticamente mais simples.

Cláusulas de proteção

A correspondência de padrões com uniões oferece suporte a guardas when exatamente como seria de esperar:

string Classify(Shape shape) => shape switch
{
 Circle(var r) when r > 100 => "Large circle",
 Circle(var r) when r > 10 => "Medium circle",
 Circle(_) => "Small circle",
 Rectangle(var w, var h) when w == h => "Square",
 Rectangle _ => "Rectangle",
 Triangle _ => "Triangle"
};

Exemplos práticos

Deixe-me examinar alguns cenários do mundo real onde os tipos de união melhoram drasticamente o código.

O padrão de resultado: substituindo exceções por erros esperados

Um dos padrões mais comuns no desenvolvimento de aplicativos modernos é a representação de operações que podem ter êxito ou falhar sem usar exceções para o fluxo de controle. As exceções devem ser excepcionais – coisas como falhas de rede ou condições de falta de memória. Um erro de validação ou um resultado “não encontrado” é um resultado esperado, não uma exceção.

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

union OrderError
{
 NotFound(Guid OrderId),
 InsufficientStock(string ProductId, int Requested, int Available),
 PaymentDeclined(string Reason),
 ValidationFailed(IReadOnlyList<string> Errors)
}

Result<Order, OrderError> ProcessOrder(OrderRequest request)
{
 if (!Validate(request, out var errors))
 return new ValidationFailed(errors);

 var product = catalog.Find(request.ProductId);
 if (product is null)
 return new NotFound(request.OrderId);

 if (product.Stock < request.Quantity)
 return new InsufficientStock(request.ProductId, request.Quantity, product.Stock);

 var paymentResult = paymentGateway.Charge(request.Payment);
 if (!paymentResult.Success)
 return new PaymentDeclined(paymentResult.Message);

 var order = CreateOrder(request, product);
 return new Ok(order);
}

O chamador é então forçado a lidar com todos os resultados possíveis:

var result = ProcessOrder(request);

var response = result switch
{
 Ok(var order) => Results.Created($"/orders/{order.Id}", order),
 Error(NotFound(var id)) => Results.NotFound($"Order {id} not found"),
 Error(InsufficientStock(var pid, var req, var avail)) =>
 Results.Conflict($"Product {pid}: requested {req}, only {avail} available"),
 Error(PaymentDeclined(var reason)) =>
 Results.UnprocessableEntity($"Payment declined: {reason}"),
 Error(ValidationFailed(var errors)) =>
 Results.BadRequest(new { Errors = errors })
};

Sem blocos try-catch, sem tipos de exceção esquecidos, sem surpresas em tempo de execução. Cada modo de falha é visível na assinatura de tipo e aplicado pelo compilador. Esta é uma grande melhoria para a confiabilidade da API.

Modelagem de Domínio: Tipos de Pagamento

Aqui está um exemplo de modelagem de domínio do mundo real – lidando com diferentes métodos de pagamento em um sistema de comércio eletrônico:

union PaymentMethod
{
 CreditCard(string CardNumber, string Expiry, string Cvv),
 BankTransfer(string Iban, string Bic),
 DigitalWallet(string Provider, string Token),
 CashOnDelivery
}

decimal CalculateProcessingFee(PaymentMethod method, decimal amount) => method switch
{
 CreditCard _ => amount * 0.029m + 0.30m,
 BankTransfer _ => 1.50m,
 DigitalWallet(provider: "PayPal", _) => amount * 0.034m + 0.35m,
 DigitalWallet _ => amount * 0.025m,
 CashOnDelivery => 4.99m
};

string FormatForReceipt(PaymentMethod method) => method switch
{
 CreditCard(var num, _, _) => $"Credit Card ending in {num[^4..]}",
 BankTransfer(var iban, _) => $"Bank Transfer ({iban[..4]}****)",
 DigitalWallet(var provider, _) => $"Digital Wallet ({provider})",
 CashOnDelivery => "Cash on Delivery"
};

Compare isso com a abordagem atual, onde você teria uma interface ou classe abstrata com cinco implementações diferentes espalhadas por cinco arquivos, possivelmente com um padrão de visitante no topo. A abordagem sindical mantém a definição dos dados e as operações juntas, legíveis e verificadas exaustivamente.

Máquinas de Estado

As máquinas de estado estão por toda parte no software – processamento de pedidos, mecanismos de fluxo de trabalho, gerenciamento de conexões, estado da interface do usuário. Os sindicatos os tornam explícitos e seguros:

union ConnectionState
{
 Disconnected,
 Connecting(string Host, int Port, DateTime StartedAt),
 Connected(string Host, int Port, TcpClient Client),
 Reconnecting(string Host, int Port, int Attempt, TimeSpan Delay),
 Failed(string Host, Exception Error)
}

ConnectionState HandleEvent(ConnectionState state, ConnectionEvent evt) => (state, evt) switch
{
 (Disconnected, Connect(var host, var port)) =>
 new Connecting(host, port, DateTime.UtcNow),

 (Connecting(var h, var p, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Connecting(var h, var p, _), ConnectionFailed(var ex)) =>
 new Reconnecting(h, p, Attempt: 1, Delay: TimeSpan.FromSeconds(1)),

 (Reconnecting(var h, var p, var attempt, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(var ex)) when attempt >= 5 =>
 new Failed(h, ex),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(_)) =>
 new Reconnecting(h, p, attempt + 1, TimeSpan.FromSeconds(Math.Pow(2, attempt))),

 (Connected(_, _, var client), Disconnect) =>
 new Disconnected,

 _ => state // Ignore events that don't apply to current state
};

Cada estado carrega exatamente os dados relevantes para esse estado. Você não pode acessar acidentalmente um TcpClient quando estiver no estado Connecting porque ele não existe nessa variante. O sistema de tipos impõe os invariantes da máquina de estados.

Considerações sobre serialização e interoperabilidadeUma das questões práticas que surgem imediatamente com os tipos de união é: como serializá-los? Se você estiver criando APIs ou armazenando dados, precisará da serialização JSON para funcionar corretamente.

A equipe de design tem discutido o suporte integrado System.Text.Json para tipos de união. A abordagem esperada envolve a serialização com uma propriedade discriminadora:

{
 "$type": "Circle",
 "radius": 5.0
}

{
 "$type": "Rectangle",
 "width": 10.0,
 "height": 20.0
}

Isso é consistente com o suporte de serialização polimórfica existente introduzido no .NET 7 com atributos JsonDerivedType. A expectativa é que os sindicatos funcionem com System.Text.Json prontos para uso, usando o nome da variante como discriminador de tipo por padrão.

Para o Entity Framework Core, a abordagem provável é armazenar valores de união usando uma coluna discriminadora — semelhante a como o mapeamento de herança de tabela por hierarquia (TPH) já funciona. A integração exata do EF Core ainda está sendo projetada, mas a infraestrutura para lidar com hierarquias de tipo fechado já existe.

Vale a pena notar que a interoperabilidade com outras linguagens .NET deve ser tranquila, já que as uniões serão compiladas em hierarquias de classe IL padrão nos bastidores. O código F# que consome uma união C# o veria como uma hierarquia de tipos padrão e vice-versa.

Como experimentar

No momento em que este artigo foi escrito, os tipos de união estavam disponíveis como um recurso de visualização nas visualizações mais recentes do SDK do .NET. Para experimentar a sintaxe proposta, você precisará:

Instale o SDK de visualização .NET mais recente
Habilite a versão do idioma de visualização em seu arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <LangVersion>preview</LangVersion>
 </PropertyGroup>
</Project>

Lembre-se de que os recursos de visualização estão sujeitos a alterações. A sintaxe, o comportamento e o diagnóstico do compilador podem evoluir significativamente antes do lançamento final. Não envie código de produção dependendo de recursos de linguagem de visualização, mas experimente-os e forneça feedback. A equipe C# monitora ativamente as discussões do repositório csharplang.

Se você quiser acompanhar o andamento da proposta, os principais locais a serem observados são:

O repositório dotnet/csharplang para discussões sobre design de linguagem
O repositório dotnet/roslyn para o progresso da implementação do compilador
O blog .NET para anúncios oficiais

Comparação com abordagens existentes

Deixe-me fazer uma comparação rápida para que você possa ver como as diferentes abordagens se comparam:

Recurso	Registros Abstratos	UmDe<T1,T2>	Enum + Dados	Tipos de União
Verificação de exaustividade	❌ Não	✅ Sim	❌ Não	✅ Sim
Correspondência de padrões	✅ Sim	❌ Limitado	❌ Manual	✅ Nativo
Fechamento imposto pelo compilador	❌Não	✅ Sim	❌Não	✅ Sim
Dados por variante	✅ Sim	✅ Sim	⚠️Frágil	✅ Sim
Legibilidade	⚠️ Verboso	⚠️ Posicional	❌ Pobre	✅ Excelente
Serialização	✅ Manual	⚠️ Complexo	✅ Manual	✅ Integrado
Padrão	⚠️ Moderado	✅ Baixo	⚠️ Alto	✅ Mínimo
Nenhuma dependência externa	✅ Sim	❌ NuGet	✅ Sim	✅ Sim

O que isso significa para o ecossistema .NET

A introdução de sindicatos discriminados terá repercussões em todo o ecossistema .NET. Aqui está o que espero ver:

O design da biblioteca será melhorado. APIs que atualmente retornam null para indicar “não encontrado” ou lançam exceções para falhas de validação poderão retornar tipos Result<T, E> em vez disso. Isso torna os modos de falha explícitos na assinatura de tipo — você pode ver o que pode dar errado observando a assinatura do método, não lendo a documentação ou o código-fonte.

A modelagem de domínio se torna mais expressiva. A lacuna entre o domínio do problema e a representação do código diminui drasticamente. Quando seu especialista em domínio diz “um pagamento pode ser um cartão de crédito, uma transferência bancária ou dinheiro na entrega”, você pode modelar isso diretamente como uma união, em vez de traduzi-lo em uma hierarquia de herança.

As ideias de F# tornam-se acessíveis aos desenvolvedores de C#. Muitos desenvolvedores de C# admiraram o sistema de tipos de F# à distância, mas não conseguiram adotá-lo em suas organizações. Os tipos de união trazem um dos recursos mais poderosos do F# para o C#, o que é uma vitória para todo o ecossistema .NET.

Menos erros de tempo de execução. A verificação exaustiva por si só evitará categorias inteiras de bugs. Cada vez que você adiciona uma nova variante a uma união, o compilador irá guiá-lo para cada lugar na base de código que precisa de atualização. Chega de casos switch esquecidos, chega de NotImplementedException em ramificações padrão que só surgem na produção.

Conclusão

Os sindicatos discriminados estão no topo da lista de desejos da comunidade C# há quase uma década, e por boas razões. Eles resolvem uma lacuna fundamental no sistema de tipos – a capacidade de modelar dados que podem ser “uma entre várias coisas” com segurança imposta pelo compilador.

A palavra-chave union proposta traz uma sintaxe limpa e concisa que se integra profundamente à correspondência de padrões do C#, funciona com genéricos, oferece suporte a métodos e interfaces e permite verificação exaustiva que detecta bugs em tempo de compilação em vez de tempo de execução.

Esteja você construindo modelos de domínio, projetando APIs com tipos de erros explícitos, implementando máquinas de estado ou apenas tentando substituir hierarquias de herança desajeitadas por algo mais natural – os tipos de união mudarão a forma como você escreve C#.

Estamos esperando há muito tempo por isso. A sintaxe é elegante, a integração com os recursos de linguagem existentes é cuidadosa e o impacto prático será sentido em todo o ecossistema .NET.

Fique de olho nas versões prévias, experimente o recurso e forneça feedback à equipe de design de linguagem. Este é um daqueles recursos que, depois de usá-lo, você se perguntará como conseguiu viver sem ele.

Construindo um sistema RAG em C# com Kernel Semântico

Wed, 18 Mar 2026 00:00:00 +0000

Introdução

Se você tentou usar um LLM para responder perguntas sobre seus próprios dados – documentos da empresa, especificações de produtos, bases de conhecimento internas – você provavelmente notou que ele alucina ou apenas diz “Não tenho informações sobre isso”. Isso porque o modelo só sabe no que foi treinado.

RAG (Geração Aumentada de Recuperação) corrige isso. Em vez de ajustar um modelo em seus dados, você recupera partes relevantes de seus documentos no momento da consulta e os transmite ao LLM como contexto. O modelo então gera respostas baseadas em seus dados reais.

Nesta postagem, orientarei você na construção de um pipeline RAG completo em C# usando Kernel Semântico.

Como funciona o RAG

O fluxo é direto:

Ingestão: divida seus documentos em partes, gere embeddings para cada parte e armazene-os em um banco de dados vetorial
Consulta: Quando um usuário faz uma pergunta, gere uma incorporação para a consulta, pesquise no banco de dados de vetores por partes semelhantes
Gerar: Passe os pedaços recuperados como contexto para o LLM junto com a pergunta do usuário

É isso. A mágica está nos embeddings – eles capturam o significado semântico do texto como vetores, para que você possa encontrar conteúdo relevante mesmo quando as palavras exatas não correspondem.

Pré-requisitos

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.Extensions.VectorData.Abstractions
dotnet add package Microsoft.SemanticKernel.Connectors.InMemory

Para produção, você trocaria o armazenamento na memória pelo Azure AI Search, Qdrant, Pinecone ou qualquer outro banco de dados de vetores compatível. Mas o in-memory é perfeito para aprendizado e prototipagem.

Configurando o kernel

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;
using Microsoft.SemanticKernel.Embeddings;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-3-small",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

var kernel = builder.Build();

Precisamos de dois modelos: um para completar o chat (responder perguntas) e outro para gerar embeddings (transformar texto em vetores).

Definindo o modelo de dados

Precisamos de uma classe para representar nossos pedaços de documentos no armazenamento de vetores:

using Microsoft.Extensions.VectorData;

public class DocumentChunk
{
 [VectorStoreRecordKey]
 public string Id { get; set; } = Guid.NewGuid().ToString();

 [VectorStoreRecordData]
 public string Content { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public string Source { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public int ChunkIndex { get; set; }

 [VectorStoreRecordVector(1536)]
 public ReadOnlyMemory<float> Embedding { get; set; }
}

O atributo VectorStoreRecordVector(1536) informa ao armazenamento vetorial a dimensão de nossos embeddings. O modelo text-embedding-3-small produz vetores de 1536 dimensões.

Fragmentação de documentos

Antes de podermos criar embeddings, precisamos dividir nossos documentos em partes gerenciáveis. Aqui está um divisor de texto simples:

public static class TextChunker
{
 public static List<string> SplitText(string text, int maxChunkSize = 500, int overlap = 50)
 {
 var chunks = new List<string>();
 var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
 var currentChunk = new System.Text.StringBuilder();

 foreach (var paragraph in paragraphs)
 {
 if (currentChunk.Length + paragraph.Length > maxChunkSize && currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());

 // Keep overlap from the end of the previous chunk
 var overlapText = currentChunk.ToString();
 currentChunk.Clear();
 if (overlapText.Length > overlap)
 {
 currentChunk.Append(overlapText[^overlap..]);
 currentChunk.Append(' ');
 }
 }

 currentChunk.Append(paragraph);
 currentChunk.Append("\n\n");
 }

 if (currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());
 }

 return chunks;
 }
}

A sobreposição é importante — ela garante que o contexto na fronteira entre os pedaços não seja perdido. Se uma frase relevante for dividida em dois blocos, a sobreposição significa que ela aparecerá integralmente em pelo menos um deles.

Ingestão de documentos

Agora vamos juntar tudo para ingerir documentos em nosso armazenamento de vetores:

var vectorStore = new InMemoryVectorStore();
var collection = vectorStore.GetCollection<string, DocumentChunk>("documents");
await collection.CreateCollectionIfNotExistsAsync();

var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

async Task IngestDocument(string content, string source)
{
 var chunks = TextChunker.SplitText(content);

 for (int i = 0; i < chunks.Count; i++)
 {
 var embedding = await embeddingService.GenerateEmbeddingAsync(chunks[i]);

 var chunk = new DocumentChunk
 {
 Content = chunks[i],
 Source = source,
 ChunkIndex = i,
 Embedding = embedding
 };

 await collection.UpsertAsync(chunk);
 }

 Console.WriteLine($"✅ Ingested {chunks.Count} chunks from {source}");
}

// Ingest some documents
var doc1 = await File.ReadAllTextAsync("docs/product-guide.md");
var doc2 = await File.ReadAllTextAsync("docs/faq.md");
var doc3 = await File.ReadAllTextAsync("docs/troubleshooting.md");

await IngestDocument(doc1, "product-guide.md");
await IngestDocument(doc2, "faq.md");
await IngestDocument(doc3, "troubleshooting.md");

Procurando por pedaços relevantes

Quando um usuário faz uma pergunta, geramos uma incorporação para sua consulta e procuramos por partes semelhantes:

async Task<List<DocumentChunk>> SearchAsync(string query, int topK = 3)
{
 var queryEmbedding = await embeddingService.GenerateEmbeddingAsync(query);

 var searchResults = await collection.VectorizedSearchAsync(
 queryEmbedding,
 new VectorSearchOptions { Top = topK });

 var results = new List<DocumentChunk>();
 await foreach (var result in searchResults.Results)
 {
 results.Add(result.Record);
 }

 return results;
}

Gerando respostas com contexto

Agora a parte RAG – pegamos os pedaços recuperados e os incluímos como contexto em nosso prompt:

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();

async Task<string> AskAsync(string question)
{
 // Step 1: Retrieve relevant chunks
 var relevantChunks = await SearchAsync(question);

 // Step 2: Build context from chunks
 var context = string.Join("\n\n---\n\n",
 relevantChunks.Select(c => $"[Source: {c.Source}]\n{c.Content}"));

 // Step 3: Generate answer with context
 var history = new ChatHistory();
 history.AddSystemMessage($$"""
 You are a helpful assistant that answers questions based on the provided context.
 Use ONLY the information from the context to answer. If the context doesn't contain
 enough information to answer the question, say "I don't have enough information
 to answer that question."

 Do not make up information. Always cite the source document when possible.

 Context:
 {{context}}
 """);

 history.AddUserMessage(question);

 var response = await chatService.GetChatMessageContentAsync(history);
 return response.Content ?? "No response generated.";
}

Usando

// Ask questions about your documents
var answer1 = await AskAsync("How do I reset my password?");
Console.WriteLine($"Q: How do I reset my password?\nA: {answer1}\n");

var answer2 = await AskAsync("What are the system requirements?");
Console.WriteLine($"Q: What are the system requirements?\nA: {answer2}\n");

var answer3 = await AskAsync("What's the capital of France?");
Console.WriteLine($"Q: What's the capital of France?\nA: {answer3}\n");
// Should respond with "I don't have enough information" since it's not in the docs

Passando para produção

O armazenamento de vetores na memória é ótimo para prototipagem, mas para produção você precisará de um banco de dados de vetores persistente. O Kernel Semântico possui conectores para diversas opções:

# Azure AI Search
dotnet add package Microsoft.SemanticKernel.Connectors.AzureAISearch

# Qdrant
dotnet add package Microsoft.SemanticKernel.Connectors.Qdrant

# Redis
dotnet add package Microsoft.SemanticKernel.Connectors.Redis

A troca é simples, pois todos implementam a mesma interface IVectorStore:

// Instead of InMemoryVectorStore, use:
using Azure;
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var vectorStore = new AzureAISearchVectorStore(
 new Azure.Search.Documents.Indexes.SearchIndexClient(
 new Uri(config["AzureAISearch:Endpoint"]),
 new AzureKeyCredential(config["AzureAISearch:ApiKey"])));
```Todo o resto permanece igual. Essa é a beleza da abstração.

## Dicas para construir sistemas RAG

Algumas coisas que aprendi da maneira mais difícil:

- **O tamanho do pedaço é muito importante.** Muito pequeno e você perde o contexto. Muito grande e você desperdiça tokens em conteúdo irrelevante. Comece com 500-800 tokens e ajuste com base nos seus dados.
- **A sobreposição evita problemas de limite.** Uma sobreposição de 50-100 tokens entre pedaços geralmente é suficiente.
- **Recupere mais do que você pensa.** Comece com `topK = 5` e reduza se estiver recebendo muito ruído. É melhor ter contexto extra do que perder a parte relevante.
- **As instruções do sistema são cruciais.** Seja bem explícito ao usar apenas o contexto fornecido. Sem essa instrução, o modelo terá alucinações felizes “com base em seus dados de treinamento”.
- **Rastreie as fontes.** Sempre armazene metadados com seus pedaços para que você possa citar de onde veio a resposta. Os usuários confiam mais nas respostas quando podem verificar a fonte.
- **Reclassifique se necessário.** A similaridade do vetor não é perfeita. Para aplicações críticas, adicione uma etapa de reclassificação usando um modelo de codificador cruzado para melhorar a precisão.

## Conclusão

RAG é um dos padrões mais práticos em IA atualmente. Ele permite que você crie sistemas de perguntas e respostas com tecnologia de IA sobre seus próprios dados sem ajuste fino, e o Kernel Semântico o torna surpreendentemente limpo em C#. Comece com o armazenamento na memória, acerte a fragmentação e os prompts e, em seguida, troque por um banco de dados vetorial real quando estiver pronto para produção.

Boa codificação!

## Recursos

- [Documentação do armazenamento de vetores do kernel semântico](https://learn.microsoft.com/en-us/semantic-kernel/concepts/vector-store-connectors/)
- [Padrão RAG com Azure AI Search](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview)
- [Modelos de incorporação de texto](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings)

Construindo fluxos de trabalho de agentes com o Microsoft Agent Framework

Tue, 10 Feb 2026 00:00:00 +0000

Introdução

Se você leu minhas postagens anteriores sobre o Agent Framework da Microsoft, sabe como criar agentes individuais e até mesmo bate-papos em grupo com vários agentes. Mas em cenários do mundo real, muitas vezes você precisa de algo mais estruturado: um fluxo de trabalho em que os agentes executam em uma ordem específica, passam os resultados entre si e lidam com a lógica de ramificação com base nos resultados.

É exatamente isso que os recursos de fluxo de trabalho do Agent Framework oferecem. Em vez de colocar os agentes em um bate-papo em grupo e esperar que eles descubram, você define etapas, dependências e fluxo de dados explícitos entre os agentes.

O que são fluxos de trabalho de agentes?

Pense nos fluxos de trabalho dos agentes como um pipeline. Cada etapa é realizada por um agente especializado e o resultado de uma etapa alimenta a próxima. Você pode executar etapas sequencialmente, em paralelo ou condicionalmente com base nos resultados.

Alguns exemplos:

Pipeline de conteúdo: Pesquisa → Rascunho → Revisão → Publicar
Processamento de dados: Extrair → Transformar → Validar → Carregar
Suporte ao cliente: Classificar → Encaminhar → Responder → Acompanhamento

Pré-requisitos

Certifique-se de ter os pacotes mais recentes do Agent Framework:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

E um ponto final Azure OpenAI ou OpenAI configurado.

Construindo um fluxo de trabalho sequencial

Vamos construir um fluxo de trabalho de criação de conteúdo com três agentes: um pesquisador, um redator e um editor.

Definindo os agentes

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var kernel = Kernel.CreateBuilder()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"])
 .Build();

var researcher = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = """
 You are a research specialist. Given a topic, find key facts, statistics,
 and talking points. Return a structured research brief with bullet points.
 Be thorough but concise.
 """,
 Kernel = kernel
};

var writer = new ChatCompletionAgent
{
 Name = "Writer",
 Instructions = """
 You are a technical blog writer. Given a research brief, write a clear
 and engaging blog post. Use a conversational tone, include code examples
 where relevant, and structure the post with clear headings.
 """,
 Kernel = kernel
};

var editor = new ChatCompletionAgent
{
 Name = "Editor",
 Instructions = """
 You are a senior editor. Review the blog post for clarity, accuracy,
 grammar, and flow. Return the corrected version with a summary of
 changes made at the end.
 """,
 Kernel = kernel
};

Executando sequencialmente

O fluxo de trabalho mais simples é sequencial — cada agente processa a saída do anterior:

using Microsoft.SemanticKernel.Agents.Chat;
using Microsoft.SemanticKernel.ChatCompletion;

async Task<string> RunSequentialWorkflow(string topic)
{
 var history = new ChatHistory();
 string currentInput = $"Research the following topic: {topic}";

 var agents = new[] { researcher, writer, editor };

 foreach (var agent in agents)
 {
 history.AddUserMessage(currentInput);

 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 currentInput = response.ToString();
 Console.WriteLine($"✅ {agent.Name} completed");
 }

 return currentInput;
}

var result = await RunSequentialWorkflow("Blazor render modes in .NET 9");
Console.WriteLine(result);

Cada agente obtém o contexto acumulado, processa-o e o resultado passa para a próxima etapa.

Execução paralela

Às vezes, os agentes podem trabalhar de forma independente. Por exemplo, você pode querer pesquisar vários subtópicos ao mesmo tempo:

async Task<List<string>> RunParallelResearch(string[] topics)
{
 var tasks = topics.Select(async topic =>
 {
 var history = new ChatHistory();
 history.AddUserMessage($"Research: {topic}");

 var response = new System.Text.StringBuilder();
 await foreach (var message in researcher.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 Console.WriteLine($"✅ Research completed: {topic}");
 return response.ToString();
 });

 var results = await Task.WhenAll(tasks);
 return results.ToList();
}

var topics = new[]
{
 "Blazor SSR streaming",
 "Enhanced navigation in .NET 9",
 "Render mode boundaries"
};

var briefs = await RunParallelResearch(topics);

Em seguida, você pode alimentar todos os resumos de pesquisa em um único agente redator para produzir uma postagem coesa.

Ramificação condicional

Fluxos de trabalho reais precisam de decisões. Talvez você queira uma etapa de verificação de qualidade que retorne ao redator se a postagem não for boa o suficiente:

var qualityChecker = new ChatCompletionAgent
{
 Name = "QualityChecker",
 Instructions = """
 You are a quality assurance reviewer. Evaluate the blog post on:
 1. Technical accuracy
 2. Clarity and readability
 3. Completeness

 Respond with either:
 - "APPROVED" if the post meets all criteria
 - "REVISION NEEDED: [specific feedback]" if changes are required

 Be strict. Only approve posts that are truly ready to publish.
 """,
 Kernel = kernel
};

async Task<string> RunWithQualityLoop(string topic, int maxRevisions = 3)
{
 var history = new ChatHistory();

 // Step 1: Research
 history.AddUserMessage($"Research: {topic}");
 string research = await InvokeAgent(researcher, history);

 // Step 2: Write
 history.AddUserMessage(research);
 string draft = await InvokeAgent(writer, history);

 // Step 3: Quality loop
 for (int i = 0; i < maxRevisions; i++)
 {
 var qaHistory = new ChatHistory();
 qaHistory.AddUserMessage($"Review this post:\n\n{draft}");
 string qaResult = await InvokeAgent(qualityChecker, qaHistory);

 if (qaResult.Contains("APPROVED", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine($"✅ Approved after {i + 1} review(s)");
 return draft;
 }

 Console.WriteLine($"🔄 Revision {i + 1}: {qaResult[..Math.Min(100, qaResult.Length)]}...");

 // Send back to writer with feedback
 history.AddUserMessage($"Please revise based on this feedback:\n{qaResult}");
 draft = await InvokeAgent(writer, history);
 }

 Console.WriteLine("⚠️ Max revisions reached, returning latest draft");
 return draft;
}

async Task<string> InvokeAgent(ChatCompletionAgent agent, ChatHistory history)
{
 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }
 return response.ToString();
}

Esse padrão é super útil. O verificador de qualidade atua como uma porta e o fluxo de trabalho faz um loop até que a saída seja boa o suficiente ou atinja o limite máximo de revisão.

Adicionando plug-ins a agentes de fluxo de trabalho

Os agentes em fluxos de trabalho podem usar plug-ins da mesma forma que os agentes autônomos. É aqui que as coisas ficam realmente poderosas – os agentes podem chamar APIs, consultar bancos de dados ou realizar operações de arquivo como parte de sua etapa de fluxo de trabalho:

var researcherWithTools = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = "Research the topic using available tools. Summarize findings.",
 Kernel = kernel
};

// Add a web search plugin
kernel.Plugins.AddFromType<WebSearchPlugin>();

// Add a database plugin
kernel.Plugins.AddFromObject(new DatabasePlugin(connectionString), "Database");

public class WebSearchPlugin
{
 [KernelFunction, Description("Search the web for information")]
 public async Task<string> SearchAsync(
 [Description("The search query")] string query)
 {
 // Your search implementation
 using var httpClient = new HttpClient();
 var response = await httpClient.GetStringAsync(
 $"https://api.search.example.com?q={Uri.EscapeDataString(query)}");
 return response;
 }
}

Tratamento de erros em fluxos de trabalho

Ao encadear vários agentes, o tratamento de erros se torna crítico. Você não quer que uma etapa com falha trave todo o fluxo de trabalho silenciosamente:

async Task<WorkflowResult> RunResilientWorkflow(string input)
{
 var result = new WorkflowResult();

 try
 {
 result.Research = await InvokeAgent(researcher, new ChatHistory(input));
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Research failed: {ex.Message}");
 return result;
 }

 try
 {
 var writeHistory = new ChatHistory(result.Research);
 result.Draft = await InvokeAgent(writer, writeHistory);
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Writing failed: {ex.Message}");
 result.Draft = result.Research; // Fallback to research output
 }

 result.Success = result.Errors.Count == 0;
 return result;
}

class WorkflowResult
{
 public string Research { get; set; } = "";
 public string Draft { get; set; } = "";
 public List<string> Errors { get; set; } = new();
 public bool Success { get; set; }
}

Melhores práticas

Depois de criar vários fluxos de trabalho de agentes, eis o que aprendi:- Mantenha o foco nas instruções do agente — cada agente deve fazer uma coisa bem feita. Não tente ser um agente canivete suíço.

Limite o contexto — não passe todo o histórico da conversa para todos os agentes. Dê a cada passo apenas o que ele precisa.
Defina limites de revisão — loops de qualidade são ótimos, mas podem funcionar para sempre se você não tomar cuidado. Sempre tenha um limite máximo de iterações.
Registre tudo — as saídas do agente podem ser imprevisíveis. Registre a entrada e a saída de cada etapa para depuração.
Use a execução paralela com sabedoria — isso acelera as coisas, mas observe os limites de taxa da API e os custos de token.
Teste primeiro com modelos menores — desenvolva e teste sua lógica de fluxo de trabalho com GPT-3.5 antes de mudar para GPT-4o para produção.

Conclusão

Os fluxos de trabalho dos agentes permitem criar pipelines de IA complexos e de várias etapas, nos quais cada agente é um especialista. Comece com fluxos de trabalho sequenciais, adicione execução paralela onde as etapas são independentes e use ramificação condicional para portas de qualidade. Os padrões são combináveis – depois de pegar o jeito, você pode construir uma automação bastante sofisticada.

Boa codificação!

Recursos

Ciclo de vida do componente Blazor: o guia completo

Thu, 15 Jan 2026 00:00:00 +0000

Já uso o Blazor há algum tempo e, honestamente, os métodos de ciclo de vida me confundiram no início. OnInitialized versus OnInitializedAsync? OnParametersSet versus OnAfterRender? Quando StateHasChanged realmente aciona uma nova renderização? Depois de muitas tentativas e erros, finalmente tenho um modelo mental sólido para tudo isso.

O ciclo de vida em resumo

Quando um componente Blazor é renderizado, ele passa por estes métodos em ordem:

SetParametersAsync
OnInitialized / OnInitializedAsync
OnParametersSet / OnParametersSetAsync
OnAfterRender / OnAfterRenderAsync
Dispose / DisposeAsync

Vamos examinar cada um deles.

#SetParametersAsync

Este é o primeiro método chamado. Ele recebe o ParameterView bruto do componente pai. Na maioria das vezes você não substitui isso - o Blazor lida com os parâmetros de mapeamento automaticamente. Mas se você precisar de manipulação ou validação de parâmetros personalizados antes de serem atribuídos:

public override async Task SetParametersAsync(ParameterView parameters)
{
 // Custom logic before parameters are set
 if (parameters.TryGetValue<string>("Title", out var title))
 {
 Console.WriteLine($"Title is being set to: {title}");
 }

 await base.SetParametersAsync(parameters);
}

Eu usei isso exatamente uma vez em um projeto real. Na maioria das vezes você vai pular isso.

#OnInitialized/OnInitializedAsync

É aqui que você faz o trabalho de configuração – carrega dados, inicializa serviços, define valores padrão. Ele é executado uma vez quando o componente é criado pela primeira vez.

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 }
}

Uma coisa que me surpreendeu: no Blazor Server, OnInitializedAsync é chamado duas vezes durante a pré-renderização. A primeira vez durante a pré-renderização do lado do servidor e a segunda vez quando a conexão SignalR é estabelecida. Se sua chamada de API for cara, você pode querer cuidar disso:

private bool isPrerendering = true;

protected override async Task OnInitializedAsync()
{
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 isPrerendering = false;
}

Ou melhor ainda, use PersistentComponentState para evitar totalmente a chamada dupla.

#OnParametersSet/OnParametersSetAsync

Isso é acionado sempre que o componente pai é renderizado novamente e passa novos valores de parâmetro. Ele também dispara após OnInitialized. Este é o lugar certo para reagir às alterações de parâmetros:

[Parameter]
public int CategoryId { get; set; }

private int previousCategoryId;
private List<Product> products = new();

protected override async Task OnParametersSetAsync()
{
 if (CategoryId != previousCategoryId)
 {
 previousCategoryId = CategoryId;
 products = await Http.GetFromJsonAsync<List<Product>>(
 $"api/products?category={CategoryId}");
 }
}

A verificação de CategoryId != previousCategoryId é importante - sem ela, você recarregaria os dados toda vez que o pai fosse renderizado novamente, mesmo que a categoria não mudasse.

#OnAfterRender/OnAfterRenderAsync

Isso é acionado depois que o componente é renderizado no DOM. O parâmetro firstRender informa se é a renderização inicial. Este é o local para chamadas de interoperabilidade JS, já que os elementos DOM existem neste ponto:

[Inject]
private IJSRuntime JS { get; set; }

protected override async Task OnAfterRenderAsync(bool firstRender)
{
 if (firstRender)
 {
 await JS.InvokeVoidAsync("initializeChart", chartElement);
 }
}

Eu uso muito firstRender para evitar a reinicialização de bibliotecas JavaScript em cada nova renderização. Se você estiver configurando ouvintes de eventos, bibliotecas de gráficos ou qualquer coisa que toque diretamente no DOM, é aqui que tudo vai.

Deverenderizar

Este é menos conhecido, mas super útil. Ele controla se um componente é renderizado novamente quando StateHasChanged é chamado:

private bool shouldRender = true;

protected override bool ShouldRender() => shouldRender;

private void HeavyOperation()
{
 shouldRender = false;

 // Do a bunch of state changes without triggering renders
 for (int i = 0; i < 1000; i++)
 {
 items[i].Process();
 }

 shouldRender = true;
 StateHasChanged(); // Now render once with all changes
}

Usei isso para otimizar componentes que processam listas grandes. Em vez de renderizar novamente a cada alteração de item, você agrupa as atualizações e renderiza uma vez no final.

Dispose/DisposeAsync

Quando um componente é removido da UI, você deve limpar todos os recursos. Implemente IDisposable ou IAsyncDisposable:

@implements IAsyncDisposable

@code {
 private Timer? timer;
 private IJSObjectReference? jsModule;

 protected override void OnInitialized()
 {
 timer = new Timer(OnTick, null, 0, 1000);
 }

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 jsModule = await JS.InvokeAsync<IJSObjectReference>("import", "./timer.js");
 }
 }

 public async ValueTask DisposeAsync()
 {
 timer?.Dispose();

 if (jsModule is not null)
 {
 await jsModule.DisposeAsync();
 }
 }
}

Coisas comuns para descartar: temporizadores, assinaturas de eventos, referências de módulos JS, CancellationTokenSource e quaisquer serviços IDisposable que você criou.

#EstadoHasChangedEste não é um método de ciclo de vida, mas está intimamente relacionado. Diz ao Blazor “ei, meu estado mudou, por favor, me renderize novamente.” O Blazor o chama automaticamente após manipuladores de eventos, mas às vezes você precisa chamá-lo manualmente — normalmente quando o estado muda fora do fluxo de eventos normal do Blazor:

private async Task StartPolling()
{
 while (!cts.Token.IsCancellationRequested)
 {
 data = await Http.GetFromJsonAsync<Data>("api/data");
 StateHasChanged(); // Manual call needed since this isn't a Blazor event
 await Task.Delay(5000, cts.Token);
 }
}

Uma observação importante: se você estiver atualizando a partir de um thread em segundo plano no Blazor Server, use InvokeAsync:

await InvokeAsync(() =>
{
 data = newData;
 StateHasChanged();
});

A imagem completa

Esta é a ordem em que tudo acontece:

Component created
 └─ SetParametersAsync
 └─ OnInitialized / OnInitializedAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ Render
 └─ OnAfterRender(firstRender: true)

Parameter change from parent
 └─ SetParametersAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ ShouldRender?
 └─ Render
 └─ OnAfterRender(firstRender: false)

Component removed
 └─ Dispose / DisposeAsync

Depois de ter esse fluxo em mente, a depuração de problemas do ciclo de vida se torna muito mais fácil.

Espero que você tenha gostado da postagem! Sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca.

Recursos

Agent Framework da Microsoft para salvar o Natal

Tue, 16 Dec 2025 00:00:00 +0000

Introdução

Encontrar os presentes de Natal perfeitos pode ser estressante. Entre o brainstorming de ideias para presentes, a comparação de preços entre lojas e a garantia de que tudo chegue no prazo, as compras de fim de ano rapidamente se tornam cansativas. E se pudéssemos delegar essas tarefas a agentes especializados de IA que trabalham juntos? Nesta postagem, exploraremos como usar o Agent Framework da Microsoft para construir um sistema multiagente onde cada agente se especializa em uma tarefa específica, desde a geração de ideias de presentes até a comparação de preços, tudo coordenado por meio de fluxos de trabalho.

Calendário Festivo de Tecnologia 2025

Este projeto faz parte da minha sessão no Festive Tech Calendar 2025, um evento comunitário incrível que celebra a tecnologia durante as festas de fim de ano. Você pode encontrar mais sobre o evento em Sessionize.

O que é o Agent Framework da Microsoft?

O Agent Framework é a solução da Microsoft para construir, orquestrar e implantar agentes de IA e sistemas multiagentes. Ele fornece uma base flexível para a criação de agentes que podem trabalhar sequencialmente, simultaneamente ou por meio de padrões de transferência. A estrutura oferece suporte aos modelos OpenAI, Azure OpenAI e Microsoft Foundry, tornando-a incrivelmente versátil.

Os principais recursos incluem:

Orquestração multiagente: bate-papo em grupo, padrões sequenciais, simultâneos e de transferência
Ecossistema de plug-ins: Estenda com funções nativas, OpenAPI e Model Context Protocol (MCP)
Suporte ao fluxo de trabalho: crie pipelines de agentes complexos com executores e bordas

Pré-requisitos

Antes de mergulhar no código, certifique-se de ter:

-.NET 9

Acesso Azure OpenAI (ou chave API OpenAI)
Visual Studio ou Código do Visual Studio

Instale os pacotes necessários (observe que o sinalizador --prerelease é necessário durante a visualização):

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Azure.AI.Agents.Persistent --prerelease

Os agentes de compras de presentes

Nosso localizador de presentes de Natal será composto por três agentes especializados trabalhando juntos:

Agente de ideias para presentes - Gera sugestões criativas de presentes com base no perfil do destinatário
Agente de comparação de preços - Encontra os melhores preços em diferentes lojas
Agente de Resumo - Compila as recomendações finais

Os modelos

Vamos começar definindo nossos modelos de dados que fluirão pelo pipeline do agente:

public class GiftRecipient
{
 public string Name { get; set; } = string.Empty;
 public int Age { get; set; }
 public List<string> Interests { get; set; } = [];
 public decimal Budget { get; set; }
}

public class GiftIdea
{
 public string Name { get; set; } = string.Empty;
 public string Description { get; set; } = string.Empty;
 public string Category { get; set; } = string.Empty;
 public decimal EstimatedPrice { get; set; }
}

public class PriceResult
{
 public string GiftName { get; set; } = string.Empty;
 public string Store { get; set; } = string.Empty;
 public decimal Price { get; set; }
 public string Url { get; set; } = string.Empty;
}

public class GiftRecommendation
{
 public GiftIdea Gift { get; set; } = new();
 public List<PriceResult> Prices { get; set; } = [];
 public PriceResult? BestDeal { get; set; }
}

Construindo os Agentes

A beleza do Agent Framework é a facilidade de criar agentes especializados. Cada agente é simplesmente um ChatClientAgent com um prompt de sistema específico que define sua experiência.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

public static class ChristmasAgentFactory
{
 public static AIAgent CreateGiftIdeaAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a creative Christmas gift advisor. When given information about a person
 (age, interests, budget), you suggest thoughtful and personalized gift ideas.

 For each suggestion, provide:
 - Gift name
 - Brief description of why it's a good fit
 - Category (Electronics, Books, Fashion, Home, Experience, etc.)
 - Estimated price range

 Always suggest 3-5 gift options within the specified budget.
 Format your response as a structured list.");
 }

 public static AIAgent CreatePriceComparisonAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a price comparison specialist. Given a list of gift ideas,
 you research and compare prices from different online retailers.

 For each gift, provide:
 - Store name (Amazon, Best Buy, Target, Walmart, etc.)
 - Current price
 - Any available discounts or deals

 Always highlight the best deal for each item.
 Consider shipping costs and delivery times for Christmas.");
 }

 public static AIAgent CreateSummaryAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a gift recommendation summarizer. Take the gift ideas and price
 comparisons and create a final recommendation report.

 Your summary should:
 - Rank gifts by value (quality vs price)
 - Highlight the top pick with reasoning
 - Include total cost estimate
 - Add any tips for holiday shopping

 Make the summary cheerful and festive!");
 }
}

Criando o fluxo de trabalho

Agora vem a parte divertida: conectar nossos agentes em um fluxo de trabalho sequencial. O Agent Framework fornece WorkflowBuilder e AgentWorkflowBuilder para compor agentes em diferentes padrões.

public static class ChristmasGiftWorkflow
{
 public static async Task RunAsync()
 {
 // Set up the Azure OpenAI client
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
 ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
 ?? "gpt-4o-mini";

 var chatClient = new AzureOpenAIClient(
 new Uri(endpoint),
 new DefaultAzureCredential())
 .GetChatClient(deploymentName)
 .AsIChatClient();

 // Create our specialized agents
 AIAgent giftIdeaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
 AIAgent priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
 AIAgent summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

 // Build a sequential workflow: Ideas -> Prices -> Summary
 var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftFinder",
 [giftIdeaAgent, priceAgent, summaryAgent]);

 // Define our gift recipient
 var recipient = new GiftRecipient
 {
 Name = "Mom",
 Age = 55,
 Interests = ["gardening", "cooking", "reading", "yoga"],
 Budget = 100
 };

 var prompt = $@"Find Christmas gifts for {recipient.Name},
 age {recipient.Age}, who enjoys {string.Join(", ", recipient.Interests)}.
 Budget: ${recipient.Budget}";

 // Execute the workflow with streaming
 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

 // Send the turn token to start processing
 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 // Watch for workflow events
 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is AgentRunUpdateEvent agentUpdate)
 {
 Console.Write(agentUpdate.Data);
 }
 else if (evt is WorkflowOutputEvent outputEvent)
 {
 Console.WriteLine("\n🎄 Final Recommendations:");
 Console.WriteLine(outputEvent.Data);
 }
 }
 }
}

Executando Agentes Simultaneamente

E se quisermos procurar presentes para várias pessoas ao mesmo tempo? O Agent Framework oferece suporte à execução simultânea, o que é perfeito para este cenário:

public static async Task FindGiftsForEveryoneAsync(IChatClient chatClient, List<GiftRecipient> recipients)
{
 // Create an agent for each recipient
 var agents = recipients.Select(r => new ChatClientAgent(
 chatClient,
 $@"Find the perfect Christmas gift for {r.Name} (age {r.Age}),
 who loves {string.Join(", ", r.Interests)}. Budget: ${r.Budget}.
 Provide one well-researched recommendation with price."
 )).ToList();

 // Build a concurrent workflow - all agents run in parallel
 var workflow = AgentWorkflowBuilder.BuildConcurrent(
 "FamilyGiftFinder",
 agents);

 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, "Find gifts now!"));

 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is WorkflowOutputEvent output)
 {
 Console.WriteLine("🎁 All gift recommendations ready!");
 Console.WriteLine(output.Data);
 }
 }
}

Executores personalizados para mais controlePara cenários mais complexos, você pode criar executores personalizados que oferecem controle refinado sobre o fluxo de trabalho:

public sealed class GiftValidatorExecutor : Executor<List<ChatMessage>, List<ChatMessage>>
{
 public GiftValidatorExecutor() : base("GiftValidator") { }

 public override async ValueTask<List<ChatMessage>> HandleAsync(
 List<ChatMessage> messages,
 IWorkflowContext context,
 CancellationToken cancellationToken = default)
 {
 var lastMessage = messages.LastOrDefault()?.Text ?? "";

 // Validate that suggestions are within budget
 if (lastMessage.Contains("over budget", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine("⚠️ Some suggestions exceeded budget, filtering...");
 // Add validation logic here
 }

 Console.WriteLine("✅ Gift suggestions validated!");
 return messages;
 }
}

Você pode então inserir este executor em seu fluxo de trabalho:

var validator = new GiftValidatorExecutor();

var workflow = new WorkflowBuilder(giftIdeaAgent)
 .AddEdge(giftIdeaAgent, validator)
 .AddEdge(validator, priceAgent)
 .AddEdge(priceAgent, summaryAgent)
 .WithOutputFrom(summaryAgent)
 .Build();

Adicionando pesquisa real na Web com o Bing Grounding

Até o momento, nossos agentes geram respostas baseadas no conhecimento do modelo de IA. Mas e se quisermos pesquisar na web os preços e a disponibilidade reais dos produtos? É aqui que entra o Grounding with Bing Search. É uma ferramenta disponível no Microsoft Foundry (anteriormente Azure AI Foundry) que permite que seus agentes incorporem dados públicos da Web em tempo real ao gerar respostas.

Primeiro, você precisará criar um recurso Grounding with Bing Search no Portal do Azure. Certifique-se de criá-lo no mesmo grupo de recursos do seu projeto de IA.

Configurando o aterramento com o Bing Search

A beleza do Grounding with Bing Search é que ele se integra diretamente aos Azure AI Agents. O agente decide quando usar a ferramenta de pesquisa com base na consulta do usuário, pesquisa na web e usa os resultados para gerar uma resposta fundamentada.

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public static class BingGroundingSetup
{
 public static async Task<PersistentAgent> CreateAgentWithBingGroundingAsync(
 string projectEndpoint,
 string modelDeploymentName,
 string bingConnectionId)
 {
 // Create the Persistent Agents client
 var agentClient = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());

 // Configure the Bing Grounding tool
 var bingGroundingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(bingConnectionId)]
 )
 );

 // Create the agent with Bing Grounding enabled
 var agent = await agentClient.Administration.CreateAgentAsync(
 model: modelDeploymentName,
 name: "ChristmasPriceHunter",
 instructions: @"You are a Christmas gift price comparison specialist.

 When given gift ideas, use Bing to search for:
 - Current prices at major retailers (Amazon, Best Buy, Target, Walmart)
 - Available discounts and holiday deals
 - Shipping times to ensure delivery before Christmas

 Always provide URLs to the products you find.
 Highlight the best deals and recommend where to buy.",
 tools: [bingGroundingTool]
 );

 return agent;
 }
}

Criando um agente de comparação de preços com pesquisa real

Agora vamos criar um comparador de preços completo que pesquisa na web informações reais sobre produtos:

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public class ChristmasPriceAgent
{
 private readonly PersistentAgentsClient _client;
 private readonly string _modelDeployment;
 private readonly string _bingConnectionId;

 public ChristmasPriceAgent(string projectEndpoint, string modelDeployment, string bingConnectionId)
 {
 _client = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());
 _modelDeployment = modelDeployment;
 _bingConnectionId = bingConnectionId;
 }

 public async Task<string> FindGiftPricesAsync(string giftIdeas)
 {
 // Create agent with Bing Grounding
 var bingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(_bingConnectionId)]
 )
 );

 var agent = await _client.Administration.CreateAgentAsync(
 model: _modelDeployment,
 name: "PriceHunter",
 instructions: @"Search the web for current prices on the given gift ideas.
 For each gift, find prices from at least 2-3 different stores.
 Include direct links to the products.
 Note any Christmas sales or discounts available.",
 tools: [bingTool]
 );

 try
 {
 // Create a thread for the conversation
 var thread = await _client.Threads.CreateThreadAsync();

 // Add the gift ideas as a message
 await _client.Messages.CreateMessageAsync(
 thread.Id,
 MessageRole.User,
 $"Find current prices for these gift ideas: {giftIdeas}"
 );

 // Run the agent
 var run = await _client.Runs.CreateRunAsync(thread.Id, agent.Id);

 // Wait for completion
 do
 {
 await Task.Delay(500);
 run = await _client.Runs.GetRunAsync(thread.Id, run.Id);
 }
 while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

 // Get the response
 var messages = _client.Messages.GetMessages(thread.Id);
 var response = messages
 .Where(m => m.Role == MessageRole.Agent)
 .SelectMany(m => m.ContentItems)
 .OfType<MessageTextContent>()
 .FirstOrDefault();

 // Clean up
 await _client.Threads.DeleteThreadAsync(thread.Id);

 return response?.Text ?? "No results found.";
 }
 finally
 {
 // Clean up the agent
 await _client.Administration.DeleteAgentAsync(agent.Id);
 }
 }
}

Integrando o Bing Grounding ao fluxo de trabalho

Veja como usar o agente de preços do Bing em um fluxo de trabalho completo para encontrar presentes:

public static async Task RunWithBingGroundingAsync()
{
 var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")!;
 var modelDeployment = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
 var bingConnectionId = Environment.GetEnvironmentVariable("BING_CONNECTION_ID")!;
 // Connection ID format: /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection}

 Console.WriteLine("🔍 Searching the web for real prices with Bing Grounding...\n");

 var priceAgent = new ChristmasPriceAgent(projectEndpoint, modelDeployment, bingConnectionId);

 // First, generate gift ideas (could come from another agent)
 var giftIdeas = "1. Milwaukee cordless drill set, 2. Weber portable grill, 3. Carhartt beanie";

 // Search for real prices
 var priceResults = await priceAgent.FindGiftPricesAsync(giftIdeas);

 Console.WriteLine("📊 Price Comparison Results:");
 Console.WriteLine(priceResults);
 Console.WriteLine("\n🎁 Happy Shopping! 🎁");
}

Processando citações dos resultados do Bing

Um aspecto importante do Grounding with Bing Search é que as respostas incluem citações com links para os sites de origem. Veja como extraí-los e exibi-los:

public static void ProcessBingGroundingResponse(IEnumerable<PersistentThreadMessage> messages)
{
 foreach (var message in messages.Where(m => m.Role == MessageRole.Agent))
 {
 foreach (var content in message.ContentItems)
 {
 if (content is MessageTextContent textContent)
 {
 var response = textContent.Text;

 // Process URL citations
 if (textContent.Annotations != null)
 {
 foreach (var annotation in textContent.Annotations)
 {
 if (annotation is MessageTextUriCitationAnnotation uriAnnotation)
 {
 // Replace citation placeholder with markdown link
 response = response.Replace(
 uriAnnotation.Text,
 $" [{uriAnnotation.UriCitation.Title}]({uriAnnotation.UriCitation.Uri})"
 );
 }
 }
 }

 Console.WriteLine(response);
 }
 }
 }
}

Agora, quando o agente de comparação de preços é executado, ele usa o Grounding with Bing Search para encontrar listas de produtos reais, preços atuais e ofertas disponíveis na web ao vivo. O agente decide automaticamente quando pesquisar com base na consulta e retorna respostas fundamentadas com citações adequadas.

O Programa Completo

Veja como tudo acontece em Program.cs:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

Console.WriteLine("🎄 Christmas Gift Finder - Powered by AI Agents 🎄\n");

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
 .GetChatClient(deployment)
 .AsIChatClient();

// Create the agent team
var ideaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
var priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
var summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

// Build the workflow
var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftWorkflow",
 [ideaAgent, priceAgent, summaryAgent]);

Console.Write("Who are you shopping for? ");
var recipientName = Console.ReadLine() ?? "Someone special";

Console.Write("What are their interests? ");
var interests = Console.ReadLine() ?? "general";

Console.Write("What's your budget? $");
var budget = Console.ReadLine() ?? "50";

var prompt = $"Find Christmas gifts for {recipientName} who enjoys {interests}. Budget: ${budget}";

Console.WriteLine("\n🔍 Searching for the perfect gifts...\n");

await using var run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (var evt in run.WatchStreamAsync())
{
 switch (evt)
 {
 case AgentRunUpdateEvent update:
 Console.Write(update.Update.Text);
 break;
 case WorkflowOutputEvent output:
 Console.WriteLine("\n\n🎁 Happy Shopping! 🎁");
 break;
 }
}

Conclusão

O Agent Framework da Microsoft torna surpreendentemente fácil a construção de sistemas multiagentes, onde cada agente é especializado em uma tarefa específica. Ao coordenar estes agentes através de fluxos de trabalho, podemos resolver problemas complexos como as compras de Natal de uma forma estruturada e eficiente.

O que torna isso ainda mais poderoso é a capacidade de adicionar recursos do mundo real por meio de ferramentas. Ao integrar o Grounding com o Bing Search do Microsoft Foundry, nosso agente de comparação de preços pode realmente pesquisar na Web preços, ofertas e disponibilidade atuais, transformando um simples chatbot de IA em um assistente de compras verdadeiramente útil com citações adequadas.

O suporte da estrutura para padrões sequenciais, simultâneos e de transferência significa que você pode projetar sistemas de agentes que atendam exatamente às suas necessidades. Seja para encontrar presentes, planejar viagens ou qualquer outra tarefa de várias etapas, o Agent Framework fornece os blocos de construção para que isso aconteça.Nesta época de festas, deixe os agentes de IA cuidarem da pesquisa enquanto você se concentra em embrulhar presentes e aproveitar o tempo com a família!

Código Fonte

Os conceitos mostrados nesta postagem são baseados nos exemplos oficiais do Agent Framework. Você pode explorar mais exemplos no repositório GitHub do Microsoft Agent Framework.

Boas festas e boa codificação! 🎄

Construindo um agregador de feed RSS com tecnologia de IA

Fri, 12 Dec 2025 00:00:00 +0000

Como MVP da Microsoft e entusiasta de tecnologia, constantemente me afogo no oceano de conteúdo incrível publicado nos DevBlogs da Microsoft. Dos anúncios do .NET às atualizações do Visual Studio, das inovações do Azure aos aprofundamentos do Kernel Semântico – sempre há algo novo e interessante acontecendo no ecossistema da Microsoft.

O problema? Acompanhar tudo isso é quase impossível.

Eu queria ficar por dentro dos anúncios mais recentes e compartilhá-los com minha rede, mas verificar manualmente sete feeds RSS diferentes, ler artigos, criar postagens envolventes nas redes sociais e acompanhar o que já compartilhei estava se tornando um trabalho de tempo integral por si só. Todas as manhãs eu abria várias abas do navegador, examinava dezenas de artigos, tentava lembrar quais já havia compartilhado e então gastava um tempo precioso escrevendo posts sobre aqueles que chamavam minha atenção.

Então fiz o que qualquer desenvolvedor faria: automatizei.

Neste guia abrangente, mostrarei como construí um agregador de feeds RSS com tecnologia de IA que monitora vários feeds RSS do Microsoft DevBlogs para novos conteúdos, usa Azure OpenAI e Kernel Semântico para analisar artigos e gerar postagens envolventes, cria documentação detalhada de markdown para cada artigo analisado, envia notificações via Telegram para que eu possa revisar e compartilhar o conteúdo, rastreia tudo para evitar postagens duplicadas e é executado automaticamente por meio do GitHub Actions.

Vamos nos aprofundar em cada aspecto desta solução.

A história por trás deste projeto

Vivendo com sobrecarga de informações

Deixe-me pintar um retrato da minha manhã típica antes de construir esta ferramenta. Eu acordava, pegava meu café e abria meu laptop para conferir o que há de novo no ecossistema de desenvolvedores da Microsoft. Primeiro, eu navegaria até o site principal do DevBlogs para ver se havia algum anúncio importante. Então eu verificaria o blog do .NET especificamente porque essa é minha principal pilha de tecnologia. Depois disso, eu iria para o blog do Kernel Semântico, já que a IA está se tornando cada vez mais importante. O blog do Visual Studio foi o próximo da lista porque as atualizações do IDE podem impactar significativamente meu fluxo de trabalho diário. Em seguida, veio o blog DevOps para notícias relacionadas a CI/CD e GitHub, seguido pelo blog All Things Azure para atualizações de infraestrutura em nuvem e, finalmente, o blog Azure SQL para inovações de banco de dados.

São sete feeds diferentes para verificar. Cada um desses blogs publica vários artigos por semana, às vezes vários por dia durante períodos de anúncios importantes, como .NET Conf ou Build. São potencialmente dezenas de artigos para rastrear, ler e compartilhar. E o problema é o seguinte: como alguém que valoriza o compartilhamento de conhecimento com a comunidade, eu não queria apenas ler esses artigos. Eu queria compartilhar os mais valiosos com minha rede no LinkedIn, ajudando outros desenvolvedores a se manterem informados também.Mas criar uma boa postagem no LinkedIn leva tempo. Você precisa ler o artigo completamente, entender os pontos-chave, pensar por que ele é importante para o seu público, escrever um gancho envolvente e formatar tudo de maneira adequada. Multiplique isso por vários artigos por semana e você terá horas de trabalho.

O que eu realmente queria

Depois de lidar com isso durante meses, sentei-me e pensei em como seria a solução ideal. Em primeiro lugar, nunca mais queria perder anúncios importantes. O sistema deve capturar automaticamente novos artigos assim que forem publicados. Eu também queria economizar tempo na criação de conteúdo, permitindo que a IA ajudasse a criar postagens envolventes – não para substituir totalmente minha voz, mas para me dar um ponto de partida sólido que eu pudesse personalizar.

A consistência foi outro grande fator. Eu queria compartilhar conteúdo regularmente, sem ter que me lembrar de fazer isso manualmente todos os dias. O aspecto do rastreamento também foi crucial – eu precisava de uma maneira de saber o que já compartilhei para evitar postar duplicatas e irritar meus seguidores. Por fim, queria me manter organizado com um registro permanente de tudo o que processei, para poder olhar para trás e ver quais tópicos abordei.

A solução toma forma

A solução que imaginei seria executada de acordo com um cronograma usando GitHub Actions, totalmente sem usar as mãos. Ele buscaria todos os sete feeds automaticamente, sem que eu precisasse abrir uma única guia do navegador. O componente de IA realmente leria e compreenderia o conteúdo e depois o resumiria de uma forma que fosse útil para meu público. Em vez de eu ter que escrever postagens do zero, isso criaria conteúdo de mídia social pronto para compartilhar que eu poderia ajustar se necessário. Tudo seria enviado ao meu Telegram para revisão, para que eu pudesse rapidamente olhar para o meu telefone e decidir o que compartilhar. E, claro, manteria um registro permanente de tudo para referência futura.

Antes de começarmos a construir

O que você precisa em sua máquina

Para acompanhar este tutorial, você precisará de algumas coisas instaladas em sua máquina de desenvolvimento. O mais importante é o .NET SDK versão 9.0 ou posterior. Este é o nosso tempo de execução e fornece todas as ferramentas de construção de que precisamos. Se você não o instalou, acesse dot.net e baixe a versão mais recente. A instalação é simples no Windows, macOS ou Linux.

Você também desejará que o Git seja instalado para controle de versão. Enviaremos nosso código para o GitHub e usaremos GitHub Actions para automação, portanto, ter o Git configurado localmente é essencial. Qualquer versão recente funcionará bem.

Para o seu ambiente de desenvolvimento, recomendo Visual Studio ou VS Code. Pessoalmente, eu uso o VS Code na maior parte do meu trabalho atualmente porque é leve e tem excelente suporte a C# por meio da extensão C# Dev Kit. Mas se você estiver mais confortável com o Visual Studio completo, isso também funciona perfeitamente.

Serviços e contas que você precisaAlém das ferramentas locais, você precisará de contas com alguns serviços. O mais importante é o Azure OpenAI, que alimenta nossa análise de IA. Este é um serviço pré-pago, mas os custos são mínimos para este caso de uso – estamos falando de centavos por artigo analisado. Se não tiver uma conta do Azure, você poderá se inscrever para uma avaliação gratuita que inclui alguns créditos para começar.

Para notificações, usaremos um Telegram Bot. A grande vantagem do Telegram é que sua API de bot é totalmente gratuita. Você pode criar quantos bots quiser e enviar mensagens ilimitadas. Orientarei você no processo de configuração posteriormente neste guia.

Por fim, você precisará de uma conta GitHub para hospedar seu código e executar GitHub Actions. O nível gratuito é mais que suficiente para este projeto. O GitHub oferece 2.000 minutos de execução de Actions por mês em repositórios privados e minutos ilimitados em repositórios públicos.

As bibliotecas que tornam isso possível

Nosso projeto depende de três pacotes NuGet principais, cada um servindo a um propósito específico.

O primeiro é o HtmlAgilityPack, que é o padrão ouro para análise de HTML no .NET. Quando buscamos um artigo em um blog, recuperamos o HTML completo da página – incluindo menus de navegação, rodapés, anúncios e todo tipo de elementos com os quais não nos importamos. HtmlAgilityPack nos permite analisar esse HTML e extrair apenas o conteúdo do artigo que precisamos.

O segundo pacote é Microsoft.SemanticKernel, que é o SDK da Microsoft para integração de modelos de IA em aplicativos. Pense nisso como uma ponte entre seu código .NET e grandes modelos de linguagem como GPT-4. Ele lida com toda a complexidade de chamadas de API, gerenciamento de tokens e análise de respostas, permitindo que você se concentre no que deseja que a IA realmente faça.

O terceiro pacote é System.ServiceModel.Syndication, que fornece suporte integrado para análise de feeds RSS e Atom. RSS pode parecer uma tecnologia antiga, mas ainda é a melhor maneira de obter atualizações estruturadas de blogs e sites de notícias. Este pacote transforma feeds XML brutos em objetos C# fortemente tipados e fáceis de trabalhar.

Compreendendo a arquitetura

Como as peças se encaixam

Antes de mergulharmos no código, deixe-me explicar como todos os componentes funcionam juntos. Compreender o panorama geral tornará os detalhes da implementação muito mais claros.

No nível mais alto, temos nosso arquivo principal Program.cs que atua como orquestrador. Este é o ponto de entrada da nossa aplicação e coordena todos os outros componentes. Quando o aplicativo é executado, ele primeiro carrega a configuração das variáveis de ambiente – coisas como chaves de API e credenciais do Telegram. Em seguida, ele busca feeds RSS de todas as sete fontes do Microsoft DevBlogs. À medida que processa esses feeds, ele desduplica artigos para lidar com casos em que o mesmo artigo aparece em vários feeds. Ele verifica cada artigo em nosso arquivo de rastreamento para ver se já o processamos. Para novos artigos, ele os entrega ao analisador de IA para processamento.A classe ArticleAnalyzer é onde a mágica da IA acontece. Este componente recebe um artigo e faz diversas coisas com ele. Primeiro, ele busca o conteúdo HTML completo da URL do artigo. Em seguida, ele extrai texto limpo desse HTML, removendo todos os elementos de navegação, scripts e estilos desnecessários. Assim que tiver texto limpo, ele o envia para o Azure OpenAI por meio do Kernel Semântico com um prompt cuidadosamente elaborado. A IA analisa o artigo e retorna uma resposta estruturada que inclui um resumo, tópicos principais, explicação de relevância e, o mais importante, uma postagem no LinkedIn pronta para uso. O analisador analisa esta resposta e retorna um objeto ArticleAnalysis contendo todas essas informações.

A classe MarkdownGenerator pega esse objeto ArticleAnalysis e cria um registro permanente dele. Ele gera um arquivo markdown bem formatado que inclui todos os metadados do artigo, a análise da IA e a postagem gerada. Esses arquivos são armazenados em um diretório de postagens geradas, fornecendo um arquivo pesquisável de tudo o que você processou.

Por fim, a integração do Telegram envia o conteúdo do post gerado para o seu telefone. Este é o ponto onde você, como ser humano, analisa o trabalho da IA e decide se deseja compartilhá-lo. O bot envia uma mensagem com o conteúdo da postagem e você pode copiá-la diretamente para o LinkedIn ou modificá-la primeiro.

O Fluxo de Dados

Deixe-me explicar o que acontece quando um novo artigo é publicado no blog .NET. O fluxo de trabalho começa quando o GitHub Actions aciona nosso aplicativo de acordo com sua programação – digamos, a cada seis horas. O aplicativo é ativado e começa a buscar todos os sete feeds RSS. Cada feed retorna um documento XML contendo os artigos mais recentes daquele blog.

À medida que analisamos cada feed, extraímos artigos individuais e os armazenamos em uma lista. Mas aqui está uma parte complicada: o feed principal do DevBlogs geralmente inclui artigos que também aparecem nos feeds de categorias individuais. Portanto, um artigo sobre “.NET 10” pode aparecer tanto no feed principal quanto no feed específico do .NET. Lidamos com isso rastreando URLs em um HashSet, que evita automaticamente duplicatas.

Assim que tivermos nossa lista desduplicada de artigos, nós a filtraremos apenas para os mais recentes – normalmente artigos publicados no último dia ou depois. Não queremos processar artigos antigos que já tratamos em execuções anteriores. Em seguida, verificamos cada artigo recente em nosso arquivo de rastreamento. Se já processamos e postamos sobre um artigo, nós o ignoramos.

Para cada novo artigo, iniciamos o pipeline de análise de IA. O analisador busca o HTML completo do artigo, limpa-o e envia-o para o GPT-4 com nosso prompt. A IA lê o artigo e gera uma análise abrangente junto com uma postagem no LinkedIn. Salvamos essa análise em um arquivo markdown para nossos registros.Com a análise concluída, formatamos uma mensagem e enviamos via Telegram. A mensagem inclui o conteúdo da postagem gerado com o URL e as hashtags anexadas. No meu celular recebo uma notificação, reviso a postagem e, se gostar, posso copiá-la e compartilhá-la no LinkedIn com apenas alguns toques.

Por fim, atualizamos nosso arquivo de rastreamento para marcar este artigo como processado, para que não o tratemos novamente em execuções futuras. Se algum arquivo foi criado ou modificado, o GitHub Actions envia essas alterações de volta ao repositório, mantendo tudo sincronizado.

Configurando o projeto do zero

Criando a estrutura da solução

Vamos começar a construir. Abra seu terminal e navegue até onde deseja criar o projeto. Gosto de manter meus projetos organizados em uma pasta Desenvolvimento, mas você pode colocá-los onde fizer sentido para você.

Primeiro, criaremos um novo arquivo de solução. No .NET, uma solução é um contêiner que pode conter vários projetos. Embora tenhamos apenas um projeto no momento, começar com uma solução torna mais fácil adicionar mais projetos posteriormente, se necessário. Execute o comando dotnet new sln -n vs-feed-linkedin para criar uma solução chamada vs-feed-linkedin.

A seguir, precisamos criar nosso projeto de aplicativo de console. Colocaremos isso em um subdiretório src para manter as coisas organizadas. Execute dotnet new console -n VsFeedLinkedin -o src para criar um projeto de console chamado VsFeedLinkedin na pasta src. Em seguida, adicione este projeto à nossa solução com dotnet sln add src/VsFeedLinkedin.csproj.

Agora navegue até o diretório src com cd src. É aqui que adicionaremos nossos pacotes NuGet e faremos a maior parte do nosso desenvolvimento.

Adicionando os pacotes necessários

Com nosso projeto criado, precisamos adicionar os três pacotes NuGet que mencionei anteriormente. Execute cada um destes comandos em sequência:

dotnet add package System.ServiceModel.Syndication --version 9.0.9
dotnet add package Microsoft.SemanticKernel --version 1.30.0
dotnet add package HtmlAgilityPack --version 1.11.72

Depois de executar esses comandos, seu arquivo de projeto deverá ficar parecido com isto:

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

 <PropertyGroup>
 <OutputType>Exe</OutputType>
 <TargetFramework>net9.0</TargetFramework>
 <ImplicitUsings>enable</ImplicitUsings>
 <Nullable>enable</Nullable>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="HtmlAgilityPack" Version="1.11.72" />
 <PackageReference Include="Microsoft.SemanticKernel" Version="1.30.0" />
 <PackageReference Include="System.ServiceModel.Syndication" Version="9.0.9" />
 </ItemGroup>

</Project>

O arquivo do projeto informa ao .NET que estamos construindo um executável (OutputType é Exe), direcionado ao .NET 9.0 e usando recursos modernos do C#, como usos implícitos e tipos de referência anuláveis. A seção ItemGroup lista nossas três dependências de pacotes com suas versões exatas.

Aprofunde-se nos feeds RSS

O que exatamente é RSS?

Antes de começarmos a escrever código para buscar feeds, vamos ter certeza de que entendemos com o que estamos trabalhando. RSS significa Really Simple Syndication e é um formato XML padronizado para distribuição de atualizações de conteúdo. A ideia é simples: em vez de exigir que os usuários visitem seu site para ver se há conteúdo novo, você publica um arquivo legível por máquina que lista seu conteúdo recente. Os aplicativos podem então pesquisar esse arquivo periodicamente para descobrir novos artigos.

O RSS existe desde o final dos anos 1990 e início dos anos 2000. Você pode pensar que é uma tecnologia ultrapassada, mas na verdade ainda é amplamente utilizada – especialmente por blogs, sites de notícias e podcasts. A beleza do RSS é a sua simplicidade. É apenas XML com uma estrutura definida e qualquer aplicativo pode analisá-lo.

A estrutura de um feed de DevBlogsAo buscar um feed RSS do Microsoft DevBlogs, você recebe de volta um documento XML que segue uma estrutura específica. No nível superior, há um elemento rss que contém um único elemento de canal. O canal representa o próprio blog e inclui metadados como título, URL e descrição do blog.

Dentro do canal, você encontrará vários elementos de item, cada um representando uma postagem individual do blog. Cada item inclui um título (o título do artigo), um link (a URL onde você pode ler o artigo completo), um pubDate (quando o artigo foi publicado), um elemento dc:creator (o nome do autor), um ou mais elementos de categoria (tags para o artigo) e uma descrição (geralmente um resumo ou trecho do artigo).

Aqui está um exemplo simplificado de como isso se parece:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
 <channel>
 <title>.NET Blog</title>
 <link>https://devblogs.microsoft.com/dotnet</link>
 <description>The latest news about .NET</description>
 <item>
 <title>Announcing .NET 10</title>
 <link>https://devblogs.microsoft.com/dotnet/announcing-dotnet-10</link>
 <pubDate>Mon, 10 Dec 2025 12:00:00 GMT</pubDate>
 <dc:creator>Microsoft</dc:creator>
 <category>Announcements</category>
 <category>.NET</category>
 <description>Article summary...</description>
 </item>
 </channel>
</rss>

A grande vantagem do pacote System.ServiceModel.Syndication do .NET é que ele analisa tudo isso para nós. Não precisamos navegar manualmente nos nós XML ou nos preocupar com diferentes versões de RSS. Apenas carregamos o feed e recuperamos objetos fortemente digitados.

Os sete feeds que monitoramos

Na minha implementação, monitoro sete feeds diferentes do Microsoft DevBlogs. O feed principal do DevBlogs em devblogs.microsoft.com/feed nos dá uma visão ampla de tudo o que a Microsoft está publicando em todos os seus blogs de desenvolvedores. O feed específico do .NET em devblogs.microsoft.com/dotnet/feed concentra-se especificamente em versões, recursos e práticas recomendadas do .NET. O feed do Kernel Semântico em devblogs.microsoft.com/semantic-kernel/feed abrange a orquestração e integração de IA – cada vez mais importante à medida que a IA se torna central para o desenvolvimento moderno.

O feed do Visual Studio em devblogs.microsoft.com/visualstudio/feed me mantém atualizado sobre as melhorias do IDE e os recursos de produtividade. O feed DevOps em devblogs.microsoft.com/devops/feed abrange tópicos de Azure DevOps, GitHub e CI/CD. O feed All Things Azure em devblogs.microsoft.com/all-things-azure/feed concentra-se em serviços de nuvem e padrões de arquitetura. Por fim, o feed SQL do Azure em devblogs.microsoft.com/azure-sql/feed abrange inovações e recursos de banco de dados.

Você pode estar se perguntando por que verifico o feed principal e os feeds de categorias individuais. O feed principal me dá amplitude – verei artigos de qualquer blog de desenvolvedor da Microsoft, incluindo aqueles que talvez eu não conheça. Os feeds de categoria me dão profundidade – eles garantem que eu não perca nada importante nas minhas principais áreas de interesse, mesmo que esses artigos sejam empurrados para fora do feed principal por causa de conteúdos mais recentes.

Construindo a lógica de busca de RSS

A função principal de busca

Agora vamos escrever algum código. A base do nosso aplicativo é a capacidade de buscar e analisar feeds RSS. Aqui está a função que lida com isso:

static async Task<SyndicationFeed?> FetchRssFeedAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 var response = await httpClient.GetStringAsync(url);

 using var stringReader = new StringReader(response);

 var settings = new XmlReaderSettings
 {
 DtdProcessing = DtdProcessing.Parse,
 MaxCharactersFromEntities = 1024
 };

 using var xmlReader = XmlReader.Create(stringReader, settings);

 return SyndicationFeed.Load(xmlReader);
}

Deixe-me explicar o que esse código faz. Começamos criando um HttpClient, que é a classe integrada do .NET para fazer solicitações HTTP. Definimos um cabeçalho User-Agent porque alguns servidores bloqueiam solicitações que não se identificam. É uma boa prática definir isso mesmo quando os servidores não exigem isso.Em seguida, fazemos uma solicitação GET para a URL do feed e recebemos a resposta como uma string. Esta string contém o XML bruto do feed RSS.

Para analisar esse XML, criamos um StringReader para agrupar nossa string de resposta e, em seguida, configuramos alguns XmlReaderSettings. A configuração DtdProcessing é importante – os feeds RSS às vezes incluem declarações DTD (Document Type Definition) que precisam ser processadas. A configuração MaxCharactersFromEntities é uma medida de segurança que evita ataques de bomba XML, limitando a quantidade de expansão da entidade que pode ocorrer.

Por fim, criamos um XmlReader com essas configurações e usamos SyndicationFeed.Load para analisar o XML em um objeto SyndicationFeed fortemente tipado. Isso nos dá acesso aos metadados do feed e a todos os seus itens por meio de boas propriedades C# em vez de navegação XML bruta.

Buscando vários feeds com tratamento de erros

No mundo real, as solicitações de rede falham. Os servidores ficam inativos, as conexões atingem o tempo limite e o XML pode ficar malformado. Precisamos lidar com esses casos com elegância. Veja como buscamos todos os nossos feeds e ao mesmo tempo somos resilientes a falhas:

var allArticles = new List<(SyndicationItem item, string feedUrl)>();
var seenUrls = new HashSet<string>();

foreach (var feedUrl in feedUrls)
{
 try
 {
 Console.WriteLine($" 📡 Fetching {feedUrl}...");
 var feed = await FetchRssFeedAsync(feedUrl);

 if (feed?.Items != null && feed.Items.Any())
 {
 foreach (var item in feed.Items)
 {
 var itemUrl = item.Links.FirstOrDefault()?.Uri.ToString() ?? "";
 if (!string.IsNullOrEmpty(itemUrl) && seenUrls.Add(itemUrl))
 {
 allArticles.Add((item, feedUrl));
 }
 }
 }
 }
 catch (Exception ex)
 {
 Console.WriteLine($" ⚠️ Failed to fetch {feedUrl}: {ex.Message}");
 }
}

Mantemos duas coleções aqui. A lista allArticles conterá todos os artigos que encontrarmos, juntamente com o feed de onde eles vieram. O HashSet vistoUrls rastreia quais URLs de artigos já vimos, ajudando-nos a evitar duplicatas.

Percorremos cada URL de feed e envolvemos a operação de busca em um bloco try-catch. Se a busca de um feed específico falhar – talvez o servidor esteja temporariamente inativo – registramos um aviso e continuamos com o próximo feed. Dessa forma, um problema com um feed não nos impede de processar os outros.

Para cada feed obtido com sucesso, iteramos seus itens. Extraímos o URL do artigo da coleção Links do item. O método HashSet.Add retorna false se a URL já estiver no conjunto, o que é perfeito para nossa lógica de desduplicação. Só adicionamos o artigo à nossa lista se for novo.

Armazenamos o URL do feed junto com cada artigo porque essas informações podem ser úteis posteriormente – por exemplo, podemos querer saber de qual feed específico veio um artigo para fins de depuração ou registro.

Tratamento de duplicatas e estado de rastreamento

O desafio da desduplicação

Como mencionei anteriormente, o Microsoft DevBlogs possui uma estrutura de feed hierárquica que cria um desafio interessante. Quando um membro da equipe .NET publica um artigo sobre, digamos, melhorias de desempenho no .NET 10, esse artigo provavelmente aparecerá no feed principal do DevBlogs e no feed específico do .NET. Às vezes, pode até aparecer no feed do Visual Studio se estiver relacionado aos recursos do IDE.

Se processássemos ingenuamente cada artigo de cada feed, acabaríamos analisando e postando o mesmo artigo diversas vezes. Isso desperdiçaria chamadas de API para o Azure OpenAI, enviaria spam para nosso Telegram com notificações duplicadas e potencialmente irritaria nossos seguidores se postássemos duplicatas.A solução é a desduplicação baseada em URL. Cada artigo possui um URL exclusivo, então podemos usá-lo como identificador. A estrutura de dados HashSet é perfeita para isso porque fornece tempo de pesquisa O(1) e evita automaticamente duplicatas. Quando tentamos adicionar uma URL que já está no conjunto, o método Add simplesmente retorna false, informando que devemos pular esse artigo.

Estado persistente com Markdown

A desduplicação lida com duplicatas em uma única execução, mas e entre execuções? Quando nosso aplicativo é executado a cada seis horas, precisamos lembrar quais artigos já processamos para não manipulá-los novamente.

Optei por armazenar esse estado em um arquivo markdown chamado postado-artigos.md. Por que redução? Algumas razões. Primeiro, é legível por humanos. Posso abrir o arquivo e ver imediatamente quais artigos compartilhei. Em segundo lugar, é controlado por versão. Como esse arquivo está em nosso repositório Git, tenho um histórico completo de quando os artigos foram processados. Terceiro, serve como documentação. Qualquer pessoa que olhar o repositório pode ver o que o aplicativo fez.

O formato deste arquivo é simples. Ele tem um cabeçalho, um carimbo de data e hora mostrando quando o aplicativo foi executado pela última vez e, em seguida, uma lista de artigos em formato de link de desconto:

# Posted Articles

*Last run: 2025-12-10 15:30:00*

List of articles posted to LinkedIn:

- [Announcing .NET 10](https://devblogs.microsoft.com/dotnet/announcing-dotnet-10?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-10 15:30:00 (Published: 2025-12-10)
- [Visual Studio 2026 Preview](https://devblogs.microsoft.com/visualstudio/vs-2026-preview?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-09 10:15:00 (Published: 2025-12-09)

Carregando e analisando o arquivo de rastreamento

Para verificar se já processamos um artigo, precisamos carregar este arquivo e extrair as URLs. Aqui está a função que faz isso:

static HashSet<string> LoadPostedArticles(string filePath)
{
 var postedUrls = new HashSet<string>();

 if (!File.Exists(filePath))
 {
 return postedUrls;
 }

 var lines = File.ReadAllLines(filePath);
 foreach (var line in lines)
 {
 var match = System.Text.RegularExpressions.Regex.Match(line, @"\(([^)]+)\)");
 if (match.Success)
 {
 var url = match.Groups[1].Value;

 if (url.Contains("?wt.mc_id="))
 {
 url = url.Substring(0, url.IndexOf("?wt.mc_id="));
 }
 else if (url.Contains("?"))
 {
 url = url.Substring(0, url.IndexOf("?"));
 }

 url = url.TrimEnd('/');
 postedUrls.Add(url);
 }
 }

 return postedUrls;
}

Esta função retorna um HashSet contendo todas as URLs que já processamos. Começamos verificando se o arquivo existe – na primeira execução, não existirá, então retornamos um conjunto vazio.

Para cada linha do arquivo, usamos uma regex para extrair a URL do formato do link markdown. A regex $([^)]+)$ corresponde a qualquer coisa entre parênteses, que é onde os links markdown armazenam seus URLs.

Depois vem uma etapa importante: normalização de URL. Os URLs do mesmo artigo podem variar em formato. O feed RSS pode nos fornecer https://devblogs.microsoft.com/dotnet/article, mas nossa versão salva tem um parâmetro de rastreamento anexado: https://devblogs.microsoft.com/dotnet/article?wt.mc_id=DT-MVP-5004972. Alguns URLs possuem barras finais, outros não.

Para lidar com isso, eliminamos todos os parâmetros de consulta (tudo após ?) e removemos as barras finais. Essa normalização garante que reconhecemos os artigos como duplicados, mesmo que seus URLs sejam diferentes nessas formas superficiais.

Salvando novos artigos

Quando processamos um artigo com sucesso, precisamos adicioná-lo ao nosso arquivo de rastreamento:

static void SavePostedArticle(string filePath, string url, string title, DateTimeOffset publishDate)
{
 var markdownEntry = $"- [{title}]({url}) - Posted on {DateTime.Now:yyyy-MM-dd HH:mm:ss} (Published: {publishDate:yyyy-MM-dd})\n";

 if (!File.Exists(filePath))
 {
 File.WriteAllText(filePath, "# Posted Articles\n\n*Last run: {DateTime.Now:yyyy-MM-dd HH:mm:ss}*\n\nList of articles posted:\n\n");
 }

 File.AppendAllText(filePath, markdownEntry);
}

Esta função cria uma entrada formatada em markdown com o título do artigo como um link, seguido por carimbos de data e hora mostrando quando o postamos e quando foi publicado originalmente. Se o arquivo ainda não existir, primeiro o criamos com um cabeçalho.

O mecanismo de análise de IA

Compreendendo o kernel semânticoAgora chegamos à parte mais interessante da nossa aplicação – a análise de IA. O Kernel Semântico é o SDK de código aberto da Microsoft para integração de grandes modelos de linguagem em aplicativos. É mais do que apenas um wrapper para chamadas de API. Ele fornece uma estrutura para a construção de aplicativos sofisticados de IA com recursos como plug-ins, planejadores e memória.

Para nosso caso de uso, estamos usando os recursos de conclusão de bate-papo do Semantic Kernel. Enviaremos um prompt ao Azure OpenAI e o modelo analisará nosso artigo e gerará uma resposta. O Kernel Semântico lida com toda a complexidade de autenticação de API, formatação de solicitação e análise de resposta.

Configurando o analisador de artigos

Vejamos como configuramos nossa classe de analisador:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using HtmlAgilityPack;

namespace VsFeedLinkedin.Services;

public class ArticleAnalyzer
{
 private readonly Kernel _kernel;
 private readonly IChatCompletionService _chatService;

 public ArticleAnalyzer(string endpoint, string apiKey, string deploymentName)
 {
 var builder = Kernel.CreateBuilder();

 builder.AddAzureOpenAIChatCompletion(
 deploymentName: deploymentName,
 endpoint: endpoint,
 apiKey: apiKey
 );

 _kernel = builder.Build();
 _chatService = _kernel.GetRequiredService<IChatCompletionService>();
 }

O Kernel Semântico usa um padrão de construtor para configuração. Criamos um KernelBuilder, adicionamos nosso serviço de conclusão de chat Azure OpenAI com as credenciais necessárias e, em seguida, construímos o kernel. Do kernel compilado, recuperamos a interface IChatCompletionService, que usaremos para enviar prompts e receber respostas.

O construtor usa três parâmetros: o ponto de extremidade do Azure OpenAI (algo como https://your-resource.openai.azure.com/), sua chave de API e o nome da implantação (como gpt-4o). Eles são transmitidos a partir de variáveis de ambiente, mantendo nossas credenciais seguras.

Elaborando o prompt perfeito

O aviso que enviamos para a IA é crucial. Um prompt bem elaborado produz resultados consistentes e de alta qualidade. Uma solicitação vaga ou mal estruturada produz resultados inconsistentes e medíocres. Passei um tempo considerável iterando esse prompt para obter resultados que me agradam:

var prompt = $"""
 You are a professional tech content analyst and LinkedIn content creator.
 Analyze the following Microsoft DevBlogs article and create an engaging LinkedIn post.

 Article Title: {title}
 Author: {author}
 URL: {url}
 Tags: {string.Join(", ", tags)}

 Article Content:
 {cleanContent}

 Please provide:
 1. A brief summary (2-3 sentences) of the key points
 2. The main technologies or topics covered
 3. Why this is relevant for developers/tech professionals
 4. An engaging LinkedIn post (max 1300 characters) that:
 - Starts with a hook or attention-grabbing statement
 - Highlights the key value for readers
 - Includes a call to action
 - Uses appropriate emojis (but not too many)
 - Maintains a professional yet approachable tone
 - DO NOT include hashtags in the post (they will be added separately)
 - DO NOT include the URL in the post (it will be added separately)

 Format your response as follows:
 ## Summary
 [Your summary here]

 ## Key Topics
 [List of main topics/technologies]

 ## Relevance
 [Why this matters]

 ## LinkedIn Post
 [Your engaging LinkedIn post here]
 """;

Deixe-me explicar as decisões de design aqui. Começamos dando à IA um papel claro: “Você é um analista de conteúdo técnico profissional e criador de conteúdo do LinkedIn”. Isso prepara o modelo para responder com estilo e voz apropriados.

Fornecemos todo o contexto que a IA precisa: título do artigo, autor, URL, tags do feed RSS e o conteúdo completo do artigo. Quanto mais contexto dermos, melhor será a análise.

Então especificamos exatamente o que queremos de volta. Peço quatro coisas: um resumo, tópicos principais, explicação de relevância e uma postagem no LinkedIn. Especificamente para a postagem no LinkedIn, dou instruções detalhadas sobre o que constitui uma boa postagem - ela deve ter um gancho, destacar o valor, incluir uma frase de chamariz, usar emojis de maneira adequada e manter um tom profissional.

As instruções negativas são igualmente importantes. Eu digo explicitamente à IA para NÃO incluir hashtags ou URL na postagem. Por que? Porque eu os adiciono separadamente e, se a IA os incluísse, teria duplicatas. Este tipo de instrução explícita evita erros comuns.

Finalmente, especifico o formato de saída exato. Ao solicitar seções marcadas com ## cabeçalhos, facilito a análise programática da resposta. A IA é muito boa em seguir instruções de formatação e essa consistência torna nosso código de análise mais simples e confiável.

Executando a Análise

Veja como juntamos tudo:

public async Task<ArticleAnalysis> AnalyzeArticleAsync(
 string title,
 string url,
 string htmlContent,
 string author,
 List<string> tags)
{
 var cleanContent = ExtractTextFromHtml(htmlContent);

 if (cleanContent.Length > 8000)
 {
 cleanContent = cleanContent.Substring(0, 8000) + "...";
 }

 var chatHistory = new ChatHistory();
 chatHistory.AddUserMessage(prompt);

 var response = await _chatService.GetChatMessageContentAsync(chatHistory);
 var responseText = response.Content ?? "";

 return ParseAnalysisResponse(responseText, title, url, author, tags);
}
```Primeiro extraímos o texto limpo do conteúdo HTML (explicarei isso na próxima seção). Então truncamos o conteúdo se for muito longo. Modelos de linguagem grandes têm limites de tokens e artigos muito longos podem excedê-los. Ao limitar o limite de 8.000 caracteres, garantimos que permaneceremos dentro dos limites e, ao mesmo tempo, forneceremos um contexto substancial.

Criamos um objeto ChatHistory e adicionamos nosso prompt como uma mensagem do usuário. Esta é a abstração do Semantic Kernel para interações baseadas em chat. Enviamos isso para o serviço de conclusão de chat e recebemos uma resposta. Finalmente, analisamos a resposta para extrair as seções individuais.

### Analisando a resposta da IA

A IA retorna sua resposta como texto formatado com nossa estrutura solicitada. Precisamos analisar isso em campos individuais:

```csharp
private static ArticleAnalysis ParseAnalysisResponse(
 string response,
 string title,
 string url,
 string author,
 List<string> tags)
{
 var analysis = new ArticleAnalysis
 {
 Title = title,
 Url = url,
 Author = author,
 Tags = tags,
 RawAnalysis = response
 };

 var sections = response.Split("##", StringSplitOptions.RemoveEmptyEntries);

 foreach (var section in sections)
 {
 var lines = section.Trim().Split('\n', 2);
 if (lines.Length < 2) continue;

 var sectionTitle = lines[0].Trim().ToLower();
 var sectionContent = lines[1].Trim();

 switch (sectionTitle)
 {
 case "summary":
 analysis.Summary = sectionContent;
 break;
 case "key topics":
 analysis.KeyTopics = sectionContent;
 break;
 case "relevance":
 analysis.Relevance = sectionContent;
 break;
 case "linkedin post":
 analysis.LinkedInPost = sectionContent;
 break;
 }
 }

 return analysis;
}

Dividimos a resposta pelos marcadores ##, o que nos dá cada seção. Para cada seção, dividimos por nova linha para separar o cabeçalho do conteúdo. Em seguida, usamos uma instrução switch para atribuir o conteúdo de cada seção à propriedade apropriada.

Também armazenamos a resposta bruta e não analisada. Isso é útil para depuração – se algo der errado com a análise, podemos ver o que a IA realmente retornou.

Extraindo conteúdo de HTML

Por que precisamos limpar o HTML

Quando buscamos um artigo em um blog, obtemos o HTML completo da página. Isso inclui muito mais do que apenas o conteúdo do artigo – há menus de navegação, cabeçalhos, rodapés, barras laterais, widgets de artigos relacionados, seções de comentários, scripts para análise e rastreamento, folhas de estilo e todos os tipos de outros elementos.

Se enviássemos tudo isso para a nossa IA, várias coisas ruins aconteceriam. A IA teria que processar muitos textos irrelevantes, desperdiçando tokens e potencialmente confundindo a análise. O texto de navegação e rodapé pode ser incluído no resumo. Scripts e CSS seriam tratados como conteúdo, poluindo ainda mais a análise.

Precisamos extrair apenas o conteúdo do artigo – a parte que um leitor humano realmente leria.

Usando HtmlAgilityPack

HtmlAgilityPack é uma biblioteca robusta de análise de HTML para .NET. Ao contrário do XML, o HTML geralmente é malformado – as tags podem não ser fechadas corretamente, os atributos podem não ser citados corretamente. HtmlAgilityPack lida com tudo isso com elegância, fornecendo-nos uma estrutura semelhante a DOM que podemos consultar e manipular.

Aqui está nossa função de extração:

private static string ExtractTextFromHtml(string html)
{
 if (string.IsNullOrWhiteSpace(html))
 return string.Empty;

 var doc = new HtmlDocument();
 doc.LoadHtml(html);

 var nodesToRemove = doc.DocumentNode.SelectNodes("//script|//style|//nav|//footer|//header");
 if (nodesToRemove != null)
 {
 foreach (var node in nodesToRemove)
 {
 node.Remove();
 }
 }

 var text = doc.DocumentNode.InnerText;

 text = System.Text.RegularExpressions.Regex.Replace(text, @"\s+", " ");
 return text.Trim();
}

Carregamos o HTML em um HtmlDocument, que o analisa em uma estrutura de árvore. Em seguida, usamos XPath para selecionar todos os nós que queremos remover. A expressão XPath //script|//style|//nav|//footer|//header seleciona todos os elementos de script (código JavaScript que não precisamos), elementos de estilo (CSS que não precisamos), elementos de navegação (menus de navegação), elementos de rodapé e elementos de cabeçalho.

Após remover esses nós, obtemos a propriedade InnerText, que extrai todo o conteúdo do texto enquanto remove as tags HTML. Isso nos dá o texto simples do artigo.Finalmente, limpamos os espaços em branco. O HTML geralmente tem muitos espaços em branco extras para fins de formatação – vários espaços, tabulações, novas linhas. Usamos um regex para substituir qualquer sequência de caracteres de espaço em branco por um único espaço e, em seguida, cortamos o resultado.

Buscando o artigo completo

O feed RSS fornece apenas resumos, não o conteúdo completo do artigo. Para obter o texto completo, precisamos buscar a página web do artigo:

public static async Task<string> FetchArticleContentAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 try
 {
 return await httpClient.GetStringAsync(url);
 }
 catch (Exception ex)
 {
 Console.WriteLine($"⚠️ Failed to fetch article content: {ex.Message}");
 return string.Empty;
 }
}

Isso é simples – fazemos uma solicitação HTTP GET para o URL do artigo e retornamos a resposta HTML. Nós o envolvemos em um try-catch porque as solicitações de rede podem falhar e preferimos retornar uma string vazia do que travar todo o aplicativo.

Criando Documentação Permanente

Por que gerar arquivos Markdown

Cada vez que analisamos um artigo, geramos um arquivo markdown detalhado que documenta essa análise. Isso serve a vários propósitos.

Primeiro, ele cria um arquivo pesquisável. Com o tempo, você construirá uma coleção de artigos analisados. Você pode pesquisar nesses arquivos para encontrar conteúdo anterior sobre tópicos específicos.

Em segundo lugar, proporciona transparência. Você pode ver exatamente o que a IA gerou para cada artigo, incluindo a análise completa e a postagem no LinkedIn.

Terceiro, é útil para depuração. Se algo der errado com uma postagem, você pode consultar o arquivo markdown para entender o que aconteceu.

A classe geradora de Markdown

public class MarkdownGenerator
{
 private readonly string _outputDirectory;

 public MarkdownGenerator(string outputDirectory)
 {
 _outputDirectory = outputDirectory;

 if (!Directory.Exists(_outputDirectory))
 {
 Directory.CreateDirectory(_outputDirectory);
 }
 }

 public string GenerateMarkdownFile(ArticleAnalysis analysis)
 {
 var sb = new StringBuilder();

 var safeTitle = GenerateSafeFileName(analysis.Title);
 var fileName = $"{analysis.AnalyzedAt:yyyy-MM-dd}_{safeTitle}.md";
 var filePath = Path.Combine(_outputDirectory, fileName);

 sb.AppendLine($"# {analysis.Title}");
 sb.AppendLine();
 sb.AppendLine("## Article Information");
 sb.AppendLine();
 sb.AppendLine($"- **Author:** {analysis.Author}");
 sb.AppendLine($"- **URL:** [{analysis.Url}]({analysis.Url})");
 sb.AppendLine($"- **Published:** {analysis.PublishDate:yyyy-MM-dd}");
 sb.AppendLine($"- **Analyzed:** {analysis.AnalyzedAt:yyyy-MM-dd HH:mm:ss}");
 sb.AppendLine($"- **Tags:** {string.Join(", ", analysis.Tags)}");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## AI Analysis");
 sb.AppendLine();
 sb.AppendLine("### Summary");
 sb.AppendLine();
 sb.AppendLine(analysis.Summary);
 sb.AppendLine();
 sb.AppendLine("### Key Topics");
 sb.AppendLine();
 sb.AppendLine(analysis.KeyTopics);
 sb.AppendLine();
 sb.AppendLine("### Relevance for Developers");
 sb.AppendLine();
 sb.AppendLine(analysis.Relevance);
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## Generated LinkedIn Post");
 sb.AppendLine();
 sb.AppendLine("```");
 sb.AppendLine(análise.LinkedInPost);
 AppendLine("```");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("*This analysis was generated using AI (Semantic Kernel with Azure OpenAI)*");

 File.WriteAllText(filePath, sb.ToString());
 return filePath;
 }

O construtor pega um caminho de diretório de saída e o cria se ele não existir. O método GenerateMarkdownFile pega um objeto ArticleAnalysis e produz um documento de redução bem formatado.

O nome do arquivo inclui a data e uma versão higienizada do título. Isso torna os arquivos fáceis de classificar cronologicamente e identificar rapidamente.

Lidando com nomes de arquivos inseguros

Os títulos dos artigos podem conter caracteres que não são permitidos em nomes de arquivos – coisas como dois pontos, barras, pontos de interrogação e aspas. Precisamos higienizar estes:

private static string GenerateSafeFileName(string title)
{
 var invalidChars = Path.GetInvalidFileNameChars();
 var safeTitle = new string(title
 .Where(c => !invalidChars.Contains(c))
 .ToArray());

 safeTitle = safeTitle.Replace(" ", "-").Replace("--", "-");

 if (safeTitle.Length > 50)
 {
 safeTitle = safeTitle.Substring(0, 50);
 }

 return safeTitle.TrimEnd('-').ToLowerInvariant();
}

Usamos Path.GetInvalidFileNameChars() para obter uma lista de caracteres que não podem aparecer em nomes de arquivos no sistema operacional atual. Nós os filtramos, substituímos os espaços por hífens para facilitar a leitura, limitamos o comprimento a 50 caracteres e convertemos para letras minúsculas para maior consistência.

Configurando notificações de telegrama

Por que escolhi o Telegram

Para o componente de notificação, considerei várias opções – email, SMS, Slack, Discord e Telegram. No final das contas, escolhi o Telegram por vários motivos.

A API é totalmente gratuita, sem limites de taxa para uso razoável. Muitos serviços de notificação têm limites de quantas mensagens você pode enviar gratuitamente, mas o Telegram não restringe mensagens de bot a usuários individuais.

A API do bot é incrivelmente simples. São apenas solicitações HTTP com cargas JSON. Não há fluxos de autenticação complexos nem webhooks necessários para funcionalidades básicas.O Telegram funciona em qualquer lugar – no meu telefone, no meu desktop, no meu navegador. Posso receber notificações onde quer que esteja e responder imediatamente.

As mensagens suportam formatação avançada. Posso usar texto em negrito, itálico e até blocos de código para tornar minhas notificações mais legíveis.

Criando seu bot de telegrama

Configurar um bot do Telegram é surpreendentemente fácil. Abra o Telegram e pesquise @BotFather – este é o bot oficial do Telegram para criar e gerenciar bots. Inicie uma conversa com BotFather e envie o comando /newbot. O BotFather solicitará um nome para o seu bot (este é o nome de exibição) e um nome de usuário (deve ser exclusivo e terminar em “bot”). Depois de fornecer isso, o BotFather criará seu bot e fornecerá um token de API. Este token é como uma senha – mantenha-o em segredo e não o envie para repositórios públicos.

Para encontrar seu ID de bate-papo para que o bot saiba para onde enviar mensagens, inicie uma conversa com seu novo bot procurando por ele e pressionando Iniciar. Em seguida, acesse a URL https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates no seu navegador ou usando curl. Procure o objeto chat na resposta – o campo id é o seu ID de bate-papo.

Envio de mensagens via API

Esta é a nossa função para enviar mensagens do Telegram:

static async Task SendToTelegramAsync(string botToken, string chatId, string message)
{
 using var httpClient = new HttpClient();

 var telegramApiUrl = $"https://api.telegram.org/bot{botToken}/sendMessage";

 var payload = new
 {
 chat_id = chatId,
 text = message,
 parse_mode = "HTML"
 };

 var jsonContent = JsonSerializer.Serialize(payload);
 var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

 var response = await httpClient.PostAsync(telegramApiUrl, content);

 if (!response.IsSuccessStatusCode)
 {
 var errorContent = await response.Content.ReadAsStringAsync();
 throw new Exception($"Telegram API error: {response.StatusCode} - {errorContent}");
 }
}

A API Telegram Bot é baseada em REST. Fazemos uma solicitação POST para o endpoint sendMessage com um corpo JSON contendo o ID do chat (para onde enviar), o texto da mensagem (o que enviar) e, opcionalmente, um modo de análise (para formatação).

Definir parse_mode como “HTML” nos permite usar tags HTML básicas em nossas mensagens – coisas como <b>bold</b> e <i>italic</i>. Isso pode tornar as notificações mais legíveis, embora, para nosso caso de uso atual, enviemos texto simples.

Se a solicitação falhar, lançamos uma exceção com detalhes sobre o que deu errado. Isso ajuda na depuração se algo não estiver funcionando.

Configurando o aplicativo

Variáveis de ambiente

Nosso aplicativo precisa de várias informações confidenciais – chaves de API, tokens de bot e URLs de endpoint. Nunca devemos codificá-los ou submetê-los ao controle de versão. Em vez disso, usamos variáveis de ambiente, que podem ser definidas com segurança em cada ambiente onde o aplicativo é executado.

Para o Telegram, precisamos de TELEGRAM_BOT_TOKEN (o token que o BotFather lhe deu) e TELEGRAM_CHAT_ID (seu ID do chat para onde as mensagens devem ser enviadas).

Para o Azure OpenAI, precisamos de AZURE_OPENAI_ENDPOINT (a URL do seu recurso), AZURE_OPENAI_API_KEY (sua chave de API) e AZURE_OPENAI_DEPLOYMENT (o nome do seu modelo implantado, como “gpt-4o”).

Carregando configuração no código

Veja como carregamos esses valores na inicialização do aplicativo:

var telegramBotToken = Environment.GetEnvironmentVariable("TELEGRAM_BOT_TOKEN");
var telegramChatId = Environment.GetEnvironmentVariable("TELEGRAM_CHAT_ID");

var azureOpenAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
var azureOpenAiDeployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o";

var aiAnalysisEnabled = !string.IsNullOrWhiteSpace(azureOpenAiEndpoint) &&
 !string.IsNullOrWhiteSpace(azureOpenAiKey);

Usamos Environment.GetEnvironmentVariable para ler cada valor. Para o nome da implantação, fornecemos um padrão de “gpt-4o” se nenhum valor for definido.

Em seguida, verificamos se a análise de IA deve ser habilitada, verificando se temos um endpoint e uma chave de API. Isso permite que o aplicativo seja executado em modo degradado se o Azure OpenAI não estiver configurado – ele ainda buscará feeds e rastreará artigos, mas sem a análise de IA.### Degradação Graciosa

Este conceito de degradação graciosa é importante. Não queremos que o aplicativo trave só porque um recurso opcional não está configurado:

ArticleAnalyzer? articleAnalyzer = null;
MarkdownGenerator? markdownGenerator = null;

if (aiAnalysisEnabled)
{
 Console.WriteLine("🤖 AI Analysis enabled - Using Azure OpenAI with Semantic Kernel");
 articleAnalyzer = new ArticleAnalyzer(azureOpenAiEndpoint!, azureOpenAiKey!, azureOpenAiDeployment);
 markdownGenerator = new MarkdownGenerator(articlesOutputDir);
}
else
{
 Console.WriteLine("ℹ️ AI Analysis disabled - Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY to enable");
}

Se a IA estiver habilitada, criamos o analisador e o gerador de descontos. Caso contrário, os deixamos nulos e pulamos as etapas relacionadas à IA durante o processamento. O aplicativo ainda agrega valor ao buscar feeds e enviar notificações básicas, mesmo sem o aprimoramento de IA.

Automatizando com ações do GitHub

Por que as ações do GitHub

O verdadeiro poder desta solução vem da automação. Não queremos executar manualmente o aplicativo a cada poucas horas – queremos que ele seja executado automaticamente em segundo plano.

GitHub Actions é perfeito para isso. Ele está integrado ao GitHub, portanto não há serviço adicional para configurar. É gratuito para repositórios públicos e inclui minutos gratuitos generosos para repositórios privados. Ele pode ser executado de acordo com uma programação, acionando nosso aplicativo em intervalos regulares. Possui gerenciamento de segredos integrado para armazenar nossas chaves de API com segurança. E pode enviar alterações de volta ao repositório, mantendo nosso arquivo de rastreamento atualizado.

O arquivo de fluxo de trabalho

Crie um arquivo em .github/workflows/fetch-and-notify.yml com o seguinte conteúdo:

name: Fetch DevBlogs and Notify

on:
 schedule:
 - cron: '0 */6 * * *'
 workflow_dispatch:

jobs:
 fetch-and-notify:
 runs-on: ubuntu-latest

 steps:
 - name: Checkout repository
 uses: actions/checkout@v4

 - name: Setup .NET
 uses: actions/setup-dotnet@v4
 with:
 dotnet-version: '9.0.x'

 - name: Restore dependencies
 run: dotnet restore src/VsFeedLinkedin.csproj

 - name: Build
 run: dotnet build src/VsFeedLinkedin.csproj --no-restore

 - name: Run application
 env:
 TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
 TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
 AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
 AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
 AZURE_OPENAI_DEPLOYMENT: ${{ secrets.AZURE_OPENAI_DEPLOYMENT }}
 run: dotnet run --project src/VsFeedLinkedin.csproj

 - name: Commit and push changes
 run: |
 git config user.name "GitHub Actions Bot"
 git config user.email "actions@github.com"

 if [[ -n $(git status --porcelain posted-articles.md generated-posts/) ]]; then
 TIMESTAMP=$(date +%Y%m%d_%H%M%S)
 git add posted-articles.md generated-posts/
 git commit -m "chore($TIMESTAMP): processed new articles"
 git push
 else
 echo "No changes to commit"
 fi

Deixe-me explicar cada parte. A seção on define quando o fluxo de trabalho é executado. O gatilho de agendamento usa sintaxe cron – 0 */6 * * * significa “no minuto 0 de cada 6 horas.” Portanto, o fluxo de trabalho é executado à meia-noite, 6h, meio-dia e 18h UTC. O gatilho workflow_dispatch permite execuções manuais na UI do GitHub, o que é útil para testes.

O trabalho é executado no ubuntu-latest, que é uma máquina virtual Linux. Verificamos nosso repositório, configuramos o .NET 9, restauramos os pacotes NuGet e construímos o projeto.

A etapa Executar aplicativo é onde a mágica acontece. Passamos nossos segredos como variáveis de ambiente usando a sintaxe ${{ secrets.SECRET_NAME }}. Esses segredos são armazenados com segurança no GitHub e nunca expostos em logs.

Finalmente, enviamos todas as alterações de volta ao repositório. Configuramos o Git com uma identidade de bot, verificamos se há alguma alteração em nosso arquivo de rastreamento ou no diretório de postagens gerado e, em caso afirmativo, criamos um commit e enviamos por push.

Configurando segredos

Para adicionar segredos ao seu repositório GitHub, vá para Configurações do seu repositório, depois Segredos e variáveis e, em seguida, Ações. Clique em “Novo segredo do repositório” e adicione cada uma de suas variáveis de ambiente. Os nomes devem corresponder exatamente ao que referenciamos no arquivo de fluxo de trabalho.

Concluindo

O que construímos

Analisando tudo o que abordamos, construímos um agregador de feed RSS abrangente e baseado em IA que automatiza o que costumava ser um processo manual tedioso. O aplicativo monitora automaticamente sete feeds do Microsoft DevBlogs, capturando cada novo artigo assim que é publicado. Ele lida com as complexidades da desduplicação, reconhecendo quando o mesmo artigo aparece em vários feeds.A análise de IA alimentada pelo Semantic Kernel e Azure OpenAI lê e entende o conteúdo do artigo, gerando resumos, identificando os principais tópicos e explicando a relevância – tudo automaticamente. Mais importante ainda, ele cria postagens envolventes no LinkedIn que posso compartilhar com o mínimo de edição.

A integração do Telegram significa que sou notificado no meu telefone sempre que há novo conteúdo para revisar. Posso dar uma olhada na mensagem, decidir se quero compartilhá-la e agir imediatamente.

E como ele é executado no GitHub Actions de acordo com uma programação, não preciso me lembrar de fazer nada. O sistema funciona em segundo plano e só envolvo quando há algo que vale a pena compartilhar.

As tecnologias que tornaram isso possível

Este projeto reuniu diversas tecnologias e cada uma desempenhou um papel crucial. O .NET 9 forneceu uma base sólida com recursos de linguagem modernos e excelente desempenho. O Semantic Kernel simplificou a integração da IA, lidando com toda a complexidade das chamadas de API e gerenciamento de respostas. O Azure OpenAI forneceu a inteligência – a capacidade de realmente compreender e analisar conteúdo técnico. HtmlAgilityPack resolveu o complicado problema de extrair texto limpo de páginas da web. System.ServiceModel.Syndication facilitou muito a análise de RSS. A API do Telegram Bot nos forneceu notificações gratuitas e confiáveis. E o GitHub Actions uniu tudo isso com uma execução automatizada e programada.

Pensando em custos

Uma pergunta que você pode ter é: quanto custa para funcionar? A resposta é: não muito.

O Telegram é totalmente gratuito – sem custos para enviar mensagens através do seu bot.

GitHub Actions é gratuito para repositórios públicos. Para repositórios privados, você recebe 2.000 minutos por mês no nível gratuito, o que é mais que suficiente para nosso caso de uso.

O Azure OpenAI é o único componente pago e os custos são mínimos. Usando o GPT-4o, analisar um artigo típico de blog custa algo entre um e três centavos. Mesmo que você processe dezenas de artigos por mês, terá menos de um dólar em custos de IA.

Onde você pode levar isso a seguir

Embora esta solução funcione muito bem para minhas necessidades, há muitas maneiras de estendê-la. Você pode adicionar suporte para múltiplas plataformas sociais – talvez postar no Twitter/X, Mastodon ou Bluesky, além do LinkedIn. Você pode implementar a análise de sentimento para rastrear o tom dos artigos ao longo do tempo e identificar tendências. Você pode permitir diferentes modelos de prompt para diferentes feeds, gerando diferentes estilos de postagens para diferentes tópicos. Você poderia construir um painel web para revisar e gerenciar postagens em vez de usar o Telegram. Você pode acompanhar as métricas de engajamento do conteúdo postado para ver quais tópicos têm maior repercussão em seu público.

Considerações FinaisO que mais adoro neste projeto é que ele incorpora uma filosofia na qual acredito fortemente: a automação deve cuidar das partes tediosas, deixando as partes criativas e de tomada de decisão para os humanos. O sistema faz todo o trabalho pesado – buscar, analisar, analisar, gerar – mas eu ainda reviso tudo antes de compartilhar. As postagens geradas por IA são pontos de partida que posso customizar e personalizar.

Ao combinar o poder do .NET, do Kernel Semântico e do Azure OpenAI, criamos uma ferramenta que economiza horas de trabalho manual todas as semanas, mantendo a qualidade e a consistência. É o tipo de automação prática que faz uma diferença real na vida diária.

Se você construir algo semelhante ou tiver ideias para melhorias, adoraria ouvir sobre isso. Sinta-se à vontade para entrar em contato no LinkedIn!

Boa codificação e feliz Natal! 🎄

Construindo sistemas de IA multiagentes com a estrutura de agentes da Microsoft

Mon, 01 Dec 2025 00:00:00 +0000

Introdução

Entramos na era dos sistemas de IA multiagentes. Em vez de uma única IA monolítica cuidar de tudo, a indústria está migrando para agentes especializados que colaboram para resolver problemas complexos – como uma equipe bem organizada de especialistas. Um agente pesquisa, outro analisa, um terceiro escreve e um coordenador mantém todos no caminho certo.

Se você trabalhou com grandes modelos de linguagem, provavelmente atingiu o limite do que um único prompt pode fazer. As janelas de contexto ficam cheias, as instruções ficam confusas e a qualidade diminui. As arquiteturas multiagentes resolvem isso decompondo tarefas complexas em responsabilidades específicas, onde cada agente é especialista em uma coisa.

O Agent Framework da Microsoft, parte do ecossistema mais amplo do Kernel Semântico, oferece aos desenvolvedores .NET um kit de ferramentas de primeira classe para construir exatamente esses tipos de sistemas. Nesta postagem, iremos do zero a um pipeline multiagente totalmente funcional, abordando os principais conceitos, padrões de orquestração e código prático de que você precisa para começar.

O que é o Agent Framework da Microsoft?

O Agent Framework é a resposta da Microsoft para construir, orquestrar e implantar agentes de IA e sistemas multiagentes em .NET. Ele acompanha – e se integra profundamente – o Kernel Semântico, que tem sido o SDK de código aberto da Microsoft para orquestração de IA desde 2023.

Pense desta forma: o Kernel Semântico fornece os primitivos (kernels, plug-ins, memória, planejadores), enquanto o Estrutura do Agente fornece abstrações de nível superior projetadas especificamente para comunicação e coordenação entre agentes.

A estrutura dá suporte a vários provedores de modelos, incluindo Azure OpenAI, OpenAI e modelos hospedados no Azure AI Foundry. Seu design é independente de modelo, mas está profundamente integrado ao ecossistema do Azure, o que o torna particularmente atraente para cenários empresariais.

Os principais recursos incluem:

Vários tipos de agentes: ChatCompletionAgent, OpenAIAssistantAgent e AzureAIAgent para diferentes back-ends
Padrões de orquestração: fluxos de trabalho sequenciais, simultâneos, de transferência e de bate-papo em grupo
Ecossistema de plug-ins: Estenda agentes com funções C# nativas, especificações OpenAPI e ferramentas Model Context Protocol (MCP)
Gerenciamento de conversas: threading integrado, gerenciamento de histórico e estratégias de encerramento
Observabilidade: Integração com OpenTelemetry para rastrear interações de agentes

Conceitos-chave

Antes de escrevermos qualquer código, vamos estabelecer o vocabulário. O Agent Framework gira em torno de algumas abstrações básicas.

Agentes

Um agente é uma entidade apoiada por um modelo de IA, configurado com instruções específicas (um prompt do sistema), um nome e, opcionalmente, um conjunto de plug-ins ou ferramentas. Cada agente é um especialista – você define o que ele sabe, o que pode fazer e como deve se comportar.

ChatCompletionAgenteO tipo de agente mais direto. Ele envolve um ponto final de conclusão de chat (Azure OpenAI, OpenAI, etc.) e mantém uma conversa. Não há monitoração de estado entre invocações — você fornece o histórico e ele responde. Isso o torna leve e fácil de raciocinar.

ChatCompletionAgent agent = new()
{
 Name = "Reviewer",
 Instructions = "You are a senior code reviewer. Analyze the provided code for bugs, security issues, and style violations. Be concise and actionable.",
 Kernel = kernel
};

OpenAIAAssistantAgente

Este tipo de agente aproveita a API OpenAI Assistants, que fornece estado de conversação no lado do servidor, manipulação de arquivos e interpretação de código. É mais pesado, mas oferece threads persistentes e ferramentas integradas, como interpretador de código e pesquisa de arquivos.

OpenAIAssistantAgent agent = await OpenAIAssistantAgent.CreateAsync(
 clientProvider: clientProvider,
 definition: new OpenAIAssistantDefinition("gpt-4o")
 {
 Name = "DataAnalyst",
 Instructions = "You analyze datasets and produce statistical summaries."
 }
);

AgentGroupChat

Este é o orquestrador. AgentGroupChat gerencia conversas múltiplas entre vários agentes, controlando quem fala em seguida, quando a conversa termina e como o histórico é compartilhado. É onde acontece a mágica da colaboração multiagente.

Padrões de orquestração

A estrutura oferece suporte a quatro padrões principais de orquestração, cada um adequado para problemas diferentes.

Sequencial

Os agentes executam um após o outro em uma ordem definida. A saída do Agente A alimenta o Agente B, cuja saída alimenta o Agente C. Isso é ideal para pipelines: rascunho → revisão → edição → publicação.

// Conceptual flow
var draft = await writerAgent.InvokeAsync("Write a blog post about .NET 9");
var reviewed = await reviewerAgent.InvokeAsync($"Review this: {draft}");
var edited = await editorAgent.InvokeAsync($"Edit based on feedback: {reviewed}");

Simultâneo

Vários agentes trabalham na mesma entrada simultaneamente. Você distribui o trabalho e depois agrega os resultados. Ótimo para obter perspectivas diversas – como ter três revisores analisando a mesma solicitação pull.

Transferência

Um agente decide transferir o controle para outro agente com base no contexto da conversa. Isso imita o funcionamento de uma equipe de atendimento ao cliente: o agente da linha de frente lida com dúvidas básicas e encaminha para especialistas quando necessário.

Bate-papo em grupo

Vários agentes participam de uma conversa aberta, revezando-se com base em uma estratégia de seleção. A classe AgentGroupChat implementa esse padrão com lógica configurável de tomada de turno e terminação.

Construindo seu primeiro agente

Vamos ser práticos. Veja como construir seu primeiro agente passo a passo.

Pré-requisitos

Você precisará de:

SDK do .NET 9
Um recurso Azure OpenAI com um modelo implantado (por exemplo, gpt-4o)
Visual Studio ou VS Code

Configurando o Projeto

Crie um novo aplicativo de console e instale os pacotes necessários:

dotnet new console -n AgentDemo
cd AgentDemo
dotnet add package Microsoft.SemanticKernel --prerelease
dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

Criando um Agente Simples

Primeiro, configure o kernel com a configuração do Azure OpenAI:

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);

Kernel kernel = builder.Build();

Agora crie um agente e invoque-o:

ChatCompletionAgent agent = new()
{
 Name = "TechWriter",
 Instructions = """
 You are a technical writer specializing in software documentation.
 Write clear, concise content aimed at experienced developers.
 Use code examples when appropriate.
 Always structure your output with headings and bullet points.
 """,
 Kernel = kernel
};

ChatHistory history = new();
history.AddUserMessage("Explain dependency injection in .NET in 200 words.");

await foreach (ChatMessageContent response in agent.InvokeAsync(history))
{
 Console.WriteLine(response.Content);
}

É isso. Você tem um agente trabalhando. Mas o verdadeiro poder surge quando os agentes trabalham juntos.

Orquestração Multiagente com AgentGroupChat

Vamos criar algo mais interessante: um bate-papo em grupo onde vários agentes colaboram. A classe AgentGroupChat gerencia o fluxo da conversa, incluindo quem fala em seguida e quando parar.

Definindo os Agentes

Criaremos três agentes: um redator, um revisor e um editor.

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a content writer. When given a topic, produce a well-structured
 draft. Focus on clarity and technical accuracy.
 When you receive feedback from the Reviewer, incorporate it into a
 revised draft.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a content reviewer. Analyze drafts for technical accuracy,
 clarity, and completeness. Provide specific, actionable feedback.
 Do NOT rewrite the content — only provide feedback.
 When the content meets your standards, respond with: APPROVED
 """,
 Kernel = kernel
};

ChatCompletionAgent editor = new()
{
 Name = "Editor",
 Instructions = """
 You are an editor. Once content is approved by the Reviewer,
 polish it for grammar, tone, and formatting.
 Output only the final polished version.
 When you have produced the final version, respond with: COMPLETE
 """,
 Kernel = kernel
};

Configurando o bate-papo em grupo

O AgentGroupChat precisa de duas configurações principais: uma estratégia de seleção (quem fala a seguir) e uma estratégia de rescisão (quando parar).

AgentGroupChat chat = new(writer, reviewer, editor)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [editor],
 MaximumIterations = 12
 }
 }
};

Estratégia de rescisão personalizadaA estratégia de encerramento define quando a conversa termina. Aqui está um personalizado que procura a palavra-chave “COMPLETE”:

class ApprovalTerminationStrategy : TerminationStrategy
{
 protected override Task<bool> ShouldAgentTerminateAsync(
 Agent agent,
 IReadOnlyList<ChatMessageContent> history,
 CancellationToken cancellationToken = default)
 {
 bool isComplete = history
 .Last()
 .Content?
 .Contains("COMPLETE", StringComparison.OrdinalIgnoreCase) ?? false;

 return Task.FromResult(isComplete);
 }
}

Conduzindo a conversa

Inicie a conversa com uma mensagem do usuário e deixe os agentes colaborarem:

chat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User,
 "Write a 300-word technical overview of gRPC vs REST for microservices.")
);

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
 Console.WriteLine("---");
}

O fluxo será mais ou menos assim:

Escritor produz um rascunho
Revisor fornece feedback
Escritor revisa com base no feedback
Revisor diz “APROVADO”
Editor dá um polimento e diz “COMPLETO”
A conversa termina

Esse vaivém continua automaticamente até que a condição de encerramento seja atendida ou MaximumIterations seja alcançado.

Plug-ins e ferramentas

Os agentes tornam-se verdadeiramente poderosos quando podem interagir com sistemas externos. O Agent Framework oferece suporte a três mecanismos principais de extensão.

Funções nativas (plugins do kernel)

Você pode conceder aos agentes acesso a métodos C# como ferramentas. O agente chamará essas funções quando determinar que são necessárias:

public class ContentToolsPlugin
{
 [KernelFunction("word_count")]
 [Description("Counts the number of words in the provided text.")]
 public int WordCount([Description("The text to count words in")] string text)
 {
 return text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 }

 [KernelFunction("check_readability")]
 [Description("Calculates a readability score for the given text.")]
 public string CheckReadability([Description("The text to analyze")] string text)
 {
 var words = text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 var sentences = text.Split(['.', '!', '?'], StringSplitOptions.RemoveEmptyEntries).Length;

 if (sentences == 0) return "Unable to calculate — no sentences found.";

 double avgWordsPerSentence = (double)words / sentences;

 return avgWordsPerSentence switch
 {
 < 15 => $"Easy to read (avg {avgWordsPerSentence:F1} words/sentence)",
 < 25 => $"Moderate difficulty (avg {avgWordsPerSentence:F1} words/sentence)",
 _ => $"Difficult to read (avg {avgWordsPerSentence:F1} words/sentence). Consider shorter sentences."
 };
 }
}

Registre o plugin no kernel antes de criar o agente:

kernel.Plugins.AddFromType<ContentToolsPlugin>();

ChatCompletionAgent analyst = new()
{
 Name = "ContentAnalyst",
 Instructions = "Analyze content using available tools. Report word count and readability.",
 Kernel = kernel,
 Arguments = new KernelArguments(
 new PromptExecutionSettings
 {
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
 })
};

Protocolo de Contexto do Modelo (MCP)

MCP é um padrão aberto para conectar modelos de IA a ferramentas e fontes de dados externas. O Agent Framework oferece suporte a MCP, o que significa que seus agentes podem usar ferramentas expostas por qualquer servidor compatível com MCP. Isso abre as portas para sistemas de arquivos, bancos de dados, APIs e muito mais — tudo por meio de uma interface padronizada.

// Example: Adding an MCP server for file operations
kernel.Plugins.AddFromMcpServer("filesystem",
 new Uri("http://localhost:3000/mcp"));

Isso é particularmente interessante porque significa que seus agentes não estão limitados ao que você cria — eles podem aproveitar um ecossistema de ferramentas MCP que outros desenvolvem e compartilham.

Exemplo do mundo real: pipeline de revisão de conteúdo

Vamos juntar tudo com um cenário prático. Imagine que você está construindo uma ferramenta interna que automatiza a revisão de conteúdo para uma equipe de documentação. O pipeline tem quatro etapas:

Pesquisador — Reúne informações técnicas relevantes
Escritor — Produz um rascunho baseado em pesquisas
Revisor — Verifica a precisão e integridade
Editor — Formata e prepara o resultado final

Aqui está uma implementação condensada:

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

// Build the kernel
var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);
Kernel kernel = builder.Build();

// Define specialized agents
ChatCompletionAgent researcher = new()
{
 Name = "Researcher",
 Instructions = """
 You are a technical researcher. Given a topic, identify the key
 concepts, recent developments, and important details that should
 be covered. Output a structured research brief.
 """,
 Kernel = kernel
};

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a technical writer. Using the research brief provided,
 write a comprehensive, well-structured article. Include code
 examples where relevant. Target audience: experienced developers.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a senior technical reviewer. Check the article for:
 - Technical accuracy
 - Completeness relative to the research brief
 - Code correctness
 - Clarity and structure
 If everything looks good, respond with APPROVED.
 Otherwise, provide specific feedback for revision.
 """,
 Kernel = kernel
};

ChatCompletionAgent publisher = new()
{
 Name = "Publisher",
 Instructions = """
 You are a content publisher. Once the article is approved,
 format it with proper markdown, add a summary at the top,
 and ensure consistent formatting throughout.
 End your response with COMPLETE.
 """,
 Kernel = kernel
};

// Configure the group chat
AgentGroupChat chat = new(researcher, writer, reviewer, publisher)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [publisher],
 MaximumIterations = 15
 }
 }
};

// Start the pipeline
chat.AddChatMessage(new ChatMessageContent(
 AuthorRole.User,
 "Create a technical article about implementing health checks in ASP.NET Core microservices."
));

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.ForegroundColor = message.AuthorName switch
 {
 "Researcher" => ConsoleColor.Cyan,
 "Writer" => ConsoleColor.Green,
 "Reviewer" => ConsoleColor.Yellow,
 "Publisher" => ConsoleColor.Magenta,
 _ => ConsoleColor.White
 };

 Console.WriteLine($"\n{'='new string('=', 60)}");
 Console.WriteLine($"[{message.AuthorName}]");
 Console.WriteLine(new string('=', 60));
 Console.WriteLine(message.Content);
}

Console.ResetColor();

Esse pipeline produz um artigo totalmente pesquisado, escrito, revisado e formatado – tudo por meio da colaboração do agente. Cada agente se concentra no que faz de melhor e o AgentGroupChat coordena o fluxo de trabalho.

Melhores práticas

Depois de construir vários sistemas multiagentes, aqui estão os padrões e práticas que considero mais valiosos.

Tratamento de erros

Sempre defina MaximumIterations em sua estratégia de rescisão. Sem ele, os agentes podem entrar em ciclos infinitos — especialmente quando um revisor continua encontrando problemas e um redator continua revisando sem melhorar.

TerminationStrategy = new ApprovalTerminationStrategy()
{
 MaximumIterations = 12 // Safety net
}

Envolva as invocações do seu agente em blocos try-catch. Limites de taxa de API, problemas de rede e erros de modelo são realidades dos sistemas de produção:

try
{
 await foreach (var message in chat.InvokeAsync(cancellationToken))
 {
 // Process messages
 }
}
catch (HttpOperationException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
{
 // Implement retry with exponential backoff
 await Task.Delay(TimeSpan.FromSeconds(30), cancellationToken);
}

ObservabilidadeO Agent Framework se integra ao OpenTelemetry, o que significa que você pode rastrear cada interação do agente, chamada de ferramenta e uso de token. Isso é essencial para depurar fluxos de trabalho multiagentes, onde nem sempre é óbvio qual agente causou o problema.

Configure a telemetria básica adicionando os pacotes de telemetria do Kernel Semântico e configurando seu exportador preferido (Application Insights, Jaeger, etc.):

builder.Services.AddOpenTelemetry()
 .WithTracing(tracing =>
 {
 tracing.AddSource("Microsoft.SemanticKernel*");
 tracing.AddOtlpExporter();
 });

Gerenciamento de Custos

Os sistemas multiagentes multiplicam seus custos de API: cada turno de agente é uma chamada de API, e os bate-papos em grupo podem gerar muitos turnos. Algumas estratégias para manter os custos sob controle:

Use modelos mais baratos para agentes mais simples: Nem todo agente precisa do GPT-4o. Um revisor pode funcionar bem com um modelo menor, enquanto apenas o redator precisa do rebatedor pesado.
Limitar histórico: use ReducedHistoryCount nas configurações de execução para limitar a quantidade de contexto de conversa que cada agente recebe.
Definir limites rígidos de iteração: Evite conversas descontroladas com valores MaximumIterations razoáveis.
Cache quando possível: se um agente realizar a mesma pesquisa repetidamente, armazene em cache os resultados em um plugin.

Design do Agente

Mantenha o foco nas instruções: cada agente deve ter uma responsabilidade única e clara. Instruções amplas levam a um desempenho medíocre em todas as tarefas.
Seja explícito sobre o formato de saída: diga aos agentes exatamente como estruturar suas respostas. Isso torna a análise downstream confiável.
Use palavras-chave de rescisão: defina sinais claros (como “APROVADO” ou “CONCLUÍDO”) que os agentes usam para indicar que terminaram. Isso torna as estratégias de rescisão simples e previsíveis.

Conclusão

Os sistemas de IA multiagentes representam uma mudança fundamental na forma como construímos aplicações inteligentes. Em vez de lutar com um único prompt para lidar com tudo, podemos decompor os problemas em funções especializadas e permitir que os agentes colaborem.

O Agent Framework da Microsoft torna isso prático para desenvolvedores .NET. As abstrações são claras – agentes, chats em grupo, estratégias de seleção e rescisão – e se compõem naturalmente. Combinado com o ecossistema de plug-ins do Kernel Semântico e a hospedagem de modelos do Azure, você tem uma pilha completa para criar sistemas multiagentes de nível de produção.

A estrutura ainda está evoluindo (muitos pacotes estão em versão prévia), mas os padrões principais são sólidos e a direção é clara. Se você estiver criando aplicativos com tecnologia de IA em .NET, agora é a hora de começar a experimentar arquiteturas multiagentes.

Comece aos poucos: crie dois agentes que colaborem em uma tarefa simples. Depois de ver a melhoria da qualidade em relação às abordagens de agente único, você desejará decompor tudo em equipes de agentes.

Boa codificação!

Renderizando HTML bruto no Blazor com MarkupString

Sat, 22 Nov 2025 00:00:00 +0000

Outro dia eu estava construindo um componente que precisava renderizar algum HTML vindo de um CMS. Eu tinha a string HTML em uma variável e simplesmente a coloquei no modelo como @myHtml. E, claro, o Blazor escapou de tudo e renderizou as tags reais como texto na página. Não é o que eu queria.

O problema

Por padrão, o Blazor codifica qualquer string renderizada em um modelo. Então, se você tiver:

@code {
 private string content = "<strong>Hello</strong> <em>world</em>";
}

E você faz isso:

<div>@content</div>

Você verá o texto literal <strong>Hello</strong> <em>world</em> na página em vez de Hello world. O Blazor faz isso propositalmente para evitar ataques XSS, que é o comportamento padrão correto.

A solução: MarkupString

Se você realmente precisa renderizar HTML bruto, coloque sua string em um MarkupString:

<div>@((MarkupString)content)</div>

E é isso! Agora o Blazor renderizará o HTML como marcação real. Você também pode atribuí-lo a uma variável:

@code {
 private string rawHtml = "<strong>Hello</strong> <em>world</em>";
 private MarkupString HtmlContent => (MarkupString)rawHtml;
}

<div>@HtmlContent</div>

Um exemplo do mundo real

Eu estava extraindo o conteúdo do blog de uma API e precisava renderizá-lo em um componente de visualização. O conteúdo tinha todo tipo de HTML – títulos, blocos de código, links, imagens. Aqui está aproximadamente o que parecia:

@inject HttpClient Http

@if (article is not null)
{
 <article>
 <h1>@article.Title</h1>
 <div class="content">
 @((MarkupString)article.HtmlBody)
 </div>
 </article>
}

@code {
 [Parameter]
 public int ArticleId { get; set; }

 private ArticleDto? article;

 protected override async Task OnInitializedAsync()
 {
 article = await Http.GetFromJsonAsync<ArticleDto>($"api/articles/{ArticleId}");
 }
}

Funciona perfeitamente. O HTML da API é renderizado como marcação real.

Tenha cuidado com conteúdo não confiável

Isso é importante: MarkupString não limpa o HTML. Ele renderiza tudo o que você fornecer, incluindo tags <script>. Portanto, se o conteúdo vier da entrada do usuário ou de uma fonte não confiável, você precisará higienizá-lo primeiro.

Não há sanitizador de HTML integrado no Blazor, mas você pode usar uma biblioteca como HtmlSanitizer:

using Ganss.Xss;

@code {
 private HtmlSanitizer sanitizer = new();

 private MarkupString SafeHtml(string html)
 {
 var clean = sanitizer.Sanitize(html);
 return (MarkupString)clean;
 }
}

<div>@SafeHtml(untrustedContent)</div>

Isso remove elementos perigosos como manipuladores <script>, onclick e outras coisas que você não deseja renderizar do conteúdo fornecido pelo usuário.

Quando usar

Eu uso MarkupString para:

Conteúdo CMS ou markdown que foi convertido para HTML no lado do servidor
Saída do editor de rich text
Visualização de modelos de e-mail
Qualquer HTML pré-construído de fontes confiáveis

Para qualquer coisa que venha da entrada do usuário, sempre higienize primeiro. Melhor prevenir do que remediar.

Espero que você tenha gostado da postagem! Sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca.

Recursos

O que há de novo no EF Core 9: os recursos que você precisa conhecer

Tue, 18 Nov 2025 00:00:00 +0000

O Entity Framework Core 9 foi lançado junto com o .NET 9 em novembro de 2024 e, depois de passar muito tempo trabalhando com ele em vários projetos, posso dizer que é um dos lançamentos mais significativos dos últimos tempos. Não porque reinventa a roda, mas porque aperfeiçoa as áreas onde o EF Core tem causado historicamente mais atrito: tradução de consultas, desempenho e trabalho com padrões de dados modernos.

Nesta postagem, examinarei os recursos que tiveram maior impacto no meu trabalho diário. Se você ainda estiver no EF Core 8 (ou mesmo 7), isso deverá lhe dar uma imagem clara do que o espera do outro lado da atualização.

EF Core 9 no ecossistema .NET 9

O EF Core 9 é direcionado ao .NET 8 e .NET 9, o que significa que você não precisa necessariamente atualizar todo o seu aplicativo para o .NET 9 para aproveitar a maioria desses recursos. Dito isso, algumas das melhorias de AOT e de desempenho estão intimamente associadas às alterações de tempo de execução do .NET 9, portanto, você aproveitará ao máximo percorrendo todo o caminho.

O lançamento segue a cadência ímpar/par estabelecida pela Microsoft: versões ímpares (como .NET 9) são Standard Term Support (STS) com 18 meses de suporte, enquanto versões pares (como .NET 8) são Long Term Support (LTS). Tenha isso em mente ao planejar seu cronograma de atualização.

Melhorias na tradução do LINQ

É aqui que a maioria dos desenvolvedores sentirá a diferença imediatamente. O EF Core 9 fez avanços significativos na tradução de expressões LINQ para SQL que realmente fazem sentido.

Melhor GroupBy Traduções

Se você já escreveu uma consulta GroupBy no EF Core e acabou com avisos de avaliação do lado do cliente ou SQL bizarro, você conhece o problema. O EF Core 9 lida com um conjunto muito mais amplo de cenários GroupBy diretamente no SQL.

var salesByCategory = await context.Products
 .GroupBy(p => p.Category.Name)
 .Select(g => new
 {
 Category = g.Key,
 TotalRevenue = g.Sum(p => p.Price * p.UnitsSold),
 AveragePrice = g.Average(p => p.Price),
 ProductCount = g.Count()
 })
 .OrderByDescending(x => x.TotalRevenue)
 .ToListAsync();

Nas versões anteriores, as consultas envolvendo agregações sobre propriedades de navegação dentro de GroupBy às vezes recorriam à avaliação do cliente. O EF Core 9 traduz isso de forma limpa para uma única consulta SQL com GROUP BY, SUM, AVG e COUNT.

Projeções e subconsultas complexas

Subconsultas aninhadas e projeções complexas também receberam uma grande atualização. Considere algo assim:

var orderSummaries = await context.Customers
 .Select(c => new CustomerSummaryDto
 {
 Name = c.FullName,
 TotalOrders = c.Orders.Count(),
 MostRecentOrder = c.Orders
 .OrderByDescending(o => o.OrderDate)
 .Select(o => new OrderBriefDto
 {
 Id = o.Id,
 Date = o.OrderDate,
 Total = o.LineItems.Sum(li => li.Quantity * li.UnitPrice)
 })
 .FirstOrDefault(),
 TopCategory = c.Orders
 .SelectMany(o => o.LineItems)
 .GroupBy(li => li.Product.Category.Name)
 .OrderByDescending(g => g.Count())
 .Select(g => g.Key)
 .FirstOrDefault()
 })
 .ToListAsync();

O EF Core 9 agora pode traduzir toda essa expressão em SQL sem acionar a avaliação do lado do cliente. A consulta gerada usa subconsultas correlacionadas e junções laterais quando apropriado, e o plano SQL é consideravelmente mais eficiente do que as versões anteriores produziriam.

Coleções Primitivas Parametrizadas

Uma das melhorias mais destacadas do LINQ é a capacidade de passar coleções de valores primitivos diretamente para consultas:

var statusFilter = new List<string> { "Active", "Pending", "Review" };

var filteredOrders = await context.Orders
 .Where(o => statusFilter.Contains(o.Status))
 .ToListAsync();

No EF Core 8, isso foi traduzido usando cláusulas IN com valores embutidos, o que significava que o cache do plano de consulta não poderia ser reutilizado quando a lista fosse alterada. O EF Core 9 parametriza essas coleções adequadamente, enviando-as como um parâmetro estruturado. Isso é importante para o cache do plano de consulta no SQL Server e no PostgreSQL.## Operações em massa — ExecuteUpdate e ExecuteDelete

ExecuteUpdate e ExecuteDelete foram introduzidos no EF Core 7, mas o EF Core 9 expande o que você pode fazer com eles de maneiras significativas.

Expressões de atualização mais complexas

Agora você pode usar expressões mais complexas em ExecuteUpdate, incluindo referências a outras tabelas através de propriedades de navegação:

await context.Products
 .Where(p => p.Category.IsDiscontinued)
 .ExecuteUpdateAsync(setters => setters
 .SetProperty(p => p.IsAvailable, false)
 .SetProperty(p => p.DiscontinuedDate, DateTimeOffset.UtcNow)
 .SetProperty(p => p.Price, p => p.Price * 0.5m));

Isso gera uma única instrução UPDATE com um JOIN para a tabela de categorias — sem necessidade de carregar entidades na memória, sem sobrecarga de controle de alterações.

Exclusões condicionais em massa com subconsultas

Exclusões em massa com filtros de subconsulta agora são totalmente suportadas:

await context.AuditLogs
 .Where(log => log.CreatedAt < DateTime.UtcNow.AddYears(-2))
 .Where(log => !context.ProtectedRecords
 .Any(pr => pr.AuditLogId == log.Id))
 .ExecuteDeleteAsync();

Isso se traduz em uma DELETE com uma subconsulta NOT EXISTS, exatamente o que você escreveria à mão. Nenhuma entidade carregada, sem viagens de ida e volta.

Melhorias na coluna JSON

As colunas JSON têm sido um dos recursos mais interessantes nas versões recentes do EF Core, e o EF Core 9 as leva ainda mais longe.

Consultando dentro do JSON

Agora você pode filtrar e projetar dados em colunas JSON com melhor suporte de tradução:

public class Order
{
 public int Id { get; set; }
 public string CustomerName { get; set; }
 public ShippingAddress Address { get; set; } // Stored as JSON
 public List<OrderNote> Notes { get; set; } // Stored as JSON
}

public class ShippingAddress
{
 public string Street { get; set; }
 public string City { get; set; }
 public string State { get; set; }
 public string ZipCode { get; set; }
 public string Country { get; set; }
}

public class OrderNote
{
 public DateTime CreatedAt { get; set; }
 public string Text { get; set; }
 public string Author { get; set; }
}

Configuração em seu DbContext:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Order>(builder =>
 {
 builder.OwnsOne(o => o.Address, ab =>
 {
 ab.ToJson();
 });

 builder.OwnsMany(o => o.Notes, nb =>
 {
 nb.ToJson();
 });
 });
}

Agora você pode consultar diretamente no JSON:

var newYorkOrders = await context.Orders
 .Where(o => o.Address.State == "NY")
 .OrderByDescending(o => o.Notes.Count)
 .Select(o => new
 {
 o.CustomerName,
 o.Address.City,
 LatestNote = o.Notes
 .OrderByDescending(n => n.CreatedAt)
 .Select(n => n.Text)
 .FirstOrDefault()
 })
 .ToListAsync();

O EF Core 9 gera chamadas JSON_VALUE e JSON_QUERY adequadas no SQL Server (ou equivalente em outros provedores), e a tradução cobre uma gama muito mais ampla de operações LINQ em elementos JSON do que antes.

Atualizando propriedades JSON

Um dos pontos de atrito no EF Core 8 era que a atualização de uma única propriedade dentro de uma coluna JSON faria com que todo o documento JSON fosse reescrito. O EF Core 9 melhora isso com um rastreamento de alterações mais granular para tipos mapeados em JSON, gerando atualizações mais direcionadas quando possível.

var order = await context.Orders.FindAsync(orderId);
order.Address.ZipCode = "10001";
await context.SaveChangesAsync();

Em fornecedores suportados, isto pode gerar uma modificação JSON mais direcionada em vez de reescrever todo o blob.

Tipos Complexos — Objetos de Valor Sem Identidade

Tipos complexos são um dos recursos que os profissionais de Design Orientado a Domínio estavam esperando. Ao contrário dos tipos próprios, os tipos complexos não têm identidade — são objetos de valor puro.

[ComplexType]
public record Money(decimal Amount, string Currency);

[ComplexType]
public record DateRange(DateTime Start, DateTime End);

public class Project
{
 public int Id { get; set; }
 public string Name { get; set; }
 public Money Budget { get; set; }
 public DateRange Timeline { get; set; }
}

Eles são armazenados como colunas niveladas na tabela pai — Budget_Amount, Budget_Currency, Timeline_Start, Timeline_End — sem exigir uma tabela separada ou qualquer tipo de chave.

A principal diferença em relação aos tipos próprios: os tipos complexos são comparados por valor, não por referência. Duas instâncias Money com os mesmos Amount e Currency são consideradas iguais, independentemente da entidade a que pertencem.

var expensiveProjects = await context.Projects
 .Where(p => p.Budget.Amount > 100_000m && p.Budget.Currency == "USD")
 .OrderByDescending(p => p.Budget.Amount)
 .ToListAsync();

Isso se traduz diretamente na filtragem nas colunas niveladas – limpa, eficiente e exatamente o que você espera.

Suporte HierarchyId para SQL Server

Se você já trabalhou com dados hierárquicos no SQL Server — organogramas, árvores de categorias, sistemas de arquivos — você sabe que HierarchyId é o tipo integrado para isso. O EF Core 9 oferece suporte de primeira classe para isso.

public class Employee
{
 public int Id { get; set; }
 public string Name { get; set; }
 public string Title { get; set; }
 public HierarchyId PathFromCeo { get; set; }
}

Agora você pode consultar relacionamentos hierárquicos diretamente:

var managerId = HierarchyId.Parse("/1/3/");

// All direct and indirect reports
var allReports = await context.Employees
 .Where(e => e.PathFromCeo.IsDescendantOf(managerId))
 .Where(e => e.PathFromCeo != managerId) // exclude the manager
 .OrderBy(e => e.PathFromCeo)
 .ToListAsync();

// Direct reports only (one level down)
var directReports = await context.Employees
 .Where(e => e.PathFromCeo.GetAncestor(1) == managerId)
 .ToListAsync();

// Get an employee's depth in the hierarchy
var employeesWithDepth = await context.Employees
 .Select(e => new
 {
 e.Name,
 e.Title,
 Level = e.PathFromCeo.GetLevel()
 })
 .OrderBy(e => e.Level)
 .ToListAsync();
```Tudo isso se traduz em métodos nativos `HierarchyId` do SQL Server. Se você estiver implementando estruturas em árvore com chaves estrangeiras autorreferenciadas e CTEs recursivas, esta é uma abordagem muito mais limpa.

## Modelos compilados e suporte AOT

Os desenvolvedores preocupados com o desempenho apreciarão o investimento contínuo em modelos compilados e suporte à compilação antecipada (AOT).

### Modelos compilados

Os modelos compilados pré-geram os metadados do modelo que o EF Core normalmente cria na inicialização. Para modelos grandes (pense em centenas de entidades), isso pode reduzir drasticamente o tempo de inicialização a frio.

```bash
dotnet ef dbcontext optimize --output-dir CompiledModels --namespace MyApp.CompiledModels

Então ligue:

builder.Services.AddDbContext<AppDbContext>(options =>
 options
 .UseSqlServer(connectionString)
 .UseModel(MyApp.CompiledModels.AppDbContextModel.Instance));

No EF Core 9, os modelos compilados são mais completos — eles suportam mais recursos de mapeamento e geram resultados menores. Para um modelo com cerca de 400 entidades, o tempo de inicialização pode cair de vários segundos para quase instantâneo.

Progresso da compilação AOT

O suporte completo do AOT nativo para o EF Core ainda é um trabalho em andamento, mas o EF Core 9 faz avanços significativos. Muitos dos caminhos de código com muita reflexão foram refatorados para serem fáceis de cortar, e os modelos compilados são uma parte fundamental da história do AOT. Se você estiver visando cenários como Azure Functions ou microsserviços em que a inicialização a frio é importante, essas melhorias serão diretamente relevantes.

Atualizações do provedor Cosmos DB

O provedor Azure Cosmos DB continua a amadurecer com o EF Core 9. Algumas melhorias notáveis:

Manipulação de chave de partição

O provedor agora oferece suporte a chaves de partição hierárquicas e lida com filtros de chaves de partição de maneira mais inteligente:

public class TenantDocument
{
 public string Id { get; set; }
 public string TenantId { get; set; } // Partition key
 public string Region { get; set; } // Sub-partition key
 public string Content { get; set; }
}

// This query now correctly uses the partition key for routing
var docs = await context.TenantDocuments
 .Where(d => d.TenantId == "tenant-42" && d.Region == "us-east")
 .Where(d => d.Content.Contains("important"))
 .ToListAsync();

Tradução aprimorada de LINQ para NoSQL

Mais operações LINQ agora são traduzidas para o dialeto SQL do Cosmos DB, incluindo melhor suporte para Contains, Any, operações de matriz aninhadas e funções matemáticas. As consultas que anteriormente dependiam da avaliação do cliente agora são tratadas no lado do servidor.

Suporte para pesquisa de vetores

O EF Core 9 introduz suporte antecipado para pesquisa de similaridade vetorial com o Cosmos DB, o que é útil se você estiver criando aplicativos que se integram a embeddings ou pesquisa orientada por IA:

var results = await context.Documents
 .OrderBy(d => EF.Functions.VectorDistance(d.Embedding, queryVector))
 .Take(10)
 .ToListAsync();

Melhorias na migração

As migrações obtiveram algumas melhorias na qualidade de vida que tornam o trabalho com elas menos penoso em ambientes de equipe.

Tabelas Temporais em Migrações

As migrações agora lidam com a configuração da tabela temporal de maneira mais elegante, com suporte adequado para colunas de período e nomenclatura de tabela de histórico:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Employee>()
 .ToTable("Employees", b => b.IsTemporal(t =>
 {
 t.HasPeriodStart("ValidFrom");
 t.HasPeriodEnd("ValidTo");
 t.UseHistoryTable("EmployeeHistory");
 }));
}

Scripts Idempotentes

O comando Script-Migration (e seu equivalente CLI) produz scripts idempotentes melhores por padrão, com tratamento aprimorado de casos extremos em torno de alterações de esquema que dependem de dados existentes em determinados estados.

Pacotes de migração

Os pacotes de migração, que empacotam suas migrações em um executável independente para implantação, são mais confiáveis no EF Core 9, com melhores relatórios de erros e lógica de nova tentativa para falhas transitórias.

dotnet ef migrations bundle --self-contained -r linux-x64

Isso produz um binário que você pode executar em seu pipeline de CI/CD sem precisar do SDK do .NET instalado em seu destino de implantação.

Benchmarks de desempenhoAqui estão alguns benchmarks aproximados de meus próprios testes. Eles são de um projeto com cerca de 200 entidades, executado no SQL Server 2022, medido com BenchmarkDotNet. Seus números irão variar, mas as melhorias relativas devem ser semelhantes.

Cenário	EF Núcleo 8	EF Núcleo 9	Melhoria
Construção de modelo (inicialização a frio)	1.850m	320m	~5,8x mais rápido (compilado)
Consulta simples (entidade única por PK)	0,42ms	0,38ms	~10% mais rápido
Consulta complexa (junções + agregação)	3,1ms	2,4ms	~23% mais rápido
Atualização em massa (10 mil linhas)	145m	118m	~19% mais rápido
Consulta de coluna JSON	2,8ms	1,9ms	~32% mais rápido
Salvar alterações (100 entidades)	48m	41m	~15% mais rápido

A melhoria do modelo compilado é a mais dramática, mas as melhorias constantes em geral se somam — especialmente em cenários de alto rendimento, onde você executa milhares de consultas por segundo.

Atualizando do EF Core 8

Se você estiver no EF Core 8, o caminho de atualização será relativamente tranquilo. Aqui está uma lista de verificação:

1. Atualize seus pacotes:

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="9.0.0" />

2. Verifique se há alterações recentes. A lista do EF Core 9 é relativamente curta em comparação com algumas versões anteriores. Os mais notáveis:

Algumas APIs anteriormente obsoletas foram removidas
Mudanças na forma como certas consultas GroupBy são traduzidas (elas agora vão para o lado do servidor, o que muda o comportamento se você estiver confiando na avaliação do cliente)
Pequenas alterações na saída do andaime de migração

3. Gere novamente modelos compilados se você os estiver usando. O formato mudou, então modelos compilados antigos não funcionarão com o EF Core 9.

4. Execute seu conjunto de testes. Preste atenção especial às consultas que foram avaliadas anteriormente no cliente — elas agora podem ser avaliadas no servidor, o que geralmente é melhor, mas pode revelar diferenças de dados.

5. Verifique suas consultas do Cosmos DB se você estiver usando esse provedor. As traduções aprimoradas significam que algumas consultas serão executadas de maneira diferente (geralmente mais rápidas), mas vale a pena verificar se os resultados são idênticos.

Uma atualização mínima para um projeto típico é assim:

dotnet add package Microsoft.EntityFrameworkCore --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.0
dotnet build
dotnet test

Se tudo for compilado e os testes passarem, você provavelmente está em boa forma. Se você encontrar problemas, a documentação de alterações significativas do EF Core 9 contém orientações detalhadas de migração para cada alteração.

Concluindo

O EF Core 9 não é uma versão revolucionária – é uma versão evolutiva, e era exatamente isso que precisava ser. As melhorias do LINQ por si só justificam a atualização para a maioria dos projetos, e recursos como aprimoramentos de colunas JSON, tipos complexos e HierarchyId suportam padrões de abertura que antes eram estranhos ou impossíveis.

Se eu tivesse que escolher os três recursos que tiveram maior impacto em meus projetos:

Coleções primitivas parametrizadas — porque a eficiência do cache do plano de consulta é importante em escala
Melhorias na coluna JSON — porque o padrão de documento relacional híbrido é incrivelmente útil
Modelos compilados — porque o tempo de inicialização afeta diretamente a produtividade do desenvolvedor e a velocidade de implantaçãoA equipe do EF Core está em uma trajetória sólida desde o EF Core 5, e a versão 9 continua essa tendência. Se você já usa o EF Core 8, a atualização é de baixo risco e alta recompensa. Se você está em algo mais antigo, nunca houve melhor momento para dar o salto.

Boa codificação – e boas consultas.

Introdução ao Kernel Semântico: Orquestração de IA em C#

Sun, 05 Oct 2025 00:00:00 +0000

Se você está construindo aplicativos .NET e observando a evolução do cenário de IA, provavelmente já se perguntou: qual é a melhor maneira de integrar grandes modelos de linguagem em meus projetos C# sem transformar minha base de código em espaguete? Esse é exatamente o problema que o Kernel Semântico da Microsoft resolve, e depois de passar o último ano construindo aplicativos de produção com ele, posso dizer que ele se tornou uma das ferramentas mais importantes em meu kit de ferramentas para desenvolvedores.

Nesta postagem, explicarei tudo o que você precisa para começar a usar o Kernel Semântico – desde a compreensão dos conceitos básicos até a construção de um assistente de IA do mundo real. Esteja você apenas mergulhando no desenvolvimento de IA ou procurando uma maneira estruturada de orquestrar chamadas LLM em seus aplicativos .NET existentes, este guia tem o que você precisa.

O que é Kernel Semântico?

O Kernel Semântico (SK) é um SDK de código aberto da Microsoft que atua como uma camada de orquestração entre o código do seu aplicativo e grandes modelos de linguagem como GPT-4o, Azure OpenAI ou outros serviços de IA. Pense nele como um middleware leve que permite combinar código C# tradicional com recursos de IA de uma forma limpa e combinável.

Mas por que não chamar diretamente a API OpenAI? É absolutamente possível – e para casos de uso simples, tudo bem. Mas o momento em que você precisa:

Deixe a IA decidir quais funções chamar com base na entrada do usuário
Combine várias chamadas de IA com código tradicional em um pipeline
Adicione memória e contexto para que a IA se lembre de interações anteriores
Crie agentes de várias etapas que raciocinam em tarefas complexas

…você se verá reinventando a roda. O Kernel Semântico oferece tudo isso pronto para uso, com suporte .NET de primeira classe, integração de injeção de dependência e uma arquitetura de plug-in que parece natural para qualquer desenvolvedor C#.

O projeto está no GitHub no repositório microsoft/semantic-kernel e possui SDKs para C#, Python e Java. O SDK C# é o mais maduro e é nele que nos concentraremos aqui.

Conceitos Básicos

Antes de escrevermos qualquer código, vamos entender os blocos de construção.

O Núcleo

O Kernel é o objeto central no Kernel Semântico. É o orquestrador – aquilo que une seus serviços, plug-ins e configuração de IA. Você cria um, registra seus serviços e plug-ins nele e depois o usa para executar prompts ou invocar funções. Se você estiver familiarizado com injeção de dependência no ASP.NET Core, o Kernel parecerá muito familiar — é essencialmente um contêiner de serviço com superpoderes de IA.

Plug-ins e funções

Um plugin é uma coleção de funções relacionadas que o Kernel pode invocar. As funções vêm em dois sabores:

Funções de prompt — definidas como modelos de linguagem natural que são enviados ao LLM
Funções nativas — métodos C# regulares decorados com atributos que o Kernel pode descobrir e chamar

Por exemplo, você pode ter um WeatherPlugin com uma função nativa GetCurrentWeather(string city) e uma função de prompt que resume os dados meteorológicos de maneira amigável.### Conectores AI

Os conectores são a forma como o Kernel Semântico se comunica com os serviços de IA. Os mais comuns são:

AzureOpenAIChatCompletion — para serviço Azure OpenAI
OpenAIChatCompletion — para API da OpenAI diretamente
Incorporação de conectores para pesquisa de vetores e memória

Você os registra no Kernel na inicialização e todo o resto funciona.

Configurando seu projeto

Vamos sujar as mãos. Comece criando um novo aplicativo de console:

dotnet new console -n SemanticKernelDemo
cd SemanticKernelDemo

Agora adicione os pacotes NuGet do Kernel Semântico:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI

Se você estiver usando o OpenAI diretamente em vez do Azure OpenAI:

dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

Para suporte de memória e incorporações (usaremos isso mais tarde):

dotnet add package Microsoft.SemanticKernel.Plugins.Memory
dotnet add package Microsoft.Extensions.VectorData.Abstractions

Seu .csproj deve ser direcionado ao .NET 8 ou posterior. As versões mais recentes do Semantic Kernel aproveitam ao máximo os recursos modernos do .NET.

Seu primeiro kernel

Vamos começar com o exemplo mais simples possível: criar um Kernel, conectá-lo a um serviço de IA e fazer uma pergunta.

using Microsoft.SemanticKernel;

// Build the kernel with Azure OpenAI
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();

// Invoke a simple prompt
var result = await kernel.InvokePromptAsync(
 "Explain dependency injection in C# in three sentences."
);

Console.WriteLine(result);

Se você estiver usando o OpenAI diretamente, troque o registro do serviço:

builder.AddOpenAIChatCompletion(
 modelId: "gpt-4o",
 apiKey: "your-openai-api-key"
);

É isso. Execute-o e você obterá uma explicação concisa sobre injeção de dependência. Mas isso está apenas arranhando a superfície.

Usando modelos de prompt

Os modelos de prompt permitem parametrizar seus prompts com variáveis usando sintaxe no estilo Handlebars:

var prompt = """
 You are a technical writer. Write a brief summary of {{$topic}}
 aimed at developers with {{$experienceLevel}} experience.
 Keep it under 200 words.
 """;

var function = kernel.CreateFunctionFromPrompt(prompt);

var arguments = new KernelArguments
{
 ["topic"] = "gRPC in .NET",
 ["experienceLevel"] = "intermediate"
};

var result = await kernel.InvokeAsync(function, arguments);
Console.WriteLine(result);

É aqui que o Kernel Semântico começa a brilhar – você pode definir modelos de prompt reutilizáveis, versioná-los e compô-los em fluxos de trabalho maiores.

Plugins e funções nativas

Os plug-ins são onde o Kernel Semântico preenche a lacuna entre a IA e seu código C# existente. Uma função nativa é apenas um método regular que você expõe ao Kernel.

using Microsoft.SemanticKernel;
using System.ComponentModel;

public class TimePlugin
{
 [KernelFunction("get_current_time")]
 [Description("Gets the current date and time in UTC")]
 public string GetCurrentTime()
 {
 return DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss UTC");
 }

 [KernelFunction("get_time_in_timezone")]
 [Description("Gets the current time in a specific timezone")]
 public string GetTimeInTimezone(
 [Description("The IANA timezone identifier, e.g. 'America/New_York'")] string timezone)
 {
 var tz = TimeZoneInfo.FindSystemTimeZoneById(timezone);
 var time = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
 return time.ToString("yyyy-MM-dd HH:mm:ss");
 }
}

Observe os atributos [KernelFunction] e [Description]. Eles são críticos – as descrições são o que a IA lê para entender quando e como chamar suas funções. Boas descrições fazem a diferença entre uma IA que usa suas ferramentas de maneira eficaz e outra que é confusa.

Registre o plugin em seu kernel:

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();

var kernel = builder.Build();

Você também pode construir plugins mais complexos que injetam serviços. Como o Kernel Semântico se integra ao Microsoft.Extensions.DependencyInjection, seus plug-ins podem receber dependências de construtor como qualquer outro serviço:

public class OrderPlugin
{
 private readonly IOrderRepository _repository;

 public OrderPlugin(IOrderRepository repository)
 {
 _repository = repository;
 }

 [KernelFunction("get_order_status")]
 [Description("Retrieves the status of an order by its ID")]
 public async Task<string> GetOrderStatus(
 [Description("The order ID to look up")] string orderId)
 {
 var order = await _repository.GetByIdAsync(orderId);
 return order is null
 ? $"No order found with ID {orderId}"
 : $"Order {orderId}: {order.Status}, placed on {order.CreatedAt:d}";
 }
}

Chamada de função e invocação automática

É aqui que as coisas ficam realmente interessantes. Com a chamada de função (também conhecida como chamada de ferramenta), você permite que o modelo de IA decida quais das funções registradas chamar com base no contexto da conversa. O modelo não executa código — ele retorna uma solicitação estruturada dizendo “Quero chamar a função X com esses argumentos” e o Kernel trata da invocação real.

Veja como ativar a chamada automática de função:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();
builder.Plugins.AddFromType<WeatherPlugin>();

var kernel = builder.Build();

// Enable automatic function calling
var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

var result = await kernel.InvokePromptAsync(
 "What time is it in Tokyo and what's the weather like there?",
 new KernelArguments(settings)
);

Console.WriteLine(result);

Com FunctionChoiceBehavior.Auto(), o Kernel irá:

Envie seu prompt para a IA junto com descrições de todas as funções disponíveis
A IA decide que precisa ligar para get_time_in_timezone e get_weather
O Kernel executa automaticamente essas funções
Os resultados são enviados de volta para a IA
A IA compõe uma resposta em linguagem natural usando os resultados da funçãoEsse loop pode acontecer várias vezes em uma única invocação — a IA pode chamar várias funções em sequência para reunir todas as informações necessárias. Você também pode usar FunctionChoiceBehavior.Required() para forçar a IA a chamar pelo menos uma função ou fornecer uma lista específica de funções que ela pode usar.

Conclusão do bate-papo com histórico

Para aplicativos de conversação, você desejará usar o ChatCompletionService diretamente com um objeto ChatHistory:

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a helpful developer assistant. You have access to tools
 for checking the time and weather. Be concise and friendly.
 """);

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();
 if (string.IsNullOrWhiteSpace(input)) break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 history.AddAssistantMessage(response.Content ?? "");
 Console.WriteLine($"Assistant: {response.Content}");
}

Isso fornece um chatbot totalmente interativo que mantém o histórico de conversas e pode chamar seus plug-ins conforme necessário.

Memória e incorporações

Um dos padrões mais poderosos em aplicativos de IA é Retrieval-Augmented Generation (RAG) — dando à IA acesso aos seus próprios dados, incorporando-os no espaço vetorial e recuperando pedaços relevantes no momento da consulta.

O Kernel Semântico fornece abstrações para trabalhar com armazenamentos e embeddings de vetores. Veja como configurar um armazenamento de vetores na memória para desenvolvimento:

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.SemanticKernel.Embeddings;

#pragma warning disable SKEXP0010

// Create an embedding generation service
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-ada-002",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();
var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

// Generate embeddings for your documents
var documents = new[]
{
 "Semantic Kernel is an open-source SDK for AI orchestration.",
 "Azure OpenAI provides enterprise-grade AI models.",
 "Plugins in SK allow you to expose C# methods to AI models."
};

var embeddings = await embeddingService.GenerateEmbeddingsAsync(documents);

Para cenários de produção, você armazenaria essas incorporações em um banco de dados vetorial dedicado, como Azure AI Search, Qdrant ou Pinecone. O Kernel Semântico possui conectores para tudo isso através das abstrações Microsoft.Extensions.VectorData.

Um fluxo RAG típico é assim:

Ingestão: fragmente seus documentos, gere embeddings e armazene-os em um banco de dados vetorial
Recuperar: quando um usuário fizer uma pergunta, incorpore a consulta e encontre os documentos mais semelhantes
Gerar: Passe os documentos recuperados como contexto para o LLM junto com a pergunta do usuário

[KernelFunction("search_knowledge_base")]
[Description("Searches the internal knowledge base for relevant information")]
public async Task<string> SearchKnowledgeBase(
 [Description("The search query")] string query)
{
 var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query);

 var results = await _vectorStore.SearchAsync(queryEmbedding, limit: 3);

 return string.Join("\n\n", results.Select(r => r.Text));
}

Ao expor seu pipeline RAG como uma função de kernel, a IA pode decidir automaticamente quando precisa pesquisar sua base de conhecimento – mantendo a orquestração limpa e deixando o modelo fazer o que faz de melhor.

Planejadores e Agentes

À medida que seus aplicativos de IA se tornam mais complexos, você precisará da IA para planejar e executar tarefas de várias etapas. É aqui que entra a estrutura de agente do Semantic Kernel.

O básico: agente de conclusão de bate-papo

O tipo de agente mais simples envolve um modelo de conclusão de chat com instruções e plug-ins:

using Microsoft.SemanticKernel.Agents;

#pragma warning disable SKEXP0110

var agent = new ChatCompletionAgent
{
 Name = "DevAssistant",
 Instructions = """
 You are a senior .NET developer assistant. Help users with code
 reviews, architecture decisions, and debugging. Always provide
 code examples when relevant. Use your available tools to look up
 current information when needed.
 """,
 Kernel = kernel,
 Arguments = new KernelArguments(settings)
};

var history = new ChatHistory();

history.AddUserMessage("How should I structure a clean architecture project in .NET 8?");

await foreach (var message in agent.InvokeAsync(history))
{
 Console.WriteLine(message.Content);
 history.Add(message);
}

Colaboração multiagente

As coisas ficam realmente poderosas quando você tem vários agentes trabalhando juntos. O Kernel Semântico oferece suporte a padrões de chat em grupo onde agentes com diferentes especializações colaboram:

#pragma warning disable SKEXP0110

var codeReviewer = new ChatCompletionAgent
{
 Name = "CodeReviewer",
 Instructions = """
 You review C# code for bugs, performance issues, and best practices.
 Be specific about what you find and suggest concrete fixes.
 """,
 Kernel = kernel
};

var securityAuditor = new ChatCompletionAgent
{
 Name = "SecurityAuditor",
 Instructions = """
 You focus exclusively on security vulnerabilities in code.
 Look for injection attacks, authentication issues, data exposure,
 and OWASP Top 10 violations.
 """,
 Kernel = kernel
};

var groupChat = new AgentGroupChat(codeReviewer, securityAuditor)
{
 ExecutionSettings = new AgentGroupChatSettings
 {
 TerminationStrategy = new MaximumIterationTerminationStrategy(4)
 }
};

groupChat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User, "Review this code: ...")
);

await foreach (var message in groupChat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
}

Esse padrão é extremamente útil para tarefas complexas onde diferentes perspectivas ou áreas de especialização precisam ser consideradas. Cada agente opera com seu próprio prompt de sistema e pode ter seu próprio conjunto de plug-ins.

Exemplo do mundo real: construindo um assistente de documentação de projeto

Vamos unir tudo com um exemplo prático: um assistente de IA que ajuda os desenvolvedores a entender uma base de código lendo arquivos e respondendo perguntas.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using System.ComponentModel;

// Define our plugins
public class FileSystemPlugin
{
 private readonly string _rootPath;

 public FileSystemPlugin(string rootPath)
 {
 _rootPath = rootPath;
 }

 [KernelFunction("read_file")]
 [Description("Reads the contents of a file from the project directory")]
 public async Task<string> ReadFile(
 [Description("Relative path to the file")] string path)
 {
 var fullPath = Path.Combine(_rootPath, path);

 if (!File.Exists(fullPath))
 return $"File not found: {path}";

 var content = await File.ReadAllTextAsync(fullPath);

 // Truncate very large files
 if (content.Length > 8000)
 content = content[..8000] + "\n... [truncated]";

 return content;
 }

 [KernelFunction("list_files")]
 [Description("Lists files in a directory, optionally filtered by extension")]
 public string ListFiles(
 [Description("Relative directory path")] string directory,
 [Description("File extension filter like '.cs' or '.json'")] string? extension = null)
 {
 var fullPath = Path.Combine(_rootPath, directory);

 if (!Directory.Exists(fullPath))
 return $"Directory not found: {directory}";

 var files = Directory.GetFiles(fullPath, "*.*", SearchOption.AllDirectories)
 .Select(f => Path.GetRelativePath(_rootPath, f))
 .Where(f => extension is null || f.EndsWith(extension))
 .Take(50);

 return string.Join("\n", files);
 }
}

public class DocumentationPlugin
{
 [KernelFunction("generate_summary")]
 [Description("Generates a structured markdown summary for documentation")]
 public string GenerateSummaryTemplate(
 [Description("Name of the component")] string componentName,
 [Description("Brief description")] string description,
 [Description("Key responsibilities as comma-separated values")] string responsibilities)
 {
 var items = responsibilities.Split(',', StringSplitOptions.TrimEntries);
 var bullets = string.Join("\n", items.Select(r => $"- {r}"));

 return $"""
 ## {componentName}

 {description}

 ### Responsibilities
 {bullets}

 ---
 *Generated documentation — review and expand as needed.*
 """;
 }
}

// Wire it all up
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromObject(new FileSystemPlugin("./src"));
builder.Plugins.AddFromType<DocumentationPlugin>();

var kernel = builder.Build();

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a codebase documentation assistant. You help developers understand
 projects by reading source files and explaining architecture, patterns,
 and design decisions.

 When asked about code, use your tools to read the actual files rather
 than guessing. Be specific and reference actual code when possible.
 Generate documentation artifacts when asked.
 """);

var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

Console.WriteLine("Documentation Assistant ready. Ask me about your codebase!");
Console.WriteLine("Type 'exit' to quit.\n");

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();

 if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
 break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 Console.WriteLine($"\nAssistant: {response.Content}\n");
 history.AddAssistantMessage(response.Content ?? "");
}

Este assistente pode:- Liste e leia arquivos do diretório do seu projeto

Responda a perguntas sobre a base de código lendo arquivos de origem reais
Gerar documentação em formato markdown
Mantenha o contexto da conversa para que as perguntas de acompanhamento funcionem naturalmente

A IA decide automaticamente quando ligar para read_file, list_files ou generate_summary com base no que você pergunta. Pergunte “O que o OrderService faz?” e ele lerá o arquivo, analisará e explicará. Peça para “Gerar documentação para o módulo de autenticação” e ele explorará os arquivos, entenderá a estrutura e produzirá um resumo formatado.

Dicas para Produção

Antes de enviar seu aplicativo de Kernel Semântico, aprendi algumas coisas da maneira mais difícil:

Use a injeção de dependência corretamente. Em aplicativos ASP.NET Core, registre o Kernel e os serviços em seu contêiner DI em vez de criá-los in-line:

builder.Services.AddKernel()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: configuration["AzureOpenAI:Endpoint"]!,
 apiKey: configuration["AzureOpenAI:ApiKey"]!
 )
 .Plugins.AddFromType<TimePlugin>()
 .AddFromType<OrderPlugin>();

Trate de erros normalmente. As chamadas LLM podem falhar, atingir o tempo limite ou retornar resultados inesperados. Envolva suas invocações em blocos try-catch e implemente políticas de repetição com Polly ou os recursos de resiliência integrados.

Monitore o uso de tokens. Cada prompt, cada descrição de função e cada parte do histórico de bate-papo consome tokens. Use filtros para registrar e rastrear o uso:

kernel.FunctionInvocationFilters.Add(new LoggingFilter());

Mantenha as descrições de suas funções precisas. Descrições vagas levam a IA a chamar funções incorretamente. Teste suas descrições perguntando: “Se eu apenas lesse a descrição, saberia exatamente quando e como usar esta função?”

Conclusão

O Kernel Semântico é uma daquelas bibliotecas que muda fundamentalmente a forma como você pensa sobre a construção de aplicativos. Não é apenas um wrapper de API: é uma estrutura de orquestração que permite compor recursos de IA com código tradicional de uma forma que seja sustentável, testável e pronta para produção.

O que mais adoro nele é que respeita o ecossistema .NET. Ele usa padrões que você já conhece – injeção de dependência, atributos, assíncrono/espera, interfaces – e os estende ao mundo da IA. Você não precisa aprender um paradigma completamente novo; você acabou de adicionar IA como outro recurso em seu kit de ferramentas.

Se você está criando aplicativos .NET e ainda não explorou o Kernel Semântico, agora é a hora. O SDK é estável, a comunidade é ativa e os padrões que ele permite — desde a simples orquestração imediata até a colaboração multiagente — estão se tornando habilidades essenciais para os desenvolvedores modernos.

Comece pequeno. Crie um Kernel, registre um plugin e observe a IA chamar seu código. Depois que isso acontecer, você começará a ver oportunidades para adicionar inteligência em todos os lugares dos seus aplicativos.

A documentação oficial e o repositório GitHub são excelentes recursos para continuar sua jornada. Feliz edifício!

Herdando componentes no Blazor

Thu, 04 Sep 2025 00:00:00 +0000

Eu estava construindo um projeto que tinha várias páginas de formulário e cada uma delas tinha a mesma lógica de estado de carregamento, o mesmo tratamento de erros e as mesmas notificações do sistema. Copiar e colar tudo isso parecia errado, então examinei a herança de componentes no Blazor. Acontece que é bastante simples, já que os componentes do Blazor são apenas classes C#.

O básico

Cada componente Blazor herda de ComponentBase por padrão. Você pode criar sua própria classe base que estende ComponentBase e então fazer com que seus componentes sejam herdados dela.

Digamos que a maioria de nossas páginas precise de estado de carregamento e tratamento de erros. Podemos criar uma classe base:

using Microsoft.AspNetCore.Components;

public abstract class PageBase : ComponentBase
{
 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected async Task LoadDataAsync(Func<Task> action)
 {
 try
 {
 IsLoading = true;
 ErrorMessage = null;
 await action();
 }
 catch (Exception ex)
 {
 ErrorMessage = ex.Message;
 }
 finally
 {
 IsLoading = false;
 StateHasChanged();
 }
 }
}

#Usando a classe base

Agora, em qualquer componente de página, em vez de herdar de ComponentBase, herdamos de nosso PageBase:

@page "/users"
@inherits PageBase

@if (IsLoading)
{
 <div class="spinner"></div>
}
else if (ErrorMessage is not null)
{
 <div class="alert alert-danger">@ErrorMessage</div>
}
else
{
 <ul>
 @foreach (var user in users)
 {
 <li>@user.Name</li>
 }
 </ul>
}

@code {
 private List<User> users = new();

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 users = await Http.GetFromJsonAsync<List<User>>("api/users");
 });
 }
}

A diretiva @inherits PageBase é a chave. Diz ao Blazor para usar nossa classe base em vez do padrão ComponentBase. Agora temos IsLoading, ErrorMessage e LoadDataAsync() gratuitamente em todas as páginas herdadas dele.

Injetando serviços na classe base

Você também pode injetar serviços na classe base para que estejam disponíveis para todos os componentes filhos:

public abstract class PageBase : ComponentBase
{
 [Inject]
 protected NavigationManager Navigation { get; set; } = default!;

 [Inject]
 protected IToastService Toast { get; set; } = default!;

 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected void NavigateBack() => Navigation.NavigateTo("javascript:history.back()");

 protected void ShowSuccess(string message) => Toast.ShowSuccess(message);
}

Cada componente que herda de PageBase agora tem acesso a Navigation, Toast, NavigateBack() e ShowSuccess() sem precisar injetar nada.

Indo mais fundo com classes base genéricas

Você pode até criar classes base genéricas para padrões CRUD comuns:

public abstract class CrudPageBase<T> : PageBase
{
 protected List<T> Items { get; set; } = new();
 protected T? SelectedItem { get; set; }

 protected abstract Task<List<T>> FetchItems();
 protected abstract Task DeleteItem(T item);

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 Items = await FetchItems();
 });
 }

 protected async Task OnDelete(T item)
 {
 await LoadDataAsync(async () =>
 {
 await DeleteItem(item);
 Items = await FetchItems();
 ShowSuccess("Item deleted.");
 });
 }
}

Então sua página real fica super limpa:

@page "/products"
@inherits CrudPageBase<Product>

@* just the markup, all logic lives in the base class *@

@code {
 protected override Task<List<Product>> FetchItems()
 => Http.GetFromJsonAsync<List<Product>>("api/products");

 protected override Task DeleteItem(Product item)
 => Http.DeleteAsync($"api/products/{item.Id}");
}

Quando usar e quando não usar

A herança de componentes é ótima para comportamento compartilhado, como estados de carregamento, tratamento de erros, verificações de autenticação ou padrões CRUD. Mas não exagere com hierarquias de herança profundas - se você estiver indo mais de dois níveis de profundidade, provavelmente estará melhor com a composição (como a abordagem LoadingComponent de uma postagem anterior).

Eu normalmente mantenho uma classe base por “tipo” de página: PageBase para páginas normais, FormPageBase para formulários, e isso é tudo.

Espero que você tenha gostado da postagem! Sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca.

Recursos

Herança de componente ASP.NET Core Razor

.NET Aspire: criando aplicativos nativos da nuvem da maneira certa

Wed, 20 Aug 2025 00:00:00 +0000

Se você já criou um aplicativo distribuído em .NET, você sabe o que fazer. Você cria uma API Web, adiciona um trabalhador em segundo plano, adiciona Redis para armazenamento em cache, PostgreSQL para persistência, talvez RabbitMQ para mensagens - e de repente você está gastando mais tempo conectando infraestrutura do que escrevendo lógica de negócios. Cadeias de conexão espalhadas por arquivos appsettings.json, verificações de integridade que você esqueceu de configurar, observabilidade que é sempre o “problema do próximo sprint”.

Eu estive lá. Mais vezes do que eu gostaria de admitir.

Esse é exatamente o problema para o qual o .NET Aspire foi projetado para resolver. Depois de executá-lo em produção por vários meses, quero compartilhar o que aprendi - o que é bom, o que é ótimo e as pegadinhas.

O que é o .NET Aspire?

O .NET Aspire é uma pilha opinativa para a construção de aplicativos distribuídos, observáveis e prontos para produção com o .NET. Não é uma estrutura no sentido tradicional — ela não substitui o ASP.NET Core nem força você a adotar um novo modelo de programação. Em vez disso, ele se baseia no que você já sabe e preenche as lacunas que sempre existiram na criação de aplicativos nativos da nuvem.

Basicamente, o Aspire oferece quatro coisas:

AppHost — Um projeto que define toda a topologia de seu aplicativo distribuído. Quais serviços existem, de que dependem e como se conectam.
Padrões de serviço — Um projeto compartilhado que configura preocupações transversais, como verificações de integridade, políticas de resiliência e OpenTelemetry — uma vez, para todos os seus serviços.
Componentes — pacotes NuGet que fornecem integrações padronizadas com serviços de apoio como Redis, PostgreSQL, RabbitMQ, Azure Storage e muito mais.
Painel do desenvolvedor — Uma IU em tempo real que mostra logs, rastreamentos e métricas de todo o seu aplicativo distribuído durante o desenvolvimento local.

A filosofia é simples: se todo aplicativo em nuvem .NET precisa dessas coisas, por que estamos todos implementando-as do zero sempre?

Configurando seu primeiro projeto Aspire

Começar é simples. Você precisará do .NET 8 ou posterior e da carga de trabalho do Aspire instalada:

dotnet workload update
dotnet workload install aspire

Agora crie um novo projeto inicial do Aspire:

dotnet new aspire-starter -n MyCloudApp

Isso gera uma solução com quatro projetos:

MyCloudApp.AppHost — O orquestrador
MyCloudApp.ServiceDefaults — Configuração compartilhada
MyCloudApp.ApiService — Um exemplo de API da Web
MyCloudApp.Web — Uma interface do Blazor

Execute o AppHost e você verá imediatamente o painel do Aspire aberto em seu navegador, mostrando todos os seus serviços, seus logs e sua saúde. Nenhum arquivo Docker Compose. Sem gerenciamento manual de portas. Simplesmente funciona.

dotnet run --project MyCloudApp.AppHost

Essa primeira experiência foi o que me fisgou. Em menos de um minuto, você tem um aplicativo distribuído totalmente orquestrado com observabilidade integrada.

O padrão AppHost

O AppHost é onde mora a magia. É um pequeno aplicativo de console que usa um padrão de construtor para definir a topologia do seu aplicativo distribuído — quais recursos existem e como os serviços se conectam a eles.

Esta é a aparência de um AppHost realista:

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources
var postgres = builder.AddPostgres("postgres")
 .WithPgAdmin()
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache");

var rabbitmq = builder.AddRabbitMQ("messaging")
 .WithManagementPlugin();

// Application services
var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReference(rabbitmq);

var orderApi = builder.AddProject<Projects.OrderApi>("order-api")
 .WithReference(postgres)
 .WithReference(rabbitmq);

var frontend = builder.AddProject<Projects.WebFrontend>("frontend")
 .WithExternalHttpEndpoints()
 .WithReference(catalogApi)
 .WithReference(orderApi);

builder.Build().Run();
```Leia esse código em voz alta. Praticamente se documenta. "A API do catálogo faz referência a PostgreSQL, Redis e RabbitMQ. O frontend faz referência à API do catálogo e à API do pedido." Essa é a sua arquitetura, expressa em código.

Algumas coisas dignas de nota:

- **`WithReference`** faz o trabalho pesado. Ele injeta automaticamente cadeias de conexão e URLs de serviço no projeto de consumo por meio de variáveis de ambiente e configuração. Seus serviços não precisam saber *onde* o Redis está sendo executado — o Aspire cuida disso.
- **`WithPgAdmin()`** e **`WithManagementPlugin()`** ativam UIs de administração para PostgreSQL e RabbitMQ juntamente com os serviços reais. Durante o desenvolvimento, eles são inestimáveis.
- **`WithExternalHttpEndpoints()`** marca um serviço como acessível externamente, o que é importante no momento da implantação.

### Configuração de recursos

Você pode configurar recursos com controle refinado:

```csharp
var postgres = builder.AddPostgres("postgres")
 .WithEnvironment("POSTGRES_MAX_CONNECTIONS", "200")
 .WithDataVolume("postgres-data")
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache")
 .WithDataVolume("redis-data");

Os volumes de dados garantem que seus dados de desenvolvimento local sobrevivam às reinicializações do contêiner. Pequenos detalhes, grande melhoria na qualidade de vida.

Padrões de serviço: o herói desconhecido

O projeto ServiceDefaults é a parte mais subestimada do Aspire. É uma biblioteca compartilhada à qual todos os serviços da sua solução fazem referência e configura todas as preocupações transversais que você esqueceria ou implementaria de forma inconsistente.

Esta é a aparência de um Extensions.cs típico em ServiceDefaults:

public static class Extensions
{
 public static IHostApplicationBuilder AddServiceDefaults(
 this IHostApplicationBuilder builder)
 {
 builder.ConfigureOpenTelemetry();
 builder.AddDefaultHealthChecks();
 builder.Services.AddServiceDiscovery();

 builder.Services.ConfigureHttpClientDefaults(http =>
 {
 http.AddStandardResilienceHandler();
 http.AddServiceDiscovery();
 });

 return builder;
 }

 public static IHostApplicationBuilder ConfigureOpenTelemetry(
 this IHostApplicationBuilder builder)
 {
 builder.Logging.AddOpenTelemetry(logging =>
 {
 logging.IncludeFormattedMessage = true;
 logging.IncludeScopes = true;
 });

 builder.Services.AddOpenTelemetry()
 .WithMetrics(metrics =>
 {
 metrics.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddRuntimeInstrumentation();
 })
 .WithTracing(tracing =>
 {
 tracing.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddGrpcClientInstrumentation();
 });

 builder.AddOpenTelemetryExporters();
 return builder;
 }

 public static IHostApplicationBuilder AddDefaultHealthChecks(
 this IHostApplicationBuilder builder)
 {
 builder.Services.AddHealthChecks()
 .AddCheck("self", () => HealthCheckResult.Healthy(),
 ["live"]);

 return builder;
 }
}

Então, em Program.cs de cada serviço, uma linha faz tudo:

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

// Your service-specific configuration...

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

Essa única chamada AddServiceDefaults() fornece:

OpenTelemetry com registro estruturado, métricas e rastreamento distribuído
Verificações de integridade com pontos de extremidade de atividade e prontidão
Descoberta de serviços para que os serviços possam se encontrar pelo nome
Políticas de resiliência em todas as chamadas HTTP de saída (novas tentativas, disjuntores, tempos limite)

Isso é o que separa uma demonstração “funciona na minha máquina” de um sistema pronto para produção. E o Aspire torna isso o padrão, não uma reflexão tardia.

Componentes do Aspire

Os componentes Aspire são pacotes NuGet que padronizam como seus serviços se conectam à infraestrutura de apoio. Elas são mais do que apenas bibliotecas cliente: elas incluem verificações de integridade, registro, rastreamento e resiliência configurável pronta para uso.

Redis

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddRedisDistributedCache("cache");

É isso. A string de conexão vem do AppHost via WithReference. O componente registra um IDistributedCache apoiado por Redis, com verificações de integridade e instrumentação OpenTelemetry já instaladas.

Você também pode usar o Redis para cache de saída:

builder.AddRedisOutputCache("cache");

PostgreSQL com Entity Framework Core

builder.AddNpgsqlDbContext<CatalogDbContext>("catalogdb", settings =>
{
 settings.DisableRetry = false;
});

Isso registra seu DbContext com uma conexão com o banco de dados catalogdb definido no AppHost. Inclui pool de conexões, verificações de integridade e políticas de nova tentativa.

CoelhoMQ

builder.AddRabbitMQClient("messaging");

Registra um IConnection da biblioteca cliente RabbitMQ, totalmente configurado e com integridade verificada.

Integrações Azure

O Aspire também possui componentes de primeira classe para serviços Azure:

// Azure Blob Storage
builder.AddAzureBlobClient("blobs");

// Azure Service Bus
builder.AddAzureServiceBusClient("servicebus");

// Azure Key Vault
builder.AddAzureKeyVaultClient("secrets");
```O padrão é sempre o mesmo: uma linha no AppHost para definir o recurso, uma linha no serviço consumidor para utilizá-lo. Os detalhes da conexão fluem automaticamente.

## O painel do desenvolvedor

O painel do Aspire é um daqueles recursos que parece interessante até você realmente usá-lo - então você não consegue se imaginar trabalhando sem ele.

Quando você executa seu AppHost localmente, o painel é iniciado e fornece:

- **Visão geral dos recursos** — Visão geral de todos os seus serviços e infraestrutura, com indicadores de status
- **Logs estruturados** — Streaming de logs em tempo real de todos os serviços, filtráveis e pesquisáveis
- **Rastreamentos distribuídos** — Rastreamentos de solicitação de ponta a ponta abrangendo vários serviços, visualizados como gráficos em chamas
- **Métricas** — taxas de solicitação HTTP, taxas de erro, latências e métricas personalizadas em tempo real
- **Logs do console** — stdout/stderr brutos de cada contêiner e projeto

O rastreamento distribuído é particularmente valioso. Quando uma solicitação chega ao seu frontend, flui pela API do catálogo, toca no Redis e no PostgreSQL – você vê toda a cadeia com tempo para cada salto. Chega de adivinhar onde está o gargalo.

Achei o painel mais útil durante a depuração. Em vez de seguir várias janelas de terminal ou alternar entre arquivos de log, tudo fica em um só lugar com IDs de correlação que vinculam eventos relacionados entre serviços.

O painel também está disponível como um contêiner independente, o que significa que você pode usá-lo em ambientes de teste ou pipelines de CI:

```bash
docker run --rm -p 18888:18888 \
 mcr.microsoft.com/dotnet/aspire-dashboard:latest

Implantação

O Aspire ajuda durante o desenvolvimento, mas e a produção? É aqui que as coisas ficam práticas.

Aplicativos de contêiner do Azure

O caminho de implantação mais simples é o Azure Container Apps (ACA), que tem suporte Aspire de primeira classe. Você pode implantar diretamente usando a CLI do Desenvolvedor do Azure:

azd init
azd up

O comando azd init detecta seu Aspire AppHost e gera a infraestrutura como código necessária. azd up provisiona tudo — registro de contêiner, aplicativos de contêiner, bancos de dados, instâncias Redis — com base em sua topologia AppHost.

Seu AppHost se torna essencialmente seu manifesto de implantação. O mesmo código que define “catalog-api depende de PostgreSQL e Redis” orienta o provisionamento da infraestrutura.

###Kubernetes

Para implantações do Kubernetes, o Aspire não gera manifestos diretamente, mas a topologia do AppHost é mapeada de forma limpa para os recursos do Kubernetes. A ferramenta da comunidade aspirate (Aspir8) pode gerar gráficos Helm ou manifestos Kubernetes a partir de seu AppHost:

dotnet tool install -g aspirate
aspirate generate
aspirate apply

Considerações de implantação

Algumas coisas para manter em mente:- As cadeias de conexão mudam entre ambientes. Localmente, o Aspire ativa contêineres e injeta cadeias de conexão automaticamente. Na produção, você apontará para serviços gerenciados. O Aspire usa configuração .NET padrão, portanto, as variáveis de ambiente e o Azure Key Vault funcionam conforme esperado.

O AppHost não funciona em produção. É uma ferramenta de orquestração de desenvolvimento e implantação. Na produção, seus serviços são executados de forma independente, configurados por meio de variáveis de ambiente e orquestradores.
Os recursos de infraestrutura tornam-se serviços geridos. O seu contentor PostgreSQL local torna-se a Base de Dados Azure para PostgreSQL. O seu contentor Redis local torna-se Azure Cache para Redis. O código de consumo não muda.

Dicas do mundo real

Depois de executar o Aspire em produção por um tempo, aqui estão as lições que nos pouparam tempo:

1. Use verificações personalizadas do ciclo de vida dos recursos

Não confie apenas na inicialização do contêiner para determinar se um recurso está pronto. O PostgreSQL pode aceitar conexões TCP antes de estar realmente pronto para atender consultas.

var postgres = builder.AddPostgres("postgres")
 .AddDatabase("catalogdb")
 .WithHealthCheck();

O Aspire pode executar verificações de integridade de recursos e manter serviços dependentes até que estejam realmente prontos.

2. Extraia padrões comuns em extensões

Se vários serviços compartilharem configurações semelhantes, crie métodos de extensão:

public static class AppHostExtensions
{
 public static IResourceBuilder<ProjectResource> AddWorkerService(
 this IDistributedApplicationBuilder builder,
 string name,
 IResourceBuilder<IResourceWithConnectionString> db,
 IResourceBuilder<IResourceWithConnectionString> messaging)
 {
 return builder.AddProject<Projects.WorkerService>(name)
 .WithReference(db)
 .WithReference(messaging)
 .WithReplicas(3);
 }
}

3. Aproveite WithReplicas para testes de carga

var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReplicas(5);

WithReplicas ativa várias instâncias de um serviço localmente. Isso é ótimo para testar balanceamento de carga, bugs de simultaneidade e comportamento de cache distribuído sem implantar em um cluster.

4. Use parâmetros para valores sensíveis

Não codifique credenciais, mesmo para desenvolvimento local:

var dbPassword = builder.AddParameter("db-password", secret: true);

var postgres = builder.AddPostgres("postgres", password: dbPassword)
 .AddDatabase("catalogdb");

Ao executar localmente, o Aspire solicitará o valor ou o lerá nos segredos do usuário. No CI/CD, isso vem de variáveis de ambiente.

5. Testes de integração tornam-se triviais

O Aspire inclui um pacote de testes que torna o teste de integração de aplicativos distribuídos extremamente fácil:

[Fact]
public async Task CatalogApiReturnsProducts()
{
 var appHost = await DistributedApplicationTestingBuilder
 .CreateAsync<Projects.MyCloudApp_AppHost>();

 await using var app = await appHost.BuildAsync();
 await app.StartAsync();

 var httpClient = app.CreateHttpClient("catalog-api");
 var response = await httpClient.GetAsync("/api/products");

 response.EnsureSuccessStatusCode();

 var products = await response.Content
 .ReadFromJsonAsync<List<Product>>();
 Assert.NotEmpty(products);
}

Isso acelera todo o seu aplicativo distribuído - incluindo bancos de dados e corretores de mensagens - executa seu teste e o desmonta. Testes reais de integração em infraestrutura real, em seu pipeline de CI. Sem zombarias.

6. Monitore o uso de recursos localmente

Ao executar vários contêineres localmente, fique atento ao consumo de recursos. Uma instância PostgreSQL, Redis e RabbitMQ com UI de gerenciamento pode consumir facilmente de 2 a 3 GB de RAM. Se você estiver em uma máquina restrita, considere usar configurações de recursos mais leves:

var redis = builder.AddRedis("cache")
 .WithContainerRuntimeArgs("--memory=256m");

Conclusão

O .NET Aspire mudou fundamentalmente a forma como construo aplicativos distribuídos. Não porque introduza conceitos revolucionários — verificações de integridade, OpenTelemetry e orquestração de contêineres não são novidade. Mas porque isso os torna padrão. Ele toma as centenas de pequenas decisões que você normalmente teria que tomar, implementa-as com padrões sensatos e permite substituí-las quando necessário.O padrão AppHost é, na minha opinião, a maior vitória. Ter a topologia de seu aplicativo distribuído expressa como código (não espalhada em arquivos Docker Compose, manifestos do Kubernetes e documentos README) torna o sistema compreensível. Novos membros da equipe podem abrir Program.cs no AppHost e entender toda a arquitetura em minutos.

Se você estiver construindo aplicativos distribuídos com .NET, dê uma olhada séria no Aspire. Comece com o modelo aspire-starter, explore o painel e adote gradualmente os componentes conforme necessário. Você não precisa apostar tudo no primeiro dia – o Aspire é aditivo por design.

Os dias em que você passava seu primeiro sprint conectando o padrão de infraestrutura acabaram. Deixe o Aspire cuidar do encanamento para que você possa se concentrar no que realmente importa: sua aplicação.

Autenticação e autorização no Blazor: um guia prático

Sat, 12 Jul 2025 00:00:00 +0000

Se você trabalhou com ASP.NET MVC ou Razor Pages, provavelmente tem um modelo mental de como a autenticação funciona: o middleware intercepta a solicitação, verifica um cookie ou token, preenche HttpContext.User e você está pronto para a corrida. O Blazor altera esse modelo mental de maneiras sutis, mas importantes — e se você não entender essas diferenças desde o início, acabará depurando problemas de autenticação que parecem impossíveis.

Nesta postagem, quero explicar como a autenticação e a autorização realmente funcionam no Blazor, abrangendo os modelos de hospedagem Server e WebAssembly. Iremos desde o básico até provedores personalizados, OAuth externo e as armadilhas que vi atrapalhar até mesmo desenvolvedores .NET experientes.

Por que o Auth no Blazor é diferente

No ASP.NET tradicional, cada interação do usuário é uma solicitação HTTP. O servidor valida as credenciais, define um cookie e cada solicitação subsequente carrega esse cookie. O pipeline de autenticação é linear e previsível.

Blazor Server opera em uma conexão SignalR persistente. Depois que a solicitação HTTP inicial carrega a página, todas as interações subsequentes acontecem por meio de WebSockets. Não há nenhuma nova solicitação HTTP para cada clique de botão, portanto o middleware não é executado novamente em cada interação. O HttpContext está disponível durante a conexão inicial, mas depender dele durante toda a vida útil de um circuito é uma receita para bugs.

Blazor WebAssembly é executado inteiramente no navegador. Não há nenhum HttpContext no lado do servidor. O estado de autenticação deve ser obtido de uma API, armazenado no lado do cliente e gerenciado por meio de tokens — normalmente JWTs. O servidor confia no cliente apenas no que diz respeito à validação do token.

Isso significa que o Blazor precisa de sua própria abstração para o estado de autenticação, que funcione independentemente do modelo de hospedagem. Essa abstração é o AuthenticationStateProvider.

Estado de autenticação: The Foundation

No coração do sistema de autenticação do Blazor está AuthenticationStateProvider. Esta é uma classe abstrata que expõe um único método crítico:

public abstract Task<AuthenticationState> GetAuthenticationStateAsync();

O objeto AuthenticationState envolve um ClaimsPrincipal — o mesmo modelo de identidade usado em todo o .NET. Os componentes não se comunicam diretamente com cookies ou tokens; eles perguntam ao AuthenticationStateProvider o estado atual.

Para disponibilizar esse estado para toda a sua árvore de componentes, o Blazor fornece CascadingAuthenticationState. Você normalmente envolve seu roteador com ele em App.razor ou em seu layout:

<CascadingAuthenticationState>
 <Router AppAssembly="@typeof(App).Assembly">
 <Found Context="routeData">
 <AuthorizeRouteView RouteData="@routeData"
 DefaultLayout="@typeof(MainLayout)">
 <NotAuthorized>
 <p>You're not authorized to view this page.</p>
 </NotAuthorized>
 </AuthorizeRouteView>
 </Found>
 <NotFound>
 <LayoutView Layout="@typeof(MainLayout)">
 <p>Page not found.</p>
 </LayoutView>
 </NotFound>
 </Router>
</CascadingAuthenticationState>

O AuthorizeRouteView está cumprindo uma função dupla aqui: verifica se o usuário está autenticado e autorizado antes de renderizar o componente da página correspondente e fornece uma UI substituta quando não está.

No .NET 8 e posterior com o modelo Blazor unificado, você configurará isso em seu App.razor e a estrutura manipulará o parâmetro em cascata automaticamente quando você usar AddCascadingAuthenticationState() em seu registro de serviço.

Integração de identidade ASP.NET

Para a maioria dos projetos, você não precisa criar a autenticação do zero. O ASP.NET Identity oferece gerenciamento de usuários, hash de senha, autenticação de dois fatores e confirmação de conta prontos para uso.A configuração com o Blazor começa em Program.cs:

builder.Services.AddDbContext<ApplicationDbContext>(options =>
 options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddDefaultIdentity<IdentityUser>(options =>
 {
 options.SignIn.RequireConfirmedAccount = true;
 options.Password.RequireDigit = true;
 options.Password.RequiredLength = 8;
 })
 .AddRoles<IdentityRole>()
 .AddEntityFrameworkStores<ApplicationDbContext>();

builder.Services.AddAuthentication(options =>
 {
 options.DefaultScheme = IdentityConstants.ApplicationScheme;
 options.DefaultSignInScheme = IdentityConstants.ExternalScheme;
 });

Com o modelo Blazor Web App no .NET 8+, a UI de identidade com scaffolding usa componentes Razor diretamente. Você obtém páginas de login, registro e gerenciamento de contas que se integram naturalmente ao restante do seu aplicativo Blazor - chega de mistura estranha de Razor Pages e componentes Blazor.

O ApplicationDbContext herda de IdentityDbContext e você precisará executar migrações para criar as tabelas de identidade:

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
 public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
 : base(options) { }
}

dotnet ef migrations add InitialIdentity
dotnet ef database update

O componente AuthorizeView

Depois que o estado de autenticação estiver fluindo pela sua árvore de componentes, AuthorizeView permite renderizar a UI condicionalmente:

<AuthorizeView>
 <Authorized>
 <p>Welcome, @context.User.Identity?.Name!</p>
 <a href="/account/manage">Manage Account</a>
 <form method="post" action="/account/logout">
 <button type="submit">Log Out</button>
 </form>
 </Authorized>
 <NotAuthorized>
 <a href="/account/login">Log In</a>
 <a href="/account/register">Register</a>
 </NotAuthorized>
</AuthorizeView>

O parâmetro context dentro de <Authorized> dá acesso ao AuthenticationState, para que você possa inspecionar declarações, funções e a identidade do usuário diretamente em sua marcação.

Você também pode usar AuthorizeView com funções e políticas:

<AuthorizeView Roles="Admin,Moderator">
 <Authorized>
 <button @onclick="DeletePost">Delete Post</button>
 </Authorized>
</AuthorizeView>

<AuthorizeView Policy="CanEditArticles">
 <Authorized>
 <button @onclick="EditArticle">Edit</button>
 </Authorized>
</AuthorizeView>

Uma coisa a ter em mente: AuthorizeView é uma preocupação da interface do usuário. Oculta ou mostra elementos, mas não protege a lógica subjacente. Se alguém puder chamar seu endpoint de API ou invocar seu método diretamente, ele ignorará AuthorizeView completamente. Sempre imponha a autorização também no lado do servidor.

O atributo [Autorizar]

Para proteger uma página inteira, aplique o atributo [Authorize]:

@page "/admin/dashboard"
@attribute [Authorize(Roles = "Admin")]

<h1>Admin Dashboard</h1>
<p>Only administrators can see this page.</p>

Quando um usuário não autenticado navega para esta página, o AuthorizeRouteView entra em ação e renderiza o modelo <NotAuthorized> que você definiu anteriormente. Você pode redirecionar para uma página de login lidando com o caso NotAuthorized com navegação:

<NotAuthorized>
 @if (!context.User.Identity?.IsAuthenticated ?? true)
 {
 <RedirectToLogin />
 }
 else
 {
 <p>You don't have permission to access this page.</p>
 }
</NotAuthorized>

Um componente RedirectToLogin simples pode ser parecido com:

@inject NavigationManager Navigation

@code {
 protected override void OnInitialized()
 {
 var returnUrl = Uri.EscapeDataString(Navigation.Uri);
 Navigation.NavigateTo($"/account/login?returnUrl={returnUrl}", forceLoad: true);
 }
}

O forceLoad: true é importante aqui - você deseja uma navegação HTTP real para que o middleware de autenticação do lado do servidor possa lidar com o fluxo de login corretamente.

Autorização baseada em funções e políticas

As funções são o modelo mais simples: atribua usuários a grupos como “Administrador” ou “Editor” e verifique a associação. Mas as políticas oferecem muito mais flexibilidade.

Registre políticas em Program.cs:

builder.Services.AddAuthorizationCore(options =>
{
 options.AddPolicy("CanPublish", policy =>
 policy.RequireClaim("Permission", "Publish"));

 options.AddPolicy("MinimumAge", policy =>
 policy.Requirements.Add(new MinimumAgeRequirement(18)));

 options.AddPolicy("PremiumUser", policy =>
 policy.RequireRole("Premium")
 .RequireClaim("Subscription", "Active"));
});

Os requisitos personalizados precisam de um manipulador:

public class MinimumAgeRequirement : IAuthorizationRequirement
{
 public int MinimumAge { get; }
 public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
}

public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
 protected override Task HandleRequirementAsync(
 AuthorizationHandlerContext context,
 MinimumAgeRequirement requirement)
 {
 var dateOfBirthClaim = context.User.FindFirst("DateOfBirth");

 if (dateOfBirthClaim is null)
 return Task.CompletedTask;

 var dateOfBirth = DateOnly.Parse(dateOfBirthClaim.Value);
 var age = DateOnly.FromDateTime(DateTime.Today).Year - dateOfBirth.Year;

 if (age >= requirement.MinimumAge)
 context.Succeed(requirement);

 return Task.CompletedTask;
 }
}

Registre o manipulador:

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

Nos componentes, você também pode verificar a autorização programaticamente quando precisar de lógica dinâmica:

@inject IAuthorizationService AuthorizationService
@inject AuthenticationStateProvider AuthStateProvider

@code {
 private bool canPublish;

 protected override async Task OnInitializedAsync()
 {
 var authState = await AuthStateProvider.GetAuthenticationStateAsync();
 var result = await AuthorizationService.AuthorizeAsync(
 authState.User, "CanPublish");
 canPublish = result.Succeeded;
 }
}

Provedores OAuth externos

O suporte para “Fazer login com o Google” ou “Fazer login com GitHub” é simples com o middleware de autenticação ASP.NET. Eles são configurados no lado do servidor, pois o fluxo OAuth requer redirecionamentos HTTP.

builder.Services.AddAuthentication()
 .AddGoogle(options =>
 {
 options.ClientId = builder.Configuration["Auth:Google:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Google:ClientSecret"]!;
 options.Scope.Add("profile");
 })
 .AddMicrosoftAccount(options =>
 {
 options.ClientId = builder.Configuration["Auth:Microsoft:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Microsoft:ClientSecret"]!;
 })
 .AddGitHub(options =>
 {
 options.ClientId = builder.Configuration["Auth:GitHub:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:GitHub:ClientSecret"]!;
 });

Para GitHub, você precisará do pacote AspNet.Security.OAuth.GitHub NuGet, pois ele não está incluído nas bibliotecas ASP.NET padrão.

A IU de login fornece links que acionam o desafio externo:

@page "/account/external-login"

<h2>Sign in with an external provider</h2>

<form method="post" action="/api/auth/external-login">
 <button type="submit" name="provider" value="Google">
 Sign in with Google
 </button>
 <button type="submit" name="provider" value="Microsoft">
 Sign in with Microsoft
 </button>
 <button type="submit" name="provider" value="GitHub">
 Sign in with GitHub
 </button>
</form>

O endpoint da API aciona o desafio e lida com o retorno de chamada:

app.MapPost("/api/auth/external-login", (string provider, HttpContext context) =>
{
 var properties = new AuthenticationProperties
 {
 RedirectUri = "/api/auth/external-callback"
 };
 return Results.Challenge(properties, [provider]);
});

A autenticação externa no Blazor sempre requer uma navegação de página inteira – você não pode concluir um redirecionamento OAuth dentro de um circuito SignalR ou de um aplicativo WebAssembly sem passar pelo servidor.

Autenticação baseada em token no Blazor WebAssemblyO Blazor WebAssembly é executado no cliente, portanto, a autenticação baseada em cookies não se aplica da mesma maneira. Em vez disso, normalmente você usa JWTs armazenados na memória e anexados a solicitações HTTP de saída.

A estrutura fornece AuthorizationMessageHandler para anexar tokens automaticamente:

builder.Services.AddHttpClient("API",
 client => client.BaseAddress = new Uri("https://api.example.com"))
 .AddHttpMessageHandler<AuthorizationMessageHandler>();

builder.Services.AddScoped(sp =>
 sp.GetRequiredService<IHttpClientFactory>().CreateClient("API"));

Para aplicativos Blazor WASM autônomos que são autenticados em sua própria API, você implementará um AuthenticationStateProvider personalizado que analisa o JWT:

public class JwtAuthenticationStateProvider : AuthenticationStateProvider
{
 private readonly ILocalStorageService _localStorage;
 private readonly HttpClient _httpClient;

 public JwtAuthenticationStateProvider(
 ILocalStorageService localStorage,
 HttpClient httpClient)
 {
 _localStorage = localStorage;
 _httpClient = httpClient;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var token = await _localStorage.GetItemAsync<string>("authToken");

 if (string.IsNullOrWhiteSpace(token))
 return new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()));

 _httpClient.DefaultRequestHeaders.Authorization =
 new AuthenticationHeaderValue("Bearer", token);

 var claims = ParseClaimsFromJwt(token);
 var identity = new ClaimsIdentity(claims, "jwt");

 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void NotifyAuthStateChanged()
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 private IEnumerable<Claim> ParseClaimsFromJwt(string jwt)
 {
 var payload = jwt.Split('.')[1];

 var padded = payload.Length % 4 switch
 {
 2 => payload + "==",
 3 => payload + "=",
 _ => payload
 };

 var bytes = Convert.FromBase64String(padded);
 var json = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(bytes);

 return json?.Select(kvp => new Claim(kvp.Key, kvp.Value.ToString()))
 ?? Enumerable.Empty<Claim>();
 }
}

Após um login bem-sucedido, você armazena o token e notifica o estado de autenticação:

public class AuthService
{
 private readonly HttpClient _httpClient;
 private readonly ILocalStorageService _localStorage;
 private readonly JwtAuthenticationStateProvider _authStateProvider;

 public AuthService(
 HttpClient httpClient,
 ILocalStorageService localStorage,
 AuthenticationStateProvider authStateProvider)
 {
 _httpClient = httpClient;
 _localStorage = localStorage;
 _authStateProvider = (JwtAuthenticationStateProvider)authStateProvider;
 }

 public async Task<bool> LoginAsync(string email, string password)
 {
 var response = await _httpClient.PostAsJsonAsync("/api/auth/login",
 new { Email = email, Password = password });

 if (!response.IsSuccessStatusCode)
 return false;

 var result = await response.Content
 .ReadFromJsonAsync<LoginResponse>();

 await _localStorage.SetItemAsync("authToken", result!.Token);
 _authStateProvider.NotifyAuthStateChanged();

 return true;
 }

 public async Task LogoutAsync()
 {
 await _localStorage.RemoveItemAsync("authToken");
 _authStateProvider.NotifyAuthStateChanged();
 }
}

Uma palavra de cautela: armazenar JWTs em localStorage os expõe a ataques XSS. Para aplicativos de maior segurança, considere manter os tokens apenas na memória e usar tokens de atualização ou adotar o padrão Backend-for-Frontend (BFF), onde o servidor gerencia tokens e o cliente usa cookies somente HTTP.

Blazor Server vs. WebAssembly: considerações de segurança

O modelo de hospedagem muda fundamentalmente sua postura de segurança.

Blazor Server mantém toda a lógica do seu componente no servidor. O cliente só vê diferenças de HTML renderizadas no SignalR. Isso significa:

A lógica sensível nunca sai do servidor
Você pode acessar bancos de dados e serviços internos diretamente dos componentes
O estado de autenticação vem do HttpContext do servidor na conexão inicial
O circuito pode sobreviver ao cookie de autenticação — se o cookie de um usuário expirar, o circuito permanecerá ativo até ser desconectado
Você deve lidar com a desconexão do circuito normalmente e revalidar o estado de autenticação na reconexão

Blazor WebAssembly é executado inteiramente no navegador. Isso significa:

Todo o código do seu componente pode ser baixado e inspecionado
Nunca coloque segredos, cadeias de conexão ou lógica de negócios confidenciais em componentes WASM
A autenticação só é aplicada no cliente para UX; a aplicação real deve acontecer na sua camada API
O gerenciamento de tokens é de sua responsabilidade
Considere usar o modelo hospedado onde um projeto de servidor lida com autenticação e atende o aplicativo WASM

Um padrão que recomendo para aplicativos WebAssembly é tratar cada componente como se fosse uma “UI não confiável” e cada endpoint de API como se estivesse sendo chamado por um cliente desconhecido. Valide tudo do lado do servidor, independentemente do que o cliente verifique.

Construindo um AuthenticationStateProvider personalizado

Às vezes, os provedores integrados não se adaptam à sua arquitetura. Talvez você esteja integrando um sistema de autenticação legado ou precise pesquisar alterações no estado de autenticação. Aqui está um provedor personalizado mais completo para Blazor Server:

public class CustomAuthStateProvider : AuthenticationStateProvider
{
 private readonly IHttpContextAccessor _httpContextAccessor;
 private readonly IUserService _userService;

 public CustomAuthStateProvider(
 IHttpContextAccessor httpContextAccessor,
 IUserService userService)
 {
 _httpContextAccessor = httpContextAccessor;
 _userService = userService;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var httpContext = _httpContextAccessor.HttpContext;

 if (httpContext?.User?.Identity?.IsAuthenticated != true)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var userId = httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier);

 if (userId is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var user = await _userService.GetUserWithClaimsAsync(userId);

 if (user is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var claims = new List<Claim>
 {
 new(ClaimTypes.NameIdentifier, user.Id),
 new(ClaimTypes.Name, user.DisplayName),
 new(ClaimTypes.Email, user.Email)
 };

 claims.AddRange(user.Roles.Select(r => new Claim(ClaimTypes.Role, r)));
 claims.AddRange(user.Permissions.Select(p => new Claim("Permission", p)));

 var identity = new ClaimsIdentity(claims, "Custom");
 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void MarkUserAsAuthenticated(string userId)
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 public void MarkUserAsLoggedOut()
 {
 var anonymous = new ClaimsPrincipal(new ClaimsIdentity());
 var authState = Task.FromResult(new AuthenticationState(anonymous));
 NotifyAuthenticationStateChanged(authState);
 }
}

Registre-o em Program.cs:

builder.Services.AddScoped<AuthenticationStateProvider, CustomAuthStateProvider>();
builder.Services.AddScoped<CustomAuthStateProvider>();

O principal insight aqui é NotifyAuthenticationStateChanged - chamá-lo aciona o parâmetro em cascata para atualização, que reavalia cada AuthorizeView e AuthorizeRouteView em sua árvore de componentes. É assim que você faz a UI reagir aos eventos de login/logout sem uma atualização completa da página.

Armadilhas e soluções comuns

Depois de trabalhar com autenticação do Blazor em muitos projetos, aqui estão os problemas que vejo com mais frequência:

1. Usando HttpContext nos componentes do servidor Blazor`HttpContext` está disponível durante a solicitação HTTP inicial, mas é `null` ou obsoleto durante as interações do SignalR. Não injete `IHttpContextAccessor` em componentes executados após a renderização inicial.

Solução: capture o que você precisa de HttpContext durante a inicialização e armazene-o em um serviço com escopo definido:

public class UserContext
{
 public string? UserId { get; set; }
 public string? AccessToken { get; set; }
}

// In a component that renders during the initial HTTP request:
@inject IHttpContextAccessor HttpContextAccessor
@inject UserContext UserContext

@code {
 protected override void OnInitialized()
 {
 var context = HttpContextAccessor.HttpContext;
 UserContext.UserId = context?.User.FindFirstValue(ClaimTypes.NameIdentifier);
 UserContext.AccessToken = context?.Request.Headers.Authorization
 .ToString().Replace("Bearer ", "");
 }
}

Você chama sua API de login, ela é bem-sucedida, mas a IU ainda mostra “Log In”.

Solução: Você deve chamar NotifyAuthenticationStateChanged em seu AuthenticationStateProvider depois que o estado de autenticação for alterado. A estrutura não detecta magicamente que um token foi armazenado ou um cookie foi definido.

3. Atributo de autorização que não funciona em componentes

Você adiciona [Authorize] a um componente, mas ele não bloqueia usuários não autenticados.

Solução: Certifique-se de usar AuthorizeRouteView em vez de RouteView simples em seu App.razor. O padrão RouteView ignora totalmente os atributos de autorização.

4. A pré-renderização quebra o estado de autenticação

Durante a pré-renderização do lado do servidor no Blazor WebAssembly, não há token de autenticação disponível. Os componentes são renderizados como não autenticados e, em seguida, passam para o estado autenticado após o carregamento do WASM.

Solução: desative a pré-renderização para páginas sensíveis à autenticação com @rendermode InteractiveWebAssembly (sem pré-renderização) ou administre o estado de carregamento normalmente:

<AuthorizeView>
 <Authorized>
 <p>Welcome back, @context.User.Identity?.Name</p>
 </Authorized>
 <Authorizing>
 <p>Loading...</p>
 </Authorizing>
 <NotAuthorized>
 <a href="/login">Sign in</a>
 </NotAuthorized>
</AuthorizeView>

5. Expiração de token em circuitos de longa duração

Os circuitos do Blazor Server podem permanecer ativos por horas. Se o seu token ou sessão expirar, o usuário permanecerá “autenticado” na IU, mas as chamadas de API começarão a falhar.

Solução: implemente uma verificação periódica ou use um RevalidatingServerAuthenticationStateProvider:

public class RevalidatingAuthStateProvider
 : RevalidatingServerAuthenticationStateProvider
{
 private readonly IServiceScopeFactory _scopeFactory;

 public RevalidatingAuthStateProvider(
 ILoggerFactory loggerFactory,
 IServiceScopeFactory scopeFactory)
 : base(loggerFactory)
 {
 _scopeFactory = scopeFactory;
 }

 protected override TimeSpan RevalidationInterval => TimeSpan.FromMinutes(30);

 protected override async Task<bool> ValidateAuthenticationStateAsync(
 AuthenticationState authenticationState, CancellationToken cancellationToken)
 {
 await using var scope = _scopeFactory.CreateAsyncScope();
 var userManager = scope.ServiceProvider
 .GetRequiredService<UserManager<IdentityUser>>();

 var user = await userManager.GetUserAsync(authenticationState.User);
 return user is not null;
 }
}

Isso valida que o usuário ainda existe (e seu carimbo de segurança não mudou) a cada 30 minutos.

Conclusão

A autenticação e a autorização no Blazor exigem uma mudança de pensamento em relação ao ASP.NET tradicional de solicitação e resposta. A abstração AuthenticationStateProvider é a chave para entender como tudo se encaixa - uma vez que você internaliza isso, o resto segue naturalmente.

Para a maioria dos aplicativos, comece com o ASP.NET Identity e os modelos integrados. Eles lidam com o trabalho pesado de gerenciamento de usuários, hash de senha e geração de token. Adicione políticas e autorização baseada em declarações à medida que seus requisitos aumentam. Adicione provedores OAuth externos quando seus usuários esperarem.

O modelo de hospedagem é importante: o Blazor Server oferece uma postura de segurança mais tradicional, onde o código permanece no servidor, enquanto o WebAssembly leva você a pensar primeiro na API, onde o cliente não é confiável por design. Nenhum deles é inerentemente mais seguro – eles apenas têm modelos de ameaças diferentes.

Qualquer que seja a abordagem escolhida, lembre-se da regra de ouro: a autorização na UI é para a experiência do usuário, a autorização no servidor é para segurança. Sempre aplique ambas.

JavaScript isolado no Blazor com arquivos JS colocados

Wed, 18 Jun 2025 00:00:00 +0000

Se você já trabalhou com Blazor e JS Interop antes, provavelmente acabou com um enorme arquivo app.js cheio de funções aleatórias para diferentes componentes. Funciona, mas fica confuso rapidamente. Felizmente, existe uma abordagem muito mais limpa: arquivos JavaScript colocados.

A ideia

Assim como o isolamento CSS, o Blazor permite colocar um arquivo .razor.js próximo ao seu componente. O módulo JavaScript é carregado sob demanda, somente quando o componente realmente precisa dele. Sem scripts globais, sem poluição.

#Configurando

Digamos que temos um componente Clipboard.razor que copia texto para a área de transferência. Crie um arquivo chamado Clipboard.razor.js ao lado dele:

export function copyToClipboard(text) {
 navigator.clipboard.writeText(text).then(() => {
 console.log("Copied to clipboard!");
 });
}

Observe a palavra-chave export - isso é importante. Blazor carrega-o como um módulo ES padrão.

Carregando o módulo no Blazor

No seu componente, você usa IJSRuntime para importar o módulo. O caminho segue uma convenção: ./_content/{ASSEMBLY_NAME}/{COMPONENT_PATH}.razor.js para bibliotecas, ou apenas o caminho relativo para o projeto atual.

@inject IJSRuntime JS
@implements IAsyncDisposable

<button @onclick="Copy">Copy to clipboard</button>

@code {
 [Parameter]
 public string Text { get; set; }

 private IJSObjectReference? module;

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 module = await JS.InvokeAsync<IJSObjectReference>(
 "import", "./Components/Clipboard.razor.js");
 }
 }

 private async Task Copy()
 {
 if (module is not null)
 {
 await module.InvokeVoidAsync("copyToClipboard", Text);
 }
 }

 public async ValueTask DisposeAsync()
 {
 if (module is not null)
 {
 await module.DisposeAsync();
 }
 }
}

Algumas coisas a serem observadas aqui:

Carregamos o módulo em OnAfterRenderAsync porque JS Interop não está disponível durante a pré-renderização do lado do servidor
Mantemos uma referência ao módulo com IJSObjectReference
Implementamos IAsyncDisposable para limpar o módulo quando o componente é destruído

Por que isso é melhor

Antes, eu costumava despejar tudo em um único wwwroot/js/app.js. Funcionou, mas encontrar funções era uma tarefa difícil, e cada página carregava JavaScript desnecessário. Com arquivos JS colocados:

Cada componente possui seu próprio JavaScript
Os módulos são carregados lentamente, somente quando necessário
Sem conflitos de nomes de funções globais
Mais fácil de manter e excluir — ao excluir o componente, você exclui o JS com ele

Uma pegadinha com o caminho

O caminho que você passa para import depende se você está em um aplicativo Blazor independente ou em uma biblioteca de classes Razor. Para um aplicativo Blazor normal, o caminho é relativo a wwwroot. O arquivo .razor.js é copiado lá no momento da construção, então você faz referência a ele a partir do local do componente no projeto.

Se você receber um 404 ao carregar o módulo, verifique novamente o caminho e certifique-se de que o arquivo termine em .razor.js, não apenas em .js.

Espero que você tenha gostado da postagem! Sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca.

Recursos

ASP.NET Core Blazor JavaScript com JS colocado

Blazor Interatividade em .NET 9 e .NET 10: um guia completo

Sun, 15 Jun 2025 00:00:00 +0000

Se você tem criado aplicativos da web com o Blazor nos últimos anos, sabe que a estrutura já percorreu um caminho longo. O que começou como uma escolha entre Blazor Server e Blazor WebAssembly evoluiu para um modelo de renderização unificado e flexível que permite escolher a estratégia de interatividade certa para cada componente do seu aplicativo.

Com o .NET 8, obtivemos uma mudança fundamental: a introdução de modos de renderização e renderização estática no lado do servidor (SSR) como padrão. Agora, o .NET 9 e o .NET 10 baseiam-se nessa base com refinamentos que tornam a experiência do desenvolvedor mais suave e a experiência do usuário final mais rápida.

Nesta postagem, quero mostrar o quadro completo da interatividade do Blazor como está hoje: como funcionam os modos de renderização, o que o SSR de streaming traz para a mesa, como a navegação aprimorada e o manuseio de formulários mudam o jogo e o que há de novo nos lançamentos mais recentes. Se você está planejando um novo projeto do Blazor ou pensando em atualizar, este é o guia que eu gostaria de ter quando comecei a me aprofundar em tudo isso.

Uma rápida retrospectiva: como chegamos aqui

Antes do .NET 8, você precisava se comprometer com um modelo de hospedagem no nível do projeto. Blazor Server significava que tudo rodava no servidor por meio de uma conexão SignalR. Blazor WebAssembly significava que tudo rodava no navegador. Cada um tinha vantagens e desvantagens e misturá-las era doloroso.

O .NET 8 mudou o jogo ao introduzir um único modelo de projeto — o Blazor Web App — que unifica os dois modelos. O conceito principal é modos de renderização: você decide por componente como ele deve ser renderizado e onde a interatividade acontece. O padrão tornou-se SSR estático, o que significa que os componentes são renderizados no servidor e enviam HTML simples para o navegador – sem SignalR, sem WebAssembly, apenas HTML rápido.

O .NET 9 aperfeiçoou esses conceitos, melhorou a experiência do desenvolvedor e otimizou o desempenho. O .NET 10 vai além com melhor manipulação de reconexão, estado persistente do componente nos modos de renderização e melhorias na forma como o próprio script Blazor é entregue.

Vamos analisar tudo.

Modos de renderização no .NET 9

No coração do Blazor moderno está o conceito de modos de renderização. Existem quatro modos que você deve conhecer:

1. SSR estático (o padrão)

Quando você cria um novo Blazor Web App, os componentes são renderizados estaticamente no servidor por padrão. O servidor processa o componente Razor, gera HTML e o envia ao navegador. Não há conexão persistente, nem tempo de execução do WebAssembly – apenas solicitação/resposta tradicional.

Isso é perfeito para páginas com muito conteúdo, painéis que exibem principalmente dados ou qualquer página onde você não precise de interação em tempo real.

@page "/products"

<h1>Our Products</h1>

@foreach (var product in products)
{
 <div class="product-card">
 <h3>@product.Name</h3>
 <p>@product.Description</p>
 <span class="price">@product.Price.ToString("C")</span>
 </div>
}

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await ProductService.GetAllAsync();
 }
}

Esse componente é renderizado no servidor, produz HTML e pronto. Nenhuma conexão contínua. Carregamento inicial rápido, ótimo para SEO, uso mínimo de recursos do servidor.

2. Servidor InterativoQuando você precisar de interatividade em tempo real – manipulação de cliques em botões, processamento de entrada do usuário, atualização dinâmica da UI – você pode optar pelo modo Servidor Interativo. Isso estabelece uma conexão SignalR entre o navegador e o servidor, e as atualizações da IU acontecem por meio dessa conexão.

@page "/counter"
@rendermode InteractiveServer

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

A diretiva @rendermode InteractiveServer é suficiente. O componente é renderizado inicialmente no servidor e, em seguida, uma conexão SignalR é estabelecida para lidar com interações subsequentes. Seus manipuladores de eventos C# são executados no servidor e as diferenças da UI são enviadas para o navegador.

Quando usá-lo: Quando você precisa de interatividade, seus componentes precisam de acesso a recursos do lado do servidor (bancos de dados, APIs, sistemas de arquivos) e você deseja um carregamento inicial rápido, sem esperar o download do WebAssembly.

3. WebAssembly interativo

Se você deseja interatividade sem manter uma conexão com o servidor, o Interactive WebAssembly executa a lógica do componente diretamente no navegador usando o tempo de execução do .NET WebAssembly.

@page "/search"
@rendermode InteractiveWebAssembly

<h1>Product Search</h1>

<input @bind="searchTerm" @bind:event="oninput" placeholder="Search products..." />

@if (filteredProducts.Any())
{
 <ul>
 @foreach (var product in filteredProducts)
 {
 <li>@product.Name — @product.Price.ToString("C")</li>
 }
 </ul>
}

@code {
 private string searchTerm = string.Empty;
 private List<Product> allProducts = new();
 private IEnumerable<Product> filteredProducts => allProducts
 .Where(p => p.Name.Contains(searchTerm, StringComparison.OrdinalIgnoreCase));

 protected override async Task OnInitializedAsync()
 {
 allProducts = await Http.GetFromJsonAsync<List<Product>>("api/products") ?? new();
 }
}

A desvantagem: há um custo inicial de download para o tempo de execução do .NET e seus assemblies. Mas, uma vez carregado, o componente é executado inteiramente no navegador, sem viagens de ida e volta do servidor para interações da interface do usuário.

Quando usar: Para componentes altamente interativos onde a latência é importante (pense: editores de rich text, ferramentas de desenho, filtragem em tempo real), quando você deseja reduzir a carga do servidor ou quando está criando um aplicativo Web progressivo (PWA).

4. Automático Interativo

Este é o meio-termo pragmático e um dos meus recursos favoritos. O Interactive Auto começa com a renderização do lado do servidor via SignalR para o primeiro carregamento e, em seguida, baixa silenciosamente o tempo de execução do WebAssembly em segundo plano. Nas visitas subsequentes, o componente é executado no WebAssembly.

@page "/dashboard"
@rendermode InteractiveAuto

<h1>Dashboard</h1>

<DashboardWidget Title="Sales" Value="@salesTotal" />
<DashboardWidget Title="Users" Value="@activeUsers" />

<button @onclick="RefreshData">Refresh</button>

@code {
 private decimal salesTotal;
 private int activeUsers;

 protected override async Task OnInitializedAsync()
 {
 await RefreshData();
 }

 private async Task RefreshData()
 {
 var data = await DashboardService.GetSummaryAsync();
 salesTotal = data.SalesTotal;
 activeUsers = data.ActiveUsers;
 }
}

Isso oferece o melhor dos dois mundos: primeira renderização rápida (sem espera pelo download do WASM) e, eventualmente, o componente é executado no lado do cliente. O usuário não percebe a transição.

Quando usar: Quando você deseja carregamentos iniciais rápidos e eventual execução no lado do cliente. É uma ótima opção padrão para muitos componentes interativos.

Streaming SSR: o melhor dos dois mundos

Streaming SSR é um daqueles recursos que parece simples, mas faz uma enorme diferença no desempenho percebido. A ideia é a seguinte: em vez de esperar que todos os seus dados sejam carregados antes de enviar qualquer HTML, o servidor envia o shell da página imediatamente e então transmite atualizações de conteúdo à medida que os dados ficam disponíveis.

@page "/reports"
@attribute [StreamRendering]

<h1>Monthly Reports</h1>

@if (reports is null)
{
 <div class="loading-spinner">
 <p>Loading reports...</p>
 </div>
}
else
{
 <table class="table">
 <thead>
 <tr>
 <th>Month</th>
 <th>Revenue</th>
 <th>Growth</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var report in reports)
 {
 <tr>
 <td>@report.Month</td>
 <td>@report.Revenue.ToString("C")</td>
 <td class="@(report.Growth >= 0 ? "text-success" : "text-danger")">
 @report.Growth.ToString("P1")
 </td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private List<MonthlyReport>? reports;

 protected override async Task OnInitializedAsync()
 {
 // This might take a couple of seconds
 reports = await ReportService.GetMonthlyReportsAsync();
 }
}

Com o atributo [StreamRendering], eis o que acontece:

O servidor envia imediatamente o HTML com o botão giratório de carregamento.
OnInitializedAsync executa e busca os dados.
Quando os dados chegam, o servidor transmite o HTML atualizado (a tabela) para o navegador.
O navegador corrige o DOM sem recarregar a página inteira.

O usuário vê a página instantaneamente com um indicador de carregamento e, em seguida, o conteúdo é preenchido. Não é necessária nenhuma estrutura JavaScript. Nenhuma conexão WebSocket. Apenas um uso inteligente de streaming HTTP.Quando usar: Qualquer página SSR estática que busca dados durante a renderização. Páginas de listagem de produtos, painéis, relatórios – em qualquer lugar onde o carregamento inicial de dados possa levar mais do que algumas centenas de milissegundos.

Quando NÃO usar: Se os dados forem carregados extremamente rápido (menos de 100 ms), a sobrecarga de streaming não vale a pena. Além disso, o streaming SSR não oferece interatividade contínua – para isso, você ainda precisa de um modo de renderização interativo.

Navegação aprimorada e tratamento de formulários

Uma das melhorias sutis, mas poderosas, no Blazor moderno é a navegação aprimorada. Por padrão, o Blazor intercepta cliques em links internos e envios de formulários, buscando o conteúdo da nova página via fetch e corrigindo o DOM em vez de fazer uma navegação completa no navegador.

Isso significa que navegar entre páginas SSR estáticas parece um SPA – sem flash de página inteira, a posição de rolagem pode ser preservada e a experiência é suave como a seda.

Como funciona

Quando o script Blazor (blazor.web.js) é carregado, ele intercepta automaticamente cliques em links internos. Em vez de uma navegação de navegador tradicional, ele:

Faz uma solicitação fetch para o URL de destino.
Recebe a resposta HTML.
Mescla o novo conteúdo no DOM existente.
Atualiza o URL e o histórico do navegador.

Você não precisa fazer nada para ativar isso – ele está ativado por padrão. Mas você pode controlá-lo:

<!-- Disable enhanced navigation for a specific link -->
<a href="/legacy-page" data-enhance-nav="false">Legacy Page</a>

<!-- Force a full page reload for external-like behavior -->
<a href="/downloads/report.pdf" data-enhance-nav="false">Download Report</a>

Manipulação aprimorada de formulários

Os formulários recebem o mesmo tratamento. Quando você usa EditForm ou o elemento padrão <form> com o tratamento de formulário do Blazor, os envios são interceptados e tratados via fetch:

@page "/contact"

<EditForm Model="contactModel" OnValidSubmit="HandleSubmit" FormName="contact" Enhance>
 <DataAnnotationsValidator />

 <div class="mb-3">
 <label for="name">Name</label>
 <InputText id="name" @bind-Value="contactModel.Name" class="form-control" />
 <ValidationMessage For="() => contactModel.Name" />
 </div>

 <div class="mb-3">
 <label for="email">Email</label>
 <InputText id="email" @bind-Value="contactModel.Email" class="form-control" />
 <ValidationMessage For="() => contactModel.Email" />
 </div>

 <div class="mb-3">
 <label for="message">Message</label>
 <InputTextArea id="message" @bind-Value="contactModel.Message" class="form-control" />
 <ValidationMessage For="() => contactModel.Message" />
 </div>

 <button type="submit" class="btn btn-primary">Send</button>
</EditForm>

@code {
 [SupplyParameterFromForm]
 private ContactModel contactModel { get; set; } = new();

 private async Task HandleSubmit()
 {
 await ContactService.SubmitAsync(contactModel);
 contactModel = new ContactModel();
 }
}

O atributo Enhance em EditForm diz ao Blazor para interceptar o envio do formulário. O formulário é enviado para o servidor, o servidor o processa e renderiza novamente a página, e o HTML atualizado é transmitido de volta – tudo sem uma navegação de página inteira. Parece interativo, mas é totalmente renderizado pelo servidor.

Observe o atributo [SupplyParameterFromForm] - é assim que o Blazor vincula os dados do formulário postado ao seu modelo em cenários de SSR estáticos. É a ponte entre as postagens de formulário tradicionais e o modelo de componentes do Blazor.

Interatividade por página e por componente

Um dos aspectos mais poderosos do novo modelo é que você pode misturar modos de renderização em um único aplicativo. Sua página de listagem de produtos pode ser SSR estático, seu carrinho de compras pode ser Interactive Server e seu configurador de produto pode ser Interactive WebAssembly - tudo no mesmo aplicativo.

Configurando modos de renderização no nível do componente

Você pode definir o modo de renderização diretamente em um componente usando a diretiva @rendermode:

@* This component is interactive via Server *@
@rendermode InteractiveServer

<h3>Live Chat</h3>
<!-- chat UI here -->

Ou você pode configurá-lo ao usar um componente de um pai:

@page "/product/{Id:int}"

<h1>@product?.Name</h1>
<p>@product?.Description</p>

<!-- This child component gets its own interactive render mode -->
<ProductConfigurator Product="product" @rendermode="InteractiveWebAssembly" />

<!-- This stays static -->
<ProductReviews ProductId="Id" />

@code {
 [Parameter] public int Id { get; set; }
 private Product? product;

 protected override async Task OnInitializedAsync()
 {
 product = await ProductService.GetByIdAsync(Id);
 }
}

Neste exemplo, a página em si é SSR estática. O componente ProductConfigurator é executado no WebAssembly para uma rica interatividade do lado do cliente. O componente ProductReviews permanece estático porque está apenas exibindo dados.

Configurando modos de renderização globalmente

Se quiser que todas as páginas sejam interativas por padrão, você pode definir o modo de renderização no nível raiz em App.razor:

<Routes @rendermode="InteractiveServer" />
```Isso torna cada página interativa por meio da renderização do servidor. Componentes individuais ainda podem substituir isso, se necessário.

### Regras importantes a serem lembradas

Existem algumas restrições a serem lembradas ao misturar modos de renderização:

- **Um componente filho não pode ter um modo de renderização "mais interativo" que seu pai.** Se um componente pai for estático, os filhos poderão ser estáticos ou interativos. Mas se um pai for Interactive Server, um filho não poderá ser Interactive WebAssembly (precisaria ser Server ou Auto).
- **Componentes interativos não podem usar diretamente serviços com escopo de pais estáticos.** Se um componente for executado no WebAssembly, ele não poderá acessar instâncias `DbContext` do lado do servidor diretamente — você precisará de uma camada de API.
- **O estado não é transferido automaticamente entre os modos de renderização.** Se um componente for pré-renderizado no servidor e depois alternar para o WebAssembly, você precisará lidar explicitamente com a persistência do estado — mais sobre isso na seção .NET 10.

## O que há de novo no .NET 10

O .NET 10 continua a abordagem de melhoria incremental, com foco na confiabilidade e na experiência do desenvolvedor. Aqui estão os destaques da interatividade do Blazor:

### Experiência de reconexão aprimorada

Se você usou o modo Servidor Interativo na produção, provavelmente encontrou a sobreposição de reconexão — aquele momento em que a conexão do SignalR cai e o usuário vê uma mensagem "Reconectando...". No .NET 10, essa experiência fica significativamente melhor.

A lógica de reconexão agora é mais inteligente para tentar novamente. Em vez de um intervalo fixo de novas tentativas, ele usa uma estratégia de espera que se adapta à situação. A IU durante a reconexão também é mais refinada e você tem ganchos melhores para personalizar a experiência:

```razor
<!-- In your App.razor or layout -->
<div id="components-reconnect-modal">
 <div class="reconnect-visible">
 <p>Connection lost. Attempting to reconnect...</p>
 <div class="spinner"></div>
 </div>
 <div class="reconnect-failed">
 <p>Could not reconnect to the server.</p>
 <button onclick="location.reload()">Reload</button>
 </div>
 <div class="reconnect-rejected">
 <p>Your session has expired.</p>
 <a href="/">Return to Home</a>
 </div>
</div>

A estrutura agora também tenta a reconexão de forma mais agressiva em falhas transitórias e pode restaurar o estado do circuito de forma mais confiável. Isso significa menos momentos do tipo “recarregue a página” para seus usuários.

Estado persistente do componente nos modos de renderização

Este é um grande problema. No .NET 9, quando um componente é pré-renderizado no servidor e depois faz a transição para o WebAssembly (ou alterna entre os modos de renderização), o estado do componente é perdido. O componente é reinicializado efetivamente, o que pode levar a buscas de dados duplicadas e intermitência na interface do usuário.

O .NET 10 melhora o serviço PersistentComponentState para funcionar de maneira mais integrada nas transições do modo de renderização:

@page "/weather"
@rendermode InteractiveWebAssembly
@inject PersistentComponentState ApplicationState

<h1>Weather Forecast</h1>

@if (forecasts is null)
{
 <p>Loading...</p>
}
else
{
 @foreach (var forecast in forecasts)
 {
 <div class="forecast-card">
 <h4>@forecast.Date.ToShortDateString()</h4>
 <p>@forecast.Summary — @forecast.TemperatureC°C</p>
 </div>
 }
}

@code {
 private List<WeatherForecast>? forecasts;
 private PersistingComponentStateSubscription persistingSubscription;

 protected override async Task OnInitializedAsync()
 {
 persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);

 if (!ApplicationState.TryTakeFromJson<List<WeatherForecast>>(
 "weather-forecasts", out var restored))
 {
 // Data wasn't persisted from prerendering — fetch it
 forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("api/weather");
 }
 else
 {
 forecasts = restored;
 }
 }

 private Task PersistData()
 {
 ApplicationState.PersistAsJson("weather-forecasts", forecasts);
 return Task.CompletedTask;
 }

 public void Dispose()
 {
 persistingSubscription.Dispose();
 }
}

Com as melhorias no .NET 10, esse padrão funciona de maneira mais confiável. O estado serializado durante a pré-renderização está adequadamente disponível quando o componente é inicializado em seu modo interativo, evitando buscas duplas de dados e a breve oscilação que os usuários podem ver.

Blazor Script como um ativo da Web estático

Nas versões anteriores, o arquivo Blazor JavaScript (blazor.web.js) era servido a partir do endpoint interno da estrutura. No .NET 10, ele é entregue como um ativo da Web estático. Isso pode parecer uma pequena mudança, mas traz benefícios práticos:- Melhor armazenamento em cache: os ativos estáticos da Web obtêm cabeçalhos de cache e URLs com impressão digital adequados, para que os navegadores os armazenem em cache com mais eficiência.

Compatível com CDN: Como é um arquivo estático regular, os CDNs podem armazená-lo em cache e servi-lo a partir de pontos de presença.
Compressão: A compactação estática de ativos da Web é aplicada automaticamente, reduzindo o tamanho do script na transmissão.

Você não precisa alterar a forma como faz referência a ele — a estrutura trata o caminho atualizado automaticamente.

Melhores práticas: escolhendo o modo de renderização correto

Depois de trabalhar com todos esses modos em vários projetos, aqui está minha estrutura de decisão:

Comece com SSR estático

Torne o SSR estático seu padrão. A maioria das páginas na maioria dos aplicativos trata principalmente da exibição de dados. Páginas de produtos, postagens de blog, perfis de usuário, páginas de configurações – não precisam de interatividade em tempo real. O SSR estático oferece o melhor desempenho, o menor uso de recursos e o modelo mental mais simples.

Adicione interatividade apenas quando necessário

Identifique os componentes específicos que precisam responder às interações do usuário em tempo real. Um botão “curtir”, um widget de bate-papo, uma interface de arrastar e soltar – tudo isso precisa de interatividade. Mas a página que os cerca provavelmente não.

Use o Interactive Auto como seu modo interativo preferido

Quando você precisa de interatividade, o Interactive Auto costuma ser a melhor opção padrão. Oferece carregamentos iniciais rápidos (renderização do servidor) com eventual execução no lado do cliente (WebAssembly). O usuário obtém o melhor dos dois mundos e você escreve seu código uma vez.

Reservar Servidor Interativo para Casos Específicos

Use o Servidor Interativo quando:

Seu componente precisa de acesso direto aos recursos do servidor (bancos de dados, sistema de arquivos, APIs internas).
O tamanho do download do WebAssembly é uma preocupação e você não pode usar o Auto.
Você precisa que o componente seja sempre executado no servidor por motivos de segurança (por exemplo, processamento de dados confidenciais).

Use streaming SSR generosamente

Se suas páginas SSR estáticas buscarem algum dado, adicione [StreamRendering]. O custo é mínimo e a melhoria de desempenho percebida é significativa. Os usuários veem o conteúdo aparecendo progressivamente, em vez de ficarem olhando para uma página em branco.

Lide com as transições de estado com cuidado

Se você estiver usando Interactive Auto ou misturando pré-renderização com WebAssembly, sempre use PersistentComponentState para evitar buscas de dados duplicadas. Seus usuários agradecerão pela ausência de conteúdo oscilante.

Mantenha a árvore de componentes em mente

Lembre-se das regras de hierarquia do modo de renderização. Planeje sua árvore de componentes para que os limites interativos façam sentido. Um padrão comum é ter um layout estático com “ilhas” interativas incorporadas quando necessário:

@* Layout: Static SSR *@
<header>
 <NavMenu />
 <UserMenu @rendermode="InteractiveServer" /> @* Needs real-time auth state *@
</header>

<main>
 @Body
</main>

<footer>
 <ChatWidget @rendermode="InteractiveAuto" /> @* Rich interactivity *@
</footer>

Conclusão

O modelo de interatividade do Blazor no .NET 9 e .NET 10 representa uma abordagem madura e bem pensada para a construção de aplicativos da web. A capacidade de escolher modos de renderização por componente, a navegação aprimorada e contínua, o SSR de streaming e as melhorias contínuas na reconexão e no gerenciamento de estado tornam-no uma escolha atraente para uma ampla gama de aplicações.A principal ideia é que a interatividade é um espectro, não uma escolha binária. A maior parte do seu aplicativo pode ser estática. Algumas partes precisam de interatividade orientada pelo servidor. Alguns podem se beneficiar da execução no navegador. O Blazor agora permite que você faça essa escolha com a granularidade mais fina — o componente individual — sem lutar contra a estrutura.

Se você estiver iniciando um novo projeto, meu conselho é simples: crie um Blazor Web App, comece com SSR estático, adicione [StreamRendering] a páginas com muitos dados e promova componentes individuais para modos interativos somente quando precisar deles. Você acabará com um aplicativo rápido, eficiente e bem dimensionável.

Boa codificação e, como sempre, fique à vontade para entrar em contato se tiver dúvidas!

APIs mínimas em .NET: criando APIs HTTP leves

Thu, 10 Apr 2025 00:00:00 +0000

Se você já cria APIs com ASP.NET Core há algum tempo, provavelmente está familiarizado com a abordagem baseada em controlador: crie uma classe de controlador, decore-a com atributos, injete seus serviços por meio do construtor e conecte suas rotas. Funciona, e funciona bem - mas às vezes parece que você está escrevendo muita cerimônia no que equivale a “aceitar este pedido, fazer algo, retornar uma resposta”.

Esse é exatamente o problema que as APIs mínimas pretendem resolver. Introduzidas no .NET 6, as APIs mínimas permitem definir pontos de extremidade HTTP com muito pouco padrão. Sem controladores, sem atributos, sem malabarismo com classes de inicialização — apenas mapeamentos diretos de rota para manipulador em um estilo limpo e funcional.

Nesta postagem, quero orientar você sobre tudo o que você precisa saber sobre APIs mínimas: desde o primeiro endpoint até a organização de grandes aplicativos, tratamento de autenticação, validação, documentos OpenAPI e considerações de desempenho. Vamos lá.

Por que APIs mínimas?

Antes de começarmos, vamos falar sobre por que você escolheria APIs mínimas em vez da abordagem tradicional baseada em controlador.

Controladores são ótimos quando você precisa de uma estrutura estruturada e opinativa. Eles fornecem vinculação de modelo, filtros, negociação de conteúdo e uma separação clara de preocupações prontas para uso. Para aplicações empresariais de grande porte com dezenas de desenvolvedores, a consistência imposta pelos controladores pode ser um benefício real.

APIs mínimas, por outro lado, brilham quando você deseja:

Menos clichê — sem classes de controlador, sem atributos [ApiController], sem configuração de inicialização separada.
Inicialização mais rápida — menos operações baseadas em reflexão no momento da inicialização.
Modelo mental mais simples — uma rota é mapeada diretamente para um manipulador. É isso.
Otimizado para microsserviços — quando sua API tem de 5 a 10 endpoints, uma configuração completa do controlador pode parecer um exagero.

A boa notícia é que esta não é uma decisão de um ou outro. Você pode misturar controladores e APIs mínimas no mesmo projeto. Mas quando você se sentir confortável com a abordagem mínima, poderá buscá-la com mais frequência do que esperava.

Primeiros passos

Vamos criar uma API Minimal do zero. Se você tiver o SDK do .NET instalado, é tão simples quanto:

dotnet new web -n MyMinimalApi
cd MyMinimalApi

Isso fornece um Program.cs parecido com isto:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

É isso. Essa é uma API funcional. Não Startup.cs, nenhuma classe de controlador, nenhuma configuração de roteamento. Você executa dotnet run, pressiona http://localhost:5000 e obtém “Olá, mundo!” voltar. A simplicidade aqui é o ponto principal.

Vamos torná-lo um pouco mais útil com uma API de tarefas clássica:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var todos = new List<Todo>();

app.MapGet("/todos", () => todos);

app.MapGet("/todos/{id:int}", (int id) =>
 todos.FirstOrDefault(t => t.Id == id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound());

app.MapPost("/todos", (Todo todo) =>
{
 todos.Add(todo);
 return Results.Created($"/todos/{todo.Id}", todo);
});

app.MapDelete("/todos/{id:int}", (int id) =>
{
 var todo = todos.FirstOrDefault(t => t.Id == id);
 if (todo is null) return Results.NotFound();
 todos.Remove(todo);
 return Results.NoContent();
});

app.Run();

record Todo(int Id, string Title, bool IsComplete);

Temos CRUD completo em menos de 30 linhas. Esse é o poder da abordagem mínima.

Manipuladores de rota

Manipuladores de rota são as funções executadas quando uma solicitação corresponde a uma rota. Você tem várias opções para defini-los.

Expressões Lambda

A abordagem mais comum e o que você verá na maioria dos exemplos:

app.MapGet("/hello", () => "Hello!");
app.MapGet("/hello/{name}", (string name) => $"Hello, {name}!");

Grupos de métodos

Para uma lógica mais complexa, você pode apontar para um método nomeado:

app.MapGet("/products", GetProducts);
app.MapPost("/products", CreateProduct);

static IResult GetProducts(AppDbContext db)
 => Results.Ok(db.Products.ToList());

static IResult CreateProduct(Product product, AppDbContext db)
{
 db.Products.Add(product);
 db.SaveChanges();
 return Results.Created($"/products/{product.Id}", product);
}
```Esta é minha abordagem preferida para qualquer coisa além de uma linha. Ele mantém sua seção de mapeamento de rotas limpa e legível – você pode ver rapidamente quais pontos de extremidade existem sem se aprofundar nos detalhes de implementação.

### Funções locais

Você também pode usar funções locais, o que é útil quando você deseja manter os manipuladores próximos às suas definições de rota:

```csharp
app.MapGet("/health", CheckHealth);

IResult CheckHealth()
{
 // Some health check logic
 return Results.Ok(new { Status = "Healthy", Timestamp = DateTime.UtcNow });
}

Associação de parâmetros

Uma das coisas que realmente aprecio nas APIs mínimas é como a vinculação de parâmetros é intuitiva. A estrutura descobre de onde extrair valores com base no contexto e no tipo.

Parâmetros de rota

app.MapGet("/users/{id:int}", (int id) => $"User {id}");
app.MapGet("/files/{*path}", (string path) => $"File: {path}"); // catch-all

Parâmetros de string de consulta

app.MapGet("/search", (string? query, int page = 1, int pageSize = 20) =>
 Results.Ok(new { query, page, pageSize }));

Tipos anuláveis tornam-se parâmetros opcionais. Os valores padrão funcionam exatamente como você espera.

Corpo da solicitação

app.MapPost("/orders", (Order order) =>
{
 // 'order' is automatically deserialized from the JSON body
 return Results.Created($"/orders/{order.Id}", order);
});

Cabeçalho e vinculação de serviço

app.MapGet("/protected", (
 [FromHeader(Name = "X-Api-Key")] string apiKey,
 [FromServices] ILogger<Program> logger) =>
{
 logger.LogInformation("Request with API key: {Key}", apiKey[..4] + "****");
 return Results.Ok("Authorized");
});

HttpContext e HttpRequest

Quando você precisar de acesso de nível inferior:

app.MapGet("/info", (HttpContext context) =>
{
 var userAgent = context.Request.Headers.UserAgent.ToString();
 var ip = context.Connection.RemoteIpAddress?.ToString();
 return Results.Ok(new { userAgent, ip });
});

Vinculação personalizada com BindAsync

Para tipos complexos, você pode implementar um método estático BindAsync:

public record PaginationParams(int Page, int PageSize)
{
 public static ValueTask<PaginationParams?> BindAsync(HttpContext context)
 {
 int.TryParse(context.Request.Query["page"], out var page);
 int.TryParse(context.Request.Query["pageSize"], out var pageSize);

 var result = new PaginationParams(
 Page: page > 0 ? page : 1,
 PageSize: pageSize > 0 ? Math.Min(pageSize, 100) : 20
 );

 return ValueTask.FromResult<PaginationParams?>(result);
 }
}

app.MapGet("/items", (PaginationParams pagination, AppDbContext db) =>
{
 var items = db.Items
 .Skip((pagination.Page - 1) * pagination.PageSize)
 .Take(pagination.PageSize)
 .ToList();

 return Results.Ok(items);
});

Isso é incrivelmente poderoso. Você define a lógica de ligação uma vez e a reutiliza em todos os seus endpoints.

Validação

Uma área em que as APIs mínimas não oferecem tanta coisa pronta para uso em comparação com os controladores é a validação de modelo. Não há aplicação automática de [Required] ou [StringLength]. Mas existem padrões claros para lidar com isso.

Validação manual

A abordagem mais simples — basta validar no manipulador:

app.MapPost("/users", (CreateUserRequest request) =>
{
 if (string.IsNullOrWhiteSpace(request.Email))
 return Results.BadRequest(new { Error = "Email is required" });

 if (request.Name?.Length > 100)
 return Results.BadRequest(new { Error = "Name must be 100 characters or less" });

 // Create user...
 return Results.Created($"/users/{request.Email}", request);
});

Usando uma biblioteca de validação

Para qualquer coisa não trivial, recomendo usar FluentValidation ou uma biblioteca semelhante:

public class CreateUserValidator : AbstractValidator<CreateUserRequest>
{
 public CreateUserValidator()
 {
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
 RuleFor(x => x.Age).InclusiveBetween(0, 150);
 }
}

Você pode conectar isso aos seus endpoints por meio de filtros de endpoint, o que nos leva à próxima seção.

Filtros de endpoint

Os filtros de endpoint são um dos melhores recursos das APIs mínimas. Pense neles como middleware, mas com escopo para endpoints específicos, em vez de todo o pipeline. Eles foram introduzidos no .NET 7 e são fantásticos para questões transversais.

Filtro Básico

app.MapPost("/todos", (Todo todo) =>
{
 // Handle the request
 return Results.Created($"/todos/{todo.Id}", todo);
})
.AddEndpointFilter(async (context, next) =>
{
 var todo = context.GetArgument<Todo>(0);

 if (string.IsNullOrEmpty(todo.Title))
 {
 return Results.BadRequest(new { Error = "Title is required" });
 }

 return await next(context);
});

Filtro de validação com FluentValidation

É aqui que tudo se torna realmente poderoso – um filtro de validação reutilizável:

public class ValidationFilter<T> : IEndpointFilter where T : class
{
 private readonly IValidator<T> _validator;

 public ValidationFilter(IValidator<T> validator)
 {
 _validator = validator;
 }

 public async ValueTask<object?> InvokeAsync(
 EndpointFilterInvocationContext context,
 EndpointFilterDelegate next)
 {
 var model = context.Arguments
 .OfType<T>()
 .FirstOrDefault();

 if (model is null)
 return Results.BadRequest(new { Error = "Request body is required" });

 var result = await _validator.ValidateAsync(model);

 if (!result.IsValid)
 {
 var errors = result.Errors
 .GroupBy(e => e.PropertyName)
 .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray());

 return Results.ValidationProblem(errors);
 }

 return await next(context);
 }
}

// Usage
app.MapPost("/users", (CreateUserRequest request) =>
{
 // Only reached if validation passes
 return Results.Created($"/users/{request.Email}", request);
})
.AddEndpointFilter<ValidationFilter<CreateUserRequest>>();

Filtro de registro

app.MapGet("/products", (AppDbContext db) => db.Products.ToList())
 .AddEndpointFilter(async (context, next) =>
 {
 var logger = context.HttpContext
 .RequestServices.GetRequiredService<ILogger<Program>>();

 var sw = Stopwatch.StartNew();
 var result = await next(context);
 sw.Stop();

 logger.LogInformation("Endpoint executed in {Elapsed}ms", sw.ElapsedMilliseconds);

 return result;
 });

Você pode encadear vários filtros e eles são executados na ordem em que são adicionados — assim como o middleware.

Integração OpenAPI/Swagger

Uma boa documentação de API não é mais opcional. Felizmente, as APIs Minimal têm suporte de primeira classe para OpenAPI por meio do pacote Microsoft.AspNetCore.OpenApi.

Configuração básica

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/todos", () => new List<Todo>())
 .WithName("GetTodos")
 .WithDescription("Retrieves all todo items")
 .WithTags("Todos");

app.Run();

Metadados avançados de endpoint

Você pode fornecer informações detalhadas sobre seus endpoints:

app.MapPost("/todos", (Todo todo) =>
{
 return Results.Created($"/todos/{todo.Id}", todo);
})
.WithName("CreateTodo")
.WithDescription("Creates a new todo item")
.WithTags("Todos")
.Accepts<Todo>("application/json")
.Produces<Todo>(StatusCodes.Status201Created)
.Produces(StatusCodes.Status400BadRequest)
.ProducesValidationProblem();

Usando WithOpenApi para personalização

Para controle refinado sobre o documento OpenAPI gerado:

app.MapGet("/todos/{id:int}", (int id) => Results.Ok(new Todo(id, "Sample", false)))
 .WithOpenApi(operation =>
 {
 operation.Summary = "Get a specific todo";
 operation.Description = "Retrieves a single todo item by its unique identifier.";
 operation.Parameters[0].Description = "The unique identifier of the todo item";
 return operation;
 });

Isso oferece o mesmo nível de controle de documentação que você obteria com os comentários XML do Swashbuckle nos controladores, mas de uma forma mais explícita, que prioriza o código.

Autenticação e Autorização

A proteção de endpoints mínimos da API segue os mesmos padrões do restante do ASP.NET Core — basta aplicá-los de maneira diferente.

Configuração básica```csharp

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = “https://your-identity-provider.com”; options.Audience = “your-api”; });

builder.Services.AddAuthorizationBuilder() .AddPolicy(“AdminOnly”, policy => policy.RequireRole(“Admin”)) .AddPolicy(“PremiumUser”, policy => policy.RequireClaim(“subscription”, “premium”));

var app = builder.Build();

app.UseAuthentication(); app.UseAuthorization();


### Aplicando autorização a endpoints

```csharp
// Require any authenticated user
app.MapGet("/profile", (ClaimsPrincipal user) =>
{
 return Results.Ok(new
 {
 Name = user.FindFirstValue(ClaimTypes.Name),
 Email = user.FindFirstValue(ClaimTypes.Email)
 });
}).RequireAuthorization();

// Require a specific policy
app.MapDelete("/admin/users/{id}", (int id) =>
{
 // Delete user logic
 return Results.NoContent();
}).RequireAuthorization("AdminOnly");

// Allow anonymous access
app.MapGet("/public/health", () => Results.Ok(new { Status = "Healthy" }))
 .AllowAnonymous();

Observe como você pode injetar ClaimsPrincipal diretamente nos parâmetros do seu manipulador — a estrutura cuida do resto. Essa é uma daquelas pequenas coisas que fazem as APIs Minimal parecerem realmente elegantes.

Organizando APIs grandes

O elefante na sala com APIs mínimas é a organização. Quando seu Program.cs tem 50 endpoints, fica uma bagunça. Aqui estão os padrões que uso para manter as coisas gerenciáveis.

Grupos de rotas

Os grupos de rotas (introduzidos no .NET 7) permitem compartilhar configurações entre endpoints relacionados:

var todos = app.MapGroup("/todos")
 .WithTags("Todos")
 .RequireAuthorization();

todos.MapGet("/", (AppDbContext db) => db.Todos.ToListAsync());
todos.MapGet("/{id:int}", (int id, AppDbContext db) => db.Todos.FindAsync(id));
todos.MapPost("/", (Todo todo, AppDbContext db) =>
{
 db.Todos.Add(todo);
 db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
});

Todos os endpoints do grupo compartilham o prefixo /todos, a tag Todos e o requisito de autorização. Limpar.

Métodos de extensão

Este é o padrão que realmente aumenta. Mova cada grupo de endpoints para sua própria classe estática:

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
 public static RouteGroupBuilder MapTodoEndpoints(this WebApplication app)
 {
 var group = app.MapGroup("/todos").WithTags("Todos");

 group.MapGet("/", GetAll);
 group.MapGet("/{id:int}", GetById);
 group.MapPost("/", Create);
 group.MapPut("/{id:int}", Update);
 group.MapDelete("/{id:int}", Delete);

 return group;
 }

 private static async Task<IResult> GetAll(AppDbContext db)
 => Results.Ok(await db.Todos.ToListAsync());

 private static async Task<IResult> GetById(int id, AppDbContext db)
 => await db.Todos.FindAsync(id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound();

 private static async Task<IResult> Create(Todo todo, AppDbContext db)
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 }

 private static async Task<IResult> Update(int id, Todo updated, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 todo.Title = updated.Title;
 todo.IsComplete = updated.IsComplete;
 await db.SaveChangesAsync();

 return Results.Ok(todo);
 }

 private static async Task<IResult> Delete(int id, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 db.Todos.Remove(todo);
 await db.SaveChangesAsync();

 return Results.NoContent();
 }
}

// Program.cs — stays clean
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapTodoEndpoints();
app.MapUserEndpoints();
app.MapOrderEndpoints();

app.Run();

Seu Program.cs se torna um índice para sua API. Cada grupo de endpoints reside em seu próprio arquivo. Esta é a abordagem que recomendo para aplicações de produção.

Biblioteca Carter

Se você quiser ainda mais estrutura, a biblioteca Carter oferece uma abordagem baseada em módulos:

public class TodoModule : ICarterModule
{
 public void AddRoutes(IEndpointRouteBuilder app)
 {
 app.MapGet("/todos", async (AppDbContext db) =>
 await db.Todos.ToListAsync());

 app.MapPost("/todos", async (Todo todo, AppDbContext db) =>
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 });
 }
}

Carter descobre e registra automaticamente todos os módulos. É um bom meio-termo entre a abordagem bruta da API Mínima e os controladores completos.

TypedResults e tipos de resposta

A partir do .NET 7, você pode usar TypedResults em vez de Results para respostas com segurança de tipo. Isso pode parecer uma pequena mudança, mas traz benefícios reais para a documentação e testabilidade do OpenAPI.

app.MapGet("/todos/{id:int}", async Task<Results<Ok<Todo>, NotFound>> (int id, AppDbContext db) =>
{
 var todo = await db.Todos.FindAsync(id);
 return todo is not null
 ? TypedResults.Ok(todo)
 : TypedResults.NotFound();
});

O tipo de retorno Results<Ok<Todo>, NotFound> informa explicitamente à estrutura (e aos seus documentos OpenAPI) exatamente quais tipos de resposta este endpoint pode produzir. Chega de suposições, chega de chamadas manuais Produces<>() para casos básicos.

Para vários resultados possíveis:

app.MapPost("/todos",
 async Task<Results<Created<Todo>, ValidationProblem, Conflict>>
 (Todo todo, AppDbContext db) =>
{
 if (string.IsNullOrEmpty(todo.Title))
 return TypedResults.ValidationProblem(
 new Dictionary<string, string[]>
 {
 { "Title", new[] { "Title is required" } }
 });

 if (await db.Todos.AnyAsync(t => t.Title == todo.Title))
 return TypedResults.Conflict();

 db.Todos.Add(todo);
 await db.SaveChangesAsync();

 return TypedResults.Created($"/todos/{todo.Id}", todo);
});

Comecei a usar TypedResults em todos os novos projetos. O compilador detecta incompatibilidades entre os tipos de retorno declarados e o que você realmente retorna, o que elimina uma classe inteira de surpresas em tempo de execução.

Considerações de desempenho

Um dos pontos de venda das APIs Minimal é o desempenho, e vale a pena entender por que elas são mais rápidas.

Sobrecarga de inicialização reduzida. Os controladores dependem muito da reflexão para descobrir endpoints, vincular modelos e aplicar filtros. APIs mínimas usam geradores de origem (a partir do .NET 7) para gerar código de ligação em tempo de compilação. Isso significa menos trabalho na inicialização e menos alocação de memória por solicitação.

Sem pipeline MVC. APIs baseadas em controlador passam por todo o pipeline MVC: seleção de ação, vinculação de modelo, filtros de ação, execução de resultados. APIs mínimas ignoram tudo isso e vão direto do roteamento para o seu manipulador.

Compilação RequestDelegate. A estrutura compila suas expressões lambda em instâncias RequestDelegate otimizadas. O código resultante é muito próximo do que você escreveria à mão se estivesse trabalhando diretamente com HttpContext.

Aqui estão algumas dicas práticas para maximizar o desempenho:

// Use AsNoTracking for read-only queries
app.MapGet("/products", async (AppDbContext db) =>
 await db.Products.AsNoTracking().ToListAsync());

// Return results directly — avoid unnecessary allocations
app.MapGet("/count", async (AppDbContext db) =>
 await db.Products.CountAsync());

// Use cancellation tokens for long-running operations
app.MapGet("/report", async (AppDbContext db, CancellationToken ct) =>
 await db.Orders
 .AsNoTracking()
 .GroupBy(o => o.Status)
 .Select(g => new { Status = g.Key, Count = g.Count() })
 .ToListAsync(ct));
```Também vale a pena mencionar que a lacuna de desempenho entre controladores e APIs mínimas continua diminuindo a cada versão do .NET. Para a maioria dos aplicativos, a diferença não será o gargalo, mas sim as consultas ao banco de dados e as chamadas de serviço externas. Escolha com base na experiência do desenvolvedor e nas necessidades do projeto, não em benchmarks.

## Conclusão

As APIs mínimas percorreram um longo caminho desde sua introdução no .NET 6. O que começou como um recurso de demonstração do tipo "olá mundo" amadureceu e se tornou uma escolha legítima para APIs de produção. Com filtros de endpoint, grupos de rotas, resultados digitados e suporte sólido a OpenAPI, você tem tudo o que precisa para criar serviços bem estruturados e de fácil manutenção.

Minha recomendação? Se você estiver iniciando um novo projeto de API — especialmente um microsserviço ou uma API interna focada — experimente seriamente as APIs Minimal. Use o padrão de método de extensão para organização, conte com filtros de endpoint para questões transversais e aproveite `TypedResults` para segurança de tipo.

Para projetos existentes baseados em controlador, não há pressa para migrar. Ambas as abordagens funcionam bem e você pode até usá-las lado a lado. Mas da próxima vez que você precisar adicionar um pequeno serviço ou uma API interna rápida, ignore os controladores e vá para o mínimo. Você pode não voltar.

Boa codificação!

Usando CSS isolado em componentes do Blazor

Wed, 12 Mar 2025 00:00:00 +0000

Uma coisa que sempre me incomodou ao trabalhar com o Blazor foi como era fácil quebrar acidentalmente estilos entre componentes. Você adicionava uma classe em um componente e, de repente, outra coisa em uma página completamente diferente parecia desativada. Acontece que o Blazor tem uma solução integrada para isso: isolamento CSS.

O que é isolamento CSS?

O isolamento CSS permite definir estilos para um componente específico. O Blazor faz isso gerando um atributo exclusivo para cada componente no momento da construção e anexando-o aos seletores CSS. Portanto, seus estilos se aplicam apenas ao componente ao qual pertencem.

Não há necessidade de nomenclatura BEM, nem de hacks malucos de especificidade. Apenas CSS limpo e com escopo definido.

#Como usar

Digamos que você tenha um componente chamado Card.razor:

<div class="card">
 <h3 class="card-title">@Title</h3>
 <p class="card-body">@ChildContent</p>
</div>

@code {
 [Parameter]
 public string Title { get; set; }

 [Parameter]
 public RenderFragment ChildContent { get; set; }
}

Para adicionar estilos isolados, basta criar um arquivo com o mesmo nome, mas com extensão .razor.css. Neste caso: Card.razor.css.

.card {
 border: 1px solid var(--color-border);
 border-radius: 8px;
 padding: 1rem;
 background: var(--color-bg-secondary);
}

.card-title {
 font-size: 1.1rem;
 font-weight: 600;
 margin-bottom: 0.5rem;
}

.card-body {
 color: var(--color-text-secondary);
 font-size: 0.9rem;
}

E é isso! O Blazor irá selecioná-lo automaticamente e definir o escopo desses estilos apenas para o componente Card. Se você tiver outra classe .card em outro lugar, ela não será afetada.

Como funciona nos bastidores

Quando você cria seu projeto, o Blazor reescreve o HTML e o CSS. Seu componente recebe um atributo exclusivo como b-3x8qz7k2f1, e os seletores CSS recebem esse atributo anexado:

.card[b-3x8qz7k2f1] {
 border: 1px solid var(--color-border);
 /* ... */
}

O pacote CSS gerado é servido como {ProjectName}.styles.css. Certifique-se de ter isso em seu index.html ou _Host.cshtml:

<link href="YourApp.styles.css" rel="stylesheet" />

Se você perder esse link, seus estilos isolados não aparecerão e você passará 30 minutos se perguntando o que está acontecendo. Confie em mim, eu estive lá.

Visando elementos filhos

Uma coisa a ter em mente é que, por padrão, o CSS isolado se aplica apenas aos elementos do componente atual. Se você deseja estilizar elementos dentro de um componente filho, você precisa do combinador ::deep:

::deep .child-element {
 color: red;
}

Isso diz ao Blazor para aplicar o estilo aos elementos correspondentes também nos componentes filhos. Muito útil quando você tem um componente wrapper que precisa estilizar seus filhos.

Quando usar

Eu uso isolamento CSS para praticamente todos os componentes agora. Isso mantém as coisas limpas e previsíveis. A única vez que não uso isso é para estilos verdadeiramente globais, como redefinições, tipografia ou variáveis de tema - elas vão em um arquivo CSS compartilhado.

Espero que você tenha gostado da postagem! Sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca.

Recursos

Isolamento de CSS do ASP.NET Core Blazor

Controlando os gastos de Natal com Kernel Semântico

Sat, 28 Dec 2024 00:00:00 +0000

## Introdução

À medida que as festas de fim de ano se aproximam, gerenciar despesas pode se tornar um desafio, principalmente com a enxurrada de compras e compras de presentes. Nesta postagem do blog, exploraremos como aproveitar a inteligência artificial para ajudar a controlar seus gastos de Natal usando tecnologias .NET. Ao analisar recibos com o poder do Kernel Semântico e da IA, podemos extrair com eficiência detalhes importantes, como nomes de lojas, datas, listas de itens e valores totais. Esta solução permite monitorar e gerenciar sem esforço seus gastos de Natal, garantindo que você mantenha o controle do seu orçamento sem o incômodo de revisar manualmente os recibos.

Calendário de Adviento de Inteligência Artificial 2024 em espanhol

Este projeto foi inspirado na minha participação no Calendario de Adviento de Inteligencia Artificial 2024 en Español, um evento online dedicado à IA. Você pode encontrar mais sobre o evento neste link Dev.to.

O projeto

Para este projeto, usaremos o Azure OpenAI, um serviço que nos permite utilizar modelos de IA poderosos, como o GPT-4, para processar e analisar imagens. O processo envolve várias etapas, desde a configuração do serviço API de back-end até a integração com um front-end do Blazor para uploads de imagens. Também usaremos o .NET Aspire, um componente que ajuda a conectar tudo perfeitamente.

Pré-requisitos

Antes de mergulharmos no código, certifique-se de ter os seguintes pré-requisitos:

-.NET 9

Acesso Azure OpenAI (chave API)
Visual Studio ou Código do Visual Studio
Conhecimento básico de Blazor, clientes HTTP e desenvolvimento de API

A solução Visual Studio

Acabaremos tendo algo assim, gosto de manter as coisas separadas e com nomes legais então é assim:

Mas vamos passo a passo criando coisas!

Passo 0: Os modelos

O núcleo do aplicativo Receipt Scanner depende de vários modelos principais que facilitam a interação entre os serviços front-end, API e IA. Abaixo estão os principais modelos utilizados neste projeto:

AnalyzeReceiptRequest
Este modelo representa a estrutura de solicitação para análise de um recibo. Ele contém a propriedade ImageBytes, que contém a matriz de bytes da imagem do recibo que será processada.
```
public class AnalyzeReceiptRequest
{
 public byte[] ImageBytes { get; set; }
}
```
ReceiptAnalyzeResult
Este modelo captura o resultado após o processamento de um recibo. Contém os dados estruturados extraídos do recibo, como nome da loja, data, itens e valor total.
```
public class ReceiptAnalyzeResult
{
 public DateTime CreatedAt { get; set; }
 public ReceiptData Result { get; set; }
}
```

Dados de Recibo
Este é o modelo que contém os dados estruturados do recebimento. Inclui propriedades para nome da loja, data, lista de itens (com nome e preço de cada item) e valor total no recibo.

public class ReceiptData
{
 public string Store { get; set; }
 public DateTime? Date { get; set; }
 public List<ReceiptItem> Items { get; set; }
 public decimal? Total { get; set; }
}

Item de recibo
Cada item do recibo é representado por este modelo. Ele contém o nome do item e seu preço.

public class ReceiptItem
{
 public string Name { get; set; }
 public decimal? Price { get; set; }
}
```Esses modelos servem de base para a passagem de dados entre o cliente e o servidor, garantindo um fluxo tranquilo de informações. A API recebe a imagem do recibo e, em troca, processa e retorna um objeto JSON estruturado que pode ser facilmente consumido pelo front-end.

Etapa 1: Configurando o serviço API de back-end

A primeira etapa na construção deste aplicativo é configurar um serviço API para analisar imagens de recibos. Usaremos a API Azure OpenAI para extrair informações das imagens de recibo. Aqui está um resumo de como tudo se encaixa:

Serviço de IA – Um mergulho profundo

O serviço de IA está no centro do nosso sistema de análise de recibos. É responsável pela comunicação com a API do Azure OpenAI para processar os dados da imagem e retornar insights significativos. A classe AiApiClient é o cliente que lidará com todas as interações com a API Azure OpenAI.

Implementação do cliente de IA

O AiApiClient é o principal componente responsável por enviar a imagem do recibo (em formato de matriz de bytes) para a API Azure OpenAI. Ele lida com a comunicação, registro de erros e análise de dados:

public class AiApiClient
{
 private readonly HttpClient _httpClient;
 private readonly ILogger<AiApiClient> _logger;

 public AiApiClient(HttpClient httpClient, ILogger<AiApiClient> logger)
 {
 _httpClient = httpClient;
 _logger = logger;
 }

 public async Task<ReceiptAnalyzeResult?> AnalyzeAsync(byte[] imageBytes, CancellationToken cancellationToken = default)
 {
 if (imageBytes == null || imageBytes.Length == 0)
 {
 _logger.LogWarning("ImageBytes is null or empty.");
 return null;
 }

 _logger.LogInformation("Sending analyze request with image bytes of length: {Length}", imageBytes.Length);

 var request = new AnalyzeReceiptRequest
 {
 ImageBytes = imageBytes
 };

 try
 {
 var response = await _httpClient.PostAsJsonAsync("/analyze-receipt", request, cancellationToken);

 if (!response.IsSuccessStatusCode)
 {
 _logger.LogWarning("Failed to analyze receipt. StatusCode: {StatusCode}", response.StatusCode);
 return null;
 }

 var analyzeResult = await response.Content.ReadFromJsonAsync<ReceiptAnalyzeResult>(cancellationToken: cancellationToken);

 if (analyzeResult == null)
 {
 _logger.LogWarning("No content received from AI API service.");
 return null;
 }

 _logger.LogInformation("Analysis result received: {AnalyzeResult}", analyzeResult);

 return analyzeResult;
 }
 catch (Exception ex)
 {
 _logger.LogError(ex, "An error occurred while analyzing the receipt.");
 return null;
 }
 }
}

Nesta parte do código, definimos o método AnalyzeAsync, que é responsável por:

Envio da matriz de bytes da imagem para a API Azure OpenAI.
Tratamento de quaisquer erros ou respostas malsucedidas da API.
Analisar os dados JSON retornados em um resultado estruturado (ReceiptAnalyzeResult).

Os benefícios de separar esta funcionalidade num serviço dedicado (AiApiClient) incluem:

Tratamento de erros: Tratamento centralizado de erros, como problemas de rede ou respostas inválidas.
Registro: Registro adequado de solicitações e respostas para monitorar o comportamento do sistema.

Serviço API - Tratamento de solicitações e respostas

O Serviço de API atua como intermediário entre o aplicativo front-end Blazor e o serviço de IA. Este serviço é responsável por aceitar os dados da imagem, repassá-los ao serviço de IA e devolver os resultados da análise ao cliente.

Ponto final da API

Nesta etapa, definimos um endpoint de API simples para aceitar imagens de recebimento, encaminhá-las ao serviço de IA para processamento e retornar os resultados ao cliente:

using ReceiptScanner.Shared.Clients;
using ReceiptScanner.Shared.Models;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddProblemDetails();

// Register AiApiClient with HttpClient
builder.Services.AddHttpClient<AiApiClient>(client =>
{
 client.BaseAddress = new Uri("https+http://aiservice");
});

// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

if (app.Environment.IsDevelopment())
{
 app.MapOpenApi();
}

// POST endpoint to analyze receipt
app.MapPost("/api/analyze-receipt", async (AnalyzeReceiptRequest request, AiApiClient aiApiClient, ILogger<Program> logger) =>
{
 if (request.ImageBytes == null || request.ImageBytes.Length == 0)
 {
 logger.LogWarning("ImageBytes is null or empty.");
 return Results.BadRequest("ImageBytes is required.");
 }

 logger.LogInformation("Received analyze receipt request with image bytes of length: {Length}", request.ImageBytes.Length);

 try
 {
 var result = await aiApiClient.AnalyzeAsync(request.ImageBytes);

 if (result == null)
 {
 logger.LogWarning("Failed to analyze the receipt.");
 return Results.Problem("Unable to process the receipt at this time. Please try again later.");
 }

 logger.LogInformation("Analysis completed successfully. Result: {Result}", result);

 return Results.Ok(result);
 }
 catch (Exception ex)
 {
 logger.LogError(ex, "An error occurred while processing the receipt.");
 return Results.Problem("An error occurred while processing the receipt. Please try again later.");
 }
});

app.MapDefaultEndpoints();

app.Run();

Este ponto final:

Aceita a imagem do recibo como parte do corpo da solicitação.
Chama o método endopint AiService para enviar a imagem ao Azure OpenAI para processamento.
Devolve o resultado da análise ao cliente.

Etapa 2: Configurando o front-end do Blazor

Agora que configuramos o backend, vamos voltar nossa atenção para o frontend do Blazor. É aqui que os usuários podem fazer upload de imagens de recibos para análise e ver os resultados.

Implementação da página Blazor

A página Blazor fornece uma interface simples onde os usuários podem fazer upload de várias imagens de recibo e ver os resultados da análise exibidos em uma tabela. Aqui está o código da página:

@page "/analyzer"
@using ReceiptScanner.Shared.Clients
@using ReceiptScanner.Shared.Models
@using System.Globalization
@inject ApiServiceClient ApiClient
@inject ILogger<Program> Logger

@attribute [StreamRendering]
@rendermode InteractiveServer

<PageTitle>Receipt Analyzer</PageTitle>

<h1 class="text-center my-4">Receipt Analyzer</h1>

<div class="container">
 <p class="lead text-center mb-4">Upload receipt images below to extract their data.</p>

 <!-- File Upload Section -->
 <div class="card mb-4">
 <div class="card-body">
 <InputFile OnChange="HandleFileSelected" multiple class="form-control mb-3" />
 <button class="btn btn-primary w-100" @onclick="ProcessReceipts" disabled="@(!hasFiles)" type="button">
 <span class="@(!processing ? "d-none" : "") spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
 @if (processing)
 {
 <span>Processing...</span>
 }
 else
 {
 <span>Process Receipts</span>
 }
 </button>
 </div>
 </div>

 <!-- Uploaded Images Preview -->
 @if (fileBytesList.Any())
 {
 <div class="card mb-4">
 <div class="card-header">
 <h5 class="mb-0">Uploaded Receipt Images</h5>
 </div>
 <div class="card-body">
 <div class="row">
 @foreach (var fileBytes in fileBytesList)
 {
 <div class="col-12 col-md-4 mb-3">
 <img src="@($"data:image/jpeg;base64,{Convert.ToBase64String(fileBytes)}")" class="img-fluid rounded" alt="Uploaded receipt" />
 </div>
 }
 </div>
 </div>
 </div>
 }

 <!-- Processing Indicator -->
 @if (processing)
 {
 <div class="alert alert-info text-center" role="alert">
 <strong>Processing receipts...</strong> Please wait while we analyze the uploaded files.
 </div>
 }

 <!-- Analysis Results Section -->
 @if (analyzedReceipts != null && analyzedReceipts.Any())
 {
 <div class="card">
 <div class="card-header">
 <h5 class="mb-0">Analysis Results</h5>
 </div>
 <div class="card-body">
 <table class="table table-striped table-bordered">
 <thead>
 <tr>
 <th>Store</th>
 <th>Date</th>
 <th>Total</th>
 <th>Items</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var receipt in analyzedReceipts)
 {
 <tr>
 <td>@(receipt.Result?.Store ?? "Unknown")</td>
 <td>@(receipt.Result?.Date?.ToString() ?? "Unknown")</td>
 <td>@(receipt.Result?.Total?.ToString("C", ci) ?? "Unknown")</td>
 <td>
 <ul class="list-unstyled">
 @if (receipt.Result?.Items is not null)
 {
 @foreach (var item in receipt.Result?.Items!)
 {
 <li><strong>@item.Name</strong> - @item.Price?.ToString("C", ci)</li>
 }
 }
 </ul>
 </td>
 </tr>
 }
 </tbody>
 </table>
 </div>
 </div>
 }
 else if (processed && (analyzedReceipts == null || !analyzedReceipts.Any()))
 {
 <div class="alert alert-warning text-center" role="alert">
 <strong>No results found.</strong> Please try again with different images or ensure they are clear and legible.
 </div>
 }
</div>

@code {
 private bool hasFiles;
 private bool processing;
 private bool processed;
 private List<byte[]> fileBytesList = new();
 private List<ReceiptAnalyzeResult> analyzedReceipts = new();
 CultureInfo ci = new CultureInfo("es-es");

 private async Task HandleFileSelected(InputFileChangeEventArgs e)
 {
 try
 {
 fileBytesList.Clear();

 foreach (var file in e.GetMultipleFiles())
 {
 var memoryStream = new MemoryStream();
 await file.OpenReadStream().CopyToAsync(memoryStream);
 fileBytesList.Add(memoryStream.ToArray());
 }

 hasFiles = fileBytesList.Any();
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while handling file upload.");
 }
 }

 private async Task ProcessReceipts()
 {
 if (!hasFiles)
 return;

 processing = true;
 analyzedReceipts.Clear();

 try
 {
 foreach (var fileBytes in fileBytesList)
 {
 var result = await ApiClient.AnalyzeReceiptAsync(fileBytes);
 if (result != null)
 {
 analyzedReceipts.Add(result);
 }
 }
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while processing receipts.");
 }
 finally
 {
 processing = false;
 processed = true;
 }
 }
}

```Esta página permite aos usuários fazer upload de recibos e mostra os resultados da análise em uma tabela com nomes de lojas, datas, valores totais e lista de itens.

<p alinhar="centro">
<img src="https://imgur.com/BLswKhm.png">
</p>

## Etapa 3: .NET Aspire

<p alinhar="centro">
<img src="https://imgur.com/ja56RWN.png">
</p>

### O que é o .NET Aspire?

O .NET Aspire é um conjunto de ferramentas, modelos e pacotes poderosos para criar aplicativos observáveis e prontos para produção. O .NET Aspire é fornecido por meio de uma coleção de pacotes NuGet que tratam de questões específicas nativas da nuvem. Os aplicativos nativos da nuvem geralmente consistem em peças ou microsserviços pequenos e interconectados, em vez de uma base de código única e monolítica. Os aplicativos nativos da nuvem geralmente consomem um grande número de serviços, como bancos de dados, mensagens e cache. Para obter informações sobre suporte, consulte a Política de Suporte do .NET Aspire.

Um aplicativo distribuído é aquele que utiliza recursos computacionais em vários nós, como contêineres executados em hosts diferentes. Esses nós devem comunicar-se através dos limites da rede para entregar respostas aos usuários. Um aplicativo nativo da nuvem é um tipo específico de aplicativo distribuído que aproveita ao máximo a escalabilidade, a resiliência e a capacidade de gerenciamento das infraestruturas em nuvem.

Usar o **.NET Aspire** para este projeto oferece vários benefícios que melhoram a qualidade geral do sistema, como:

### 1. **Registro centralizado**

O .NET Aspire integra automaticamente o log em todo o aplicativo, o que significa que você não precisa configurar manualmente o log para cada serviço. Isso garante que os logs sejam consistentes e armazenados em um local centralizado, facilitando muito a depuração e o monitoramento.

Por exemplo, a classe `AiApiClient` usa log para registrar os bytes da imagem enviados ao serviço de IA, as respostas da API e quaisquer erros que ocorram durante o processo de análise.

```csharp
_logger.LogInformation("Sending analyze request with image bytes of length: {Length}",

 imageBytes.Length);

2. Coleta automática de métricas

O .NET Aspire também rastreia e relata automaticamente métricas importantes do aplicativo, como tempos de resposta, contagens de solicitações e taxas de erro. Isso ajuda você a entender o desempenho do aplicativo e detectar rapidamente quaisquer gargalos ou problemas.

3. Desempenho melhorado

O .NET Aspire otimiza chamadas HTTP, o que ajuda a manter baixos os tempos de resposta e a reduzir o consumo desnecessário de recursos. Ele fornece recursos como pool de conexões, novas tentativas de solicitação e roteamento inteligente.

4. Integração Perfeita

O .NET Aspire simplifica a integração de vários serviços (como os serviços de IA e API neste projeto) e agiliza o processo de implantação. Você não precisa se preocupar com configurações de baixo nível, pois o Aspire cuida das tarefas relacionadas à infraestrutura para você.

ConclusãoIA não é mais apenas uma palavra da moda ou algo que vemos em filmes de ficção científica. Atualmente, ele está resolvendo ativamente problemas do mundo real, como aquele que abordamos neste projeto: extrair dados estruturados de recibos. Com a ajuda do Azure OpenAI, do .NET Aspire e do Blazor, podemos automatizar o que de outra forma seria uma tarefa manual demorada e propensa a erros. A IA não apenas conversa ou responde a solicitações como o ChatGPT; ele interpreta imagens, extrai informações valiosas e nos fornece insights acionáveis em segundos.

Ao usar o Azure OpenAI para análise de recibos e o .NET Aspire para integração perfeita com registros e métricas, criamos uma solução poderosa e escalonável. O potencial da IA para agilizar processos de negócios, automatizar tarefas tediosas e melhorar a precisão é enorme, e este é apenas um exemplo de como pode ser aplicada.

Esta postagem faz parte do Calendario de Adviento de Inteligencia Artificial 2024 en Español, um evento que apresenta aplicações de IA do mundo real e educa a comunidade tecnológica de língua espanhola sobre as últimas tendências. Se você deseja se aprofundar na IA e em suas possibilidades, este evento é um ótimo lugar para começar.

A IA está transformando a forma como trabalhamos e este projeto é apenas um vislumbre do que é possível. O verdadeiro poder da IA está na sua capacidade de resolver problemas reais, seja processando recibos, analisando imagens ou prevendo tendências. Estamos apenas arranhando a superfície.

Código Fonte

O código-fonte completo deste projeto está disponível no GitHub. Sinta-se à vontade para baixá-lo, explorar como os serviços de IA e API funcionam juntos e adaptá-lo para seus próprios casos de uso. Se você encontrar algum problema ou tiver ideias para melhorias, não hesite em criar um problema ou enviar uma solicitação pull. Contribuições são sempre bem-vindas e seus comentários ajudarão a tornar este projeto ainda melhor!

Boa codificação!

Usando contêineres para... acompanhar os preços dos presentes de Natal?

Thu, 12 Dec 2024 00:00:00 +0000

O Natal está chegando e com ele vem a alegre tarefa de encontrar os presentes perfeitos para seus entes queridos. Se você for como eu, provavelmente adora fazer um bom negócio, mas navegar pelos preços exorbitantes de itens populares durante as festas de fim de ano pode parecer um passeio de trenó na vida real - emocionante, mas um pouco cansativo! Este ano, em vez de enlouquecer com verificações diárias de preços, decidi usar bem minhas habilidades tecnológicas e automatizar o processo.

Como desenvolvedor de software e apaixonado por aproveitar a tecnologia para resolver problemas do dia a dia, encontrei uma maneira de automatizar o processo de verificação de preços. Em vez de visitar manualmente várias lojas online todos os dias para comparar preços, decidi criar um sistema que possa fazer isso por mim. Isso não apenas economiza tempo, mas também garante que eu obtenha as melhores ofertas sem o estresse das verificações diárias.

Por que automatizar o monitoramento de preços?

Automatizar o monitoramento de preços é como ter sua própria equipe de duendes do Papai Noel trabalhando 24 horas por dia para garantir que você obtenha as melhores ofertas sem mexer um dedo. Veja por que você vai adorar:

Itens caros: Todos nós sabemos que os presentes de Natal podem ficar muito caros, especialmente quando gadgets e brinquedos estão em sua lista. Economizar dinheiro com isso pode ser tão satisfatório quanto encontrar a última árvore em estoque.
Verificações Diárias: Quem tem tempo (ou paciência) para verificar preços todos os dias? Eu não!
Automação: abrace o espírito natalino de doação – dê a si mesmo o presente da eficiência.
Precisão: A automação garante que suas verificações de preços sejam tão precisas quanto o nariz de Rudolph é brilhante.

Tecnologias principais

Para construir meu próprio ajudante do Papai Noel, decidi usar várias tecnologias importantes:

Contêineres

Os contêineres são como o embrulho de Natal do software. Eles agrupam seus aplicativos com todas as suas vantagens (dependências) para que tudo funcione tão bem quanto um passeio de trenó na neve fresca. Docker é nossa escolha para criar esses contêineres.

Blazor

Blazor é uma estrutura interessante para construir aplicativos da web interativos usando .NET. É como substituir canções de Natal genéricas pela sua própria lista de reprodução de férias - personalizada, eficiente e muito divertida.

Docker-Compose

Docker-Compose é o gestor da operação do nosso Pólo Norte. Isso nos ajuda a manter todos os nossos serviços – como a API e o front-end do Blazor – funcionando juntos em perfeita harmonia. Pense nele como o maestro da nossa sinfonia natalina.

Guia passo a passo

Agora vamos mergulhar na oficina do Papai Noel e dar vida a esse projeto!

Etapa 1: Criando a API

1.1 Configurando o Projeto

Coloque seu chapéu de Papai Noel de codificação e configure um novo projeto de API Web ASP.NET Core. Abra seu terminal (é como abrir seu calendário do advento) e execute:

dotnet new webapi -o PriceMonitorApi
cd PriceMonitorApi

Este comando cria um novo diretório chamado PriceMonitorApi e configura um projeto básico de API da Web. Imagine que é como criar uma base robusta para a sua casa de pão de gengibre.

1.2 Adicionando bibliotecas HttpClient e ScrapingEm seguida, adicione `HttpClient` e uma biblioteca para analisar HTML. Este será nosso trenó confiável para buscar e ler dados de preços.

dotnet add package HtmlAgilityPack

HtmlAgilityPack é o elfo que nos ajuda a analisar documentos HTML.

1.3 Criando Modelos

Os modelos são como o modelo dos nossos brinquedos. Vamos criar um modelo para representar as informações do produto:

namespace PriceMonitorApi.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

Acabamos de criar o modelo perfeito para nossos dados.

1.4 Implementando o serviço Scraper

Nosso serviço de scraper é como o ajudante do Papai Noel – buscando e processando informações para nós:

using HtmlAgilityPack;
using PriceMonitorApi.Models;
using System.Globalization;

namespace PriceMonitorApi.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> ScrapeProductInfoAsync(string url)
 {
 var response = await _httpClient.GetStringAsync(url);

 var htmlDoc = new HtmlDocument();
 htmlDoc.LoadHtml(response);

 var title = htmlDoc.DocumentNode.SelectSingleNode("//h1[@class='product-title']").InnerText.Trim();
 var priceString = htmlDoc.DocumentNode.SelectSingleNode("//span[@class='product-price']").InnerText.Trim();

 if (decimal.TryParse(priceString, NumberStyles.Currency, CultureInfo.InvariantCulture, out var price))
 {
 return new ProductInfo
 {
 Title = title,
 Price = price,
 Date = DateTime.UtcNow
 };
 }

 throw new Exception("Unable to parse price");
 }
 }
}

Este trecho transforma nosso HtmlAgilityPack em uma varinha mágica de férias.

1.5 Criando o controlador de API

Vamos criar um controlador que atuará como o guardião de nossos dados:

using Microsoft.AspNetCore.Mvc;
using PriceMonitorApi.Models;
using PriceMonitorApi.Services;

namespace PriceMonitorApi.Controllers
{
 [ApiController]
 [Route("api/[controller]")]
 public class ScraperController : ControllerBase
 {
 private readonly ScraperService _scraperService;

 public ScraperController(ScraperService scraperService)
 {
 _scraperService = scraperService;
 }

 [HttpGet("productinfo")]
 public async Task<ActionResult<ProductInfo>> GetProductInfo(string url)
 {
 try
 {
 var productInfo = await _scraperService.ScrapeProductInfoAsync(url);
 return Ok(productInfo);
 }
 catch (Exception ex)
 {
 return BadRequest(new { Message = ex.Message });
 }
 }
 }
}

Nosso controlador garante que os dados sejam entregues mais rápido do que o Papai Noel pela chaminé.

1.6 Registrando serviços no contêiner DI

Por último, registre seu ScraperService para garantir que ele esteja disponível quando necessário.

services.AddHttpClient<ScraperService>();

Agora sua API está pronta, como o trenó do Papai Noel na véspera de Natal!

Etapa 2: Criando o aplicativo Blazor

Blazor nos ajuda a decorar nosso projeto como uma árvore de Natal – tornando-o visualmente atraente e interativo.

2.1 Configurando o projeto Blazor

A seguir, criaremos um projeto Blazor que atua como interface para nosso passeio de trenó de monitoramento de preços.

dotnet new blazor -o PriceMonitorBlazor
cd PriceMonitorBlazor

Este comando espalha um pouco da magia do feriado para configurar um projeto básico do Blazor WebAssembly.

2.2 Adicionando modelos

Assim como configurar enfeites, adicione um modelo ProductInfo no projeto Blazor:

namespace PriceMonitorBlazor.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

2.3 Criando o serviço para chamadas de API

Crie um serviço para buscar dados de nossa API – pense nele como nosso companheiro de compras online:

using PriceMonitorBlazor.Models;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"https://localhost:5001/api/scraper/productinfo?url={url}");
 return response;
 }
 }
}

2.4 Registrando serviços no DI Container

Certifique-se de que ScraperService esteja registrado para que possamos injetá-lo em nossos componentes.

builder.Services.AddScoped<ScraperService>();

2.5 Criando o componente Blazor

Atualize Pages/Index.razor para incluir uma interface divertida e interativa:

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="FetchProductInfo">Fetch Price</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();

 private async Task FetchProductInfo()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 var productInfo = await ScraperService.GetProductInfoAsync(productUrl);
 productInfos.Add(productInfo);
 }
 }
}

É como montar uma exibição festiva de feriado – tornando nosso aplicativo interativo e agradável.

Etapa 3: Conectando tudo usando Docker-Compose

Agora vamos conectar tudo usando Docker-Compose, transformando nosso projeto em um passeio de trenó bem lubrificado.

3.1 Criando arquivos Docker

Crie Dockerfiles para os projetos API e Blazor:

PriceMonitorApi/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorApi/PriceMonitorApi.csproj", "PriceMonitorApi/"]
RUN dotnet restore "PriceMonitorApi/PriceMonitorApi.csproj"
COPY . .
WORKDIR "/src/PriceMonitorApi"
RUN dotnet build "PriceMonitorApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorApi.dll"]

PriceMonitorBlazor/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorBlazor/PriceMonitorBlazor.csproj", "PriceMonitorBlazor/"]
RUN dotnet restore "PriceMonitorBlazor/PriceMonitorBlazor.csproj"
COPY . .
WORKDIR "/src/PriceMonitorBlazor"
RUN dotnet build "PriceMonitorBlazor.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorBlazor.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorBlazor.dll"]

3.2 Criando docker-compose.yml

Conecte todos os pontos (luzes de Natal) com um único arquivo docker-compose.yml:

version: '3.4'

services:
 api:
 image: pricemonitorapi
 build:
 context: ./PriceMonitorApi
 dockerfile: Dockerfile
 ports:
 - "5000:80"
 networks:
 - price-monitor-network

 blazor:
 image: pricemonitorblazor
 build:
 context: ./PriceMonitorBlazor
 dockerfile: Dockerfile
 ports:
 - "5001:80"
 depends_on:
 - api
 networks:
 - price-monitor-network

networks:
 price-monitor-network:
 driver: bridge

Diagramas

Abaixo estão os diagramas para ajudar a visualizar os diferentes componentes e o fluxo de dados, isso nos ajudará a entender o que realmente está acontecendo em nosso mundo papai noel:

Diagrama de Arquitetura do Sistema

Diagrama de Fluxo de Dados

Diagrama de sequência

Diagrama de componentes para configuração do Docker

Etapa 4: gerenciamento de URL, atualização e atualização periódica automatizadaNesta demonstração iremos apenas armazená-lo na memória, mas em uma aplicação real, você usaria um banco de dados. Para este projeto divertido, vamos nos limitar ao armazenamento na memória.

4.1 Modificando o serviço para gerenciar URLs

Primeiro, garantiremos que nosso serviço possa adicionar e recuperar URLs, bem como buscar informações de produtos:

Atualização Services/ScraperService.cs:

using PriceMonitorBlazor.Models;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;
 private List<string> urls = new List<string>();

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"http://localhost:5000/api/scraper/productinfo?url={url}");
 return response;
 }

 public void AddUrl(string url)
 {
 if (!urls.Contains(url))
 {
 urls.Add(url);
 }
 }

 public List<string> GetUrls()
 {
 return urls;
 }

 public void ClearUrls()
 {
 urls.Clear();
 }
 }
}

4.2 Atualizando o componente Blazor para gerenciamento e atualização de URL

Em seguida, atualize Pages/Index.razor para adicionar gerenciamento de URL, atualização e atualização periódica automatizada:

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="AddUrl">Add URL</button>
</p>

<p>
 <button @onclick="RefreshPrices">Refresh All Prices</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();
 private Timer _timer;

 protected override void OnInitialized()
 {
 StartTimer();
 }

 private void StartTimer()
 {
 // Set up the timer to call RefreshPrices every minute (60000 ms)
 _timer = new Timer(async _ => await InvokeAsync(RefreshPrices), null, TimeSpan.Zero, TimeSpan.FromMinutes(1));
 }

 private void AddUrl()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 ScraperService.AddUrl(productUrl);
 productUrl = string.Empty;
 }
 }

 private async Task RefreshPrices()
 {
 productInfos.Clear();
 var urls = ScraperService.GetUrls();

 foreach (var url in urls)
 {
 var productInfo = await ScraperService.GetProductInfoAsync(url);
 productInfos.Add(productInfo);
 }
 StateHasChanged();
 }
}

Neste componente atualizado:

Usamos um Timer para chamar periodicamente o método RefreshPrices a cada minuto.
O método StartTimer inicializa o cronômetro para iniciar imediatamente e dispara a cada 60 segundos.
O método de ciclo de vida OnInitialized chama StartTimer quando o componente é inicializado para iniciar a atualização periódica.

4.3 Executando a solução

Para executar o aplicativo Blazor atualizado com os novos recursos, recompile e reinicie os contêineres do Docker:

docker-compose build
docker-compose up

Depois de carregar http://localhost:5001 em seu navegador, o aplicativo Blazor agora deve atualizar automaticamente os preços dos produtos a cada minuto, além de permitir atualizações manuais e gerenciamento de URL.

Conclusão

Construir este sistema de monitoramento de preços foi uma festa festiva! Isso não apenas me salvou do estresse das verificações diárias de preços, mas também mostrou a magia das modernas tecnologias da web.

Calendário Festivo de Tecnologia 2024

Criei esta postagem como parte do evento Festive Tech Calendar 2024, que reúne entusiastas da tecnologia, inovadores e sonhadores digitais para compartilhar conhecimento e celebrar a fusão do espírito festivo e das maravilhas tecnológicas. Esta iniciativa não visa apenas aprender e conectar-se, mas também retribuir.

Festive Tech Calendar 2024 está apoiando a Beatson Cancer Charity este ano. A Beatson Cancer Charity dedica-se a apoiar as pessoas afetadas pelo câncer, suas famílias e os profissionais de saúde que cuidam delas. Mais informações sobre seu trabalho incrível podem ser encontradas em https://www.beatsoncancercharity.org/.

Confira o site do Festive Tech Calendar em https://festivetechcalendar.com para perguntas frequentes e mais detalhes sobre o evento.

HO HO HO!

Criar este projeto foi uma maneira maravilhosa de contribuir para a festiva comunidade tecnológica e, ao mesmo tempo, apoiar uma grande causa.

Espero que você tenha achado este guia útil e que o inspire a explorar mais maneiras de usar a tecnologia para simplificar as tarefas diárias.

Se você tiver alguma dúvida ou precisar de mais assistência, não hesite em entrar em contato.

Boa codificação!

ValidationAttribute personalizado e validação Blazor

Fri, 29 Mar 2024 00:00:00 +0000

# Personalize tudo

Como você provavelmente já viu em todos os meus posts, eu realmente tento manter tudo o mais limpo possível, pois já escrevi posts sobre atributos customizados, tratamento de exceções customizadas, injeção de coleção de serviços, etc.

Com o tempo, percebi que esse tipo de codificação dá a mim e à minha equipe uma maneira de melhorar as horas extras, encontrar problemas com mais facilidade e separar o código o máximo possível.

Sim, depois dessa história legal que acabei de contar, tenho trabalhado no Blazor ultimamente como de costume e descobri que, depois de anos e anos de desenvolvimento, você pode criar atributos de validação personalizados.

Sim, é engraçado, depois de todos esses anos…

Atributos de validação personalizados

A ideia veio do trabalho, na verdade, sempre fazemos validação em todos os lugares, mas eu tinha alguns campos que exigiam o mesmo processo de validação, então pensei que poderia haver algo lá… como atributos de validação customizados!

Então, abri a documentação da Microsoft para isso e descobri que sim, você pode criar atributos de validação personalizados e atribuí-los às propriedades, assim:

public class StringLengthRangeAttribute : ValidationAttribute
{
 public int Minimum { get; set; }
 public int Maximum { get; set; }

 public StringLengthRangeAttribute()
 {
 this.Minimum = 0;
 this.Maximum = int.MaxValue;
 }

 public override bool IsValid(object value)
 {
 string strValue = value as string;
 if (!string.IsNullOrEmpty(strValue))
 {
 int len = strValue.Length;
 return len >= this.Minimum && len <= this.Maximum;
 }
 return true;
 }
}

e use-o em uma classe simples como esta:

[Required]
[StringLengthRange(Minimum = 10, ErrorMessage = "Must be >10 characters.")]

[StringLengthRange(Maximum = 20)]

[Required]
[StringLengthRange(Minimum = 10, Maximum = 20)]

Validador personalizado

Então eu tenho esse validador que preciso para algum caso de negócio específico que contará 20 primeiros caracteres que serão 9 números e um hífen, e terminarão com 2 caracteres que normalmente serão o código do país, então algo assim: 123456789-123456789-ES

Acabei chegando com algo assim, é muito simples, mas funciona:

using System;
using System.ComponentModel.DataAnnotations;
using System.Text.RegularExpressions;

public class SpecialStringValidatorAttribute : ValidationAttribute
{
 private const int TotalLength = 22;
 private const string Pattern = @"^(\d{10})-(\d{10})-([A-Za-z]{2})$";

 protected override ValidationResult IsValid(object value, ValidationContext validationContext)
 {
 string strValue = value as string;

 if (!string.IsNullOrEmpty(strValue))
 {
 if (strValue.Length != TotalLength)
 {
 return new ValidationResult($"The string must be {TotalLength} characters long.");
 }

 if (!Regex.IsMatch(strValue, Pattern))
 {
 return new ValidationResult("The string must follow the pattern: 1234567890-1234567890-AB");
 }

 return ValidationResult.Success;
 }

 return new ValidationResult("The string cannot be null or empty.");
 }
}

Testes

Eu escrevi alguns testes para eles também, só para garantir:

public class SpecialStringValidatorTests
{
 [Theory]
 [InlineData("1234567890-1234567890-AB", true)]
 [InlineData("1234567890-1234567890-XY", true)]
 [InlineData("1234567890-1234567890-A1", false)]
 [InlineData("1234567890-1234567890-A", false)]
 [InlineData("1234567890-123456789-AB", false)]
 [InlineData("1234567890-1234567890", false)]
 [InlineData("1234567890-1234567890-ABCDE", false)]
 public void SpecialStringValidatorTest(string input, bool expectedResult)
 {
 // Arrange
 var validator = new SpecialStringValidatorAttribute();

 // Act
 var result = validator.IsValid(input);

 // Assert
 Assert.Equal(expectedResult, result);
 }
}

E quando executei tive estes resultados:

Microsoft (R) Test Execution Command Line Tool Version 16.9.1
Copyright (c) Microsoft Corporation. All rights reserved.

Starting test execution, please wait...

A total of 1 test files matched the specified pattern.

Test run in progress...

Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-AB", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-XY", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A1", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-123456789-AB", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-ABCDE", expectedResult: False)

Test Run Successful.
Total tests: 7
 Passed: 7
 Total time: 1.7296 Seconds

Validação personalizada e Blazor

Então agora que sei que o dele pode ser usado, é claramente uma boa ideia implementá-lo no Blazor, certo?

Vamos supor que eu tenha este formulário, que usará o modelo Person que mostrei antes:

@using Models
@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

<EditForm Model=@Person FormName="PersonForm">
 <DataAnnotationsValidator/>
 <ValidationSummary/>
 <div class="form-group">
 <label for="Name">Name</label>
 <InputText @bind-Value=Person.Name class="form-control" id="Name" />
 <ValidationMessage For="() => Person.Name"/>
 </div>
 <div class="form-group">
 <label for="MySpecialString">My special string</label>
 <InputText @bind-Value=Person.MySpecialString class="form-control" id="Name" />
 <ValidationMessage For="() => Person.MySpecialString"/>
 </div>
 <div class="form-group">
 <label for="Age">Age</label>
 <InputNumber @bind-Value=Person.Age class="form-control" id="Age" />
 <ValidationMessage For=@(() => Person.Age) />
 </div>
 <input type="submit" class="btn btn-primary" value="Save"/>
</EditForm>

@code {
 Person Person = new Person();
}

Assim que executamos isso, obtemos os seguintes erros:

E se colocarmos apenas o que queremos, obtemos o seguinte, tudo claro:

Para ser honesto, está bastante claro que devemos mover a lógica pelo menos para validar esses formulários em atributos de validação personalizados, isso nos dá liberdade para armazenar o código desse login em um único local e podemos usá-lo posteriormente para uma API ou outro aplicativo.

Espero que tenham gostado, se tiver alguma dúvida ou quiser entrar em contato, não hesite e entre em contato comigo!

Tratamento de exceções personalizado na API .NET

Sun, 01 Oct 2023 00:00:00 +0000

Exceções são ruins, nós sabemos, certo? Mas e se tivermos que lidar com eles?

O que acontece quando temos uma exceção, por exemplo, em uma API, ela exibe uma mensagem na pilha que inclui muitas informações que podemos querer remover da resposta que nossos usuários recebem.

Para a demonstração, criei uma API dotnet e adicionei um método que lançará uma exceção:

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new Exception("This is a custom exception!");
}

Se lançarmos uma exceção, ficará assim:

System.Exception: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method16(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

Isso parece normal, é isso que você obtém de uma exceção, mas para mim está exibindo muitas informações, se você tiver bibliotecas e outras coisas, pode mostrar informações sensatas sobre seu cliente, seu projeto ou outras coisas para alguém que possa estar tentando ver as coisas.

Isto é o que parece no Swagger:

Criando uma exceção personalizada

Esta etapa poderia ser evitada, pois sabemos qual exceção será lançada, neste caso um Exception, mas para mim, ter suas exceções personalizadas é melhor, pois você tem mais controle do que está lançando.

Neste caso, acabei de criar um objeto CustomException que herda de Exception:

namespace CustomExceptionHandleDemo.Exceptions
{
 public class CustomException : Exception
 {
 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 public CustomException() { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 public CustomException(string message) : base(message) { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 /// <param cref="Exception" name="inner">Parameter for inner</param>
 public CustomException(string message, Exception inner) : base(message, inner) { }
 }
}

Depois de criarmos nossa exceção personalizada, vamos atualizar nosso método para lançar CustomException em vez de Exception:

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new CustomException("This is a custom exception!");
}

Isso por enquanto não mudará nada, mas o stack trace mostrará que o objeto que foi lançado é um CustomException em vez de Exception, dê uma olhada no início do stack trace:

CustomExceptionHandleDemo.Exceptions.CustomException: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method24(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

Criando um ExceptionFilterAttribute

A Microsoft nos deu uma maneira de lidar com exceções depois que elas foram lançadas. Você pode verificar mais informações aqui.

Mas até agora a documentação que eles nos fornecem é:

Um filtro abstrato que é executado de forma assíncrona após uma ação lançar uma exceção. As subclasses devem substituir OnException(ExceptionContext) ou OnExceptionAsync(ExceptionContext) mas não ambos.

Então vamos criar um, vamos criar CustomExceptionFilterAttribute no qual vamos substituir OnException:

using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Mvc;
using CustomExceptionHandleDemo.Exceptions;

namespace CustomExceptionHandleDemo.ExceptionFilterAttributes
{
 public class CustomExceptionFilterAttribute : ExceptionFilterAttribute
 {
 /// <summary>
 /// OnException
 /// </summary>
 /// <param cref="ExceptionContext" name="context">Parameter for context</param>
 public override void OnException(ExceptionContext context)
 {
 if (context.Exception is CustomException)
 {
 context.HttpContext.Response.StatusCode = 500;
 context.Result = new ObjectResult(context.Exception.Message);
 }
 }
 }
}

Como você pode ver, estamos dando uma olhada no ExceptionContext, quando a exceção é um tipo de CustomException, fazemos algo.

Esse algo está atualizando a resposta e o código de status do que iremos retornar.

Para atualizar o código de status, devemos atualizar context.HttpContext.Response.StatusCode e para retornar o resultado, temos que atualizar o context.Result fornecendo a ele um objeto que é herdado de ActionResult.

Este é um filtro, então significa que temos que adicionar algo adicionando [CustomExceptionFilter].

Usando o filtro

Agora, vamos replicar o método que temos e adicionar este filtro para que ele entre em ação, nosso endpoint da API ficará assim:

using CustomExceptionHandleDemo.ExceptionFilterAttributes;
using CustomExceptionHandleDemo.Exceptions;
using Microsoft.AspNetCore.Mvc;

namespace CustomExceptionHandleDemo.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 public WeatherForecastController()
 {
 }

 [HttpGet]
 [Route("GetWithoutExceptionHandler")]
 public Task GetWithoutExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }

 [HttpGet]
 [Route("GetWithExceptionHandler")]
 [CustomExceptionFilter]
 public Task GetWithExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }
 }
}

Como você pode ver, temos um novo método chamado GetWithExceptionHandler, que tem a mesma lógica que GetWithoutExceptionHandler tem, mas neste caso, adicionamos o filtro [CustomExceptionFilter] ao método.

O resultado é o seguinte após executarmos o método, vou exibir uma imagem, pois ela não está mais mostrando o stack trace:

Com isso criamos uma exceção personalizada, um filtro para substituir o que acontece quando lançamos uma exceção e a usamos em um método.

Isso pode ser usado para muitas coisas, como registrar e saber o que, quando e onde o erro acontece.

Uma maneira melhor de injetar coisas

Mon, 04 Sep 2023 00:00:00 +0000

Sempre que estou construindo coisas como serviços, repositórios, atributos ou qualquer outra coisa para injetar em minhas aplicações, há uma etapa que devemos realizar, que na verdade é adicionar os serviços à aplicação.

É sempre a mesma coisa, você vai para Program.cs e, em alguma parte do arquivo, adiciona builder.Services.AddScoped<MyService>(); para injetar o serviço.

Algo assim:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddScoped<ARepository>(); // 👀
builder.Services.AddScoped<BRepository>(); // 👀

// Services
builder.Services.AddScoped<AService>(); // 👀
builder.Services.AddScoped<BService>(); // 👀
builder.Services.AddScoped<CService>(); // 👀
builder.Services.AddScoped<DService>(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Quer dizer, funciona, mas sou exigente e não gosto muito disso.

Digamos que temos múltiplas injeções de dependência que queremos fazer, e elas não são realmente a mesma coisa, no meu caso isso poderia ser algo como ter uma biblioteca que contém todos os repositórios, outra biblioteca que tem todos os serviços e por último, outra biblioteca que contém atributos.

Nesse caso, você pode imaginar a quantidade de linhas que temos que adicionar ao Program.cs.

Digamos que temos uma biblioteca que contém alguns serviços, se quisermos incluir todos os nossos serviços, temos que trabalhar com IServiceCollection.

Então vamos criar um static class que terá um método static chamado AddServices que retorna um IServiceCollection.

Neste caso, será denominado IServiceCollectionServicesExtensions.

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddServices(this IServiceCollection services)
 {
 services
 .AddScoped<AService>()
 .AddScoped<BService>()
 .AddScoped<CService>()
 .AddScoped<DService>();

 return services;
 }
}

Além disso, também temos outra biblioteca que inclui alguns repositórios que estão sendo utilizados por estes serviços, então vamos fazer o mesmo.

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddRepositories(this IServiceCollection services)
 {
 services
 .AddScoped<ARepository>()
 .AddScoped<BRepository>();

 return services;
 }
}

Agora, temos nossos repositórios e métodos de serviços para injetar criados, mas como os usamos?

Vamos voltar ao nosso Program.cs e adicionar o seguinte:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddRepositories(); // 👀

// Services
builder.Services.AddServices(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Isso parece muito mais limpo, não é? Bem, com isso, injetamos com sucesso alguns serviços e repositórios, mas agora parece melhor e na verdade temos o que injetamos na biblioteca externa.

Injeção de dependência com atributos na API .NET

Tue, 22 Aug 2023 00:00:00 +0000

A injeção de dependência é provavelmente um dos melhores recursos que temos no .NET neste momento. Não há nenhuma maneira possível de você não estar usando-o, então se você é como eu, você deseja adicioná-lo a todas as implementações que fizer.

Filtros, conforme [documentação](https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-3.1 oficial da Microsoft):

Os filtros no ASP.NET Core permitem que o código seja executado antes ou depois de estágios específicos no pipeline de processamento de solicitações.

Filtros integrados lidam com tarefas como:

Autorização, impedindo o acesso a recursos para os quais um usuário não está autorizado.

Cache de resposta, causando curto-circuito no pipeline de solicitação para retornar uma resposta armazenada em cache.

Filtros personalizados podem ser criados para lidar com questões transversais. Exemplos de preocupações transversais incluem tratamento de erros, armazenamento em cache, configuração, autorização e registro. Os filtros evitam a duplicação de código.

Eu trabalho muito com APIs e há algumas coisas que devem executar cada solicitação, ou praticamente todas elas, então, idealmente, o que queremos fazer é trabalhar com isso mais…. injeção de dependência!

Mas às vezes é um pouco complicado, não funciona como queremos se quisermos herdar de ActionAttribute então precisamos trabalhar com TypeFilterAttribute, que nos permite fazer coisas ao substituir OnActionExecutionAsync.

Eu costumo criar esses filtros para fazer alguns registros, então vamos usar isso como exemplo:

/// <summary>
/// LoggedQueryAttribute class
/// </summary>
public class LoggedQueryTypeFilterAttribute : TypeFilterAttribute
{
 /// <summary>
 /// Constructor for <see cref="LoggedQueryTypeFilterAttribute"/>
 /// </summary>
 public LoggedQueryTypeFilterAttribute() : base(typeof(LoggedQueryFilter))
 {
 }

 /// <summary>
 /// LoggedQueryFilter class
 /// </summary>
 private class LoggedQueryFilter : IAsyncActionFilter
 {
 /// <summary>
 /// <see cref="_loggingService"/> object
 /// </summary>
 private readonly LoggingService _loggingService;

 /// <summary>
 /// Constructor for <see cref="LoggedQueryFilter"/>
 /// </summary>
 /// <param cref="LoggingService" name="loggingService">Parameter for loggingService</param>
 public LoggedQueryFilter(LoggingService loggingService)
 {
 _loggingService = loggingService;
 }

 /// <summary>
 /// OnActionExecutionAsync
 /// </summary>
 /// <param cref="ActionExecutingContext" name="context">Parameter for context</param>
 /// <param cref="ActionExecutionDelegate" name="next">Parameter for next</param>
 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 // Get properties
 var properties = (Request)context.ActionArguments.First().Value!;

 // Get call from context
 var call = context.HttpContext.Request.Path.Value!;

 // Logging
 _loggingService.LogCustomEvent(call);

 // Continue call
 await next();
 }
 }
}

A lógica é bem simples, obtemos o corpo acessando o objeto context com context.ActionArguments.First().Value, também obtemos a chamada do método com context.HttpContext.Request.Path.Value.

Então apenas chamamos nosso método do nosso serviço, neste caso é _loggingService.LogCustomEvent(call).

Então, devemos chamar await next();, porque o pipeline deve continuar.

Isto é para o atributo, agora devemos incluir esse atributo em um método.

[LoggedQueryTypeFilterAttribute]
public ActionResult<string> TestFilter()
{
 return Ok("Hello world!");
}

Espero que tenham gostado, se tiver alguma dúvida ou quiser entrar em contato, não hesite e entre em contato comigo!

Documentação do Swagger com bibliotecas externas

Fri, 17 Feb 2023 00:00:00 +0000

Usar várias bibliotecas para dividir seu código para casos futuros é uma coisa boa. Pessoalmente adoro fazer isso, se consigo dividir minha lógica para que ela possa ser reutilizada em outros projetos ou partes dos projetos.

Para mim, pelo menos, é obrigatório dividir os modelos de dados, o que inclui o Entity Framework, para que possa ser referenciado e usado em um Console application, um Blazor application ou um API.

Vamos dar uma olhada em um exemplo de como faço as coisas, este é um screenshot de um projeto que possui alguns aplicativos e uma biblioteca compartilhada que possui todos os modelos.

Este é um exemplo de classe que movi do projeto API com documentação com summary em cada propriedade e classe.

namespace CustomLibrariesDocumentation.Models
{
 /// <summary>
 /// WeatherForecast class
 /// </summary>
 public class WeatherForecast
 {
 /// <summary>
 /// Gets or sets the Date
 /// </summary>
 public DateOnly Date { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureC
 /// </summary>
 public int TemperatureC { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureF
 /// </summary>
 public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

 /// <summary>
 /// Gets or sets the Summary
 /// </summary>
 public string? Summary { get; set; }
 }
}

Se fizermos referência ao Console application e começarmos a usar o modelo, podemos ver a documentação, que é um recurso padrão no Visual Studio, então funciona bem, como você pode ver aqui:

Mas então, se fizermos referência ao API e formos para Swagger, não haverá documentação resumida.

Como podemos consertar isso?

Primeiro, temos que habilitar os comentários XML na biblioteca, para fazer isso, é necessário atualizar as configurações do projeto e habilitar ``:

Isso irá gerar alguns arquivos na pasta build que terminam com a extensão de arquivo xml, como você pode ver aqui:

Agora que fizemos isso, temos que adicionar algumas coisas no Program.cs, para podermos ler esses arquivos, isso porque por padrão ele carrega apenas a definição XML do projeto em que está.

Ele usa um método que temos dentro do AddSwaggerGen que se chama IncludeXmlComments.

A ideia é que se tivermos todos os arquivos xml, forçaremos o carregamento deles no Swagger.

builder.Services.AddSwaggerGen(s =>
{
 // Comments
 var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

 foreach (string xmlFiles in allXmlFiles)
 {
 s.IncludeXmlComments(xmlFiles);
 }
});

É direto, pegamos os arquivos xml do diretório de construção e os adicionamos com o método IncludeXmlComments.

Agora carregamos novamente o API e verificamos se conseguimos ver a documentação.

E você pode ver que podemos ver a documentação!

Espero que tenha ajudado você, qualquer dúvida não hesite em entrar em contato comigo!

Limpar filiais locais no Git

Mon, 30 Jan 2023 00:00:00 +0000

Você já chegou a um ponto em que tinha muitas filiais locais? Isso acontece muito comigo, pois usamos ramificações para cada recurso, bug ou tarefa.

Acabo com algo assim e fica super sujo depois de um tempo

Isso realmente me irrita, então vou compartilhar um comando rápido que você pode executar em seu console para fazer essa limpeza!

Encontrei este comando no Stack Overflow na seguinte resposta de Robert Corvus, que é uma versão que roda em Powerhsell.

Tenha cuidado ao executar este comando, pois você pode perder suas alterações

Antes de executá-lo, lembre-se de atualizar o MY_MASTER_BRANCH_NAME para o seu branch principal, que pode ser o master como eu uso ou os novos que vêm por padrão chamados main.

git branch | %{ $_.Trim() } | ?{ $_ -ne 'MY_MASTER_BRANCH_NAME' } | %{ git branch -D $_ }

Depois de executar este comando, você obterá uma saída como esta

Espero que seja útil para você!

Atualizando rotas de identidade no ASP.NET Core 7

Mon, 23 Jan 2023 00:00:00 +0000

Mesmo se perguntando como a Microsoft nomeia coisas tão raras? Eu sempre pensei que eles não fazem isso tão bem, mas, bem, é isso que é!

O bom disso é que você pode mudar praticamente tudo enquanto está desenvolvendo!

Você já entrou em uma página e percebeu instantaneamente que se trata de um projeto Web ASP.NET apenas fazendo o processo de registro ou login?

Já aconteceu muito comigo porque por padrão no projeto que você cria, você tem essas urls para fazer o processo de login e cadastro (também tem muitas outras páginas).

Portanto, este tutorial mostra uma maneira de atualizar essas URLs para que seu projeto fique mais bonito!!

Comportamento padrão

Quando estamos criando um projeto Blazor e decidimos utilizá-lo com o Identity, ele exibe algo assim:

E quando tentamos fazer o processo de login ou registro, vamos /Identity/Account/Login ou /Identity/Account/Register.

Mas e se eu disser que você pode atualizar efetivamente esses URLs para serem diferentes?

Estruturando as páginas `Login` e `Register`

Para atualizar essas páginas, a Microsoft as oculta, mas você pode armazená-las rapidamente e fazer as alterações desejadas!

Para fazer isso você precisa ir e Add Scaffolded Item no menu de contexto do projeto, assim:

Então irá aparecer um modal e você deve selecionar Identity duas vezes e clicar em Add:

Após este, aparecerá mais um modal, onde você poderá selecionar quais páginas de toda a Identidade deseja atualizar. Há muitas páginas que você pode atualizar, mas vamos nos concentrar em Account/Login e Account/Register:

Agora deixe funcionar um pouco e depois verifique o Solution Explorer, você encontrará alguns arquivos novos:

Esses novos arquivos são a página de login e registro que o ASP.NET adiciona ao seu projeto quando você o seleciona para adicionar Identidade!

Atualizando URLs

Como você provavelmente notou, esses arquivos são arquivos razor, já que sua extensão é cshtml, então vamos apenas usar uma diretiva para atualizar a url da página:

@page "/login"
@model LoginModel

@{
 ViewData["Title"] = "Log in";
}

<h1>@ViewData["Title"]</h1>
<div class="row">
 <div class="col-md-4">
 <section>
 <form id="account" method="post">
 <h2>Use a local account to log in.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email" class="form-label">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="current-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password" class="form-label">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="checkbox mb-3">
 <label asp-for="Input.RememberMe" class="form-label">
 <input class="form-check-input" asp-for="Input.RememberMe" />
 @Html.DisplayNameFor(m => m.Input.RememberMe)
 </label>
 </div>
 <div>
 <button id="login-submit" type="submit" class="w-100 btn btn-lg btn-primary">Log in</button>
 </div>
 <div>
 <p>
 <a id="forgot-password" asp-page="./ForgotPassword">Forgot your password?</a>
 </p>
 <p>
 <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
 </p>
 <p>
 <a id="resend-confirmation" asp-page="./ResendEmailConfirmation">Resend email confirmation</a>
 </p>
 </div>
 </form>
 </section>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to log in.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

Como você pode ver, a maior parte das coisas é a mesma, mas se você der uma olhada na primeira linha da aula, atualizei o que tínhamos antes:

@page

para

@page "/login"

Bem, isso foi fácil, não foi? Agora vamos fazer um teste rápido para ver se funciona.

Em primeiro lugar, vamos para a página padrão que temos inicialmente, para verificar se ainda funciona:

O que não acontece! Então agora vamos testar nosso novo URL que é /login:

E funciona!!

Agora vamos fazer o mesmo para o registrador, atualizamos sua página e adicionamos o caminho que queremos na diretiva @page e vamos fazer um teste!

@page "/register"
@model RegisterModel
@{
 ViewData["Title"] = "Register";
}

<h1>@ViewData["Title"]</h1>

<div class="row">
 <div class="col-md-4">
 <form id="registerForm" asp-route-returnUrl="@Model.ReturnUrl" method="post">
 <h2>Create a new account.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.ConfirmPassword" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.ConfirmPassword">Confirm Password</label>
 <span asp-validation-for="Input.ConfirmPassword" class="text-danger"></span>
 </div>
 <button id="registerSubmit" type="submit" class="w-100 btn btn-lg btn-primary">Register</button>
 </form>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to register.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

Atualizei a parte superior com @page "/login" e agora testamos se funciona:

Também funciona!!

É issoEspero que você tenha aprendido como atualizar essas urls, principalmente porque em alguns projetos quando você está fazendo as urls de uma certa maneira e aí a Identidade fica diferente, é uma merda haha!

Se precisar de alguma coisa é só twittar para mim ou me enviar um e-mail e tentarei ajudar!

Atributos personalizados na API .NET 6 Core

Fri, 09 Dec 2022 00:00:00 +0000

Atributos personalizados são realmente uma boa coisa para usar, comecei a usá-los muito recentemente, porque eles me permitem criar um único deles e reutilizá-los no controlador, na classe ou no próprio método.

Eles realmente ajudam quando você deseja fazer algumas tarefas de segurança, como verificar cabeçalhos ou verificar o valor de um parâmetro que você definitivamente precisa.

No meu caso vamos utilizá-lo em um projeto de API .NET Core, onde vamos verificar se todas as solicitações contêm um determinado cabeçalho.

HeaderCheckAttribute

Então, depois de criarmos nossa API .NET Core, vamos criar uma pasta para armazenar nossas coisas, porque gostamos de usar pastas.

E então vamos adicionar a lógica à nossa classe HeaderCheckAttribute.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

namespace DotNet6CustomAttribute.Attributes
{
 public class HeaderCheckAttribute : ActionFilterAttribute
 {
 public override void OnActionExecuting(ActionExecutingContext context)
 {
 // Get all headers
 var headers = context.HttpContext.Request.Headers;

 // Check if headers has x-dotnet-6-custom-attribute
 if (!headers.ContainsKey("x-dotnet-6-custom-attribute"))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute is missing");
 }
 else if (string.IsNullOrEmpty(headers["x-dotnet-6-custom-attribute"]))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute can't be null or empty");
 }

 base.OnActionExecuting(context);
 }
 }
}

Basicamente a lógica é: primeiro ele verifica se há um cabeçalho com a chave x-dotnet-6-custom-attribute e se estiver lá, verifica se possui valores.

Se ambas as expressões forem verdadeiras, ele retornará um BadRequestObjectResult com uma determinada mensagem.

Adicionando-o ao controlador

Podemos adicionar essa lógica a vários lugares, podemos adicioná-la diretamente a todo o controlador, ou podemos adicioná-la a alguns dos métodos, vamos adicioná-la primeiro aos métodos e depois a todo o controlador.

Então vamos decorar a classe WeatherForecastController com eles.

using DotNet6CustomAttribute.Attributes;
using Microsoft.AspNetCore.Mvc;

namespace DotNet6CustomAttribute.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 private static readonly string[] Summaries = new[]
 {
 "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
 };

 private readonly ILogger<WeatherForecastController> _logger;

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

 [HttpGet]
 [Route("GetWeatherForecastWithCheck")]
 [HeaderCheckAttribute]
 public IEnumerable<WeatherForecast> GetWithCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }

 [HttpGet]
 [Route("GetWeatherForecastWithoutCheck")]
 public IEnumerable<WeatherForecast> GetWithoutCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }
 }
}

Vamos executar o projeto!

Temos 2 funções lá: GetWeatherForecastWithCheck e GetWeatherForecastWithoutCheck, uma delas irá falhar e a outra não, mas vamos dar uma olhada no Swagger!

Como você pode ver um deles retorna um erro 400 com nossa mensagem, e o outro retorna os valores, agora para testar isso completamente, vamos executar o Postman e adicionar um cabeçalho para que também vejamos os dados usando GetWeatherForecastWithCheck.

#Carteiro

Agora rodando no Postman, adicionamos o cabeçalho e vemos que a mensagem de erro mudou, pois agora fornecemos o cabeçalho, mas não há valor para ele

Se adicionarmos um valor a ele, finalmente obteremos os valores!

#É isso

Bem, é isso! Muito simples, certo? Bem, agora você sabe como criar um atributo e atribuí-lo a métodos e controladores!

Divirta-se com eles!

Código

Todo esse projeto está no Github e você pode encontrá-lo aqui!

Se você tiver qualquer problema ou dúvida, sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca (no Twitter é na verdade @emimontesdeocaa com dois aa no final). Você também pode encontrar a maioria das minhas redes sociais no cabeçalho do blog.

Espero que você tenha gostado da postagem! Cia!

Lidar com o carregamento de componentes no Blazor

Tue, 19 Jul 2022 00:00:00 +0000

O Blazor é incrível, realmente incrível, especialmente quando fazemos coisas assíncronas, como carregar caixas, e fica bom.

Tenho tentado fazer várias maneiras de lidar com o carregamento de páginas, estados, componentes, etc. E acho que finalmente encontrei a maneira perfeita de fazer isso da maneira que desejo.

Idéia

Em vez de reescrever a lógica de carregamento em cada página ou componente, construímos o componente pai com um ChildComponent, isso nos dará a mudança para apenas reutilizar várias vezes.

Carregando código do Componente

O código é bem simples, não há muito o que fazer, um if básico com uma propriedade de carregamento, uma função de alternância interna e pronto!

@if (_loaded)
{
 <div class="text-center">
 <div class="spinner-border" role="status">
 <span class="sr-only"></span>
 </div>
 </div>
}
else
{
 @ChildContent
}

@code {
 private bool _loaded = true;

 [Parameter]
 public RenderFragment? ChildContent { get; set; }

 public void ToggleLoad(bool state)
 {
 _loaded = state;
 }
}

Uso

O uso é bem simples, para fins de teste vamos usar uma nova página e colocar nosso conteúdo dentro do componente LoadingComponent criado que acabamos de criar.

@page "/loading"
@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 This is some content
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent;


 protected override async Task OnInitializedAsync()
 {
 // We are going to simulate some load
 await Task.Delay(5000);

 loadingComponent.ToggleLoad(false);
 }

}

É assim que parece

Exemplo mais engraçado

Digamos que temos vários componentes e cada um deles tem seus tempos de carregamento, podemos construir algo que fique bem com isso!

Vamos criar um componente de carregamento falso que podemos reutilizar chamado FakeLoadingComponent.

@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 It took @ellapsedTime seconds!
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent = new();
 private int ellapsedTime = 0;
 private Random rnd = new();

 protected override async Task OnInitializedAsync()
 {
 var random = rnd.Next(0, 5000);

 // We are going to simulate some load
 await Task.Delay(random);

 ellapsedTime = random/ 1000;

 loadingComponent.ToggleLoad(false);
 StateHasChanged();
 }
}

Depois é só atualizar a página Loading com vários componentes FakeLoadingComponent e verificar o resultado!!

@page "/loading"
@using LoadingBoxes.Components

<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>

Agora isso parece muito melhor

E é isso!

Se você tiver qualquer problema ou dúvida, sinta-se à vontade para entrar em contato comigo em qualquer mídia social em @emimontesdeoca (no Twitter na verdade é @emimontesdeocaa com dois aa no final). Você também pode encontrar a maioria das minhas redes sociais no cabeçalho do blog.

Espero que você tenha gostado da postagem!

Obtendo a data de validade de um certificado

Fri, 27 May 2022 00:00:00 +0000

Existem alguns aplicativos da web que ajudam você a verificar o status atual dos certificados dos domínios que usamos, e temos alguns deles.

Criei uma Azure Function que roda uma vez por dia e verifica alguns domínios que preciso dar uma olhada, é uma aplicação de console super simples que se a data de validade do certificado for menor que 30 dias, ele enviará um email.

A lógica de funcionamento da função em si não será mostrada, gostaria de mostrar a função que faz a verificação básica do certificado e quais dados obtemos.

A função

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

Este método CheckCertificateAsync nos retornará um certificado X509Certificate2 que nos permitirá fazer um monte de coisas, incluindo dar uma olhada na data de validade.

Resultado serializado

Este é o valor serializado do objeto certificate:

{
 "Archived":false,
 "Extensions":[
 {
 "KeyUsages":160,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.15",
 "FriendlyName":"Key Usage"
 },
 "RawData":"AwIFoA=="
 },
 {
 "EnhancedKeyUsages":[
 {
 "Value":"1.3.6.1.5.5.7.3.1",
 "FriendlyName":"Server Authentication"
 },
 {
 "Value":"1.3.6.1.5.5.7.3.2",
 "FriendlyName":"Client Authentication"
 }
 ],
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.37",
 "FriendlyName":"Enhanced Key Usage"
 },
 "RawData":"MBQGCCsGAQUFBwMBBggrBgEFBQcDAg=="
 },
 {
 "CertificateAuthority":false,
 "HasPathLengthConstraint":false,
 "PathLengthConstraint":0,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.19",
 "FriendlyName":"Basic Constraints"
 },
 "RawData":"MAA="
 },
 {
 "SubjectKeyIdentifier":"634E1585565AA49402C21642A4A5979A38025797",
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.14",
 "FriendlyName":"Subject Key Identifier"
 },
 "RawData":"BBRjThWFVlqklALCFkKkpZeaOAJXlw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.35",
 "FriendlyName":"Authority Key Identifier"
 },
 "RawData":"MBaAFBQusxe3WFbLrlAJQOYfr52LFMLG"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.5.5.7.1.1",
 "FriendlyName":"Authority Information Access"
 },
 "RawData":"MEcwIQYIKwYBBQUHMAGGFWh0dHA6Ly9yMy5vLmxlbmNyLm9yZzAiBggrBgEFBQcwAoYWaHR0cDovL3IzLmkubGVuY3Iub3JnLw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.17",
 "FriendlyName":"Subject Alternative Name"
 },
 "RawData":"MB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.32",
 "FriendlyName":"Certificate Policies"
 },
 "RawData":"MEMwCAYGZ4EMAQIBMDcGCysGAQQBgt8TAQEBMCgwJgYIKwYBBQUHAgEWGmh0dHA6Ly9jcHMubGV0c2VuY3J5cHQub3Jn"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.4.1.11129.2.4.2",
 "FriendlyName":"SCT List"
 },
 "RawData":"BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSA=="
 }
 ],
 "FriendlyName":"",
 "HasPrivateKey":false,
 "PrivateKey":null,
 "IssuerName":{
 "Name":"CN=R3, O=Let's Encrypt, C=US",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMw=="
 },
 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",
 "PublicKey":{
 "EncodedKeyValue":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"MIIBCgKCAQEAq8cbDO3GAfjqqbPPCBdPost8NMRmEubv85gXecll7mZMH5qSfTPuB/ouFWL3tPMf1U8usWeoSUK/48yatzBGwmj1KKlkaW9MS2QkydztRp+kH8LvbzbQvGknuOLWGHBALLT17o/3DYxuA5LnXdY+vLvJWygQoFr2N/XhnhUjcm6OaQEJpIykydfbBQGQSEuQIIw4egpgdHkYJjCOYAsXuSSggN8/FADTCec0RzVjfFTSoJ3hV9HLE9M8MCSXjuo0AJ/MbAxq91S8XmDcRjHCCd7Zw+NjHo8cxZCQ6NqGvn3xwx8ahmmbC+CyDEcIyJJZK2Yv+qE4oS8QZfaX/RaHMwIDAQAB"
 },
 "EncodedParameters":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"BQA="
 },
 "Key":{
 "Key":{
 "Algorithm":{
 "Algorithm":"RSA"
 },
 "AlgorithmGroup":{
 "AlgorithmGroup":"RSA"
 },
 "ExportPolicy":0,
 "Handle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "IsEphemeral":true,
 "IsMachineKey":false,
 "KeyName":null,
 "KeySize":2048,
 "KeyUsage":16777215,
 "ParentWindowHandle":{
 "value":0
 },
 "Provider":{
 "Provider":"Microsoft Software Key Storage Provider"
 },
 "ProviderHandle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "UIPolicy":{
 "ProtectionLevel":0,
 "FriendlyName":null,
 "Description":null,
 "UseContext":null,
 "CreationTitle":null
 },
 "UniqueName":null
 },
 "LegalKeySizes":[
 {
 "MinSize":512,
 "MaxSize":16384,
 "SkipSize":64
 }
 ],
 "KeyExchangeAlgorithm":"RSA",
 "SignatureAlgorithm":"RSA",
 "KeySize":2048
 },
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 }
 },
 "RawData":"MIIFQDCCBCigAwIBAgISBNwTmwP/RTcrEeIgAdMrpaFtMA0GCSqGSIb3DQEBCwUAMDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMzAeFw0yMjA1MDcwOTUwMzZaFw0yMjA4MDUwOTUwMzVaMCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCrxxsM7cYB+Oqps88IF0+iy3w0xGYS5u/zmBd5yWXuZkwfmpJ9M+4H+i4VYve08x/VTy6xZ6hJQr/jzJq3MEbCaPUoqWRpb0xLZCTJ3O1Gn6Qfwu9vNtC8aSe44tYYcEAstPXuj/cNjG4Dkudd1j68u8lbKBCgWvY39eGeFSNybo5pAQmkjKTJ19sFAZBIS5AgjDh6CmB0eRgmMI5gCxe5JKCA3z8UANMJ5zRHNWN8VNKgneFX0csT0zwwJJeO6jQAn8xsDGr3VLxeYNxGMcIJ3tnD42MejxzFkJDo2oa+ffHDHxqGaZsL4LIMRwjIklkrZi/6oTihLxBl9pf9FoczAgMBAAGjggJZMIICVTAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFGNOFYVWWqSUAsIWQqSll5o4AleXMB8GA1UdIwQYMBaAFBQusxe3WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5jci5vcmcvMCcGA1UdEQQgMB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wTAYDVR0gBEUwQzAIBgZngQwBAgEwNwYLKwYBBAGC3xMBAQEwKDAmBggrBgEFBQcCARYaaHR0cDovL2Nwcy5sZXRzZW5jcnlwdC5vcmcwggEGBgorBgEEAdZ5AgQCBIH3BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSDANBgkqhkiG9w0BAQsFAAOCAQEAjSEID5MWonbSiyHbmPYWO8ImCCOjkLGxgY8WJODbrWxFy+xU44UwrWOCkqYZUlv2LRmPqSyZDrIeeHK9VMbGh71oXX+XovikgAr6PpI0Mp897nPWj0XvOBaSYG0s+f+CXMtyt0tWCsQOcl+iT82+Ja71f8gbVL6l7xESewEE78pTKEH8EqD22r8VSD7FNICD8EYQr13v3AuVWObSU/R8Td6SrSVEknw1HgJS4e9nvmrMxBGKOJ+aWrAGiUydehg8M9o2gbGckMhz6D7cwB5l618cYaXKkW1dEOYZHl++qUj1/VPK+FNkiDZOPVNN//PbZuOLwAUIlZvhqGWX5/9PBg==",
 "SerialNumber":"04DC139B03FF45372B11E22001D32BA5A16D",
 "SignatureAlgorithm":{
 "Value":"1.2.840.113549.1.1.11",
 "FriendlyName":"sha256RSA"
 },
 "SubjectName":{
 "Name":"CN=blog.emilianomontesdeoca.com",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 "Thumbprint":"28CF960F772ABFF22AA193C291492C27F8E13D4D",
 "Version":3,
 "Handle":{
 "value":2658150705632
 },
 "Issuer":"CN=R3, O=Let's Encrypt, C=US",
 "Subject":"CN=blog.emilianomontesdeoca.com"
}

Data de validade

Para saber o tempo de expiração, precisamos dar uma olhada no NotAfter e NotBefore, que estão dentro deste objeto:

 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",

Aplicativo de console

O trecho a seguir é um aplicativo de console simples desenvolvido em .NET 6, que produzirá o seguinte resultado, no qual você pode verificar qualquer uma das certificações desejadas:

using Newtonsoft.Json;
using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Text.Json;

var url = "https://blog.emilianomontesdeoca.com/";

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

var cert = await CheckCertificateAsync(url);

var serializedValue = JsonConvert.SerializeObject(cert);

Console.WriteLine(serializedValue);

Console.ReadLine();

Projeto de demonstração

Você pode encontrar o aplicativo de console em meu Github, no repositório chamado expiration-date-certificate.

Focando um elemento no Blazor

Thu, 05 May 2022 00:00:00 +0000

Depois de trabalhar no jogo Wordlzor que fiz recentemente, precisei adicionar uma funcionalidade bastante simples: focar o jogo inteiro ao entrar.

Isso precisava ser feito porque o usuário poderia realmente digitar no jogo e não apenas usar o teclado na tela.

##Arquivo Javascript

Para fazer isso, temos que criar um arquivo Javascript chamado app.js que conterá uma função

window.FocusElement = (element) => {
 element.focus();
};

Depois de fazer isso, precisamos incluir o script no arquivo index.html:

<script src="js/app.js"></script>

Componente Blazor

Depois de inicializarmos o script, precisamos encontrar um elemento no qual focar, portanto, em qualquer um de nossos componentes, precisamos referenciar esse elemento a um objeto.

Então, em nosso componente blazor, vamos adicionar uma div com Propriedade @ref:

<div @ref=@elementToFocus tabindex="0" >
 This is my focus component
</div>

Então na lógica do componente você pode ter a propriedade como um ElementReference:

/// <summary>
/// Reference to element
/// </summary>
private ElementReference elementToFocus;

Injetando JSInterop

Agora, para chamar a função que temos em nosso arquivo Javascript, precisamos usar JSInterop.

Primeiramente devemos injetá-lo no componente com a seguinte sintaxe:

[Inject]
public IJSRuntime JSRuntime { get; set; }

Com o serviço injetado, agora podemos chamar qualquer um dos métodos que ele possui, como InvokeVoidAsync, que chamará a função:

public async Task Focus()
{
 // Focus when initializing
 await JSRuntime.InvokeVoidAsync("window.FocusElement", elementToFocus);
}

E quando você chamar a função Focus(), ela focará o elemento que criamos, obviamente você pode refatorar e passar o próprio elemento como parâmetro.

Se quiser dar uma olhada em como eu implementei, dê uma olhada no código fonte do Wordlzor, usei ele para alertas e foco ao fechar o modal de instrução.

Gere arquivos *.dacpac do projeto VS Database em GitHub Actions

Mon, 18 Apr 2022 00:00:00 +0000

Se você precisa trabalhar com banco de dados e quer fazer desenvolvimento ágil, você tem que ter um fluxo onde sempre que você adicionar ou modificar uma tabela, SP, função, ele irá compilar e gerar o arquivo de implantação do banco de dados.

Já faço essa abordagem há muito tempo, fazemos as alterações no local, comparamos com nosso projeto de banco de dados e então quando fazemos commit e push de nossas alterações, elas geram um arquivo bacpac que irá para o banco de dados.

Elimina todo o trabalho de fazer isso manualmente, o que pode causar um erro humano e em um banco de dados, o que é uma péssima notícia.

Projeto de banco de dados

Quando criamos nosso projeto de banco de dados no Visual Studio e importamos um banco de dados, ficará assim

Quando rodarmos uma compilação neste projeto, ele irá gerar um arquivo dacpac que incluirá toda a nossa estrutura

Pipeline do Github

Agora que temos nosso código publicado no repositório, precisamos criar uma ação que irá compilar esse projeto, gerar esse arquivo dacpac e colocá-lo em algum lugar onde possamos baixar ou usar em outra etapa.

name: DacpacGithubActions project build

on:
 push:
 branches: main

jobs:
 build:
 runs-on: windows-latest

 steps:
 - uses: actions/checkout@v2

 - name: Setup MSBuild
 uses: microsoft/setup-msbuild@v1

 - name: Navigate to Workspace
 run: cd $GITHUB_WORKSPACE

 - name: Create Build Directory
 run: mkdir artifacts

 - name: Build Solution
 run: |
 msbuild.exe /t:DacpacGithubActions /p:DebugSymbols=false /p:DebugType=None /p:DeployOnBuild=true /p:WebPublishMethod=FileSystem /p:OutDir="../artifacts"
 
 - name: Upload artifact
 uses: actions/upload-artifact@v1.0.0
 with:
 name: DacpacGithubActionsArtifacts
 path: "../artifacts"

Esta ação fará um monte de coisas, construirá a solução e colocará o resultado na pasta artifacts, criada previamente, e então fará o upload dos arquivos dessa pasta para os artefatos.

Executando o pipeline

Agora vá em frente e acione uma compilação, o resultado deve ser o seguinte

Se realmente baixarmos o artefato e dermos uma olhada no conteúdo, é o que precisamos para o futuro, quando implementarmos uma etapa de implantação contínua, o arquivo dacpac!

Código

Todo esse projeto está no Github e você pode encontrá-lo aqui!

Espero que você tenha gostado da postagem! Cia!

Alternar temas com Javascript Interop no Blazor

Fri, 01 Apr 2022 00:00:00 +0000

Para pessoas como eu, que sofrem com flashbacks toda vez que abro uma página da web, criei uma solução super simples sobre como alternar entre o modo claro e escuro usando Javascript e chamá-lo do Blazor usando Javascript Interop.

#Definindo o atributo pai

Em primeiro lugar, temos que identificar o elemento pai com um identificador, isto porque mudamos as cores dependendo do valor desse identificador.

Para fazer isso em Javascript, teríamos que executar este comando

document.documentElement.setAttribute('data-theme', 'YOUR_IDFENTIFIER');

No nosso caso, queremos ter dois identificadores para cada tipo de estilo, que são light e dark.

Criando arquivo Javascript para lidar com a lógica

Agora temos a função de atualizar o identificador, agora vamos criar um arquivo Javscript com uma função que execute essa lógica. Nosso arquivo se chamará app.js

Nesse arquivo teremos uma função que chamará o código que mencionamos anteriormente.

var toggleTheme = function (identifier) {
 document.documentElement.setAttribute('data-theme', identifier);
}

Adicionando arquivo Javascript ao Blazor

Adicione o script ao aplicativo Blazor adicionando-o onde os scripts estão localizados.

<script src="~/js/app.js"></script>

Criando o serviço

Agora que temos o código Javascript, precisamos criar um serviço que se chamará ThemeToggleService.

Este serviço tratará da lógica para alternar entre o tema light e dark.

Injetando JSInterop

Para chamar qualquer Javascipt, temos que chamar o JSInterop, então temos que criar uma propriedade que irá injetar.

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }
}

Função para definir o identificador

Agora que criamos o serviço, vamos criar a função para definir o identificador, esta função irá apenas atualizar o data-theme na página.

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 public class ThemeToggleService
 {
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }

 public bool IsLightTheme { get; set; } = true;
 public string GetIdentifier => IsLightTheme ? "light" : "dark";

 public async Task ToggleTheme() {
 IsLightTheme = !IsLightTheme;
 await jSRuntime.InvokeVoidAsync("toggleTheme", GetIdentifier);
 }
 }
}

Adicionar serviço à inicialização

Para disponibilizar o serviço para todos os componentes e páginas, temos que adicioná-lo ao arquivo Program.cs.

builder.Services.AddSingleton<ThemeToggleService>();

Então o arquivo vai ficar assim

using BlazorDarkmodeToggle.Data;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSingleton<WeatherForecastService>();
builder.Services.AddSingleton<ThemeToggleService>();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();

app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();

Lembre-se de que isso pode mudar dependendo se você usa o Blazor Server ou o Blazor WebAssembly.

Preparando o CSS

Agora que temos parte do código pronto, temos que começar a trabalhar no CSS. O que precisamos fazer é definir todas as propriedades CSS que tratam das cores CSS, plano de fundo, etc.

:root {
 --background-color:#ffffff;
 --text-color:#000000;
}

Depois de fazer isso, usando o identificador, podemos facilmente alternar entre os identificadores, e ele usará qualquer um dos outros valores.

[data-theme="dark"] {
 --background-color: #000000;
 --text-color: #ffffff;
}

Para o desvanecimento legal da animação, vamos apenas adicionar uma propriedade transition a todas, para que fique bem.

* {
 transition: all 250ms;
}

Agora iremos atribuir essas variáveis a algumas classes css, para que possamos vê-las na página do Blazor.

.app-background {
 background-color: var(--background-color);
 width: 200px;
 height: 200px;
}

.app-text {
 color: var(--text-color);
}

Lembre-se de adicionar o arquivo ao aplicativo Blazor adicionando-o no head.

<link href="css/app.css" rel="stylesheet" />

Chamando do Blazor

Então, como vamos testar isso? Para simplificar, vamos apenas adicionar uma div com a classe app-background, e dentro dela terá um p com a classe app-text.Então, vamos criar uma página chamada Theme.razor na pasta Pages e adicionar algum código para isso

@page "/theme"
@using BlazorDarkmodeToggle.Data
@inject ThemeToggleService ThemeToggleService

<button class="btn btn-primary" @onclick=Toggle>Toggle theme</button>

<br />

<div class="app-background">
 <p class="app-text">Hello world!</p>
</div>

@code{
 public async Task Toggle()
 {
 await this.ThemeToggleService.ToggleTheme();
 }
}

Poderíamos testar isso acessando /theme, mas também vamos adicioná-lo à barra de navegação

<div class="nav-item px-3">
 <NavLink class="nav-link" href="theme">
 <span class="oi oi-list-rich" aria-hidden="true"></span> Theme togle
 </NavLink>
</div>

Teste

Como você pode ver, assim que alternamos as mudanças de tema, fundo e cor da fonte, agora você pode ver o quão poderoso isso é, se você realmente desenvolver a página inteira usando essas variáveis em CSS, você poderá ter temas diferentes e apenas alterná-los!

Que incrível!!

Código

Todo esse projeto está no Github e você pode encontrá-lo aqui!

Espero que você tenha gostado da postagem!

Recursos

Chamar funções JavaScript de métodos .NET no ASP.NET Core Blazor

Carregando arquivos para o Azure Blob Storage no Blazor

Wed, 23 Mar 2022 00:00:00 +0000

O serviço de armazenamento Azure Blob é um dos serviços mais utilizados no ecossistema Azure, permite fazer upload de muitos arquivos para a nuvem e é super barato. Também possui um site intuitivo onde você pode acessá-los ou baixá-los por um link direto.

No geral, é um serviço muito bom, tenho usado tanto para projetos profissionais quanto pessoais e, honestamente, o melhor é a simplicidade de como fazê-lo funcionar.

A maioria dos casos que usei o Azure Blob Storage está no backend, carregando diretamente algo que é resultado de uma operação ou algo assim. Então, eu realmente não fiz nenhum tipo de upload de um arquivo de um site ou algo assim. Azarado!

Como sou fã do Blazor, estou apresentando uma maneira de fazer upload de arquivos para um armazenamento de Blob do Azure usando a entrada de arquivo nativa do HTML5.

Pré-requisitos

Conta Azure (se você não tiver, vá aqui com um monte de $$$).
Um IDE (VS, Código, qualquer um funcionará)
.NET Core 3.0 ou superior

Criando um Armazenamento de Blobs do Azure

Vá para o seu portal do Azure e vamos criar uma conta de armazenamento.

Primeiro pesquise por Storage accounts e clique no resultado.

Após carregar, clique em Create.

Um formulário aparecerá com várias etapas, então vá em frente e preencha-as.

Após preencher tudo com as configurações desejadas, passe na validação e crie o recurso.

Depois de criado, clique em Go to resource. Obteremos uma string de conexão que nos permitirá brincar com a API.

Obtenha as chaves de recursos

Depois de chegarmos ao nosso recurso recém-criado, vá para Acccess keys em Security + networking. Após carregar você verá um Connection string e Key, copie-os porque precisaremos deles mais tarde!

Criando um projeto legal do Blazor Server

Vou usar o Visual Studio 2022 para este tutorial, mas como disse antes, você pode usar qualquer outro IDE e apenas criar o projeto usando a CLI dotnet.

Então, vamos criar um projeto Blazor bem rápido usando o Visual Studio em apenas algumas etapas.

Se executarmos o que acabamos de criar, ficará assim, apenas um aplicativo Blazor normal e simples.

Agora que criamos o projeto, vamos fazer algumas coisas de UI para termos uma nova página com um monte de entradas para que possamos preencher com as chaves do recurso, um InputFile para o(s) arquivo(s), um botão para fazer algo e uma mensagem que resultará da ação.

Criando o modelo

Precisaremos de alguns modelos para fazer isso corretamente. Primeiro teremos a classe BlobRequest que tratará a string de conexão, o nome do contêiner e os arquivos.

Além disso, para manter tudo organizado, criaremos uma classe chamada BlobFile na qual armazenaremos o Name e o Data.

Criei uma pasta chamada Models então temos tudo separado.

As aulas são muito simples.```csharp using System.ComponentModel.DataAnnotations;

namespace UploadingFilesAzBlobBlazor.Models { public class BlobRequest { [Required(ErrorMessage = “Connection string is required”)] public string? ConnectionString { get; set; } [Required(ErrorMessage = “Container name is required”)] public string? Container { get; set; } public List? Files { get; set; } } }


```csharp
namespace UploadingFilesAzBlobBlazor.Models
{
 public class BlobFile
 {
 public string? Name { get; set; }
 public byte[]? Data { get; set; }
 }
}

Modificando a IU

Agora que criamos nosso modelo, vamos em frente e fazer mágica na UI com ele!

Primeiro de tudo, crie uma página na pasta Pages chamada Upload.razor.

Nesta página vamos adicionar um pequeno formulário que preencherá nossa classe BlobRequest, então temos que adicionar entradas para ConnectionString, Container e Files.

@page "/upload"
@using UploadingFilesAzBlobBlazor.Models
@inject IJSRuntime JsRuntime
<PageTitle> Upload</PageTitle>

<h1> Azure blob storage uploader!</h1>

<EditForm Model="@modal" OnValidSubmit="@HandleValidSubmit">
<DataAnnotationsValidator />
<ValidationSummary />

<div class="mb-3">
<label for="connectionString" class="form-label"> Connection string</label>
<InputText class="form-control" id="connectionString" @bind-Value="modal.ConnectionString" />
</div>

<div class="mb-3">
<label for="container" class="form-label"> Container name</label>
<InputText class="form-control" id="container" @bind-Value="modal.Container" />
</div>

<div class="mb-3">
<label for="formFileMultiple" class="form-label"> Files</label>
<InputFile OnChange="OnInputFileChange" class="form-control" id="formFileMultiple" multiple />
</div>

<div class="mb-3">
<button type="submit" class="btn btn-primary"> Submit</button>
</div>
</EditForm>

@code {
 private BlobRequest modal = new();
 private EditContext editContext;
 IReadOnlyList <IBrowserFile> selectedFiles;
 private void OnInputFileChange(InputFileChangeEventArgs e)
 {
 selectedFiles = e.GetMultipleFiles();
 this .StateHasChanged();
 }

 private async Task HandleValidSubmit() {
 // This is where we are going to upload stuff ! 
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
}

É um pouco de código, mas basicamente renderizará o formulário e tratará da validação.

Se você pressionar o botão para fazer upload e estiver tudo bem, será exibido um alerta.

Fazendo upload para o Armazenamento de Blobs do Azure

Agora que concluímos a maior parte da interface do usuário, vamos instalar o pacote que manipulará a API do Azure Blob Storage e nos permitirá fazer upload de arquivos. Muito simples.

Adicione o pacote NuGet

Vamos gerenciar os pacotes NuGet do projeto e adicionar Azure.Storage.Blob.

Carregar para Azure Blob Stoare

Agora vamos fazer a lógica para realmente fazer o upload do arquivo, normalmente usaríamos a string de conexão e a chave do app.config, mas para o propósito deste tutorial, usamos entradas e fornecemos os dados lá.

Primeiro, vamos adicionar o using para a classe Azure Blob Storage

@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models

Então vamos trabalhar no método HandleValidSubmit, que vai se conectar ao armazenamento de blob, criar o contêiner se ele não existir e depois fazer upload dos arquivos.

private async Task HandleValidSubmit()
{
 try
 {
 // Instantiate container
 var container = new BlobContainerClient(modal.ConnectionString, modal.Container);
 // Create container if not exists
 var createResponse = await container.CreateIfNotExistsAsync();
 // Set access policy
 if (createResponse != null && createResponse.GetRawResponse().Status == 201)
 {
 await container.SetAccessPolicyAsync(Azure.Storage.Blobs.Models.PublicAccessType.Blob);
 }

 // For each file that we have uploaded
 foreach (var file in selectedFiles)
 {
 // New blob
 var blob = container.GetBlobClient(file.Name);
 // Delete any blob with the same name
 await blob.DeleteIfExistsAsync(Azure.Storage.Blobs.Models.DeleteSnapshotsOption.IncludeSnapshots);
 // Create a file stream and use the UploadSync method to upload the Blob.
 using (var fileStream = file.OpenReadStream())
 {
 await blob.UploadAsync(fileStream, new BlobHttpHeaders { ContentType = file.ContentType });
 }
 }

 // Display success message
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
 catch (Exception e)
 {
 // Display error message
 await JsRuntime.InvokeVoidAsync("alert", "An error ocurred!");
 }
}

Testando o código

Agora é hora de testar o código, para isso basta preencher o formulário e clicar em enviar.

Iremos exibir um alerta e o arquivo deverá ser carregado no Azure Blob Storage, acesse o Portal do Azure e dê uma olhada.

Como você pode ver, o container também foi criado, agora se entrarmos no container, vemos o arquivo que carregamos.

Bom trabalho!

Refatorar

Agora que tudo funcionou, vamos mover o código da página .razor para uma classe .razor.cs para que fique melhor.

Se você estiver usando o Visual Studio 2022, há uma lâmpada quando você passa o mouse no @code, ele mostrará uma opção para Extract block to code behind, e fará o que diz!

Agora você vai ter tudo separado e pronto!

Código

Todo esse projeto está no Github e você pode encontrá-lo aqui!

Espero que você tenha gostado da postagem! Cia!

Recursos

Substituindo um controlador principal do Pimcore

Thu, 10 Dec 2020 00:00:00 +0000

Estou trabalhando em um projeto Pimcore há algum tempo, nunca toquei em PHP e Symfony na minha vida, então tem sido um grande desafio.

A documentação é ótima, quero dizer, sério, é ótima, mas parece que não foi feita para iniciantes na linguagem/framework, então tudo o que fiz tive que anotar.

Depois de aprender que você pode estender o Pimcore usando pacotes, passei horas e horas tentando substituir controladores, métodos javascript e muito mais.

Então neste post vou explicar como consegui sobrescrever um controlador. Como substituir arquivos javascript virá mais tarde 😎.

Criando o pacote

Primeiro de tudo precisamos criar um pacote para ele, é bem simples como está documentado na documentação do Pimcore, só precisamos executar bin/console pimcore:generate:bundle --namespace=EmiDemo/EmiDemoBundle na pasta do projeto.

Isso levantará algumas perguntas, mas nada com que se preocupar.

Irá criar uma nova pasta na pasta src com o namespace que declaramos antes, e dentro teremos todos os arquivos necessários para o pacote.

Além disso, o plugin será detectado pelo site de administração do Pimcore, mas será desabilitado, você deve habilitá-lo para começar a usá-lo.

#Substituindo um método de um controlador

Para sobrescrever um método em um controlador, primeiro obviamente você precisa encontrar a ação que deseja atualizar, isso parece fácil, mas vou lhe mostrar como costumo fazer (aprendi com meu colega de equipe Cesar).

Primeiro entre na página que você acha que o controlador entra em ação, no meu caso quero verificar aquela que carrega quando abrimos um ativo

Depois é só abrir o console e ir na aba rede, fazer os mesmos passos novamente e tentar encontrar a ação

Com essas informações você pode ver que a ação que carrega o ativo é http://localhost/admin/asset/get-data-by-id?_dc=1607601778450&id=2&type=image. A partir disso podemos ver que a ação do controlador é get-data-by-id.

Encontre a ação no controlador principal

Para mim, a maneira mais simples de fazer isso é encontrar em todos os arquivos do Visual Studio Code

Provavelmente encontrará mais de um então você deve dar uma olhada e decidir qual é, no nosso caso estamos trabalhando com assets então fica claro que queremos usar o AssetController.php.

Modifique o controlador principal

Depende do desenvolvedor, normalmente não faço isso porque é mais rápido simplesmente substituir o controlador e desenvolver a partir daí. Mas eu recomendo primeiro atualizar o controlador no pacote principal para ver se suas alterações funcionam.

No nosso caso retornarei apenas uma mensagem no início do método para verificar se funciona.

return $this->adminJson(['success' => false, 'message' => "Overriding the getDataByIdAction in the core!!"]);

Então vamos recarregar nosso ativo e verificar a aba rede

Vamos manter o que temos lá, para mais tarde sabermos que estamos usando a mensagem do pacote em vez da mensagem principal.

Agora vamos apenas copiar isso para um arquivo temporário para acompanhar o que fizemos.

Mova essas alterações para o pacote

Agora, para mover essas alterações para o nosso pacote, primeiro precisamos de algumas coisas do nosso controlador principal:

Espaço para nome
Importações
Nome do controlador

E obviamente o método getDataByIdAction que é aquele que queremos substituir.

Exponha o controlador

Precisamos expor o controlador, para fazer isso você precisa entrar no arquivo /src/EmiDemo/EmiDemoBundle/Resources/config/pimcore/routing.yml e adicionar

options:
 expose: true

Também precisamos mudar o prefix para aquele que iremos substituir, no nosso caso o controlador admin.

Então no final você vai ficar assim

emi_demo_emi_demo:
 resource: "@EmiDemoEmiDemoBundle/Controller/"
 type: annotation
 prefix: /admin
 options:
 expose: true

DefaultController.php

Em nosso arquivo, adicionaremos as importações e estenderemos o controlador com aquele que substituiremos

Então iremos apenas copiar o método do controlador principal e, no nosso caso, atualizar a mensagem que retornamos.

Se você se lembra, já temos uma mensagem no controlador principal: Overriding the getDataByIdAction in the core!! e agora devemos ver Overriding the getDataByIdAction in the bundle!!

Vamos apenas não retornar nada e ver que agora podemos ver a página como era antes

Comente a declaração de retorno e recarregue

É isso

E com esta pequena demonstração você pode ver como é fácil substituir um controlador central Pimcore existente. Existem alguns passos que você deve seguir, mas não é nada difícil. Apenas certifique-se de expor o controlador e limpar o cache de vez em quando enquanto estiver fazendo alterações, às vezes ele fica armazenado em cache e você fica pensando que não está funcionando e apenas está armazenado em cache.

Se você está se perguntando como substituir os arquivos javascript, isso virá em outro tutorial 😁.

Configure o Apple Magic Keyboard 2 no Windows 10

Wed, 11 Nov 2020 00:00:00 +0000

Ainda ontem comprei um Apple Magic Keyboard 2, mesmo tendo uns 5 teclados mecânicos, porque queria experimentar e era wireless.

Meu sistema operacional principal é o Windows 10, adoro ele e não quero trocá-lo então pensando nisso sabia que seria necessário fazer algumas coisas para que o teclado funcionasse perfeitamente. Eu sei como a Apple funciona e como eles gostam de manter seus dispositivos em seu ecossistema.

Problemas

Se você emparelhar o teclado, reconhecerá algumas coisas:

*As teclas de função não funcionam

Algumas teclas estão mapeadas incorretamente (isso aconteceu comigo na versão em espanhol)

Documentação

Para fazer funcionar tive que ler muito na web, mas esses dois links são os que me ajudaram a fazer funcionar:

Instalando o driver do teclado Apple

Algumas dessas etapas são da documentação mencionada anteriormente:

Instale o 7zip no seu computador, caso ainda não o tenha.
Instale Python (versão 2.x) em seu computador, caso não o tenha.
- IMPORTANTE: A versão mais recente do Python é 3.x. Porém, você precisa da versão 2.x porque o script brigadeiro não é compatível com a versão 3.x.
- (opção) O instalador, por padrão, não adiciona python.exe ao seu PATH. Se desejar, você precisa habilitar esta opção. (veja a imagem à direita)
- Se você já possui outra versão do Python, provavelmente não deseja ativar esta opção.
Baixe o brigadier (um script Python que ajuda você a baixar a versão mais recente do Boot Camp).
Clique com o botão direito no link a seguir e salve o arquivo usando “Salvar link como…”. https://raw.githubusercontent.com/timsutton/brigadier/master/brigadier
Abra a janela do prompt de comando (também conhecida como caixa DOS) e mude o diretório para onde você baixou o script brigadier.
Supondo que o script brigadier foi salvo como “brigadier.txt”, execute o seguinte comando:
- Se o Python versão 2.x estiver em seu PATH: python brigadier.txt –model=MacBook13,2
- Caso contrário: [Caminho para a versão 2.x do Python]\python.exe brigadier.txt –model=MacBook13,2
Ele irá baixar um grande pacote com todos os drivers do bootcamp
Crie uma pasta chamada BootCamp e copie BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\BootCamp.msi e BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\AppleKeyboardMagic2 nela.
Execute um powershell de administrador e execute o BootCamp.msi, ele irá instalar algumas coisas, mas precisamos atualizar o driver usando o conteúdo da pasta AppleKeyboardMagic2
Inicie o Gerenciador de Dispositivos (devmgmt.msc)
Expanda o nó Human Interface Devices
Procure por Bluetooth HID Device
Atualize o driver usando o conteúdo da pasta AppleKeyboardMagic2
Reinicie o computador

Você deverá ver o teclado bluetooth agora detectado como um teclado Apple

Atualizar comportamento das teclas FNSe você instalou tudo corretamente você notará que as teclas FN estão habilitadas por padrão, isso significa que você precisa pressionar `fn` + `F5` para realmente pressionar o botão `F5`.

Para corrigir isso, encontrei uma solução, indicada na seção de documentação, que funciona alterando alguma entrada no regedit.

Abra o regedit
Vá para HKEY_CURRENT_USER\SOFTWARE\Apple Inc.\Apple Keyboard Support
Crie ou atualize OSXFnBehavior e defina-o como 0
Reinicie o computador

Atualizar mapeamento de chaves

Se você tiver algum problema com os mapeamentos, você pode usar SharpKeys e atualizá-los.

É muito simples de usar, mas lembre-se de sair ou reiniciar o computador para habilitar as atualizações, pois atualiza o registro.

No meu caso, tive que atualizar as chaves Windows, alt, º e <>.

Adicionando bibliotecas compiladas a um pacote NuGet

Thu, 01 Oct 2020 00:00:00 +0000

Outro dia encontrei um bug sobre um NullReferenceException em uma biblioteca ausente que deveria estar lá, pois vem de um pacote nuget que carregamos.

Basicamente, compilei uma classe de biblioteca que fazia referência a alguns projetos. Na fase de construção, ele adicionaria os arquivos dll à pasta bin, mas quando packaging fosse um pacote nuget e os instalasse em outra solução, os arquivos dll que mencionei e deveriam ser copiados para a pasta bin, não estão lá.

Como resolver

Resolver este problema é bem simples, você tem que atualizar o arquivo nuspec e para cada uma das bibliotecas que deseja copiar, adicione o file na parte files.

<?xml version="1.0" encoding="utf-8"?>
<package >
 <metadata>
 <id>$id$</id>
 <version>$version$</version>
 <title>$title$</title>
 <authors>$author$</authors>
 <owners>$author$</owners>
 <requireLicenseAcceptance>false</requireLicenseAcceptance>
 <license type="expression">MIT</license>
 <projectUrl>$projectUrl$</projectUrl>
 <iconUrl>$projectIconUrl$</iconUrl>
 <description>$description$</description>
 <releaseNotes></releaseNotes>
 <copyright>$copyright$</copyright>
 <tags></tags>
 </metadata>
 <files>
 <file src="bin\Release\MyFile1.dll" target="lib\net47" />
 <file src="bin\Release\MyFile2.dll" target="lib\net47" />
 <file src="bin\Release\MyFile3.dll" target="lib\net47" />
 <file src="bin\Release\MyFile4.dll" target="lib\net47" />
 </files>
</package>

Faça o carregamento do terminal no diretório inicial do WSL

Tue, 22 Sep 2020 00:00:00 +0000

Tenho adorado o WSL para desenvolvimento e testes desde o dia em que foi lançado, então o aplicativo Terminal caiu e eu não poderia estar mais feliz, parece bom, funciona perfeitamente e ótimo desempenho.

Seria estúpido não usá-lo com a distribuição WSL em vez de usar o console que ela oferece.

Este console é obviamente bom, mas depois de usar o Terminal, não há como voltar atrás. É muito melhor, também cor.

Agora, se você iniciar o terminal e abrir uma nova aba para carregar sua distribuição WSL, ele carregará sua pasta de usuário montada.

Isso não é realmente um problema, porque se você apenas fizer cd ~ ele apenas carregará a pasta do usuário da distribuição.

O problema é que não quero fazer isso de novo e de novo, então vamos atualizar um arquivo para fazer isso sozinho.

.bashrc

Abra o terminal ou console, vá para a pasta do seu perfil e edite o arquivo .bashrc usando seu editor de texto favorito.

Adicione cd ~ no final do arquivo antes da última instrução.

Salve, reabra o console WSL com o terminal e você deverá estar na pasta de perfis.

Tenha em mente que você terá que fazer isso para todas as suas instalações WSL, já que estamos atualizando o arquivo bashrc para uma única instalação.

Geração dinâmica de objetos usando ExpandoObject

Fri, 06 Mar 2020 00:00:00 +0000

Eu estava precisando converter arquivos do Excel com suas próprias colunas definidas para um novo com colunas dinâmicas e fiquei meio confuso sobre como fazer isso corretamente, sem sérios problemas de desempenho.

Cheguei a um tutorial que você pode encontrar aqui que usa .NET ExpandoObject que praticamente permite criar um objeto e adicionar membros dinâmicos.

ExpandoObject

A definição da Microsoft é:

Representa um objeto cujos membros podem ser adicionados e removidos dinamicamente em tempo de execução.

E tem algumas observações:

A classe ExpandoObject permite adicionar e excluir membros de suas instâncias em tempo de execução e também definir e obter valores desses membros. Esta classe suporta ligação dinâmica, o que permite usar sintaxe padrão como sampleObject.sampleMember em vez de sintaxe mais complexa como sampleObject.GetAttribute(“sampleMember”).

Comportamento atual

Temos um ExcelExportService que, ao passar um List<T>, neste caso ExcelItem, usará Reflection para criar um arquivo xlsx.

Até agora, nosso código está assim:

class ExcelItem
 {
 public int Id { get; set; }
 public string Name { get; set; }
 public string Surname { get; set; }
 public string Age { get; set; }
 public string CreatedAt { get; set; }
 public string UpdatedAt { get; set; }
 }

ExcelItem é o objeto com todas as propriedades que estão sendo utilizadas para gerar o arquivo excel.

public static byte[] GetExcelBytes() {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var items in itemsToExcel)
 {
 excelItems.Add(new ExcelItem()
 {
 Id = item.Id,
 Name = item.Name,
 Surname = item.Surname,
 Age = item.Age,
 CreatedAt = item.CreatedAt
 UpdatedAt = item.UpdatedAt
 });
 }

 return exportService.ExportToExcel(excelItems);
}

Esta abordagem funciona perfeitamente, o arquivo xlsx é gerado sem problemas com cada coluna sendo cada propriedade, você usaria este método GetExcelBytes assim, por exemplo, para salvá-lo em um arquivo:

File.WriteAllBytes("path-to-somewhere/my-file.xlsx", GetExcelBytes());

O problema

Já que o que estamos fazendo certo é usar todas as propriedades do objeto ExcelItem, tudo que eu quero é não usar todas elas, apenas usando talvez 2 ou 3 delas.

Também é um requisito que eu não queira alterar o código, tudo deve ser feito pelo administrator, que decidirá quais colunas devem ser mostradas, podendo ou não conhecer as propriedades do código.

TLDR: tudo deve ser dinâmico, temos um objeto com propriedades e devemos ter certeza de que o arquivo gerado possui N propriedades desse objeto, mas obviamente não codificado.

Colunas dinâmicas

A mudança seria utilizar um objeto dynamic, pois gostaríamos de definir quais propriedades do objeto serão utilizadas para gerar a lista de colunas.

Digamos que temos um objeto com muitas propriedades, como uma tonelada delas, e não queremos realmente alterar o objeto ExcelItem toda vez que fizermos uma alteração, criamos uma tabela ColumnExcelItem, que será usada para gerar esse ExcelItem.

Estrutura do banco de dados

Salvamos esta definição em nosso banco de dados com algo assim:

Id PropertyName
---------------------
1 Name
2 Surname
3 Age

Observe que temos menos valores que as propriedades existentes do objeto ExcelItem, sendo que ele possui propriedades 6 e só temos 3 listado no banco de dados.

Observe também que PropertyName deve corresponder ao nome da propriedade do objeto que usarei para a atribuição dinâmica.

Construindo o objeto

Agora que temos a tabela do banco de dados, precisamos construir o repositório para obtê-la e poder usá-la no código.Não farei um tutorial desta parte, vou pular logo no início da nova função GetExcelBytes().

public static byte[] GetExcelBytes(List<string> columns) {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 List<dynamic> objectsToExcel = new List<dynamic>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var item in itemsToExcel)
 {
 dynamic newObject = new ExpandoObject();
 foreach (var col in columns)
 {
 this.AddProperty(newObject, col, product.GetType().GetProperty(col).GetValue(item, null));
 }

 objectsToExcel.Add(newObject);
 }

 return exportService.ExportToExcel(objectsToExcel);
}

Agora teremos a criação de um objeto com algumas das propriedades de ExcelItem, mas completamente dinâmico. Em vez de usar todas as 6 propriedades, estamos usando apenas 3 delas, aquela que queremos apenas enviar.

Agora vamos fingir que este objeto ExcelItem tem 200 propriedades, louca, mas isso pode acontecer.

A única coisa que preciso fazer é inserir as propriedades que desejo renderizar no arquivo Excel naquela tabela ColumnExcelItem e pronto.

Casos

Neste caso usamos apenas um caso, mas digamos que você deseja ter relatórios diferentes para alguns usuários. Digamos que o papel admin deva obter todas as propriedades, então você criaria algo como esta estrutura no banco de dados

ReportingTemplates

Id PropertyName
---------------------
1 Admin
2 Users

ReportingTemplateItems

Id TemplateId PropertyName
---------------------
1 1 Id
2 1 Name
3 1 Surname
4 1 Age
5 1 CreatedAt
6 1 UpdatedAt
7 2 Name
8 2 Surname
9 2 Age

Então, ao obter o modelo, você poderá ter colunas diferentes, todas dinamicamente e sem código relacionado.

Se tivermos um usuário com a função Admins, o arquivo conterá as colunas Id, Name, Surname, Age, CreatedAt, UpdatedAt.

Caso você gere-o usando a função Users, ele terá Name, Age. Surname.

Conclusão

Esta é uma maneira legal de aprender como o dynamic funciona no .NET, e é uma solução muito boa quando você precisa ter funções ou modelos diferentes para usuários diferentes e não está realmente interessado em investir tempo codificando coisas.

Entrega contínua de pacote NuGet usando TravisCI

Tue, 21 Jan 2020 00:00:00 +0000

Recentemente fiz um tutorial sobre como usar o Travis CI como uma ferramenta para testar automaticamente seu código que você acabou de enviar ou está tentando enviar para o branch master. Fazendo com que ele seja compilado e testado e finalmente informe o status dessa mudança.

Mas podemos continuar melhorando, por exemplo, a biblioteca principal que foi feita no último tutorial, quero torná-la pública usando o feed NuGet para que todos possam facilitar a operação em suas bibliotecas!

Mas como? Como vamos compilar, testar e depois publicar esse pacote no feed para que todos possam baixá-lo em seus projetos?

Bom, esse é o tutorial para 😁!

O que há de novo?

Quase não há mudanças em relação ao código, as coisas que precisamos mudar são a embalagem, a publicação e como podemos automatizá-lo.

CLI do .NET Core

Vamos usar o .NET Core CLI, usamos no tutorial anterior com comandos como dotnet restore, dotnet build e dotnet test.

Agora vamos usar um novo conjunto de comandos!

#dotnet nuget

Você pode verificar a documentação deste conjunto de ferramentas aqui, mas uma breve explicação:

dotnet nuget é um conjunto de ferramentas essenciais que inclui instalação, restauração, remoção e publicação de pacotes.

feed NuGet

NuGet é o gerenciador de pacotes para .NET. As ferramentas cliente NuGet fornecem a capacidade de produzir e consumir pacotes. A Galeria NuGet é o repositório central de pacotes usado por todos os autores e consumidores de pacotes.

O NuGet é gratuito, então você pode se inscrever, pegar sua chave de API e começar a fazer upload de pacotes. Eles serão carregados, verificados e listados para todos.

Obtenha a chave API

Para fazer upload do seu pacote, você precisará obter sua chave de API após a inscrição, então vá para a página de chaves de API e crie uma nova.

Lembre-se de que a chave de API tem validade de 365 dias.

Em seguida, copie sua chave e guarde-a em algum lugar, como dito na página, você não poderá vê-la novamente e, se não a salvou, terá que regenerá-la.

#Gerar pacote NuGet

Agora que temos a chave API, nossa próxima etapa é gerar esse pacote NuGet a partir da solução, então vá em frente e abra a solução onde você tem sua biblioteca de classes.

Usarei a solução do meu último tutorial, que possui uma classe de biblioteca .NET Core chamada CalculatorCLI.Core.

Agora vá para propriedades do projeto e depois Pacote, você verá muitas informações sobre o pacote como versão do pacote, autores, descrições e muito mais.

O próximo passo é preencher isso, você realmente não precisa preencher tudo, mas os importantes e obrigatórios são Package id, Package version, Authors e Description. Além disso, se você tentar fazer upload do arquivo sozinho, será solicitado License, precisaremos adicioná-lo também.

Depois você pode salvar, clicar com o botão direito no projeto e selecionar Pack.

1>------ Build started: Project: CalculatorCLI.Core, Configuration: Debug Any CPU ------
1>CalculatorCLI.Core -> D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\netstandard2.1\CalculatorCLI.Core.dll
1>Successfully created package 'D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\CalculatorCLI.Core.1.0.0.1.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

A saída mostrará que se tudo estiver bem, será impresso Successfully created package.

Usando `dotnet`

Assim como no tutorial anterior, usamos diferentes comandos para construir e testar a solução. Agora vamos adicionar mais comandos para empacotar e publicar os pacotes.

Esses comandos são:

dotnet pack -c <configuration>
dotnet nuget push <package> <k <apikey> -s <source>

Scripts de implantação

Como vamos mudar a forma como será a compilação, acredito que ter arquivos diferentes, cada um deles contendo uma definição de compilação dependendo do ambiente, seria a melhor ideia.

Então vamos criar uma pasta chamada scripts com três scripts bash na raiz do repositório.

scripts\compile.sh

#!/bin/sh

echo "Restoring..."
dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

echo "Building..."
dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release

scripts\test.sh

#!/bin/sh

echo "Testing..."
dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

scripts\push.sh

#!/bin/sh

echo "Packing..."
dotnet pack ./CalculatorCLI/CalculatorCLI.Core/CalculatorCLI.Core.csproj -c Release

echo "Pushing..."
dotnet nuget push ./CalculatorCLI/CalculatorCLI.Core/bin/Release/*.nupkg -s "https://nuget.org" -k $NUGET_API_KEY

Melhorando o arquivo `.travis.yml`

Agora que temos o código fonte atualizado, sabemos os comandos que precisamos usar, precisamos integrar nossa entrega contínua com integração contínua. Com isso, não precisamos fazer nada além de codificar, testar, revisar e enviar.

O que vamos fazer agora, com o arquivo .travis.yml, é o seguinte:

Adicione stages diferente
Cada stage depende da filial
Se sua compilação estiver no master, significa que o pacote deve ser atualizado, portanto, enviaremos nosso pacote para os feeds do NuGet
Se sua compilação for uma solicitação pull, ainda iremos verificar se a compilação é compilada e testada, mas não iremos publicá-la.

Estágios

Da documentação deles:

Você pode filtrar e rejeitar compilações, estágios e trabalhos especificando condições em sua configuração de compilação (seu arquivo .travis.yml).

Você pode encontrar mais informações sobre o TravisCI stages na página de documentação.

Então vamos alterar o arquivo e adicionar as etapas, que fica assim:

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

jobs:
 include:
 - stage: compile
 script: bash scripts/compile.sh

 - stage: test
 script: bash scripts/test.sh

 - stage: deploy-prod
 if: branch = master AND type = push
 name: "Deploy to NuGet"
 script: bash scripts/push.sh

Como você pode ver, temos três estágios diferentes compile, test e push, sendo que o último só será executado quando o branch for master e não for um pull request para ele, apenas um push.

Se você não entende isso, basta acessar a documentação e é explicado com bastante facilidade.

Com isso em mente, todos os pull request não enviarão nada para o feed do NuGet.

Configurando a chave API como uma variável de ambiente

Vá para as configurações de compilação do seu repositório e adicione uma nova variável de ambiente, chamada NUGET_API_KEY com o valor sendo a chave de API copiada da página NuGet.

Crie um `pull request`

Agora que temos tudo configurado, é hora de fazer um pull request e verificar se a compilação daquele pull request está ignorando o último stage.

Verifique as compilações

Assim que você fizer a solicitação pull, um build será enfileirado no painel do TravisCI, e como você pode ver, temos 2 builds diferentes lá e não três.

Agora vamos aceitar o pull request e verificar a compilação novamente para ver que agora temos três jobs em vez de dois.

E assim que você ver a compilação sendo enfileirada, você poderá ver os três trabalhos, incluindo o Deploy-prod no final.

Assim que toda a compilação for concluída, você poderá ver nos logs que o pacote foi enviado para as fontes.

E obviamente você pode ver isso na página do NuGet

#É isso

Neste tutorial, descobrimos como automatizar a entrega de pacotes NuGet. Usamos algumas ferramentas como TravisCI, stages e dotnet nuget.

Na minha opinião, mesmo que seja algo que levaria tempo para ser configurado corretamente e poderia ser muito complexo em alguns casos. Vale a pena investir tempo nesse tipo de técnica para deixar tudo perfeito e automatizado.

Você pode encontrar o código fonte, com o arquivo .travis.yml aqui, se você tiver alguma dúvida, sinta-se à vontade para entrar em contato comigo no meu twitter!

Integração contínua para um projeto .NET Core 3.0 usando TravisCI

Tue, 14 Jan 2020 00:00:00 +0000

Neste último fim de semana decidi que queria iniciar corretamente meu projeto scraper-checker-downloader que venho fazendo em diferentes repositórios.

Depois de iniciar mais um projeto, isso tinha que ser legal, muito legal, usando CI/CD, pull request, documentação, badges no readme, tudo que eu vi que é legal e de fato são as melhores práticas.

E depois de um bom final de semana acabei criando o Dramarr, um conjunto de ferramentas que fazem scrap e baixam programas de diversas fontes.

Possui diferentes repositórios na organização e a maioria deles são bibliotecas que estão sendo compiladas, testadas e implantadas no pull request e quando são mescladas no branch master.

Isso é chamado de CI/CD ou integração contínua/entrega contínua.

Mas neste tutorial falaremos apenas sobre CI.

Integração contínua

O que é isso?

Retirado do [blog](https://martinfowler.com/articles/continuousIntegration.html de Martin Fowler), que é a melhor explicação que li:

Integração Contínua é uma prática de desenvolvimento de software onde os membros de uma equipe integram seu trabalho com frequência, geralmente cada pessoa integra pelo menos diariamente - levando a múltiplas integrações por dia. Cada integração é verificada por uma construção automatizada (incluindo teste) para detectar erros de integração o mais rápido possível.

Ferramentas

Existem muitas ferramentas para integrar seu fluxo de trabalho com CI/CD, mas para este tutorial usaremos Github para armazenar nosso código e as ferramentas TravisCI para configurar o CI. Em relação à linguagem e frameworks, utilizaremos C# e o novo .NET Core 3.0.

Requisitos

Para fazer isso funcionar, você precisa de três coisas simples:

Versão mais recente do Visual Studio 2019
Conta Github
Conta Travis-CI vinculada à sua conta Github

Projeto

Para o propósito deste tutorial, faremos uma calculadora simples. Estaremos criando uma biblioteca, uma ferramenta de linha de comando e um projeto de teste para testar tudo.

Este projeto de teste também estará em execução quando configurarmos o CI, o que significa que se no futuro fizermos uma alteração no código e os testes que criamos inicialmente não passarem, receberemos uma notificação ou poderemos simplesmente rejeitar o pull request.

Criando o repositório Github

Primeiro, criaremos um repositório Github, então vá até o Github, crie o repositório e clone-o em seu ambiente local. Decidi chamar este novo repositório de CalculatorCLI-demo.

Criando a solução

Agora vamos criar uma solução vazia chamada CalculatorCLI, na pasta raiz do repositório clonado

Biblioteca principal

Como seria em um projeto do mundo real, armazenaremos nossa lógica em um projeto separado que gera uma biblioteca, então vamos criá-la.

Vá e crie um Class Library (.NET Standard) e nomeie-o como CalculatorCLI.Core

Versão do NET CoreAssim que você criar o projeto, acesse as propriedades do projeto e altere o `Target framework` para `.NET Standard 2.1`, para torná-lo compatível com projetos construídos em `.NET Core 3.0`.

Código

Para fins de tutorial, vamos criar uma classe simples que lida com operações.

using System;

namespace ConsoleCalculator.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.ADD;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

##CLI

Agora que temos o projeto principal, vamos criar o aplicativo. Neste caso, será um aplicativo de console simples que aceita argumentos e mostra um resultado.

Então vamos em frente e criar um novo Console App (.NET Core), eu o nomeei CalculatorCLI.CLI.

Versão do NET Core

Assim como fizemos antes, assim que você criar o projeto, vá nas propriedades do projeto e altere o Target framework para .NET Core 3.0, caso ainda não esteja assim.

Em seguida, adicione a referência ao ConsoleCLI.Core ao nosso projeto recém-criado.

Código

Agora, para o código, isso é mais simples do que antes.

using ConsoleCalculator.Core;
using System;
using System.Text.RegularExpressions;

namespace ConsoleCalculator.CLI
{
 public class Program
 {
 public static void Main(string[] args)
 {
 if (args.Length == 0)
 {
 PrintUsage();
 }
 else
 {
 var joinedArgs = string.Join(" ", args);
 var regex = @"-op [\+\-\*\/] -l [-0-9]+ -r [-0-9]+";

 if (Regex.IsMatch(joinedArgs, regex))
 {
 int _left = Int32.Parse(args[3]);
 int _right = Int32.Parse(args[5]);
 string _operator = args[1];

 var _operation = new Operation(_operator, _left, _right);
 var _result = _operation.DoOperation();

 Console.WriteLine($"Result is: {_result}");
 }
 else
 {
 PrintUsage();
 }
 }
 }

 public static void PrintUsage()
 {
 Console.WriteLine($"Welcome to ConsoleCalculator!");
 Console.WriteLine($"");
 Console.WriteLine($"-op Operator, it must be +,-,*,/");
 Console.WriteLine($"-l Left number");
 Console.WriteLine($"-r Left number");
 Console.WriteLine($"");
 Console.WriteLine($"Example usage: -op + -l 5 -r 6");
 }
 }
}

Estaremos utilizando esta aplicação a partir de um comando, então para que funcione temos que chamá-la passando alguns parâmetros. Por exemplo:

ConsoleCalculator.CLI.exe -op + -l 10 -r 20

O que se traduz em:

ConsoleCalculator.CLI.exe -operator + -leftValue 10 -rightValue 20

O código para isso é bem simples, se não corresponder a um determinado padrão regex, é uma chamada errada e chama o PrintUsage(). Isso significa que se inserirmos algo diferente de um número, por estar definido na regex, ele nem tentará fazer o cálculo.

Isso significa que, se chamarmos assim:

ConsoleCalculator.CLI.exe -operator + -leftValue asdfg -rightValue ghjk

Ele nunca entrará na lógica de operações e estamos salvando verificações futuras, como TryParse dos valores.

Teste

Temos a biblioteca principal e a linha de comando, mas precisamos testar agora, porque é isso que queremos fazer no CI.

Então, vamos criar um novo MSTest Test Project (.NET Core) e nomeá-lo CalculatorCLI.Tests.

Versão do NET Core

Assim como fizemos antes, assim que você criar o projeto, vá nas propriedades do projeto e altere o Target framework para .NET Core 3.0, caso ainda não esteja assim.

Em seguida, adicione a referência a ConsoleCLI.Core e ConsoleCLI.Core ao nosso projeto de teste recém-criado.

Código

Vamos dividir o teste em dois arquivos diferentes: CoreTests.cs e CLITests.cs

using CalculatorCLI.Core;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CoreTests
 {
 public int _left = 2;
 public int _right = 2;

 [TestMethod]
 public void ShouldAdd()
 {
 var expectedResult = 4;
 var operation = new Operation("+", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var expectedResult = 0;
 var operation = new Operation("-", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var expectedResult = 4;
 var operation = new Operation("*", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var expectedResult = 1;
 var operation = new Operation("/", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 [ExpectedException(typeof(System.DivideByZeroException))]
 public void ShouldThrowExceptionForDivideByZero()
 {
 var operation = new Operation("/", _left, 0);
 operation.DoOperation();
 }

 [TestMethod]
 [ExpectedException(typeof(System.Exception), "Operator invalid")]
 public void ShouldThrowExceptionForWrongOperator()
 {
 var operation = new Operation("text", _left, 0);
 operation.DoOperation();
 }
 }
}

using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CLITests
 {
 public string _left = "2";
 public string _right = "2";

 [TestMethod]
 public void ShouldAdd()
 {
 var args = new string[] { "-op", "+", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var args = new string[] { "-op", "-", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var args = new string[] { "-op", "*", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var args = new string[] { "-op", "/", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }
 }
}

Com tudo criado terminaremos com uma solução como esta:

E com isso agora podemos executar os Testes, então vá até o Test Explorer no Visual Studio e execute-os!

#Travis CI

Se ainda não o fez, TravisCI é um sistema hospedado de integração e implantação contínua.

Existem alguns passos que precisamos seguir aqui, mas primeiro vamos vincular nosso repositório Github para ser ouvido pelos agentes TravisCI para construir e testar nosso projeto.

Habilitar repositório

Para fazer isso, faça login na página do Travis CI e vá até seus repositórios, depois filtre o projeto que você criou e habilite-o, clicando no controle deslizante ao lado do nome do repositório.

Crie .travis.ymlPrecisamos criar um arquivo chamado `.travis.yml` na raiz do seu projeto, isso porque conforme indicado na documentação:

O Travis só executa compilações nos commits que você envia depois de adicionar um arquivo .travis.yml.

Então crie um arquivo .travis.yml na raiz do repositório com as seguintes linhas:

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

before_script:
 - dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

script:
 - dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release
 - dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

Não vou entrar na sintaxe de como o arquivo .travis.yml funciona, mas vamos revisar o que ele está fazendo:

Configuramos que o idioma será csharp.
Não usaremos mono porque .NET Core 3.0 será executado nativamente no Linux.
Definimos a versão dotnet como 3.0.
Definimos o os, por padrão é linux, mas eu adicionei mesmo assim.
Agora temos before_script que irá funcionar antes da lógica principal .aqui, então o que coloquei foi rodar dotnet restore para a solução para que tudo carregue perfeitamente depois.
Agora no script, faremos um dotnet builld e dotnet test em nossa solução, isso irá verificar se ela compila e então executar os testes.

Eae terminamos!

Carregar para mestre

Agora só precisamos empurrar tudo para master.

git add --all
git commit -m "Initial files"
git push

Verifique a integração contínua

Podemos verificar o status do CI do push para master que fizemos na página do repositório ou no painel do TravisCI.

Em progresso

Concluído

#Vamos quebrar isso

Agora, para ver o quão poderoso isso é, vamos quebrar o código e alterar a biblioteca principal para fazer com que ela falhe.

Mudanças de código

Então vá para o Operation.cs e mude algo que irá quebrar alguns testes.

using System;

namespace CalculatorCLI.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

E se executarmos o teste novamente, porque alteramos o caso para adição, ele falhará:

case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;

Como esperado, falhou no caso ShouldAdd:

Agora faça um commit dessa mudança e envie-a para o master, e aguarde os resultados do agente TravisCI.

git add --all
git commit -m "Breaking changes"
git push

Construir

Agora vamos para os logs do TravisCI e veremos que quebramos o projeto com sucesso, pois os testes de integração estão falhando e o status da compilação é erro.

No final do log podemos ver o próprio erro:

Vamos consertar de novo!

Agora reverta o que fizemos e envie o código para master e verifique o status da nova compilação.

Os testes estão passando com sucesso:

E construir também é um sucesso:

Conclusão

É realmente muito poderoso, CI e CD já existem há muito tempo, mas agora é muito simples executá-lo em cada projeto, não importa quão pequeno ou simples seja.Do meu ponto de vista, todos deveriam pelo menos configurar o CI para cada um de seus projetos, porque é uma boa prática e eventualmente economizará tempo na depuração e na localização de erros que não deveriam ocorrer se você tivesse definido tests e CI adequados.

#É isso

É isso sobre como criar uma solução .NET Core 3.0 que tenha integração contínua em cada build usando TravisCI e armazenando o código no Github.

Você pode encontrar o código-fonte deste projeto aqui.

Minha opinião sobre cache na memória

Tue, 03 Sep 2019 00:00:00 +0000

Tenho trabalhado em algumas coisas que lidam com uma grande quantidade de dados. Ao fazer isso, percebi que uma grande parte disso nunca muda, ou pelo menos por algum tempo fixo, isso não acontece.

Então pensei que seria útil criar um repositório de cache pessoal, claro que isso não é novidade, há algumas semanas li sobre isso no post do StackOverflow escrito por Nick Craver sobre como eles gerenciam o cache do aplicativo.

Além disso, sempre quis trabalhar com cache, como funciona, a lógica e como poderia fazê-lo funcionar, então… por que não!

Fluxo

Aqui está um fluxo rápido de como a classe que tem o controle do cache se comportará quando o usuário solicitar um valor.

Implementação

Antes de começarmos

Eu sei, eu sei. Existe System.Runtime.Caching que lida com o cache de memória. Mas eu decidi construí-lo sozinho, se você quiser usar essa classe, verifique aqui para obter instruções.

CacheItem

O primeiro passo é ter uma classe que armazene o valor de um objeto e a data de validade. Provavelmente há uma maneira melhor de fazer isso, mas foi isso que pensei, então pronto:

public class CacheItem
{
 public string Identifier { get; set; }
 public object Value { get; set; }
 public DateTime ValidUntil { get; set; }

 public CacheItem(string identifier, object value, TimeSpan valid)
 {
 Identifier = identifier;
 Value = value;
 ValidUntil = DateTime.UtcNow.Add(valid);
 }
}

CacheRepositório

Então precisamos de uma classe que lide com os objetos e os salve em algum lugar (como CacheItem). Eu gosto de lidar com todos os dados/modelos em classes que possuem o sufixo Repository, mas você não precisa, então vamos construir um para armazenamento em cache.

public class CacheRepository
{
 private static Dictionary<string, string> Cache = new Dictionary<string, string>();
 private static T Set<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var item = new Models.Item(key, lookup(), durationMinutes);
 return Save<T>(key, item);
 }
 private static T Save<T>(string key, Item item)
 {
 Cache[key] = JsonConvert.SerializeObject(item);
 return (T)item.Value;
 }
 private static T Get<T>(string key)
 {
 var cached = Cache.FirstOrDefault(x => x.Key == key).Value;
 var item = string.IsNullOrEmpty(cached) ? null : JsonConvert.DeserializeObject<Item>(cached);
 return (item == null)
 ? default : (item.ValidUntil > DateTime.UtcNow)
 ? JsonConvert.DeserializeObject<T>(JsonConvert.SerializeObject(item.Value)) : default;
 }
 public static T GetOrSet<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var cache = Get<T>(key);
 return cache == null ? Set(key, lookup, durationMinutes) : cache;
 }
}

Até agora temos um dicionário estático chamado Cache onde todos os itens serão armazenados. Lembre-se de que isso só durará enquanto o aplicativo estiver em execução, por isso este título tutorial contém cache na memória.

Tenha em mente que o item Cache será inicializado assim que a classe CacheRepository for carregada.

O único método disponível ao invocar a classe CacheRepository é GetOrSet(string key, Func<T> lookup, TimeSpan durationMinutes) que precisa de três parâmetros:

key: o identificador do objeto a ser salvo.
lookup: a função de retorno de chamada caso o cache tenha expirado ou seja nulo.
durationMinutes: a duração em minutos que será adicionada ao horário atual (em UTC).

Hora de armazenar em cache

Agora, use nosso repositório de cache para obter alguns dados de algum lugar.

Para que tudo isso faça sentido, vamos criar um objeto de exemplo com algumas propriedades, e depois um repositório para buscar e preencher uma lista desse objeto.

public class User
{
 public Guid Id { get; set; }
 public string Name { get; set; }
 public string Email { get; set; }
}
public class UserRepository
{
 public List<User> Get()
 {
 // Code to get users
 }
}

Como temos o método para preencher uma lista de User, vamos usar a classe CacheRepository.

private UserRepository _userRepository = new UserRepository();
private List<User> _user;
public List<User> User
{
 get
 {
 _user = CacheRepository.GetOrSet($"users", usersRepo.Get, TimeSpan.FromMinutes(10));
 return _user;
 }
}

E assim mesmo, toda vez que você acessar a variável User, ele irá pedir ao CacheRepository o valor de um objeto que possui a chave users.

Se essa chave existir, ela verificará a data de validade. Se qualquer uma dessas condições for falsa, ele usará o retorno de chamada para definir o valor (com usersRepo.Get) do objeto, salvá-lo no cache com a data de expiração definida como DateTime.UtcNow + TimeSpan.FromMinutes(10) e devolvê-lo.

Faça capturas de tela da página usando Devtools

Thu, 09 May 2019 00:00:00 +0000

Houve momentos em que precisei mostrar a um cliente ou colega de equipe uma captura de tela completa do estado atual do site ou até mesmo de parte dele, então tenho usado Captura de tela de página inteira e, para qualquer outro tipo de captura de tela, Ferramenta de snippet do Windows ou Snaggit. Se eu quiser hospedá-lo online como neste post Gyazo, que também tem um criador de GIF.

Recentemente descobri que Devtools tem uma ferramenta que faz uma captura de tela de página inteira, sem necessidade de extensão!

Este não é um pensamento novo, foi incluído na atualização do Devtools em abril de 2017, mas parece que moro debaixo de uma rocha e não descobri até agora…

Ferramentas de desenvolvimento

Conforme declarado na página oficial do Devtools:

Chrome DevTools é um conjunto de ferramentas para desenvolvedores web integradas diretamente no navegador Google Chrome. DevTools pode ajudá-lo a editar páginas dinamicamente e diagnosticar problemas rapidamente, o que, em última análise, ajuda a construir sites melhores e mais rápido.

Executando comandos no Devtools

Você já sabe como abrir o Devtools, mas caso tenha esquecido e por causa deste post, abra-o usando a tecla F12 ou o atalho Ctrl + Shift + I. Então você tem que abrir o Run command no menu dentro do Devtools ou usar Ctrl + Shift + P.

Ferramenta de captura de tela

Se você digitar screenshot irá filtrar os comandos, haverá 4 tipos de métodos de captura de tela que você pode usar:

Captura de tela da área
Captura de tela em tamanho real
Captura de tela do nó
Capturar captura de tela

Antes de verificar todos os métodos de captura de tela, após o devtools terminar de processar a imagem, ele irá baixá-la automaticamente com o nome da página.

Captura de tela da área

O area screenshot permitirá que você selecione uma parte do site e faça uma captura de tela.

Resultado:

Captura de tela em tamanho real

O full size screenshot fará uma captura de tela de toda a página da web, do início ao fim.

Resultado:

Captura de tela do nó

O node screenshot permitirá que você faça uma captura de tela de um nó selecionado no elemento inspecionar.

Resultado:

Capturar captura de tela

O capture screenshot fará uma captura de tela da página atual sem rolar e do tamanho do navegador.

Resultado:

Linguagens personalizadas usando recursos incorporados e externos no .NET Framework

Mon, 06 May 2019 00:00:00 +0000

Introdução

No trabalho, encontramos um problema normal com o qual tenho certeza que muitos desenvolvedores têm que lidar, que são linguagens e linguagens personalizadas dos clientes que estão prestando nossos serviços aos seus clientes.

Por exemplo, digamos que a linguagem base seja uma linguagem informal e um cliente queira uma linguagem formal porque seus clientes são pessoas mais velhas.

Observe também que esta solução é para vários idiomas, usaremos inglês e espanhol.

Minha língua materna não é o inglês. Peço desculpas por quaisquer erros no tutorial. Se você encontrar erros e quiser corrigi-los, você pode abrir uma solicitação pull em este repositório e terei prazer em aprová-lo!

Recursos

Recursos são arquivos XML com extensão .resx que possuem uma estrutura chave/valor e se parecem com o seguinte:

<?xml version="1.0" encoding="utf-8"?>
<root>
 <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
 <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
 <xsd:element name="root" msdata:IsDataSet="true">
 <xsd:complexType>
 <xsd:choice maxOccurs="unbounded">
 <xsd:element name="metadata">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" />
 </xsd:sequence>
 <xsd:attribute name="name" use="required" type="xsd:string" />
 <xsd:attribute name="type" type="xsd:string" />
 <xsd:attribute name="mimetype" type="xsd:string" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="assembly">
 <xsd:complexType>
 <xsd:attribute name="alias" type="xsd:string" />
 <xsd:attribute name="name" type="xsd:string" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="data">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
 <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
 <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="resheader">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" />
 </xsd:complexType>
 </xsd:element>
 </xsd:choice>
 </xsd:complexType>
 </xsd:element>
 </xsd:schema>
 <resheader name="resmimetype">
 <value>text/microsoft-resx</value>
 </resheader>
 <resheader name="version">
 <value>2.0</value>
 </resheader>
 <resheader name="reader">
 <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <resheader name="writer">
 <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <data name="Action_cancel" xml:space="preserve">
 <value>Finish</value>
 </data>
 <data name="Action_greeting" xml:space="preserve">
 <value>Hello</value>
 </data>
</root>

Estaremos criando recursos para dois idiomas diferentes: inglês e espanhol, então a nomenclatura dos arquivos será: resources.ISOLANGUAGECODE.resx, por exemplo: resource.es.resx para espanhol e resource.resx para inglês, caso queiramos adicionar posteriormente o alemão, o arquivo será nomeado resource.de.resx.

Recurso incorporado

Recursos incorporados, quando o projeto for compilado, serão adicionados dentro do dll.

Aqui está uma imagem com um recurso incorporado, como você pode ver, o arquivo Resource.resx não pode ser visto na compilação.

Recurso externo

Por outro lado os recursos externos ou não incorporados são recursos que serão adicionados à pasta após a compilação.

Os arquivos de recursos (.resx) estarão dentro da pasta Properties

Construindo o projeto

Vamos começar com um projeto de console no .NET Framework.

Criando o arquivo de recurso incorporado

Adicione um arquivo de recurso com algumas chaves e certifique-se de que seja um recurso incorporado, que posteriormente usaremos para atualizar com recursos externos.

Criando o arquivo de recurso externo

Para separar os recursos externos dos incorporados, iremos adicionar os recursos externos dentro de uma pasta com um nome para que possamos acessá-los facilmente posteriormente.

Dica: para adicionar uma pasta dentro da pasta Propriedades, criá-la fora e movê-la para dentro, o Visual Studio não permite criá-la

Faça o mesmo que fizemos para o recurso incorporado, vá para properties do arquivo e dentro de Advanced, Build action e altere para: Content e altere Copy to Output Dictionary para Copy if newer.

É assim que deve ser:

Adicionando uma chave ao app.config

Como somos desenvolvedores legais e gostamos de ter tudo bem feito e NÃO alterar o código de cada cliente, vamos adicionar uma chave ao appconfig que terá o nome da pasta onde estaremos procurando os arquivos de recursos

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <startup>
 <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
 </startup>
 <appSettings>
 <add key="CustomResources.Folder" value="John" />
 </appSettings>
</configuration>
```Então, mais tarde, quando procurarmos os recursos, ele procurará em `Properties.John` em vez de `Properties.Doe`.

Além disso, isso facilita a alteração quando o aplicativo já está implantado, pois você pode alterar facilmente o app.config.

## Acessando arquivos de recursos incorporados

Usar o .NET Framework é bastante fácil, então para acessar as propriedades do Embedded basta usar o objeto `Properties`, que terá como propriedade os arquivos de recursos, e dentro desse objeto estarão toda a chave/valor que temos no arquivo `resx`.

```csharp
static void Main(string[] args)
{
 var hello = Properties.Resource.Action_greeting;
 var bye = Properties.Resource.Action_cancel;

 Console.WriteLine($"Action_greeting value: {hello}, Action_cancel value: {bye}");

 Console.Read();
}

Executando isso deve nos mostrar algo assim:

Action_greeting value: Hello, Action_cancel value: Cancel

Acessando arquivos de recursos externos

Esta parte é praticamente a mesma, você pode acessar os arquivos de recursos pelo objeto Properties.

var hello = Properties.Resource.Action_greeting;
var bye = Properties.Resource.Action_cancel;

var johnhello = Properties.John.Resource.Action_greeting;
var johnbye = Properties.John.Resource.Action_cancel;

var doehello = Properties.Doe.Resource.Action_greeting;
var doebye = Properties.Doe.Resource.Action_cancel;

Problema

O principal problema ao usar este método é que cada chave é uma propriedade dentro do objeto, então temos que chamá-la como vimos antes. Se você quiser chamar a chave Action_greeting do arquivo de recursos de John temos que usar o seguinte Properties.John e depois Resource.Action_greeting.

Aí está o problema.

Isso porque se estamos desenvolvendo uma aplicação para muitos clientes, é uma má ideia mudar a forma como chamamos os arquivos de recursos de cada um deles.

Você consegue imaginar isso? Compilar a aplicação para cada cliente e mudar John para Doe e depois para outra coisa. Isso é loucura!

Solução

Nosso líder de equipe pensou em um método muito bom, algo como um sistema substituto, devemos ter um modelo base de recursos, e então para cada um dos clientes temos um arquivo de recursos que irá atualizar o arquivo com seus recursos, e terminamos com uma única lista de recursos.

Se o cliente não quiser recursos customizados usamos os recursos base, e se ele quiser, usamos os deles.

Para colocar isso em uma lista de verificação, temos que fazer:

[] Encontre uma maneira de mapear todas as chaves/valores para um dicionário para os recursos incorporados.
[] Encontre uma maneira de mapear todas as chaves/valores para um dicionário para os recursos externos
[] Misture os dois arquivos e tenha um único dicionário para cada idioma
Crie um método que acesse o dicionário e retorne o valor

Diagrama

Vamos codificar

Primeiramente, vamos criar uma classe separada onde teremos toda a nossa lógica, desde a obtenção dos arquivos de recursos, até a mistura deles e o retorno do valor. Essa classe será chamada CustomResources.

Isto é o que parece:

 class CustomResources
 {

 private static Dictionary<string, string> _ResourcesEnglish;
 private static Dictionary<string, string> ResourcesEnglish;

 private static Dictionary<string, string> _ResourcesSpanish;
 private static Dictionary<string, string> ResourcesSpanish;


 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromFile(string file)
 {
 ...
 }

 public static string GetText(string key)
 {
 ...
 }

 public static string GetText(string key, string language)
 {
 ...
 }
 }

Observe que estamos implementando o carregamento lento para propriedades, o que ajuda a aumentar o desempenho e faz com que o dicionário seja carregado uma vez.

GetDictionaryFromEmbedded: retorna um dicionário de recursos incorporados.
GetDictionaryFromFile: retorna um dicionáriou de recursos externos.
OverwriteDictionary: mistura dois dicionários e retorna um único.
GetText: retorna um valor dada uma chave

Do recurso incorporado ao dicionário

Temos que pegar todas as propriedades do arquivo xml e retornar um dicionário:

private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
{
 Dictionary<string, string> res = new Dictionary<string, string>();

 try
 {
 ResourceManager rm = new ResourceManager(embedded, Assembly.GetExecutingAssembly());
 var resourceSet = rm.GetResourceSet(new CultureInfo(cultureInfoCode), true, true);

 var resourceDictionary = resourceSet.Cast<DictionaryEntry>()
 .ToDictionary(r => r.Key.ToString(),
 r => r.Value.ToString());
 res = resourceDictionary;
 }
 catch (Exception e)
 {
 string a = e.Message;
 // Error getting resource file
 }

 return res;
}

Duas coisas:- Observe que ele precisa de um parâmetro chamado embedded, que parementers é o nome do arquivo que você pode ver no designer, no nosso caso é: resources-demo.Properties.Resource.

Também temos um parâmetro chamado cultreInfoCode, que é o código do idioma a ser selecionado. Felizmente para nós, o .NET Framework faz o trabalho para nós e não precisamos fazer nada, apenas definir que queremos inglês ou espanhol, e ele selecionará entre resource.es.resx ou resource.resx

Do recurso externo ao dicionário

Sair do arquivo é um pouco hackeado, mas não difícil, temos que obter a localização atual do executável, concatenar a localização do arquivo de recurso e então analisá-lo em um dicionário.

Mas primeiro você deve adicionar a referência a System.Windows.Forms, para poder acessar ResXResourceReader.

Agora vamos ao nosso método GetDictionaryFromFile:

private static Dictionary<string, string> GetDictionaryFromFile(string file)
{
 Dictionary<string, string> res = new Dictionary<string, string>();
 string currentPath = (System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase) + file).Replace("file:\\", "");

 try
 {
 using (ResXResourceReader resxReader = new ResXResourceReader(currentPath))
 {
 foreach (DictionaryEntry entry in resxReader)
 {
 res.Add((string)entry.Key, (string)entry.Value);
 }
 }
 }
 catch (Exception e)
 {
 string a = e.Message;
 }

 return res;
}

Os parâmetros do arquivo precisam ser preenchidos com a localização do executável até o arquivo de recurso, no nosso caso é: "\\Properties\\John\\Resource.resx".

Misturando dicionários

Já terminamos, primeiro lembre-se de adicionar System.Configuration às referências para que você possa acessar app.settings.

 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
{
 var identifier = ConfigurationManager.AppSettings["CustomResources.Folder"];
 if (String.IsNullOrEmpty(identifier))
 return currentDictionary;

 foreach (var item in newDictionary)
 {
 try
 {
 currentDictionary[item.Key] = item.Value;
 }
 catch (Exception)
 {
 if(addIfDoesntExist)
 currentDictionary.Add(item.Key, item.Value);
 }
 }

 return currentDictionary;
}

Obtendo texto do dicionário

Crie um método público que chame um método privado que selecione um idioma:

private static string GetText(string key, string language)
{
 try
 {
 switch (language)
 {
 case "es":
 return ResourceSpanish[key];
 case "en":
 default:
 return ResourceEnglish[key];
 }
 }
 catch (Exception)
 {
 return $"No value with key: {key} and language: {language}";
 }
}

public static string GetText(string key)
{
 try
 {
 return GetText(key, Thread.CurrentThread.CurrentCulture.TwoLetterISOLanguageName);
 }
 catch (Exception)
 {
 return $"No value with key: {key}";
 }
}

Observe que você terá que modificar a opção se estiver adicionando mais idiomas.

Adicionando código ao getter de propriedades

Como temos todos os métodos agora, podemos modificar o getter da propriedade pública para obter os valores.

private static Dictionary<string, string> _ResourcesEnglish;
private static Dictionary<string, string> ResourcesEnglish
{
 get
 {
 if (_ResourcesEnglish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resource");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resource.resx", "en");
 _ResourcesEnglish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesEnglish;
 }
}

private static Dictionary<string, string> _ResourcesSpanish;
private static Dictionary<string, string> ResourcesSpanish
{
 get
 {
 if (_ResourcesSpanish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resources");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resources.es.resx", "es");
 _ResourcesSpanish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesSpanish;
 }
}

Primeiro obtemos o identificador de app.settings.
Depois obtemos os recursos básicos, os incorporados.
Depois disso obtemos os recursos customizados e para isso precisamos do nome da pasta (que é o identificador).
Em seguida, misturamos e retornamos o valor.

Tudo isso será feito uma vez, após o carregamento lento.

Teste

Tudo relacionado ao código está finalizado, então agora vamos testar, para obter um valor do dicionário temos que chamar o método CustomResources.GetText(string key) que retorna o valor.

Atualizando arquivos de recursos inteiros

Este teste é um caso em que queremos atualizar toda a chave/valor dos arquivos de recursos, como você pode ver nas imagens temos as mesmas chaves, mas valores diferentes.

Vamos testar John, e para definir isso teremos o app.config definido como <add key="CustomResources.Folder" value="John" />.

Agora vamos verificar nosso arquivo de recurso base (Properties/Resource.es.resx):

E então nosso arquivo de recurso externo (Properties/John/Resource.es.resx):

Ok com tudo definido, rodamos a aplicação console, vamos parar na parte get das propriedades e verificar tudo

folderIdentifier tem o valor do appseting:

baseResources tem o valor dos recursos base, os incorporados:

customResources possui os valores dos recursos externos dentro da pasta John:

E por fim, _ResourcesSpanish tem o valor misturado dos recursos base aos recursos externos.

Atualizando apenas um

Agora vamos testar o mesmo mas com cenário diferente, basta atualizar uma chave e deixar a outra igual.

Como você pode ver, os arquivos têm o mesmo significado de valor para Action_greeting, mas valores diferentes para Action_cancel, portanto, devem ser atualizados apenas Action_cancel.

Faltando o arquivo de recurso

Se você não fornecer o arquivo de recurso externo, não importa nada porque como esperamos ter um arquivo, se falhar retornará um dicionário vazio e ao misturar os dois dicionários terminará com o base.

Par ausente no recurso incorporado

Se você tiver um par no arquivo de recurso externo, por padrão ele não o adicionará ao dicionário final, você pode alterar isso chamando o método OverwriteDictionary() ao misturar os dois dicionários e definir o parâmetro addIfDoesntExist como true.

Diferentes idiomas

Como você pode ver, não especificamos nenhum idioma, porque tudo isso está sendo feito pela função GetText(string key) que está chamando GetText(string key, string language), e o parâmetro language é preenchido por TwoLetterISOLanguageName que retorna o idioma atual do nosso thread.

No meu caso tenho o espanhol como idioma padrão e por isso sempre mostra em espanhol, mas podemos tentar usar o inglês também.

Vamos codificar um pouco e construir algo para verificar espanhol e inglês.

static void Main(string[] args)
{

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("en-US");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("es-ES");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("es-ES");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 Console.Read();
}

private static void WriteText(string key) {
 Console.WriteLine($"[Culture: {System.Threading.Thread.CurrentThread.CurrentCulture}] Key: {key} -> value: {CustomResources.GetText(key)}");
}

Executando isso, a saída deve ser algo assim:

[Culture: en-US] Key: Action_greeting -> value: Hello
[Culture: en-US] Key: Action_cancel -> value: Finish
[Culture: es-ES] Key: Action_greeting -> value: Hola
[Culture: es-ES] Key: Action_cancel -> value: Terminar

Os dois primeiros valores são de resources.resx que estão em inglês e os últimos ambos estão em espanhol e os valores são recuperados de resources.es.resx.

#É isso

Neste tutorial encontramos uma forma de mesclar recursos embarcados e externos para idiomas, essa foi uma solução para um problema que tivemos na equipe e está rodando desde então sem problemas.

Você pode verificar o código fonte aqui.

Se você tiver alguma dúvida, sinta-se à vontade para me enviar um tweet para @emimontesdeocaa e entrarei em contato com você quando tiver tempo.

Teste de integração usando Bot Framework e DirectLine para casos de fluxo

Wed, 25 Apr 2018 00:00:00 +0000

Introdução

Nas postagens anteriores do blog, fizemos alguns testes de integração para casos únicos. “Casos únicos” são aqueles casos que após perguntar algo ao bot, ele responderá apenas uma vez e depois compararemos os resultados.

Este guia não explica como são feitas a autenticação e as chamadas de API. Se você quiser conferir, consulte o guia de casos únicos.

E as conversas de fluxo?

Usando a forma atual não temos nenhum tipo de fluxo na conversa, por exemplo, se você quiser pedir ajuda e aí aparece um menu com diversas opções, e depois de selecionar uma delas, outro menu. Isso daria cerca de 2 ou mais responses. Então, isso significa que usar a solução de teste de integração que usamos antes não funcionará.

Aqui está um diagrama de como funciona o teste de integração para casos únicos.

E aqui está um diagrama de como vamos adaptar a atual solução de teste de integração aos casos de fluxo.

A explicação a seguir não cobrirá todas as informações básicas de como funciona o Bot Framework. Se você não entender, consulte a documentação oficial.

Exemplo de caso

Para o guia a seguir, usarei um bot com um fluxo de conversa criado por mim, que pede ajuda e depois seleciona diferentes opções.

Nova estrutura JSON

Agora que temos mais de um request ao falar com o bot, precisamos modificar nossa estrutura json para adicionar todos os request que iremos fazer.

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint":
 "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint":
 "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "PedirAyuda",
 "requests": [
 {
 "type": "message",
 "text": "Ayuda",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Telefono",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Oficina",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Tenerife",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 }
 ],
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "922920252",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

Como você pode ver, há uma mudança importante, request agora é requests. Isso significa que agora temos um List<Activity> em vez de um único activity.

Novos objetos

Anteriormente tínhamos nossos objetos definidos para casos únicos: TestEntry e TestEntryCollection. Para casos de fluxo estaremos criando novos objetos: TestEntryFlow e TestEntryFlowCollection.

`TestEntryFlow`

Este objeto é para cada entrada que temos na coleção, veja que o objeto Requests agora é um List<Activity> em vez de um único Activity como mencionei antes.

Como perguntaremos ao bot várias vezes, precisamos ter vários activities que serão enviados para a conversa.

public class TestEntryFlow
{
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("requests")]
 public List<Activity> Requests { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
}

`TestEntiresCollection`

Este objeto conterá as informações relevantes para DirectLine como o secret e os endpoints, além da lista de Entries que iremos testar.

Observe que, o Entries agora é uma lista de TestEntryFlow e não de TestEntry.

public class TestEntryFlowCollection
{
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntryFlow> Entries { get; set; }
}

Criando o `TestMethod` para casos de fluxo

Novo fluxo

Em primeiro lugar, dê uma olhada novamente no diagrama(é o mesmo que postei acima).

Como você pode ver, a estrutura do fluxo para fazer o teste é praticamente a mesma:

Obtenha informações
Autenticar
Crie uma conversaE aqui o que muda, agora temos que enviar várias vezes toda a solicitação para a conversa. Para fazer isso, precisamos fazer um loop para cada solicitação, enviá-la ao bot e comparar a resposta mais recente com a resposta esperada.
Envie todas as solicitações
Receba todas as mensagens
Obtenha a resposta mais recente
Compare com a resposta esperada
Afirmar resultado

Código

Em primeiro lugar, precisamos obter as informações do arquivo, é o mesmo que fizemos antes com os casos únicos.

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

Agora temos que fazer um loop para cada TestEntryFlow, do data.entries, com isso podemos seguir o mesmo fluxo que fizemos nos casos únicos até a nova parte, onde fazemos o loop no requests.

/// Arrange with current requested values
string token, newToken, conversationId;
Activity latestResponse = new Activity();

/// Act for step

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

/// 2 - Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

A etapa a seguir é bem simples, temos que fazer um loop no entry.requests e enviar cada activity para a conversa.

foreach (Activity step in entry.Requests)
{
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
}

Usamos o watermark para obter a última mensagem, o watermark é um valor que a API DirectLine retorna ao solicitar as informações da conversa.

Depois disso, só temos que preencher o globals com nosso latestReponse e expectedResponse.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

E para finalizar o caso, avaliamos a string assert no entry.

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

Código final

[TestMethod]
public async Task ShouldTestFlowCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert
 foreach (TestEntryFlow entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;
 Activity latestResponse = new Activity();

 /// Act for step

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

 foreach (Activity step in entry.Requests)
 {
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
 }

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }

 await Task.CompletedTask;
}

Melhorias

Acredito que um fluxo melhor poderia ser possível, mas essa melhoria significará que a estrutura JSON também deve ser alterada. Além disso, para que isso aconteça, o json precisa estar mais preenchido.

Para melhorar esse teste, deveríamos ter um response para cada request, e deveríamos estar afirmando toda vez que enviarmos uma mensagem. A maneira como estamos fazendo isso agora é armazenando todos os requests e o [[TOK_56]]] final.

Fiz um diagrama para mostrar como ficaria.

Acredito fortemente que essa forma é muito melhor no geral para a integridade do teste, já que você está testando praticamente todos os comportamentos do fluxo, em vez de apenas testar a resposta final.

Bem, isso é tudo neste guia, lembre-se que este guia pretende ser uma continuação do guia de casos únicos, se você se sentir perdido, verifique aquele guia que é mais longo e tem mais explicações para tudo.

Lembre-se de que todo o código está armazenado em meu github em this repositório.

Tenha um bom dia!

Teste de integração usando Bot Framework e DirectLine (1)

Tue, 24 Apr 2018 00:00:00 +0000

Como comecei a trabalhar em uma empresa por um curto período de tempo, fui designado para trabalhar em testes de integração do Bot Framework.

Meu trabalho no grupo é fazer com que o bot fique o mais estável possível, mas primeiro, o que é Bot Framework?

Crie, conecte, implante e gerencie bots inteligentes para interagir naturalmente com seus usuários em um site, aplicativo, Cortana, Microsoft Teams, Skype, Slack, Facebook Messenger e muito mais. Comece rapidamente com um ambiente completo de criação de bots, pagando apenas pelo que usar.

Você pode encontrar mais informações sobre o Bot Framework diretamente aqui.

A explicação a seguir não cobrirá todas as informações básicas de como funciona o Bot Framework. Se você não entender, consulte a documentação oficial.

Por que preciso de teste de integração?

Os testes de integração são necessários porque toda vez que um dos meus colegas de trabalho envia uma correção, um novo recurso ou até mesmo um novo bug, esses testes serão executados antes de enviar o código para produção e se algum dos testes falhar, o código não irá para produção, o que significa que o usuário final não terá o bug.

Teste de integração em bots?

Acredito que em bots os testes de integração são muito importantes. Você não pode ter um bot onde alguns de seus menus não estejam funcionando ou alguns dos recursos não retornem nada.

As empresas estão usando bots para seus clientes porque não querem que as pessoas fiquem ocupadas com seus problemas. Se um bot puder ajudar um usuário, os outros trabalhadores poderão usar seu tempo para fazer algo mais importante.

Visão geral da solução.

Para fazer isso funcionar, utilizei um projeto de Teste no Visual Studio, que utilizará WebClient para API Rest e um arquivo Json, onde armazenaremos nossos cases.

arquivo JSON

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint": "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint": "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

Como você pode ver, temos:

Segredo da linha direta -> segredo do bot publicado
Endpoint de geração de token Directline -> endpoint para obter o token usando o segredo
Endpoint de conversação direta -> endpoint para brincar com a conversa
Entrada -> o caso de teste
- Solicitar -> o que enviamos para a conversa
- Resposta -> o que esperamos obter
- Afirmar -> o que estamos comparando

Desserialização

Temos o arquivo json perfeitamente formatado, agora temos que carregá-lo na solução, então usaremos JSON.NET e algumas classes. Primeiro temos a coleção de entradas, que tem tudo, e depois temos, para cada coleção uma lista de entradas.

 /// <summary>
 /// Object to parse from the file
 /// </summary>
 public class TestEntriesCollection
 {
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntry> Entries { get; set; }
 }

E este é o objeto que possui o nome, solicitação, resposta e afirmação do caso de teste.


 public class TestEntry
 {
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("request")]
 public Activity Request { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
 }

Análise de JSON para objeto no caso de teste

Tendo as classes para o objeto de análise, é muito fácil, pois precisamos ler como o objeto.

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\data.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

Agora com esta coleção, poderemos percorrê-la e obter as informações usando, por exemplo, um foreach.

 foreach (TestEntry entry in data.Entries)
 {
 ....
 }

E isso é tudo por esta parte, a próxima parte incluirá a autorização para DirectLine, lembre-se que todo o código está armazenado no meu github no repositório this.

Teste de integração usando Bot Framework e DirectLine (2)

Tue, 24 Apr 2018 00:00:00 +0000

Nesta parte faremos a autorização DirectLine e obteremos os valores da resposta do bot.

Agora que fizemos a desserialização, é hora de pegar as informações da coleção e os inteiros que usaremos para obter a autorização, fazer as chamadas da API e afirmar o resultado.

A explicação a seguir não cobrirá todas as informações básicas de como funciona o Bot Framework. Se você não entender, consulte a documentação oficial.

Fazendo chamadas de API usando WebClient

Para facilitar a chamada da api, criei uma classe utils, onde salvamos as funções que usaremos algumas vezes, essa classe inclui uploadString para POST e downloadString para GET.

 public class Utils
 {
 /// <summary>
 /// Uploads to an URL and gets result
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <param name="serializedJson">Serialized JSON to send</param>
 /// <returns></returns>
 public static T uploadString<T>(string bearer, string url, string serializedJson)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Upload string
 serializedResult = client.UploadString(url, serializedJson);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }

 /// <summary>
 /// Downloads from URL
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <returns></returns>
 public static T downloadString<T>(string bearer, string url)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Download string
 serializedResult = client.DownloadString(url);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }
 }

Autorização DirectLine

Se você ler a documentação oficial, poderá descobrir como fazer, e é bem fácil, usando nossas funções é ainda mais fácil. Primeiramente lembre-se que estamos dentro da instrução foreach, pois estamos fazendo a autenticação para cada caso, caso o tempo acabe, o que significará que o teste falhará.

/// Arrange with current requested values
string token, newToken, conversationId;
/// Act

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

Agora temos o token, que será usado para fazer todas as chamadas seguintes para o endpoint da conversa.

Criando uma conversa.

Para falar com o bot, primeiro precisamos criar uma conversa, esta conversa retornará um novo token que inclui o id da conversa.

/// 2 -Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

Além disso, armazenamos newToken e conversationId, ambos serão necessários para o usuário enviar mensagens ao bot.

Enviar atividade para conversa

Agora, com o conversationId e o conversationEndpoint, podemos criar o endpoint final para enviar um Activity que é o request do arquivo json.

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

Receba a última mensagem

No histórico de mensagens, depois de enviarmos a atividade, o bot já deveria ter respondido, então temos que pegar todas as mensagens com a marca d’água e então usando essa marca d’água, filtrar a última mensagem/atividade.

/// 4 - Get all activities, we get a List<activity> and a watermark
var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

/// 5 - Get the latest activity which is the response we should be expecting
var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

E isso é tudo por esta parte, a próxima parte incluirá a parte onde obtemos o texto do assert no json, convertemos para código como usar eval() em Javascript, mas em C#, e então usando o Assert.isTrue() para obter o resultado final do teste.

Lembre-se de que todo o código está armazenado em meu github em este repositório.

Teste de integração usando Bot Framework e DirectLine (3)

Tue, 24 Apr 2018 00:00:00 +0000

Esta é a última parte do guia, nesta parte estaremos avaliando o texto do assert no json.

Agora que usamos o request e enviamos como um activity para o bot, obtivemos o response e temos que comparar o que o assert no json (a resposta que armazenamos no json, esta é a resposta esperada) com a resposta que obtivemos do bot.

A explicação a seguir não cobrirá todas as informações básicas de como funciona o Bot Framework. Se você não entender, consulte a documentação oficial.

Adicionando Microsoft.CodeAnalysis à solução

Primeiro de tudo, temos que incluir CodeAnalysis como um pacote NuGet.

Após a instalação, lembre-se de adicionar o pacote ao arquivo .cs.

using Microsoft.CodeAnalysis.CSharp.Scripting;

Criando um objeto `Globals`

Para avaliar, temos que passar os parâmetros ao avaliador. Este avaliador precisa de um arquivo de configuração.

 /// <summary>
/// Object to pass parameters to Roslyn compiler
/// </summary>
public class Globals
{
 /// <summary>
 /// ExpectedResponse
 /// </summary>
 public Activity Request;
 /// <summary>
 /// ReceivedResponse
 /// </summary>
 public Activity Response;
}

Essa parte é muito importante, nesse arquivo de configuração estaremos incluindo quais objetos iremos comparar, então para nós precisamos passar a resposta esperada e a resposta recebida.

Com essas informações, ele estará usando o assert no arquivo json e estará avaliando o que está escrito.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

O EvaluateAsync<T> avalia e retorna T, no nosso caso passamos o string para avaliar e o globals, que possui os dados onde irá avaliar.

Vou tentar explicar isso com um exemplo, usando uma entrada (que possui nome, solicitação, resposta e afirmação).

{
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }

Vamos pegar as coisas importantes desta entrada, primeiro a afirmação "assert": "Request.Text == Response.Text", isso significa que ele irá comparar o Request.Text com o Response.Text e retornar o valor como um booleano.

Mas quando chamamos a função await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals) estamos passando 2 parâmetros:

string string para avaliar -> "Request.Text == Response.Text"
Dados globals para o avaliador -> neste caso temos que fornecer um Request e um Response, a solicitação é a nossa resposta esperada e a resposta é a resposta recebida.

Como estamos preenchendo os dados no avaliador, agora podemos usar a string e avaliar, assim ela retornará true ou false.

Concluído

Terminamos, aqui você pode ver o TestMethod finalizado

[TestMethod]
public async Task ShouldTestSingleCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\data.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert

 foreach (TestEntry entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;

 if (entry.Request.Type == ActivityTypes.Message)
 {
 /// Act

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }
 }
 await Task.CompletedTask;
}

Diagrama

Aqui está um diagrama de todo o fluxo que seguimos para chegar a este ponto, espero que se você não entendeu algo, isso esclareça tudo.

E isso é tudo, isso é feito para casos únicos onde o caso é 1 para 1, o usuário envia um activity e o bot retorna outro único activity.

Espero que tenham gostado, o próximo serão os casos de fluxo de testes com mais de uma resposta.

Lembre-se de que todo o código está armazenado em meu github em este repositório.

Palestras

Mon, 01 Jan 0001 00:00:00 +0000

Sou um palestrante frequente em conferências internacionais de tecnologia, com foco em .NET, Azure, IA e desenvolvimento cloud-native. Fui homenageado como Sessionize Most Active Speaker em 2023, 2024 e 2025, e detenho a certificação Microsoft MVP em Tecnologias para Desenvolvedores.

Se deseja que eu fale no seu evento, vamos conversar!

2026

Blazor em 2026

Um olhar sobre o estado atual do Blazor em 2026 e como ele evoluiu junto ao .NET 10. Revisamos as últimas mudanças e melhorias, seu impacto no desenvolvimento de aplicações do mundo real e qual modelo de hospedagem Blazor se encaixa melhor em cada cenário.

Turbinando o Suporte de Nível 3 com IA: Azure Functions + OpenAI em Ação

Como Azure Functions, alertas do Azure Monitor e Azure OpenAI trabalham juntos para acelerar o suporte de Nível 3. Desde triage automático de alertas até análise inteligente de logs — um olhar prático sobre adicionar IA a fluxos de trabalho de suporte reais.

Do dashboard ao agente: o próximo passo da observabilidade

Uma sessão prática conectando o mundo dos agentes IA e a observabilidade em produção. De Semantic Kernel a agentes autônomos que consultam dados OpenTelemetry, interagem com Grafana via MCP e ajudam a operar e otimizar sistemas reais.

Em breve: Global Azure 2026 — Abril 2026, Madrid, Espanha

2025

O Framework de Agentes da Microsoft para salvar o Natal

Construindo e coordenando múltiplos agentes IA usando o Microsoft Agent Framework para encontrar os presentes de Natal perfeitos. Cada agente se especializa — desde geração de ideias de presentes até comparação de preços — trabalhando juntos para compras natalinas mais inteligentes.

Potencializando o Suporte de Nível 3 com IA: Azure Functions + Semantic Kernel em Ação

Azure Functions, Azure Monitor e Semantic Kernel trabalhando juntos para tornar o Suporte de Nível 3 mais rápido e eficiente — desde detecção automática de alertas até análise inteligente de logs.

O que há de novo no Blazor com .NET 10?

Explorando os principais novos recursos do Blazor para .NET 10, incluindo melhorias de desempenho, formulários, estado persistente e interoperabilidade JavaScript mais poderosa.

IA Híbrida com C#, Semantic Kernel e Gemini: Construa Apps Empresariais mais Inteligentes

Orquestrando fluxos de trabalho de IA híbrida em C# — misturando modelos locais (Phi-3) com Gemini Pro/Ultra via Vertex AI, construindo agentes cognitivos com plugins do Semantic Kernel e projetando arquiteturas adaptativas.

.NET Aspire: Construindo Apps Cloud-Native Sem Dor de Cabeça

Uma sessão prática construindo microserviços cloud-first que nascem escaláveis, resilientes e observáveis. Explorando como o .NET Aspire elimina 70% do boilerplate de cloud.

.NET Aspire: Cloud-Native Sem o Caos

Exemplos do mundo real de design de aplicações que nascem escaláveis — com observabilidade e resiliência automática integradas desde o primeiro commit.

2024

IA Encontra SQL: Construindo uma Pizzaria Inteligente com .NET e Semantic Kernel

Interações de IA em linguagem natural que entendem seu código e seus dados — construindo uma pizzaria inteligente com .NET e Semantic Kernel.

.NET Aspire: Aplicações Cloud-Native sem complicações

Construindo microserviços cloud-first sem dor de cabeça — uma sessão prática e orientada a demos mostrando como o .NET Aspire simplifica o desenvolvimento cloud-native.

Power Platform: A Jornada do Low-code para as Tecnologias Pro-code

Transição de Power Apps de baixo código para componentes pro-code avançados usando TypeScript, tudo na mesma plataforma.

Automação Inteligente: Transforme suas Aplicações Empresariais com IA Integrada

Levando as aplicações .NET ao próximo nível — combinando lógica tradicional com raciocínio baseado em IA usando Semantic Kernel e .NET Aspire.

Do Low-Code ao Pro-Code: Abordagens para o Desenvolvimento de IA em Soluções Empresariais

Explorando diferentes abordagens para soluções empresariais — de Power Platform com IA ao desenvolvimento tradicional com Semantic Kernel.

Controlando Gastos de Viagem com Azure

Usando Azure AI Vision, Document Intelligence e OpenAI com Semantic Kernel para automatizar o gerenciamento de despesas de viagem.

Badges e Reconhecimentos

🏆 Sessionize Most Active Speaker 2025
🏆 Sessionize Most Active Speaker 2024
🏆 Sessionize Most Active Speaker 2023
🏅 Microsoft MVP em Tecnologias para Desenvolvedores

Ver todas as sessões no Sessionize →

Sobre mim

Mon, 01 Jan 0001 00:00:00 +0000

Sobre mim

Sou Emiliano Montesdeoca, um desenvolvedor de software uruguaio-espanhol, Microsoft MVP em Tecnologias para Desenvolvedores, e pai orgulhoso baseado em Tenerife, Ilhas Canárias.

Adoro enfrentar desafios técnicos complexos e construir soluções cloud escaláveis com tecnologias Microsoft. Meu kit de ferramentas diário gira em torno de .NET, Azure, IA com Semantic Kernel e arquiteturas modernas como .NET Aspire.

O que eu faço

Como Cloud Solutions Team Lead na Intelequia Technologies, lidero o design e a entrega de aplicações cloud-native — combinando visão estratégica com execução prática. Prospero na interseção entre arquitetura e código, garantindo que nossa equipe entregue soluções elegantes e prontas para produção.

Comunidade

Sou um palestrante internacional frequente, tendo sido reconhecido como Sessionize Most Active Speaker em 2023, 2024 e 2025. Compartilho insights práticos do mundo real através de palestras em conferências ao redor do mundo e através dos meus blogs.

Também sou o criador de The .NET Blog — um recurso para a comunidade .NET — e escrevo regularmente neste blog sobre o que aprendo e construo.

Mentoria e construção de comunidade são uma parte essencial de quem sou. Retribuir ao ecossistema que moldou minha carreira é algo que levo muito a sério.

Vamos nos conectar

Estou sempre aberto a falar em eventos, colaborar em projetos ou conversar sobre arquitetura cloud e IA. Sinta-se à vontade para entrar em contato!

Email: emimontesdeoca@outlook.es
GitHub: @emimontesdeoca
X / Twitter: @emimontesdeocaa
LinkedIn: emimontesdeoca
Instagram: @emimontesdeoca
Sessionize: emimontesdeoca

Emiliano Montesdeoca

Blazor do zero: Capítulo 3 — Componentes que escalam

O que um componente Blazor realmente é

Passo 1: Comece com um componente focado

Passo 2: Use parâmetros para deixar o comportamento explícito

Passo 3: Use RenderFragment para composição

Passo 4: Prefira composição em vez de páginas gigantes

Passo 5: Equilibre markup e lógica

Passo 6: Estrutura de pastas prática

Erros comuns no início com Blazor

Próximo capítulo

Blazor do Zero: Capítulo 2 — A tua primeira app Blazor

Passo 1: Criar o projeto

Passo 2: Executar localmente

Passo 3: Entender a estrutura do projeto

Passo 4: Fazer a primeira alteração

Passo 5: Ler o Program.cs uma vez

Problemas comuns

Próximo capítulo

Blazor do Zero: Capítulo 1 — O que é Blazor?

Um breve historial

O que o Blazor realmente é

Os modelos de renderização

SSR Estático

Servidor Interativo

WebAssembly Interativo

Modo Auto

Misturar modos na mesma app

Como o Blazor se compara com frameworks JavaScript

O que precisa para acompanhar a série

A seguir

Blazor do Zero: Uma Nova Série

Para Quem É Esta Série

O Que Vamos Abordar

Por Que Uma Série, Por Que Agora

Como Acompanhar a Série

Tipos de união C#: Uniões discriminadas estão finalmente chegando

O que são sindicatos discriminados?

Como simulamos sindicatos hoje

Registros abstratos com herança

Enum manual + padrão de dados

A proposta C#: a palavra-chave union

Membros somente de valor

Uniões Genéricas

Uniões com Métodos

Correspondência de padrões aninhados

Cláusulas de proteção

Exemplos práticos

O padrão de resultado: substituindo exceções por erros esperados

Modelagem de Domínio: Tipos de Pagamento

Máquinas de Estado

Considerações sobre serialização e interoperabilidadeUma das questões práticas que surgem imediatamente com os tipos de união é: como serializá-los? Se você estiver criando APIs ou armazenando dados, precisará da serialização JSON para funcionar corretamente.

Como experimentar

Comparação com abordagens existentes

O que isso significa para o ecossistema .NET

Conclusão

Construindo um sistema RAG em C# com Kernel Semântico

Introdução

Como funciona o RAG

Pré-requisitos

Configurando o kernel

Definindo o modelo de dados

Fragmentação de documentos

Ingestão de documentos

Procurando por pedaços relevantes

Gerando respostas com contexto

Usando

Passando para produção

Construindo fluxos de trabalho de agentes com o Microsoft Agent Framework

Introdução

O que são fluxos de trabalho de agentes?

Pré-requisitos

Construindo um fluxo de trabalho sequencial

Definindo os agentes

Executando sequencialmente

Execução paralela

Ramificação condicional

Adicionando plug-ins a agentes de fluxo de trabalho

Tratamento de erros em fluxos de trabalho

Melhores práticas

Passo 3: Use `RenderFragment` para composição

A proposta C#: a palavra-chave `union`