DEV Community: Rodolpho Alves

A brief intro to SLF4J and the Java logging hell

Rodolpho Alves — Sun, 04 Sep 2022 18:06:08 +0000

Intro

This will be breaking my chain of Articles written in Brazilian Portuguese, I've fallen into the habit of making my study notes in English to make them easier to share. I'll soon translate everything here and create a translated version!

A brief history of logging in Java

At the dawn of Java logging still wasn’t as important as it is today, and as most languages of at that time everything boiled down to writing lines to the console and that was good enough! Why do you need standards and fancy structures when memory is sparse, right?

So it was common to see folks using the rather annoying System.out and System.err and doing their own solutions to write logs to files and other places!

log4j is born

This is where the Open Source community first steps in! Since Java lacked any logging standard whatsoever and it’s “native logger” (being generous here given it was err and out...) was rather poor when it came to features the community itself rose to the challenge and log4j was created as a mean to provide extensible, configurable and standardized logging for Java.

Nowadays log4j is infamous due to the security incident that wreaked havoc across the industry back in December 2021, but at its time it was a good thing. Not perfect, but good!

Of course Sun, the Java owner back then, quickly got wind of a need for standards and native ways to log stuff so they decided to make that happen!

The ‘native’ library enters the fray

With JDK 1.4, in 2002, java.util.logging was released as a native offering for logging. But… it wasn’t well received. First it was hard to decouple and isolate, then for some unknown reason they also decided it’d be nice to reinvent the wheel and use a bunch of random names for log levels instead of the standardized ones the industry had. Thanks to that you had pearls such as being able to log.fine("this is fine") but also being able to log.finer("this is even finer!") and not to mention the best of all log.finest("really great logging levels, innit?")... as you may have notice the way they decided to standardize log levels was quite log.severe("not good")!

🤦🏻 Worth noting that up to this day the java.util.logging library keeps this standard due to backwards compatibility. So even when doing Kotlin stuff in Android you can still log great fine and severe messages if you wish!

I need to switch loggers! Now what?

Now that there were two ‘popular’ contenders a new problem began to surface: What if I want to move my project from the amazing java.util.logging library into log4j?

Since both libraries were coupled to their own implementation that meant you’d need to refactor your whole code at once or roll with two logging libraries for a while. You could also create your own interfaces and implementations to hide the logging details from caller! And that’s what the community did!

Apache common-logging was born to provide means to abstract the implementation details of any logging library and provide a common, standard, API that any Application may use without caring who’s writing the logs behind the curtains! It had its shortcomings and wasn’t that widely adopted, but it’s idea lived on to see a better implementation be born. Enter SLF4J.

SLF4J to the Rescue

Simple Logging Facade for Java (SLF4J for short) is an out-of-the-box set of Interface and Abstractions that aim to consolidate and standardize logging in the JVM environment, while allowing decoupling.

The decoupling is achieved because you need only to rely on SLF4J interfaces during our implementation. This wizardry is achievable because logging libraries itself need to provide “Wrappers” or “Adapters” that plug into SLF4J abstractions to then deliver their logging functionalities.

import org.slf4j.Logger
import org.slf4j.LoggerFactory

/**
 * get a SL4J logger and do something
 */
fun getLoggerAndLog() {
    val logger: Logger = LoggerFactory.getLogger("my logger") // note that this is a SLF4J Logger Interface!
    // whichever library is 'wrapped' by SLF4J now handles the levels, formatting and everything!
    logger.debug("this is a debug message")
    logger.info("this is some information")
    logger.warn("this is a warning!")
    logger.error("this is an error")
}

In practical terms what happens here is that you need at least two dependencies to be added to your project for this to work:

'org.slf4j:slf4j-api' for the SLF4J interfaces
log4j-slf4j18-impl, com.github.tony19:logback-android, ch.qos.logback:logback-classic for the SLF4J ‘providers’

The provides themselves use Reflection and other technologies to “tie” into the LoggerFactory class and routines provided by SLF4J!

What is a “Facade”

The “Facade” within SLF4J stands for the Facade Design Pattern. In a nutshell a Facade attempts to provide a simpler (and common) access method to complex systems beneath it. This is good because it can allow for decoupling between clients of those subsystems and themselves while also reducing the need to completely understand those subsystems!

Imagine you want to buy something online. As a developer you know that you’re only inputting information in a website (or a mobile app) but you also know that there’s something beneath it. Beneath every ecommerce out there there’ll be APIs, Messaging and Databases! In a way you could say that the Frontend is a Facade for everything that happens underneath. As an online shopper you don’t need to know about which API calls are happening and which Messages are being sent over RabbitMQ, you just care that interacting with the ‘buy’ routine does all the magic for you.

Sample - Logback on Android!

First things first: Let’s start by adding the SLF4J dependency to our Application’s Gradle file:

/* snip */
dependencies {
        /* Adding SLF4J's Interfaces */
    implementation 'org.slf4j:slf4j-api:1.7.36'
}

Now we’d need to add Logback’s library, but since there are some additional steps required to run Logback on Android we can use a forked version that does all the extra work for us already: Logback-android. Now, to get Logback working we’ll need to first add the dependency and add the logback xml configuration to the application’s assets:

/* snip */
dependencies {
    implementation 'org.slf4j:slf4j-api:1.7.36'
        /* Logback-android */
    implementation 'com.github.tony19:logback-android:2.0.0'
}

<configuration>
  <appender name="logcat" class="ch.qos.logback.classic.android.LogcatAppender">
    <tagEncoder>
      <pattern>%logger{12}</pattern>
    </tagEncoder>
    <encoder>
      <pattern>[%-20thread] %msg</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="logcat" />
  </root>
</configuration>

Now all that’s left is to request a Logger by invoking the LoggerFactory.GetLogger method from SLF4J and you can Log away!

lateinit var log: Logger

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    log = LoggerFactory.getLogger("test")
    log.debug("Initializing, now with 101% more HILT")
    setContent {
        AppCanvas {
            Greeting(log)
        }
    }
}

Additional Resources

Complete notes available on my Notion workspace.

This post's cover is from https://undraw.co/

Mantendo a sanidade no mundo de Tecnologia

Rodolpho Alves — Sat, 09 Apr 2022 21:57:45 +0000

Salve pessoal! Esse será o primeiro post em que irei, brevemente, lançar um "podcast" sobre lá no YouTube! A ideia é prover um contexto por escrito para deixar registrado e disponível para aquele que, como eu, não são fãs de ficar assistindo vídeos ou podcasts direto 😎️.

Antes de irmos para o post preciso deixar algo claro: Tudo que está escrito aqui é baseado na minha própria experiência como desenvolvedor, arquiteto e gerente na área de desenvolvimento, eu não sou e nem pretendo ser um psicólogo ou expert nessa área!

Mantendo a sanidade no mundo de Tecnologia

Não é novidade para ninguém que o universo de TI é uma loucura. São bugs explodindo, caminhão esperando nota fiscal pra sair, Injection na Sprint chegando à direita e esquerda e aquela constante demanda de descobrir (e conseguir usar) o que quer que seja a novidade daquele mês/trimestre/ano - não é a toa que burnouts sejam tão comuns no nosso universo.

Para complementar com a pressão do dia-a-dia também é comum em alguns casos sentirmos uma desconexão do trabalho do dia-a-dia e o impacto que chega a um usuário. Em pessoas focadas no backend isso é praticamente de praxe - são sprints a fio desenvolvendo alguma grande feature que irá entregar dados para vários clients ou vai permitir que vários outros sistemas se conectem com o nosso e no final é normal os "louros" irem para o frontend ou o mobile. Mas mesmo assim, nem tudo são flores para o frontend também, pois...

Ainda existe uma cultura de "proteger" desenvolvedores de feedback de clientes! Muitas vezes isso é feito com boas intenções em mente como "O cliente sempre quer demais" ou "O usuário nem olhou o tutorial" - como se o desenvolvedor não tivesse a capacidade de filtrar e extrair informações mesmo de feedback negativos - e no fim isso faz com que fiquemos cada vez mais desconectados da realidade do usuário e eventualmente fiquemos desmotivados e sem entender o porquê nosso trabalho é tão valioso!

Para a cereja no bolo da catástrofe temos também nós mesmos e nossa própria cobrança. Sempre olhamos para o colega, um YouTuber ou um post lá no StackOverflow e pensamos: "Como esse cara/guria é foda. Eu não sei metade disso..." - e nessas horas esquecemos uma realidade muito importante de programar em pleno século XXI: quase toda informação está a um Google/DuckDuckGo de distância, portanto memorizar os métodos e classes de uma biblioteca é opcional!. Na hora do pull request ou da review a gente esquece que aquele sênior pode ter passado por um processo enorme de ficar pesquisando e consolidando informações antes de chegar naquele código totalmente clean e 100% testável! (Não se espelhe em desenvolvedores que não testam o próprio código 😂️)

As ferramentas para manter a Sanidade!

A introdução já foi um wall of text falando sobre os problemas e como chegamos neles, portanto é hora de falarmos um pouco de como podemos usar algumas coisas para combatermos tudo isso! Cada sub-seção aqui vai abordar uma das "ferramentas" na caixa da sanidade.

Entenda que ninguém é perfeito

Primeiro passo que eu costumo fazer comigo mesmo é me lembrar que perfeição é impossível. Todos nós temos pontos fortes e fracos, através do nosso auto-conhecimento podemos entender e nos planejar com isso em mente!

Por exemplo eu sei que sou fraquíssimo quando a questão é UI. Mesmo com um UX Designer me cantando tudo que precisa ser feito para a interface ficar bonita eu sei que eu sou travado ali e respeito essa limitação. Vou até onde eu posso, me esforço até onde dá sem me frustrar e garanto que tenho algum colega que pode me ajudar na hora de deixar uma interface de fato tinindo.

Por outro lado eu sei que sou muito bom em arquitetura. Com pouca informação consigo propor vários cenários com Pros e Contras e ajudar alguém a chegar numa decisão sobre como arquitetar sua solução. Pensando nisso eu sei onde posso melhor ajudar as pessoas e sei que vou compensar, de uma maneira ou de outra, aquele ponto fraco.

Parece clichê falar. Mas a chave aqui é se conhecer, entender seus limites e se respeitar - você nunca terá todas as respostas para todas as perguntas e está tudo bem, você não precisa disso pois dificilmente estará completamente isolado, em uma ilha deserta e sem internet, resolvendo problemas de TI.

Saiba pesquisar por informação

Sabendo (e aceitando) que não temos todas as respostas vem uma skill crítica em minha opinião: Saber buscar nas fontes de conhecimento coletivo os dados para a pergunta que você não sabe responder.

Existem várias fontes de informação que você tem à sua disposição! A pergunta que você quer responder provavelmente já foi (pelo menos parcialmente) respondida por alguém na Internet!.

No mínimo você tem acesso a essas fontes - saber como utilizar elas a seu favor vai ser um baita diferencial para dar aquele "unblocker" sem precisa se frustar tanto!

DuckDuckGo e Google: Saber pesquisar direto em qualquer search engine significa ter o poder da Internet inteira em sua mão
StackOverflow: Provavelmente vai precisar peneirar um pouco (e torcer para ter uma resposta atualizada), mas costuma ser útil para pelo menos ter ideias alternativas!
GitHub: Se você está utilizando uma biblioteca open source famosa, muito provavelmente, outras pessoas também estão! Então por qual motivo não poderíamos dar uma olhada em como os outros estão usando essas bibliotecas?
Repositórios da sua Empresa: Se é uma biblioteca interna ela está em algum repositório interno. Seja um GitHub, BitBucket, GitLab ou GitTea da vida: você também pode (e deve!) pesquisar no códigos dos outros nesses repositórios! Novamente, nem que seja para ter uma pequena nova ideia ou tentar algo levemente diferente!
YouTube: Existem muitos criadores de conteúdo para vários frameworks e linguagens de programação! É por aqui que normalmente descubro novas bibliotecas ou padrões para utilizar em meus projetos individuais.

Confie na sua equipe

No dia-a-dia normalmente esquecemos que outra fonte de informação e apoio muito importante são nossos próprios colegas. Se mantivermos e cultivarmos um mindset de crescimento será muito mais prático consultar seus colegas para ter ajuda. Inclusive ao fazer isso estamos ajudando a consolidar o conhecimento das pessoas pois ensinar e explicar faz parte do próprio processo de aprendizado!

São aqui que podemos utilizar várias metodologias:

Pair Programming: Fazer uma sessão em que das pessoas colaboram para escrever código em um único lugar (um digitando e outro falando)
Programming Dojo: Similar ao pair programming porém com mais pessoas - uma vai bater o código e as outras falam, simplesmente revezando quem está batendo o código
Code Reviews: A maneira assíncrona e normalmente mais prática para algumas organizações. Simplesmente chame seus colegas para fazer review do seu pull request antes que fazer o merge. Mesmo que seu código esteja compilando e passando todos os testes existem nuances que apenas pessoas vão pegar!

Celebre pequenas vitórias

Para balancear com a enchurrada debugs lembre-se de celebrar e valorizar pequenas vitórias! Coisas "bobas" como passar por um code review só com aprovações, aumentar a performance de uma rotina por milisegundos, aumentar a cobertura de teste de uma área do sistema mesmo que por 5 linhas ou tirar um code smell antes que ele gere um bug são coisas a se celebrar!

Além disso lembre-se também de celebrar os pequenos avanços enquanto estiver estudando! Normalmente levamos várias semanas e meses para entender completamente uma nova tecnologia, portanto não custa celebrar aquela primeira prova de conceito que fez o Kafka funcionar ou um cache no Redis ser consultado pela sua api!

Tenha válvulas de escape

Talvez o mais crítico de tudo aqui seja este ponto: Você apenas trabalha uma parte do seu dia - o resto do seu dia é seu e você deve aproveitar e respeitar isso.

Sempre que possível faça seus hobbies nesse tempo livre. Se não tiver um hobby busque um! Seja ele qual for (auxiliar em open source, escrever num blog, pedalar, correr, malhar, artes marciais, jogar video-game) esse hobby será sua válvula de escape para as horas de stress que acontecem no trabalho.

Não tem segredo - ninguém é de ferro! Algo que eu costumo muito fazer é sair para uma corrida ou um pedal mais pesado quando estou frustrado ou precisando arejar os pensamentos depois de um dia ou uma semana puxada.

E a melhor parte? Normalmente durante esses momentos que acabamos tendo as melhores ideias! Quando livramos a mente de toda a pressão e passamos a fazer algo mais "relaxante" (mesmo que canse mais o corpo kkk) conseguimos ativar nossos processos criativos e muitas vezes vemos possíveis saídas para os problemas que estavam nos assombrando durante o horário de trabalho.

É por isso que vemos essa quantidade de pessoas de TI acabando, por exemplo, indo para Maratonas, Triathlon, pedais de longa distância ou gravando vídeos aleatórios!

As Vantagens de estar bem

Só para sintetizar e encerrar o post: estar bem é o segredo para o sucesso no longo prazo. Ao estar "bem" você vai ter um processo criativo melhor (e não se engane - programar requer criatividade mesmo que não seja uma arte!), você irá se frustar menos quando errar aqui ou ali, ter uma jornada de aprendizado mais estável e sustentável e conseguirá recarregar as baterias constantemente para conseguir participar daquela reunião mais chata da semana.

Configurando um ambiente Windows para desenvolvimento

Rodolpho Alves — Wed, 08 Sep 2021 01:01:57 +0000

💭 Introdução

Que atire o a primeira pedra o desenvolvedor que usa primariamente Windows que nunca enrolou pra atualizar ou formatar uma máquina por causa do Setup estar redondo... salvo por aquele bug chato ou serviço travando a máquina toda 🤷‍♂️

E isso é uma coisa que não tem como argumentar (ainda) que o pessoal primário Linux tem de mão beijada!

Mas e se eu te falasse que com um pouco de paciência, planejamento e ~~magia~~ scripts de Powershell conseguimos chegar a algo próximo?

Cover para o post via UnDraw

🤔 Planejando!

Antes de tudo temos de pensar:

O que eu realmente preciso, do zero, em uma instalação nova do Windows?

Se questione, antes de partimos para as próximas etapas:

Qual meu foco primário?
Quais ferramentas preciso sempre?
Quais linguagens preciso sempre?
Quais atalhos gosto de usar sempre?
Quais "frescuras" instalo sempre?

As minhas respostas, em ordem:

Backend
Git, Powershell Core, Windows Terminal, SSH, Visual Studio Code, WSL, Docker
C#, Typescript
Meus atalhos de Git e Navegação terminal
oh-my-posh, posh-git, fontes com ligatures

Com base nessas respostas que vou pesar qual ferramentas de package irei utilizar e a prioridade!

Por exemplo apesar de sempre usar o Visual Studio em si sei que ele é mais demorado de instalar e, portanto, não ligo de precisar deixar ele rodando por mais tempo. Os outros ali da lista conseguem ir cobrindo a falta dele para as primeiras horas ou dia do novo setup!

1 - Escolhendo sua ferramentas para Packages

Para quem é acostumado com os Nix sabe que sempre tem um Package Manager da vida, o famoso sudo apt-get install (e similares, nem tudo é apt-get). Mas no Windows infelizmente estamos acostumados a sair caçando instaladores internet a fora, baixando, clicando em vários Next e só então vemos a coisa ser instalada.

Note que estou focando nos ambientes comuns. Existem soluções para criar imagens inteiras do Windows disponíveis para quem quer se dedicar a esse nível mas... quantas vezes você vai fazer isso fora de um ambiente empresarial?

Para o seu ambiente pessoal o que é mais fácil? Manter uma imagem de instalação pronta ou configurar alguns scripts?

Felizmente a própria comunidade partiu pro ataque e surgiu com alguns soluções para Package Managers no Windows! Alguns deles são:

Chocolatey: Requer instalação (Powershell)
Scoop: Requer instalação (Powershell)
Winget: Já incluso nas builds Insiders, passará a ser nativo no futuro, pode ser instalado pela Store

O que eles têm em comum?

Todos contam com a comunidade para manter sua lista de packages atualizada
Todos são OpenSource

Então qual o grande diferencial? A quantidade de packages que cada um tem. Em números o Chocolatey toma a frente, seguido pelo Winget e pelo Scoop. Porém o Winget se tornará nativo ao Windows em breve, enquanto que os outros precisaram de passos adicionais.

2 - Escolhendo um Package Manager com base nas suas necessidades

Essa é uma escolha que você deverá fazer com base nas ferramentas que você utiliza no seu dia a dia. No meu caso, por utilizar várias ferramentas da Microsoft, vou de winget.

Como estou utilizando o winget vou pesquisando e salvando, em um .txt a lista de ferramentas que tenha disponíveis por ele e desejo instalar. Para isso executo o comando winget search <nome_software>, trocando as o campo <nome_software> pelo nome de o que gostaria de instalar, como o próprio SDK do dotnet.

A seguinte lista é a que estou montando para a próxima vez que formatar meu laptop pessoal, todos estes são ids válidos do winget:

7zip.7zip
Mozilla.FirefoxDeveloperEdition
Microsoft.VisualStudioCode-User-x64
Git.Git
Microsoft.PowerShell
Microsoft.WindowsTerminal
Microsoft.dotnet
ditto.ditto
ShareX.ShareX
code52.Carnac
Microsoft.PowerToys
VideoLAN.VLC

A lista é "pequena" mas lembre-se: Estou focando apenas no absolutamente essencial para que eu comece a trabalhar/estudar utilizando o ambiente. O Docker, Visual Studio e WSL terão de vir depois.

🛠 Preparando!

3 - Automatizando os básicos

Como estamos falando do Windows devemos lembrar que o Powershell é uma grande ferramenta e seu amigo nas horas em que precisa automatizar algo! Ele não é tão difundido quanto os shell scripts mas ele é capaz de muita coisa!

Meu primeiro script de automação do setup vai ser um bem básico, seguindo o seguinte algoritmo:

Verifique se o winget está disponível, se sim continue
Pegue um arquivo .txt
Carregue o conteúdo, linha a linha
Para cada linha, em ordem de leitura: a. Execute winget install -e --id $linha

A implementação final é essa aqui, junto com o arquivo que mostrei acima com os IDs:

$SoftwareListFile = ".\software_list.txt"
[string[]]$SoftwareList = Get-Content $SoftwareListFile

<#
.SYNOPSIS
    Checks if a Command is currently available on Powershell
#>
function Test-CommandExists {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]$testCommand
    )

    try {
        Get-Command $testCommand -ErrorAction Stop
        return $true
    }
    catch {
        return $false
    }
}

if (!(Test-CommandExists winget)) {
    Write-Host "Winget not found, unable to continue"
    Write-Host "Check on https://github.com/microsoft/winget-cli for instructions"
    return -1
}

Write-Output "This script will attempt to install multiple softwares on your system"
$DoInstall = Read-Host -Prompt "Are you sure you want to install? If so, type 'install' bellow."
$WingetCommandParam = ($DoInstall -eq "install") ? $DoInstall : "search";

$SoftwareList
| ForEach-Object -Process {
    &winget $WingetCommandParam -e --id $_
}

Write-Output "Done!"
if (!(Test-Path "${PSScriptRoot}\bootstrap.ps1" -PathType Leaf)) {
    return;
}

$DoBootstrap = Read-Host -Prompt "Type 'bootstrap' bellow if you want to run dotfiles' bootstrap as well"
if ($DoBootstrap -eq "bootstrap") {
    . "${PSScriptRoot}\bootstrap.ps1"
}

Para quem não está acostumado com powershell pode parecer um pouco grego, mas acredite: Não tem nada ali que não seja explicado por um help <comando> no Powershell e a estrutura é bem parecida com o algoritmo, salvo a quantidade de outputs que faço!

Agora podemos ir para o próximo passo: preparar nossos dotfiles.

4 - `dotfiles` no Windows

"Mas o que são dotfiles, Rodolpho?"

dotfiles são arquivos que normalmente começam com . (algo oculto no Unix) e, normalmente, armazenam alguma configuração.

Alguns dotfiles famosos e suas aplicações são:

.gitignore: Configura os arquivos que devem ser ignorados em um repositório Git
.gitconfig: Configurações do seu usuário, normalmente encontrado em ~/.gitconfig (mesmo no Windows!)
.bashrc: Configuração do Bash. No caso do Powershell substituímos esse aqui pelo Profile.ps1!

Se você programa provavelmente vai ter um .gitconfig mesmo que nunca o tenha criado manualmente, pois os comandos git config --global normalmente acabam gerando o arquivo para você 🙂.

Explicarei na próxima seção a ideia do $PROFILE, mas para finalizarmos sobre dotfiles vamos gravar o conceito:

Um repositório de dotfiles contem arquivos de configurações que você quer compartilhar entre ambientes e um script (.sh ou .ps1) que gera links simbólicos (são tipo atalhos, mas pra gente grande) entre os arquivos do repositório e os arquivos armazenados no sistema operacional.

Ou seja, uma vez criado seu dotfiles, você só precisa fazer um git pull, ./script_que_cria_links.ps1 e sua máquina está sincronizada com o que quer que vc tenha colocado no repositório.

O PROFILE do Powershell

Quanto ao Profile.ps1 você provavelmente o acessará através do powershell com o comando code|vi|vim|nvim $PROFILE (só tire dali os editores que você não usa).

O $PROFILE é um arquivo que é executado sempre que você abre um powershell. Normalmente ele conterá atalhos, importações de módulos e verificações de que algo está disponível ou não.

O meu $PROFILE normalmente contem uma série de atalhos do Git, ativação de Modules, verificações do ambiente, atalhos para navegação e segredos específicos do Powershell.

Um pequeno trecho do meu $PROFILE:

# All Shortcuts
Set-Alias -Name "back" -Value Pop-Location
Set-Alias -Name "push" -Value Push-Location
Set-Alias -Name "touch" -Value New-Item
Set-Alias -Name "open" -Value Invoke-Item

<#
.SYNOPSIS
    Calls fetches and pulls updates from the upstream branch. Stashes and Pops if there are uncomitted changes
.DESCRIPTION
    Shortcut function for calling git fetch and git pull while keeping uncomitted changes
#>
function Invoke-Git-FetchAndPull {
    git fetch --all
    git diff --exit-code
    $hasDiff = $LASTEXITCODE
    if ($hasDiff) {
        git stash
    }
    git pull
    if ($hasDiff) {
        git stash pop
    }
}

<#
.SYNOPSIS
    Calls fetch and then rebases into the target branch
.DESCRIPTION
    Shortcut function for calling git fetch and git rebase -i
.PARAMETER TargetBranch
    The branch to rebase on, defaults to origin/develop
#>
Function Invoke-Git-FetchAndRebase {
    [CmdletBinding()]
    param (
        [Parameter(HelpMessage = "The branch to rebase on, defaults to origin/develop")]
        [string]
        $TargetBranch = "origin/develop"
    )
    git fetch --all
    git rebase -i $TargetBranch
}

# Attempt to load posh-git
try {
    Import-Module posh-git
}
catch {
    Write-Error "Unable to Import-Module posh-git, it wasn't found"
}

# Checks if SSH Agent is running and git is configured
    try {
        $sshAgentStatus = (Get-Service -Name "ssh-agent").Status
        if ($sshAgentStatus -ne "Running") {
            Write-Warning "ssh-agent isn't running, you should change its initialization"
        }
        if ($null -eq $GitSshConfig) {
            Write-Warning "GIT_SSH isn't set, it might not use windows' OpenSSH"
        }
    }
    catch {
        Write-Warning "Unable to check on ssh-agent status"
    }

Como eu tenho vários atalhos, para mim, é vantajoso manter uma cópia deste perfil no meu dotfiles para que eu consiga ter a mesma produtividade em todo ambiente meu que tiver Powershell.

Caso você queira uma base para começar seu dotfiles para Windows pode dar uma olhada no meu repositório abaixo 👇

rodolphocastro / dotfiles

Dotfiles for my Windows and Linux environments

Rodolpho Alves' dotFiles

Those are my personal settings for my Windows' environments.

If you want to use this consider forking it and changing it to your fit your own needs, don't go around blindly running scripts from the internet!

What are dotfiles

In a nutshell:

Basically this is an old-school way to OneDrive/Google Sync/Dropbox your settings. At least those that are easy to automate.

A dotfiles repository is an attempt to keep multiple settings in-sync across multiple environments without relying on external solutions. Basically once you have this repository done all you gotta do is git clone it into a new environment and run the bootstrap script.

The biggest challenge for this set of dotfiles is to deal with the Windows' way of setting stuff up. Thus why you'll notice some powershell wizardry going on. Things like what I'm trying to achieve here are way easier on nix…

View on GitHub

▶ Executando!

Tudo planejado, salvo em um pen drive e/ou na nuvem? Hora de botar a mão na massa!

5 - Rodando scripts

O primeiro passo pra sair rodando coisas num Powershell zerado é ajustar a ExecutionPolicy da sua sessão.

O comando Get-ExecutionPolicy irá te dizer qual o atual nível. Para você fazer alterações normalmente quer defini-la (Set-ExecutionPolicy) como Bypass ou RemoteUnsigned com o -Scope Process. Traduzindo: você irá permitir que o atual powershell que você está executando faça mais alterações que o normal.

Feito isso é só partir para o abraço e rodar o script que fizemos na seção acima para instalar seus softwares.

6 - Baixando nossos `dotfiles`

Tudo instalado? Hora de fazer um git clone <seu_repositório_dotfiles>, entrar no repositório e executar o script bootstrap.ps1!

7 - Usando o OpenSSH do Windows 10 com o Git

É curioso como algo tão útil passa tão batido. Porém o Windows 10 possui uma versão do OpenSSH embutida!

Você não precisa usar um cliente de terceiros para poder usufruir do ssh com o Git. Basta fazer alguns ajustes:

Colocar o OpenSSH Agent para executar a. Você pode fazer isso via Powershell ou via Serviços do Windows
Criar um par de chaves
Adicionar essas chaves ao OpenSSH Agent
Cadastrar a chave pública com o seu Repositório Remoto
Ajustar uma variável de ambiente

Irei pular o item #4 pois isso vai ser específico do seu servidor. Seja ele um GitHub, GitLab, BitBucket ou Gitea.

Ligando o OpenSSH Agent

Com Powershell

Para os fãs de Powershell basta rodar esse script numa instância de admin:

# Busca o serviço do windows chamado ssh-agent
$sshAgentService = Get-Service -Name "ssh-agent"
# Se o serviço não estiver iniciando com delay...
if ($sshAgentService.StartType -ne "AutomaticDelayedStart") {
    Write-Warning "Setting SSH Agent to DelayedStart"
    # Mande ele iniciar com delay!
    Set-Service -Name "ssh-agent" -StartupType AutomaticDelayedStart
}

Sem Powershell

Para quem não é fã do Powershell:

Abra o Executar (Atalho: Win+R) e digite services.msc.

Ordene a lista por nome e encontre um serviço chamado "OpenSSH Authentication Agent", dê um clique-duplo nele.

Na tela de propriedades altere o "Startup Type" para "Automatic (Delayed Start)", conforme:

Clique em Apply e Ok.

Criando e Adicionando Chaves SSH

Através de um terminal execute o seguinte comando, substituindo pelo seu email:

ssh-keygen -o -a 100 -t ed25519 -C "meu-email@gmail.com"

Isso irá criar um par de chaves ED25519 no diretório ~/.ssh, uma com o final .pub (Spoiler: Essa é a que você copia e cola no seu servidor!).

Agora para cadastrar sua chave com o OpenSSH Agent rode ssh-add.exe e confirme a senha da sua chave. Você verá algo como no gif abaixo:

A mensagem "Identity added" é a indicação de que tudo deu certo.

Dizendo para o Git usar o OpenSSH

Finalmente só nos resta dizer para o Git: "ow, usa isso aqui ao invés do seu ssh embutido!".

Existem várias maneiras de fazer isso. Por .gitconfig, por links simbólicos e tudo. Mas, nas versões mais recentes do Git, temos uma maneira bem menos invasiva: Variáveis de ambiente.

Antes de tudo você precisa encontrar onde está o ssh.exe do Windows. Pra pegar o da sua máquina rode em um powershell:

# Encontrando o comando "ssh" e pegando seu path
(Get-Command ssh).Path
# A output provavelmente será C:\WINDOWS\System32\OpenSSH\ssh.exe

Com esta output em mãos só nos resta agora alterar a variável de ambiente GIT_SSH para C:\WINDOWS\System32\OpenSSH\ssh.exe!

Pelo Windows 10/11:

Digite no menu iniciar "Variáveis" ou "Environment"

Selecione o primeiro item e, na nova tela, clique em "Variáveis de Ambiente|Environment Variables..." no canto direito inferior

Em "System Variables" clique em "New", chame a variável de "GIT_SSH" e insira o valor que pegamos no powershell.

Pronto. Para testar se funcionou faça um git clone com ssh. Você provavelmente não terá de digitar sua senha da chave!

Dica: Além de funcionar para o Git o ssh-agent também estará funcionando para você configurar seus acessos por ssh para servidores!

8 - Windows Subsystem for Linux (WSL)

Tem coisas que só fazem bloat no Windows ou não dão aquela experiência legal, né? Eu, por exemplo, evito ao máximo instalar o node direto no meu Windows pois a experiência no Linux é simplesmente melhor!

Por muitos anos, antes do Windows 10, isso significava ter uma Máquina Virtual (normalmente no VirtualBox) e conectar nessa máquina pra, então, abrir uma IDE/Text Editor. Porém agora temos a possibilidade de executar o Linux dentro do próprio Windows (edição Home ou maior)!

Para isso basta instalar o Windows Subsystem for Linux (WSL), instalar sua distro favorita e partir pro abraço! Você terá acesso ao bash diretamente do seu Powershell.

As intruções completas (oficiais) podem ser encontradas neste link.

Habilitando o Windows Subsystem for Linux

Pré-Requisitos

Antes de tudo verifique se seu Windows está na versão certa! O WSL requer no mínimo a build 18362 do Windows 10 1903.

Outra coisa importante é que seu setup deve permitir virtualização! Isso normalmente será habilitado pela sua BIOS. É raro isso estar bloqueado mas já vi equipamentos que bloqueavam ou ocultavam a possibilidade de ativar virtualização...

Com Powershell

Com Powershell basta você abrir um prompt de Administrador e executar:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

E pronto! O Windows vai ativar a funcionalidade pra você.

Sem Powershell

Sem Powershell você terá de pesquisar, no iniciar, por "Features" e achar o "Turn Windows features on or off".

Dentro da janela de Features localize o WSL, marque-o, e clique em Ok. O Windows então instalará a feature para você!

Habilitando Virtualização no Windows

Com Powershell

Novamente em um Powershell de Administradores, execute:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Sem Powershell

Novamente lá na tela de "Turn Windows features on or off", encontre e marque a opção "Virtual Machine Platform":

Atualizando o Kernel do Linux

Localize e baixe o Kernel mais recente do Linux para WSL.

Ativando o WSL2

Finalmente podemos ativar o WSL2, esse passo só pode ser executado pelo Powershell:

wsl --set-default-version 2

Pronto! O WSL estará pronto para você utilizar após um reboot da máquina!

Instalando sua Distro favorita

Você agora poderá instalar as Distros de Linux presentes na Windows Store ou através do winget!

Algumas distros que estão disponíveis são:

Ubuntu
Debian
Alpine
openSUSE

Agora é uma questão de você escolher a sua favorita, instalar, abrir o terminal e digitar wsl para lançar uma sessão no bash da sua distro!

9 - Docker Desktop

Quando comecei a escrever este Post (faz um tempo! Ele está como rascunho a meses já!) o processo era um pouco mais complicado 😅

Porém, hoje em dia, colocar o Docker Desktop para rodar, em sua máquina Windows, é pra lá de tranquilo.

Se você tiver acesso ao "winget" (recomendo!) basta rodar um winget install DockerDesktop e seguir as instruções na tela.

Se você quiser seguir pelo método old-school, acesse o site oficial do Docker Desktop e clique em "Download for Windows".

Alterações recentes (2021) na licença do Docker Desktop

Para quem está fora do loop: No final de Agosto de 2021 a equipe do Docker alterou a licença do Docker Desktop. (Link da notícia oficial)

Para o seu uso pessoal pode ficar tranquilo. Salvo que você fature, como indivíduo, mais de U$ 10 milhões ao ano) essas alterações na licença deverão impactar apenas empresas de grande porte.

Em resumo, se na sua organização:

ou tem mais de 250 funcionários
ou fatura um montante que ultrapassa U$ 10 milhões

Você terá de pagar para poder utilizar o Docker Desktop para Windows ou MacOS.

Notas Finais

Muito do que eu falei aqui provavelmente ficará desatualizado quando, finalmente, recebermos o Windows 11 em Outubro/2021!

Mas, até lá, sinta-se à vontade para utilizar este post como uma base para configurar seu ambiente Windows. (Diga-se de passagem, eu mesmo tenho utilizado esse artigo, mesmo em rascunho, sempre que reinstalo o Windows em um de meus computadores)

Outra recomendação, e esta será atualizada para o Windows 11, é buscar no GitHub repositórios que tenham dotfiles para ambientes Windows. O meu repositório de dotfiles está disponível lá! 👇

rodolphocastro / dotfiles

Dotfiles for my Windows and Linux environments

Rodolpho Alves' dotFiles

Those are my personal settings for my Windows' environments.

If you want to use this consider forking it and changing it to your fit your own needs, don't go around blindly running scripts from the internet!

What are dotfiles

In a nutshell:

Basically this is an old-school way to OneDrive/Google Sync/Dropbox your settings. At least those that are easy to automate.

View on GitHub

Cell CMS - Organizando, reutilizando e testando consultas do EntityFramework Core

Rodolpho Alves — Thu, 04 Feb 2021 00:37:43 +0000

Cell CMS - Organizando, reutilizando e testando consultas do EntityFramework Core

Intro

No último post falamos sobre testes unitários e como tornar a escrita e manutenção deles prática. Mas também tocamos em um assunto controverso para alguns no universo .NET:

Devo utilizar EFCore.InMemory nos meus testes unitários ou devo abstrair uma UnitOfWork e repositórios?

A ideia do post de hoje é apresentar, brevemente, os dois lados e uma solução que apesar de não ser aderente à Orientação a Objeto é uma solução prática, testável e escalável.

Lembrando que boa parte dos snippets aqui estão implementados no Cell CMS, disponível lá no GitHub!

rodolphocastro / cell-cms

CMS leve, self-contained e prático de utilizar! Feito por desenvolvedores e para desenvolvedores!

Cell CMS

Branch	Status	Descrição
Master		Ciclo estável, recomendado para produção
Develop		Ciclo em desenvolvimento, recomendado para entusiastas

Cell CMS é um content management system que visa ser:

Leve
Auto Contido (self-contained)
Prático de Utilizar

Nosso foco é em disponibilizar um CMS que desenvolvedores possam facilmente referenciar em seus aplicativos, sites e sistemas.

📚 Instruções

Utilizando uma Versão publicada

WIP, iremos suportar imagens Docker e executáveis

Compilando

Você precisará ter instalado em seu ambiente o SDK 5.0.101 do Dotnet.

Uma vez configurado basta executar dotnet build .\cell-cms.sln na raiz do repositório.

Testando

Execute dotnet test .\cell-cms.sln na raiz do repositório.

Caso queira capturar informações de cobertura de testes utilize:

dotnet test --no-restore --collect:"XPlat Code Coverage" .\cell-cms.sln

⚙ Configurações

Autenticação/Autorização

O CellCMS utiliza o Azure Active Directory como provider de identidade, então você terá de configurar sua instância do AAD conforme explicado neste post.

As seguintes variáveis de ambiente…

View on GitHub

Cover pega no unDraw.co

Motivação para Abstrair o EF Core

A principal motivação para abstrair o EFCore é simples:

É mais fácil fazer Mocks/Stubs de Interfaces, classes abstratas e métodos virtuais, portanto elas são mais testáveis

Devido à essa preocupação que o próprio projeto do EntityFramework Core criou o Provider InMemory! Afinal, como esperar que seu framework seja amplamente adotado por projetos de grande porte se tudo que utiliza ele deixa de ser testável?

Mas, vamos às abordagens práticas!

Abordagem "clássica" - UnitOfWork + Repositories

A UnitOfWork é um dos "Enterprise Patterns". A ideia é bem simples:

Você precisa de uma classe que faça a gestão centralizada do estado do banco de dados durante um processo de negócio.

Ou seja, é função da UnitOfWork:

Prover acesso aos objects que estão armazenados nas tabelas do seu banco
Prover mecanismos para salvar alterações (Commit)
Prover mecanismos para reverter alterações (Rollback)

Normalmente junto à UnitOfWork vemos um segundo padrão chamado de Repository. A ideia de um Repository é:

Centralizar as consultas (Queries) a algum object, de maneira que possamos utilizar lógicas adicionais (como um Cache) em um único lugar e minimizar a quantidade de código replicado dentro do sistema.

Soa familiar com o que um DbSet<T> e um DbContext faz, não? Pois é! Mas chega de foreshadowing.

Como são patterns eles normalmente serão introduzidos como dependências da sua classes através de suas interfaces, normalmente chamadas:

IUnitOfWork, IProjetoUnitOfWork
IMeuObjetoRepository, GenericRepository<T>

Agora vamos pensar em suas vantagens e desvantagens, sempre considerando que estamos utilizando o EntityFramework Core como nosso ORM.

Caso você queira saber mais sobre os Enterprise Patterns: Dê uma olhada no livro Patterns of Enterprise Application Architecture do Martin Fowler

Vantagens

As principais vantagens são:

Abstração: Permite que utilizemos Mocks e Stubs de maneira extremamente prática
Amplamente conhecido: Esse pattern é quase tão conhecido como Singletons
Mantém o padrão de Orientação a Objeto
As interfaces podem ser exportadas facilmente para outros projetos: Se você quiser fazer uma reutilização máxima de código você poderia declarar um repositório no seu projeto de Domínio e deixar que os diferentes runtimes façam a implementação.

Para mim as principais vantagens são #1 e #4. Especialmente se pensarmos em utilizar uma abordagem que preza pela reutilização: A mesma interface pode ser implementada no frontend com acesso a uma API REST e no backend com acesso a um banco relacional!

Desvantagens

Mais uma classe para Manutenção
Difícil de adicionar novas funcionalidade: Como você deve alterar a assinatura da Interface (ou criar uma nova) cada nova query é um novo método
Difícil de compor queries: Se você permite múltiplos filtros terá de ter métodos com inúmeros parâmetros!
Utilização de generics orientados a Copy-Paste: Essa acho que é o maior downside que vi para a abordagem até hoje! Inúmeras vezes você vê o mesmo código colado em diferentes projetos para criar um GenericRepository<T> que alivia alguns dos problemas acima
Quebra do próprio Pattern: Para tentar balancear com a nova dependência é comum ver Repositories que retornam DTOs, fazem alterações no banco, etc...

Para mim as principais desvantagens são as #1, #2 e #5. Eu mesmo já fiz repositories que fazem mais que consultar e já tive de quebrar interfaces por causa de um parâmetro a mais de filtro.

Exemplos

O seguinte snippet contém uma implementação (feita para exemplo apenas, bem incompleta!) de uma Unit of Work para o Cell CMS:

/// <summary>
/// Descreve métodos para uma UnitOfWork do CellCMS.
/// </summary>
public interface ICellCMSUnitOfWork
{
    IRepository<Feed> Feeds { get; }

    Task CommitChanges();
}

/// <summary>
/// Descreve métodos para um repositório.
/// </summary>
/// <typeparam name="T"></typeparam>
public interface IRepository<T> where T: class
{
    Task<IEnumerable<T>> ListAll();
}

/// <summary>
/// Implementação genérica de um repository.
/// </summary>
/// <typeparam name="T"></typeparam>
public class GenericRepository<T> : IRepository<T> where T : class
{
    private DbSet<T> _set;

    public GenericRepository(CellContext context)
    {
        _set = context.Set<T>();
    }
    public async Task<IEnumerable<T>> ListAll() => await _set.ToListAsync();
}

/// <summary>
/// Simulação de uma Unit of Work para o CELL CMS.
/// </summary>
public class CellCMSUnitOfWork : ICellCMSUnitOfWork
{
    private readonly CellContext _context;
    public IRepository<Feed> Feeds { get; private set; }
    public CellCMSUnitOfWork(CellContext context)
    {
        _context = context ?? throw new ArgumentNullException(nameof(context));
        Feeds = new GenericRepository<Feed>(context);
    }

    public Task CommitChanges() => _context.SaveChangesAsync();
}

Abordagem funcional - Extension Methods

Primeiramente um disclaimer: Essa solução é boa para o universo .NET, onde temos suporte a Extension Methods.

Um extension method é um método que adiciona funcionalidade a uma classe/interface existente sem precisar alterar o código original.

Boa parte das operações LINQ são extension methods, assim como maior parte das opções do próprio EntityFrameworkCore! Sem acesso ao código podemos confiar no Intellisense para mostrar quando estamos lidando com um método que foi adicionado a um tipo por extension method, note o ícone diferente nesta imagem:

Extension Methods 101

Mas Rodolpho, como posso fazer um extension method?

É mais simples do que parece! Você só precisa:

De uma static class onde seu método será armazenado
De acesso aos métodos do Tipo a ser estendido
Criar um método static onde o primeiro parâmetro recebe a keyword especial this.

Por exemplo, os seguintes extension method permitem que eu serialize um objeto para JSON, recupere o mesmo objeto a partir de um JSON e realize uma cópia do objeto através de serialização:

Note que consegui estender um generic T e uma string e, nas últimas 3 linhas, eles são chamados como se fosse realmente parte do tipo Feed e string.

public static class MyExtensions
{
    /// <summary>
    /// Serializa um objeto para um JSON.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="obj"></param>
    /// <returns></returns>
    public static string Dump<T>(this T obj) where T : new()
    {
        return JsonSerializer.Serialize(obj);
    }

    /// <summary>
    /// Restaura um objeto de a partir de um JSON.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="t"></param>
    /// <returns></returns>
    public static T Restore<T>(this string t) where T : new()
    {
        return JsonSerializer.Deserialize<T>(t);
    }

    /// <summary>
    /// Clona um objeto.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="from"></param>
    /// <returns></returns>
    public static T Clone<T>(this T from) where T : new()
    {
        return from.
            Dump().
            Restore<T>();
    }
}

// Usando os extension methods
var cobaia = new Feed();
var copy = cobaia.Clone();
Debug.Assert(copy != null);

Como o Visual Studio mostraria que estou usando uma extension:

Vantagens

Testável por unidade: Como fazemos extensão de um IQueryable<T> podemos testar através de uma List<T>
Testável por integração: Novamente, como estendemos IQueryable<T> podemos testar através de um DbSet<T> do EFCore
Armazenável próximo ao Model: Se você curte Clean Code, podemos deixar estas queries no mesmo arquivo que a classe do Model!
Permite composição: Podemos chamar filtros após filtros conforme nossa necessidade, sempre precisar de um novo método para cada nova combinação de filtros
Não duplica o pattern UoW + Repository em sua aplicação.

Todos são pontos bem legais, na minha opinião, mas vou dar uma ênfase no #5 e faço isso pois o próprio EntityFramework Core é uma implementação deste pattern!

O DbContext que herdamos é uma UnitOfWork de cara por nos permitir criar transações, realizar commits e rollbacks. E cada DbSet<T> também é repositório pois nos permite interagir com o objetos armazenados no banco!

A própria documentação do EntityFrameworkCore explica:

Uma instância do DbContext representa uma sessão com o banco de dados e pode ser utilizado para consultar e salvar instâncias de suas entidades. O DbContext é uma combinação dos patterns Unit Of Work e Repository. (tradução livre pelo autor)

Com base nisso podemos concluir que:

Uma UnitOfWork sobre um DbContext é uma abstração feita sobre uma abstração!

Desvantagens

Menos reutilizável longe do EFCore: Como dependemos do IQueryable<T> fica mais complicado reutilizar essas queries em um mobile Xamarin, por exemplo
Pouca familiaridade com extension methods: Apesar de estarem ai a anos nem todo desenvolvedor já teve de escrever seu próprio extension method
Dependendo do namespace podem causar confusão: Extension methods são carregados por namespace de uma única vez. Você não consegue escolher quais métodos serão importados.

Exemplos

O seguinte snippet contém algumas das queries do Cell CMS que migrei para este padrão e alguns testes mostrando como elas podem ser utilizadas, como se comportam com os diferentes datasets e chains!

/// <summary>
/// Queries relacionadas a Feeds.
/// </summary>
public static class FeedQueries
{
    /// <summary>
    /// Obtem todos os feeds.
    /// </summary>
    /// <param name="feeds"></param>
    /// <returns></returns>
    public static IQueryable<Feed> AllFeeds(this IQueryable<Feed> feeds) => feeds;

    /// <summary>
    /// Filtra feeds com base no ID.
    /// </summary>
    /// <param name="feeds"></param>
    /// <param name="id"></param>
    /// <returns></returns>
    public static IQueryable<Feed> WithId(this IQueryable<Feed> feeds, int id)
    {
        return feeds
            .Where(f => f.Id.Equals(id));
    }

    /// <summary>
    /// Filtra feeds com base no Nome.
    /// </summary>
    /// <param name="feeds"></param>
    /// <param name="name"></param>
    /// <returns></returns>
    public static IQueryable<Feed> FilterByNome(this IQueryable<Feed> feeds, string name)
    {
        if (string.IsNullOrWhiteSpace(name))
        {
            return feeds;
        }

        return feeds
            .Where(f => f.Nome.Contains(name, System.StringComparison.InvariantCultureIgnoreCase));
    }
}

// Testes
[Theory, CreateData]
[Trait(TraitsConstants.Label.Name, TraitsConstants.Label.Values.Domain)]
public void WithNome_EmptyData_ReturnsEmpty(string nome)
{
    // Arrange
    var subject = _emptyResult.AsQueryable();

    // Act
    var result = subject
        .FilterByNome(nome);

    // Assert
    result.Should().BeEmpty();
}

[Theory, CreateData]
[Trait(TraitsConstants.Label.Name, TraitsConstants.Label.Values.Domain)]
public void WithNome_WithDataAndValidName_ReturnsData(IEnumerable<Feed> feeds, Feed extraFeed)
{
    // Arrange
    var nome = extraFeed.Nome;
    var subject = feeds
        .Concat(new List<Feed>() { extraFeed })
        .AsQueryable();

    // Act
    var result = subject
        .FilterByNome(nome);

    // Assert
    result.Should().NotBeEmpty();
}

[Theory, CreateData]
[Trait(TraitsConstants.Label.Name, TraitsConstants.Label.Values.Domain)]
public void WithNome_WithDataAndInvalidName_ReturnsData(IEnumerable<Feed> feeds, [Frozen] string fixedName)
{
    // Arrange
    var nome = $"{fixedName}{Guid.NewGuid()}";
    var subject = feeds.AsQueryable();

    // Act
    var result = subject
        .FilterByNome(nome);

    // Assert
    result.Should().BeEmpty();
}

[Theory, CreateData]
[Trait(TraitsConstants.Label.Name, TraitsConstants.Label.Values.Domain)]
public void WithIdAndNome_WithDataAndValidNameAndValidID_ReturnsData(IEnumerable<Feed> feeds, Feed extraFeed)
{
    // Arrange
    var nome = extraFeed.Nome;
    var id = extraFeed.Id;
    var subject = feeds
        .Concat(new List<Feed>() { extraFeed })
        .AsQueryable();

    // Act
    var result = subject
        .WithId(id)
        .FilterByNome(nome);

    // Assert
    result.Should().NotBeEmpty();
}

Conclusão

Eu, pessoalmente, sempre utilizei o padrão UnitOfWork + Repository. Porém, ao descobrir que os extension methods poderiam me dar a mesma funcionalidade mas com um menor overhead passei a preferir extension methods.

Caso ainda não esteja convencido dê uma olhada nos testes e refactors feitos no Cell CMS, que agora está seguindo este padrão, para basear sua decisão!

No fundo essa decisão é uma questão de gosto pessoal. Eu prefiro ser pragmático e minimizar a quantidade de coisas que preciso dar manutenção e testar. Mas para seu projeto/equipe pode ser que o padrão UnitOfWork seja melhor aceito!

O post de hoje vai ficando por aqui, espero que tenha dado o que pensar! O próximo post provavelmente será sobre Analyzers ou Configuração de um Ambiente Windows para desenvolvimento!

Fiquem ligados para o próximo, obrigado por lerem e até então!

Cell CMS - Criando testes de maneira prática

Rodolpho Alves — Sun, 31 Jan 2021 18:17:33 +0000

Intro

No último post falamos sobre como utilizar Docker e suas ferramentas de suporte dentro do Visual Studio, quais são suas vantagens e como Containers resolvem vários problemas "clássicos" do deploy.

No post de hoje vamos fazer algo que deveríamos ter feito desde o começo do Cell CMS: Criar nossos projetos de testes unitários.

O branch principal para o post de hoje será o feature/create-tests.

rodolphocastro / cell-cms

CMS leve, self-contained e prático de utilizar! Feito por desenvolvedores e para desenvolvedores!

Cell CMS

Branch	Status	Descrição
Master		Ciclo estável, recomendado para produção
Develop		Ciclo em desenvolvimento, recomendado para entusiastas

Cell CMS é um content management system que visa ser:

Leve
Auto Contido (self-contained)
Prático de Utilizar

Nosso foco é em disponibilizar um CMS que desenvolvedores possam facilmente referenciar em seus aplicativos, sites e sistemas.

📚 Instruções

Utilizando uma Versão publicada

WIP, iremos suportar imagens Docker e executáveis

Compilando

Você precisará ter instalado em seu ambiente o SDK 5.0.101 do Dotnet.

Uma vez configurado basta executar dotnet build .\cell-cms.sln na raiz do repositório.

Testando

Execute dotnet test .\cell-cms.sln na raiz do repositório.

Caso queira capturar informações de cobertura de testes utilize:

dotnet test --no-restore --collect:"XPlat Code Coverage" .\cell-cms.sln

⚙ Configurações

Autenticação/Autorização

O CellCMS utiliza o Azure Active Directory como provider de identidade, então você terá de configurar sua instância do AAD conforme explicado neste post.

As seguintes variáveis de ambiente…

View on GitHub

Cover do artigo pega lá no unDraw

Últimas alterações do Cell CMS

Faz bastante tempo desde o meu último post. Pois é! Infelizmente acabei de distraindo com outros afazeres e estudos e acabei deixando de lado o bom hábito de escrever 😅.

Mas o Cell CMS teve algumas alterações entre o último post e este! De maneira resumida:

Migramos para .NET 5 (originalmente estávamos no .NET Core 3.1)
Criamos uma pipeline no GitHub Actions para compilar o projeto continuamente
Inúmeras alterações no meu ambiente de desenvolvimento

Eventualmente escreverei um pouco sobre estes processos, provavelmente começando pelo do ambiente (em breve devo reconfigurar mais uma vez). Prometo!

Sem mais delongas, vamos para o conteúdo em si!

Testes Unitários: O que são, de onde vieram e para que servem

De maneira bem resumida podemos dizer que testes unitários (na programação orientada a objetos) são rotinas automatizadas para garantir o funcionamento de uma classe.

Mas o que isso quer dizer, na prática?

Na prática isso quer dizer que você terá um conjunto de classes e métodos especializadas em testar de maneira rápida cada classe que compõe o seu sistema, mas preste atenção pois eles não fazem tudo! Como o próprio nome já diz o escopo deste teste é a unidade (que, eventualmente, compõem o todo do seu sistema 🤷‍♂️).

Outra grande vantagem de ter uma boa cobertura de testes unitários é poder refatorar sem medo, afinal os testes vão garantir que você não quebrou nenhuma API pública (ou se você precisou quebrar pelo menos vai te lembrar de avisar os consumidores dessa API como um [Obsolete] antes de remover de vez!).

Se você quiser saber mais sobre refatorar um amigo meu está fazendo uma série de vídeos especialmente sobre isso, dê uma olhada no canal AspiraPlay no YouTube!

Existem, além dos testes unitários, vários outros tipos de testes (manuais e automatizados) mas para o desenvolvedor o teste mais rápido de fazer e executar será, sempre, o unitário. E por isso vamos falar primeiros deles antes de pensarmos em testes de integração, funcionalidades, aceite, etc.

Uma boa leitura para esse assunto é o próprio site do grande Martin Fowler.

Como escrever um bom teste unitário

Seja qual for o framework ou linguagem de programação que você esteja utilizando sempre encontrará essas características em um bom teste unitário.

Nome do Teste

O primeiro elemento importante é o nome do seu teste. É no nome em que vamos dar aquela resumida em:

O que estamos testando
Sob quais condições/estado estamos testando
O que esperamos

Em alguns frameworks o nome do teste será o nome do método que executa a rotina de teste, em outros são utilizadas anotações, classes, atributos, comentários... Mas a constante é sempre essa:

Você deve identificar o que está testando, sob quais condições e o que você espera de resultado.

Entradas (Inputs)

O segundo elemento importante para seu teste é identificar as entradas para a rotina que você está testando. Note que isso poderá mudar bastante mas você sempre deve pensar em isolar bem o que você quer que entre no seu teste para que garanta que ele é preciso!

Alguns exemplos de testes e inputs:

Testar uma classe que cria um JSON -> Input seriam objetos diferentes
Testar uma classe que utiliza outra para salvar algo -> Input seria a classe que será utilizada via mock e o dado que seria salvo
Testar uma regra de negócio -> Input que consiga disparar esta regra de negócio e inputs que falhem a regra de negócio

Não se preocupe ainda com o que é um mock, falaremos disso depois!

O que está sendo testado (Subject)

O terceiro elemento (que apesar da ordem é o mais importante!) é o que você quer testar de verdade!

A importância de saber quem é este elemento é vital para que seu teste seja unitário de verdade. Se você não consegue identificar um único elemento você provavelmente está escrevendo um teste de integração ou você precisa rever as dependências de sua classe.

O estado do que está sendo testado (State)

Em quarto lugar você precisa pensar qual o estado que você quer testar. Isso pode ser:

Uma dependência falhando
Uma input inválida
Uma referência nula
Um parâmetro sendo omitido

Nunca tente testar todos os possíveis estados! Uma cobertura de 100% de testes pode significar que você está investindo mais tempo em testes do que funcionalidades novas!

Minha preferência pessoal é começar testando sempre dois estados: O válido e o principal inválido.

O que é esperado

Finalmente o último elemento é: o que você espera que aconteça?

Por exemplo:

Retorne null
Retorne um objeto válido
Lance uma Exception
Dê timeout após ... milissegundos

Juntando tudo: AAA

Como lembrar de tudo isso? Uma das práticas mais comuns é sempre lembras dos 3 As:

Arrange: Escolha as inputs, o que será testado e monte o cenário
Act: Realize a ação que você quer que seja testada
Assert: Verifique que a ação fez o que você esperava

Eu normalmente abro meus testes já escrevendo 3 linhas de comentários e então vou preenchendo a lógica:

// Arrange
var subject = new MinhaClasseSendoTestada(null);

// Act
var result = subject.FazAlgumaCoisa();

// Assert
Assert.IsNull(result);

Mocks e Stubs

Não sou um expert no assunto (dê uma pesquisada sobre Kent Beck, TDD Chicago e London para saber mais sobre isso) mas de maneira bem resumida:

Um Mock é um objeto que simula o comportamento de outro objeto, permitindo que você controle o que o objeto real faria e valide quantas vezes ele foi chamado, com quais parâmetros, etc. Você estará testando por comportamento.

Um STUB é um objeto que simula apenas o retorno de outro objeto, entregando respostas fixas para chamadas fixas, controlando o que é retornado quando chamariam o objeto real e apenas isso. Você estará testando por estado, maior parte das vezes, porém também poderia testar por comportamento com algumas alterações.

Unit Tests com .NET

Agora que temos uma ideia do que são testes unitários vamos pensar neles no universo do .NET, de cara já podemos dizer que existem 3 frameworks populares de testes unitários:

nUnit -> Mais clássico mas amplamente utilizado, com diversos plugins e runners
xUnit -> Mais moderno e próximo à ideia de TDD, também é amplamente utilizado
MSTest -> Não recomendado mais atualmente

A principal diferença que nós, como desenvolvedores, vamos notar entre o nUnit e o xUnit é a maneira com que eles lidam com as classes de teste.

Por padrão o xUnit cria uma instância da classe para executar cada método de teste. Você sempre terá uma certa segurança de que o estado da sua classe de teste está limpo.

Enquanto isso o nUnit utiliza a mesma instância da classe para executar todos os métodos de teste. Você terá de tomar cuidado com instâncias que podem ser alteradas pelos testes em si, levando a interdependências, travando a ordem de execução, etc...

Porém, seja xUnit ou nUnit, as classes de teste conterão os seguintes elementos:

Métodos() indicando as rotinas de teste
[Atributos] indicando que um método é um teste com ou sem parâmetros
[OutrosAtributos] indicando métodos de configuração e limpeza dos seus testes

Não vou entrar a fundo nos atributos e setups de nenhum dos dois, porém na seção de codificação mesmo você poderá ver como fica uma classe de teste utilizando o xUnit!

AutoFixture - Criação automática de massa de dados

Comentamos acima sobre a necessidade de sabermos as inputs dos nossos testes, certo? Porém as vezes você sabe o que precisa de input mas não se importa com os detalhes, certo? Nesses cenários pode ser tornar chato você ter de sempre adicionar N parâmetros no seu teste e sempre criar um new ObjetoInput(param1, param2, ...);. A biblioteca AutoFixture resolve exatamente isso!

De maneira sucinta:

AutoFixture gera a massa de dados para testes automaticamente para você. Permitindo que você gaste menos tempo na fase de Arrange de seu teste.

E melhor ainda: Ele funciona, de cara, sem nenhuma configuração em boa parte dos casos, porém você pode configurar ele com regras específicas para casos específicos!

AutoFixture / AutoFixture

AutoFixture is an open source library for .NET designed to minimize the 'Arrange' phase of your unit tests in order to maximize maintainability. Its primary goal is to allow developers to focus on what is being tested rather than how to setup the test scenario, by making it easier to create object graphs containing test data.

NSubstitute - Criação e Configuração de Mocks

A biblioteca NSubstitute é mais uma facilitadora para a nossa fase de Arrange dos testes. Lembra sobre mocks e stubs? Esse carinha aqui é quem vai criar os mocks pra gente.

De maneira curta:

NSubstitute cria, automaticamente, mocks para interfaces e métodos virtuais. Além disso você poderá controlar o que esses mocks retornam, quantas vezes podem ser chamados, etc.

nsubstitute / NSubstitute

A friendly substitute for .NET mocking libraries.

Nota: Por muito tempo utilizei uma outra biblioteca chamada Moq que faz a mesma coisa porém com sintaxe diferente. Ultimamente tenho dado preferência pelo NSubstitute exatamente por parecer legível.

Um breve exemplo do NSubstitute:

interface IEmailPublisher {
    string Driver { get; }
    Task SendTo(string r, CancellationToken ct = default);
}

var publisher = Substitute.For<IEmailPublisher>();
publisher.SendTo("temp").Returns(Task.CompletedTask);
publisher.Driver.Returns("MyDriver123");
//publisher.SendTo().ThrowsForAnyArgs<NotImplementedException>();   // Caso queira simular um erro

var result = publisher.Driver;
Assert.Equal("MyDriver123", result);    // -> True

FluentAssertions - Sintaxe fluent/builder para validar os cenários

FluentAssertions é uma biblioteca que não vai te ajudar a economizar tempo enquanto prepara seus testes mas vai tornar seus testes mais legíveis a longo prazo!

FluentAssertions permite que você descreva o que é esperado do seu teste usando uma linguagem mais próxima à natural.

Por exemplo, se eu quisesse validar em um teste que: "O resultado não é nulo, é do tipo X e é equivalente ao objeto Y"

// Usando fluent assertions
resultado.Should()
    .NotBeNull().And
    .BeOfType<X>().And
    .BeEquivalentTo(Y);

// Usando Asserts
Assert.NotNull(resultado);
Assert.IsType<X>(resultado);
Assert.IsEqual(resultado, Y);

fluentassertions / fluentassertions

A very extensive set of extension methods that allow you to more naturally specify the expected outcome of a TDD or BDD-style unit tests. Targets .NET Framework 4.7, as well as .NET Core 2.1, .NET Core 3.0, .NET 6, .NET Standard 2.0 and 2.1. Supports the unit test frameworks MSTest2, NUnit3, XUnit2, MSpec, and NSpec3.

EntityFrameworkCore.InMemory - Versão do EFCore para testes unitários

Normalmente utilizaríamos um Mock/Stub para simular o acesso ao banco em nossos testes unitários, porém os objetos e tipos do EntityFrameworkCore, apesar de "mockáveis", requerem um setup bem extenso.

Com isso em mente o próprio EntityFrameworkCore já criou uma biblioteca exatamente para que não precisemos fazer todo esse setup. O provider InMemory é a maneira de simular um acesso ao banco nos nossos testes unitários.

Existe uma discussão bem extensa sobre se usar isso não configuraria seu teste como um teste de integração e se a maneira correta não seria voltar ao velho padrão de Unit Of Work + Repositories (que o próprio EFCore já implementa por si só 🤷‍♂️).

Meu take pessoal nesse assunto é que devemos ser pragmáticos. A biblioteca está ai, pronta. Salvo que eu precise muito por que vou criar mais uma camada? Abstrações são boas (vida longa a interfaces e classe abstratas!) mas da mesma maneira que você pode pecar por usar só implementação concretas você também pode pecar por criar abstrações para tudo!

Abstrair só por abstrair é overengineering.

dotnet / efcore

EF Core is a modern object-database mapper for .NET. It supports LINQ queries, change tracking, updates, and schema migrations.

Mãos à obra: Criando nosso projeto de testes

Vamos à pratica! Fora do Visual Studio vamos criar uma nova pasta na raiz do projeto, chamada tests/. A ideia aqui é que todos os nossos projetos de testes (Unit, Integration e Feature) ficarão nesta pasta para não bagunçar a hierarquia das outras bibliotecas do projeto.

Criando o Projeto e Instalando dependências

Pelo Visual Studio:

Clique direito na solução e escolha Add new project
Pesquise nos templates por xUnit e localize um chamado xUnit Test Project (.NET Core)
Escolha um nome para seu projeto e o coloque para ser salvo na pasta tests/
Opcional, caso o projeto a ser testado seja .NET 5:
1. Clique com o direito no projeto e escolha Properties
2. Mude o campo Target framework para .NET 5.0
3. Salve as alterações e recarregue o projeto

Com o projeto criado abra o NuGet Manager para o projeto de testes e adicione os seguintes pacotes:

AutoFixture
AutoFixture.AutoNSubstitute
AutoFixture.Xunit2
FluentAssertions
Microsoft.EntityFrameworkCore.InMemory
NSubstitute

Lembre-se de adicionar como referência ao projeto de testes o projeto que será testado.

Configurando nossas Ferramentas

Com tudo instalado podemos passar para a parte de preparação. De certa maneira este passo é opcional mas se quisermos escrever nossos testes da maneira mais prática possível este passo será o grande diferencial de produtividade.

O AutoFixture.Xunit2 nos trás um atributo [AutoData] que pode ser utilizado para que os parâmetros de um teste sejam criados automaticamente pelo AutoFixture.

A parte mais legal é que herdar este atributo e customizar como o AutoFixture cria as coisas. Isso significa que podemos colocar na "pipeline" do AutoFixture coisas como o EntityFrameworkCore.InMemory, NSubstitute e customizar como alguns atributos nossos seriam criados.

Para fazer isso tudo que precisamos é criar uma nova classe CreateDataAttribute, herdar a classe AutoDataAttribute e criar um construtor que chama o base(Func<IFixture> factory).

Minha sugestão é que você crie um método estático que retorna uma IFixture e nesse método faça toda a configuração!

Por exemplo, esta é a minha versão deste atributo para o Cell CMS:

using System;

using AutoFixture;
using AutoFixture.AutoNSubstitute;
using AutoFixture.Xunit2;

using AutoMapper;

using CellCms.Api;

using Microsoft.EntityFrameworkCore;

namespace CellCms.Tests.Unit.Utils
{
    /// <summary>
    /// Atributo para configurar automaticamente os dados de um test case.
    /// </summary>
    public class CreateDataAttribute : AutoDataAttribute
    {
        public CreateDataAttribute() : base(SetupCellCmsFixture)
        {

        }

        /// <summary>
        /// Configura uma fixture com todos os objetos necessários para
        /// testar o CellCMS.
        /// </summary>
        /// <returns></returns>
        private static IFixture SetupCellCmsFixture()
        {
            var fix = new Fixture();
            fix.Customize(new AutoNSubstituteCustomization());
            SetupRecursionBehaviors(fix);
            SetupCellContext(fix);
            SetupAutoMapper(fix);
            return fix;
        }

        /// <summary>
        /// Configura e Injeta uma instância do AutoMapper.
        /// </summary>
        /// <param name="fix"></param>
        private static void SetupAutoMapper(Fixture fix)
        {
            var autoMapperConfig = new MapperConfiguration(cfg =>
            {
                cfg.AddMaps(typeof(Startup));
            });
            fix.Inject(autoMapperConfig);
            fix.Inject(autoMapperConfig.CreateMapper());
        }

        /// <summary>
        /// Configura e Injeta uma instância do CellContext.
        /// </summary>
        /// <param name="fix"></param>
        private static void SetupCellContext(Fixture fix)
        {
            var dbOptions = new DbContextOptionsBuilder()
                            .UseInMemoryDatabase(Guid.NewGuid().ToString());
            fix.Inject(new CellContext(dbOptions.Options));
        }

        /// <summary>
        /// Configura o comportamento da Fixture durante
        /// chamadas recursivas.
        /// </summary>
        /// <param name="fix"></param>
        private static void SetupRecursionBehaviors(Fixture fix)
        {
            fix.Behaviors.Remove(new ThrowingRecursionBehavior());
            fix.Behaviors.Add(new OmitOnRecursionBehavior());
        }
    }
}

É bastante verboso na primeira olhada mas lembre-se que usando esse atributo você terá muito mais produtividade para escrever seus testes!

Escrevendo nossos Testes

Finalmente podemos começar a escrever nossos testes!

Tudo que você precisa fazer agora é criar uma nova classe, criar um método para o seu teste e adicionar os atributos.

Por exemplo um dos testes do Cell CMS:

[Theory]        // Indica ao xUnit que este teste tem parâmetros
[CreateData]    // Indica que os parâmetros serão criados através do atributo que criamos na seção anterior
// O [Frozen] indica que o AutoFixture deve retornar sempre esta mesma instância para todos que precisarem dentro deste método! É como se fosse um Singleton
public async Task Handle_ExistingContext_ReturnsList([Frozen] CellContext context,
    IEnumerable<Feed> feeds,
    ListAllFeedsHandler subject)
{
    // Note que deixamos que o próprio "objeto a ser testado" seja criado pelo AutoFixture, dessa maneira o mesmo context que ele passou aqui para este método será passado para o subject!

    // Arrange
    // Aqui estou garantindo que os dados criados pelo AutoFixture estão salvos no Context do EntityFramework
    context.AddRange(feeds);
    await context.SaveChangesAsync();

    // Act
    var result = await subject.Handle(new ListAllFeeds(), default);

    // Assert
    result
        .Should()
        .NotBeNull().And
        .HaveSameCount(context.Feeds);
}

Executando os Testes

Para executar os testes por linha de comando use: dotnet test na pasta da solução.

Para executar pelo Visual Studio o principal será a janela Test Explorer (atalho: Ctrl+E, T). Porém temos alguns outros atalhos importantes e práticos:

Ctrl+R, A: Executar todos os testes;
Ctrl+R, Ctrl+A: Executar todos os testes com Debug;
Ctrl+R, T: Executar o teste selecionado (no caso o teste em que seu cursor estiver);
Ctrl+R, Ctrl+T: Executar o teste selecionado com Debug;

Finalizando

O post de hoje vai ficando por aqui! Espero que após ler esse post fique evidente que podemos escrever testes unitários de maneira rápida e prática graças a diversas bibliotecas Open Source!

Alguns assuntos que ainda quero abordar, para os próximos posts:

Analyzers
Refactoring
Domain Driven Design
Clean Architecture
Configuração de um ambiente de desenvolvimento

Fiquem ligados para o próximo post, obrigado por lerem e até a próxima!

Meet Dixture! A Test Data Builder module for Deno

Rodolpho Alves — Sat, 12 Sep 2020 03:17:38 +0000

TL;DR:

While working with Deno have you ever wished to bother less with coming up with random data for your tests?

If so then Dixture is the module for you!

rodolphocastro / dixture

Dixture is a Deno module that helps you create random data for your tests.

Dixture

Dixture helps you create random data for your tests, with zero external dependencies!

🚥 Current Status

Master status

Project status: Under development

Latest stable version: v0.2.2

🏆 Acknowledgements

Dixture is loosely based on the great AutoFixture library that exists on the .NET environment.

I've used this library for so long for my Unit and Integration tests that I needed to, somehow, get some of its functionality when working on my Deno's tests.

Thus I began working on this project.

⚡ Getting Started

Simply import us by deno.land/x/ and use your favorite flavor of test data generation!

As of v0.2.2 you can pick from two "flavors":

Functions that create and/or assign fields for your classes and instances
A Factory API that allows you to write down rules for your classes

import {
  dixtureFns,
  RuleSet,
  DixtureFactory,
  InterfaceRuleSet,
} from "https://deno.land/x/dixture@v0.2.2/mod.ts";
class Person {

…

View on GitHub

Cover is a Deno Artwork made by Heymi

Background and Motivation

Some background on myself: My fulltime job, right now, is as a fullstack engineer for c#. That means that I get to enjoy all of its perks and all the awesome NuGet packages that the .NET community created.

Some of these packages are soo helpful that they're must-haves for my daily workflow. These NuGets help me be productive while writing my tests and, to be honest, actually make me enjoy writing tests! To name a few:

AutoFixture and either AutoFixture.nUnit or AutoFixture.xUnit
FluentAssertions
Moq

So when I'm working with Deno on my free time I must admit... I miss those libraries 😅.

Wello Horld, this is Dixture

So, out of my frustration due to a lack of Test Data Generators for Deno I began to work on something, now called Dixture. I had to, somehow, make my workflow faster and since no one was writing one... might as well give it a shot, right?

Dixture is, basically, a module that simplifies your Test Data Generation. It has zero external dependencies and allows you some room for customization.

My goal is to keep Dixture as less intrusive as possible. I don't think it's fair to ask anyone to clutter their code with ClassAttributes or bother with metadata generation just for some data generation. However, given the not-on-par-with-csharp support for Reflection on Typescript, we still need some input from you, the developer, in order to give us a "blueprint" (called RuleSet inside Dixture) of how to build your class.

Enough talk, show me the code

You can check out all our samples at the GitHub repository, they're available as standalone files and on our test cases but here's a small sample on our latest Factory API:

import {
  dixtureFns,
  RuleSet,
  DixtureFactory,
} from "https://deno.land/x/dixture@v0.2.0/mod.ts";

class Person {
  name: string = "";
  age: number = 0;
  bankBalance: bigint = 1n;
  isAlive: boolean = true;
}

// 1. Creating our factory
const factory = new DixtureFactory(
  // 2. Writing in-line Rule Sets (blueprints) for our classes
  new RuleSet(
    Person, // 3. For each field we pick a resolution function
    {
      field: "name",
      resolve: dixtureFns.String,
    },
    {
      field: "age",
      resolve: dixtureFns.Int,
    }, // 4. We can even define our own resolution functions, as far as they return the expected type
    {
      field: "bankBalance",
      resolve: () => {
        if (dixtureFns.Bool()) {
          return 10000000n;
        }
        return 0n;
      },
    }, // 5. We can also omit rules, the field might not be important after all
  ),
);

What about x/y/z Feature!?

Well, currently, the roadmap is to try and allow generation for interfaces (so no need to wrap those up into classes anymore 😅), allow a Fluent/Builder api for RuleSets / Blueprints and further enhance how data is generated.

However all suggestions are welcome! Feel free to drop by our GitHub repo and create issues, fork us and send us your pull request!

Acknowledgements

Kudos to the great community behind AutoFixture for getting me into Testing and to Rhum for creating an improved test "framework" for Deno (Rhum is used for testing Dixture!)

Thanks for reading this far and stay safe!

Setting up Svelte and Tailwind... with minimal extra dependencies

Rodolpho Alves — Wed, 19 Aug 2020 22:47:52 +0000

In this post I'll show how to properly setup TailwindCss within a Svelte application. I'll show all the required dependencies and changes that should be made while maintaining a minimal number of additional dependencies and script changes.

TL;DR

In a hurry? Then just checkout this commit over at GitHub!

rodolphocastro / editorconfig-io

Quickly find editorconfigs for your project

The basics are:

Add tailwindcss + postcss-load-config to your dependencies
Init tailwindcss.config + postcss.config
Create a component to host tailwindcss and import that component into the App
Change rollup's pipeline to run postcss
Change build command to set NODE_ENV to production

TailwindCss

Initial Setup

First and foremost we need to add all the required dependencies to our project. Run npm install tailwindcss postcss-load-config.

Those dependencies are needed for setting up tailwind itself and enabling us to load poscss configuration from a separate file.

After npm finishes download the dependencies run npx tailwindcss init to create the tailwind.config.js file.

Purging unwanted classes

In order for tailwind to know which classes are used we need to point it into the correct files. This is done by editing the tailwind.config.js file and telling it to take into account all .svelte and .html files we have.

This is done by the following snippet:



module.exports = {
  purge: [
           "./**/*.svelte",  // Look for .svelte files
           "./**/*.html" // Look for .html files
        ],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

Setting up PostCSS Config

Now create a new file called postcss.config.js. This file will hold all the PostCSS related configuration.

In this file you'll point out which plugins the postcss pipeline should use. The following snippet does that for the basic taildwindcss configuration:



module.exports = {
        plugins: [
                require("tailwindcss"),
                require("autoprefixer")
        ]
}

Importing Tailwind into the Application

Finally, importing tailwind into our App can be done in many ways, such as:

Importing it from a .css file
Importing it from within a styles tag
Importing it from the styles tag of a specific component

I'll do it as a separate component with a global styles section. The following snippets creates the component that bootstraps tailwindcss:



/* Tailwind.svelte */
<style global>

@tailwind base;
@tailwind components;
@tailwind utilities;

</style>

After the component is created all we need to do is import it into our App:



<script lang="ts">
        import Tailwindcss from './Tailwind.svelte';
</script>

// Omitting unrelated lines

<Tailwindcss />

Cleaning up

This is optional, I guess you could keep the old styles if desired.

Delete the public/global.css file and its <link rel="stylesheet"> tag from index.html.

Enabling Postcss in Svelte's Rollup

Open up rollup.config.js and find the plugins > svelte section.

Here we'll point out that svelte needs to run some sort of preprocessing and we'll tell svelte which preprocessing should be executed.

The following snippet shows this allongside the default configuration:



export default {
        // Omitted for brevity
        plugins: [
                svelte({
                        // This tells svelte to run some preprocessing
                        preprocess: sveltePreprocess({
                                postcss: true,  // And tells it to specifically run postcss!
                        }),

                        // Omitted for brevity
                }),

                // Omitted for brevity
        ],
        watch: {
                clearScreen: false
        }
};

Ensuring NPM builds for Production

If you run npm run build you'll see that the generated bundle.css is quite heavy. That's because, by default, the Svelte's build command doesn't set up NODE_ENV to production!

In order to fix this all we need to do is use the --environment options built into rollup.js to set the NODE_ENV variable to production whenever we run a build script.

To do this simply change the following line within your packages.json file:



"name": "your-svelte-app",
  "scripts": {
    "build": "rollup -c --environment NODE_ENV:production",    
  },
}

This will ensure every time npm run build is called it locally sets the NODE_ENV to production. This means it doesn't impact your hot reload experience at all!

Possible Impacts

Unlike the other methods I've seen on the internet this one doesn't seem to have any side effects on your build (for production) and hot reload experiences! 😀

Monitorando uma aplicação VueJS com o Application Insights

Rodolpho Alves — Sun, 12 Jul 2020 14:20:14 +0000

🤔 Motivação

Boa tarde pessoal! Tudo bem? Para quem já leu meus posts anteriores este post é uma espécie de continuação do Publicando no GitHub.io com VueJS, onde mostrei como era possível utilizar um pouco de scripts do Powershell/Bash para realizar deploy de um App VueJS no seu domínio pessoal do GitHub!

Depois que publiquei o site, bem no começo de toda essa pandemia do Covid-19, fiquei um bom tempo com ele em um estado "estável", onde não via necessidade de mudar nada. Porém, um belo dia, visitei o site e vi que a api que ele consumia do Github estava fora do ar (foi algo pontual, depois voltou) e me dei conta como eu deveria ter criado uma rotina de falha e alguma maneira de ser notificado sobre isso.

Eis que chegamos ao post atual! Onde mostrarei como rapidamente adicionar o Microsoft Application Insights ao seu projeto Vue!

Todo o código apresentado aqui também está disponível no meu repositório do Github:

rodolphocastro / rodolphocastro.github.io

Repository for my personal webpage.

👍 Créditos

Cover disponibilizada por Markus Spiske através do Unsplash

👉 TL;DR

Os passos para utilizar o AppInsights c/ Vue são:

Crie um ApplicationInsights no Azure e salve a instrumentation key.
Adicione o package @microsoft/applicationinsights-web utilizando npm ou yarn
Crie um arquivo .env para armazenar sua instrumentation key
Crie uma instância utilizando new ApplicationInsights({...}), substituindo ... pelas configurações
Inicialize esta instância junto de seu aplicativo

☁ Criando o ApplicationInsights no Azure

Por brevidade estou assumindo que você já tenha uma conta no Azure! Caso não tenha o processo de criar uma é bem rápido e pode ser feito através do mesmo Portal!

Acesse o Portal do Azure e pesquise na barra superior por Application Insights

Clique em Add/Adicionar

Escolha um Grupo de Recursos e um Nome para sua instância do Application Insights e clique em Create no fim da página:

Finalmente, após sua instância ser criada, anote a sua Instrumentation Key.

Caso queira saber um pouco mais sobre o que podemos fazer dentro do Application Insights do Azure dê uma olhada neste post abaixo

Cell CMS — Criando logs robustos e monitorando uma API

Rodolpho Alves ・ Jun 24 '20 ・ 9 min read

#azure #applicationinsights #logging #csharp

⚙ Instalando e Utilizando no Vue

Para instalar o Application Insights basta adicionar o package @microsoft/applicationinsights-web utilizando seu package manager de preferência.

npm install @microsoft/applicationinsights-web
yarn install @microsoft/applicationinsights-web

🔑 Armazenando a Instrumentation Key

Lembra a Instrumentation Key que salvamos ao criar o App Insights no Azure? Precisamos dela para inicializar nosso AppInsights no Vue!

Como boa prática é sempre bom manter as configurações o mais distante possível do código puro, magic strings e dependências hardcoded podem dar uma baita dor de cabeça!

Felizmente se você estiver utilizando o @vue/cli (que, alias, recomendo!) isso pode ser facilmente resolvido através de variáveis de ambientes!

No Vue, ao contrário do dotNet, as variáveis de ambiente serão relevantes apenas no momento de compilação da aplicação! Para passarmos estas variáveis tudo que precisamos é um arquivo .env na raiz de nosso projeto! Dentro deste arquivo todas as variáveis que começarem com VUE_APP_ ficarão disponíveis à nossa Aplicação!

Por exemplo o seguinte arquivo .env pode ser utilizado para armazenar nossa instrumentation key:

VUE_APP_INSIGHTS_KEY=Minha-Instrumentation-Key

E, pelo código, podemos recuperar o valor desta variável através do process.env, como veremos abaixo!

Caso queira saber mais sobre as variaveis de ambiente com o @vue/cli dê uma olhada na documentação

🏆 Criando e Utilizando o AppInsights

Agora que temos nossa instrumentation key disponível ao App precisamos criar e configurar a instância do Application Insights.

Uma prática que gosto de fazer nestes cenários é criar um arquivo separado que, internamente, cria e configura a instância e apenas publica uma função para recuperar esta instância, pronta para uso.

Criar a instância é simples, a library nos disponibiliza um construtor que só precisamos chamar e passar os argumentos, conforme:

const appInsights = new ApplicationInsights({
  config: {
    instrumentationKey: process.env.VUE_APP_INSIGHTS_KEY,  // A instrumentation key
    autoTrackPageVisitTime: true,  // Flag para ativar rastreio automático de tempo por página
    enableAutoRouteTracking: true  // Flag para ativar o rastreio automático de rotas
  }
})

A única variável obrigatória é a instrumentationKey. As outras são detalhes que (pelo menos para um SPA) são desejáveis. A referência completa destas variáveis pode ser encontrada na documentação

Após criar a instância é necessário chamar o método .loadAppInsights() para carrega-la.

Finalmente, para disponibilizar a instância criada ao resto do Aplicativo, só precisamos exportar uma função que a retorna, conforme:

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({
  config: {
    instrumentationKey: process.env.VUE_APP_INSIGHTS_KEY,
    autoTrackPageVisitTime: true,
    enableAutoRouteTracking: true
  }
})
appInsights.loadAppInsights()

/**
 * Obtem a instância do AppInsights.
 */
export function useAppInsights () {
  return appInsights
}

Agora precisamos garantir que ela seja carregada assim que o usuário abrir o App. Uma boa maneira de fazer isso é adiciona-la ao main.ts/js e já disparar um track sinalizando que o App Insights foi carregado!

import { useAppInsights } from './services/AppInsights'

// Configurações do Vue...

// Criando um evento só para garantir que carregamos tudo
useAppInsights().trackEvent({ name: 'App Loaded!' })

// Criando o app em si
new Vue({
  router,
  store,
  render: h => h(App)
}).$mount('#app')

🙋‍♂️ Possíveis melhorias

Uma possível melhoria para todo esse processo seria criar um Mixin para que todo component pudesse acessar o AppInsights, porém pelo tamanho do projeto acreditei que seria um overengineering haha.

Outra melhoria seria utilizar as capacidades de Analytics do Application Insights. Este exemplo demonstra apenas o básico para que tenhamos algum tipo de monitoramento de falhas e acessos.

Além das melhorias na aplicação em si poderiamos configurar Alertas automáticos no Application Insights para quando falhas fossem detectadas!

Reescrevendo a StarWars API em Deno

Rodolpho Alves — Tue, 23 Jun 2020 11:23:28 +0000

Créditos da capa: Dimitrij Agal

👉 TL;DR;

Reescrevi a API do https://swapi.dev utilizando Deno e Svelte. Disponível para testes através do https://swapi-deno.azurewebsites.net/ e do DockerHub

O código da API + Frontend está disponível no GitHub.

rodolphocastro / deno-swapi

A StarWars API written with Deno and powered by Oak and Svelte!

💭 Inspiração

Quem nunca se inspirou em um projeto existente para auxiliar no aprendizado de uma nova linguagem de programação ou Tecnologia?

Eu sou culpado de fazer isso. Direto. Chega a dar vergonha de volta e meia olhar meu GitHub e ver tantos projetos que começo e acabo pausando só pra dar uma olhadinha em alguma outra tecnologia que me chamou a atenção 😅

O projeto da vez, inspirado pelas primeiras versões "production ready" do Deno, foi a reescrita da Star Wars API. Faz tempos que utilizo a Swapi para testar Apps (Web e Mobile) que precisam fazer chamadas a APIs REST e sempre me "frustou" um pouco ela não ter sido atualizada com os dados da trilogia mais recente!

Nota: Não que a versão v0.2.0 deste projeto esteja com os dados recentes! 😂

🦕 Deno

Para aqueles que não estão acompanhando o mundo "Node":

Deno é um runtime simples, moderno e seguro para a execução de Type/Javascript, utilizando a engine V8 e desenvolvido através do RUST
(Fonte: https://deno.land/, traduzido pelo autor)

Em suma a ideia do Deno é pegar todo o aprendizado da comunidade com o NodeJS manter o que é bom e refinar o que "precisa" ser refinado.

Em minha opinião algumas grandes vantagens do Deno são:

Suporte nativo a Typescript
Versionamento integrado ao Git (nada de packages.json ou o inferno do node_modules)
Possui um conjunto "nativo" de bibliotecas suportadas std (o que me lembra bastante o .NET)

Caso esteja lendo no futuro: Lembre-se que este post foi escrito com base na versão v1.1.1 do Deno! Então algumas coisas ainda eram novas!

Escolhendo nossas dependências

Antes de começar a bater código comecei olhando as bibliotecas que já existiam no ecossistema Deno para fazer duas tarefas primordias de uma API REST:

Servir o conteúdo através dos endpoints
Armazenar, de alguma maneira, o conteúdo.

Começando por servir o conteúdo vi que o Deno possui vários "sabores" de frameworks para APIs REST, alguns são:

Oak
Drash
Dactyl [obs: Baseado no Oak]

No momento em que comecei o projeto o que me pareceu mais tentador foi o Oak, especialmente por ser diferente do padrão dotNet Core ao qual estou acostumado 😅.

Em seguida precisava de uma maneira de armazenar o conteúdo de maneira prática. Já existem várias bibliotecas para conectar com bancos SQL e NoSQL, porém para manter o menor footprint possível para a API pensei em embarcar os dados junto à API.

Olhei nas bibliotecas std e econtrei o que precisava para lidar com arquivos: a biblioteca fs.

Sugestões para o ambiente de desenvolvimento

Antes de passarmos ao código, algumas sugestões:

Para desenvolver a API e o Portal utilizei o Visual Studio Code com as extensions:

Lendo os dados de arquivos json

Comecei modelando os dados disponíveis na API Original e os transcrevendo para seis interfaces diferentes:

Film
Person
Planet
Specie
Starship
Vehicle

Utilizando o Insomnia acessei os endpoints da API Original e extrai os dados disponíveis publicamente, higienizando alguns dados (como os "ids") e removendo o envelope.

Desta maneira construi alguns arquivos .json no seguinte formato, para armazenar os dados junto à API:

{
  "data": [
    { ... }
  ]
}

Com este formato estabelecido abstrai criei um arquivo para cada um dos models e escrevi algumas interfaces e classes para consolidar a lógica de carregar os dados a partir de arquivos e disponibilizados em um Array de seu devido tipo T:

// As of v0.55.0 this module requires the --unstable flag to be used
import * as fs from "https://deno.land/std@v0.55.0/fs/mod.ts";

/**
 * Describes the expected structure for a .json storage.
 */
interface JsonStorable<T> {
  data?: T[];
}

/**
 * Loads data and deserializes data from a json file.
 * @param dataDir directory containing the file
 * @param filename filename containing the data, serialized
 */
async function loadDataFromFiles<T>(
  dataDir: string,
  filename: string,
): Promise<T[]> {
  await fs.ensureDir(dataDir);
  const result = await fs.readJson(dataDir + "/" + filename) as JsonStorable<T>;
  return result.data ?? [];
}

Para permitir, eventualmente, a abstração para outra fonte de dados também criei uma estrutura (baseada bem vagamente no Vuex) para armazenar estes dados na aplicação, como um singleton:

export interface IState<T> {
  list(): T[];
}

export class ModelState<T> implements IState<T> {
  constructor(
    private readonly values: T[] = [],
  ) {}

  list(): T[] {
    return this.values;
  }
}

Finalmente, para casar tudo, criei algums factory methods para gerar meus States com base nos .json:

/**
 * Creates and seeds a ModelState for Films.
 * @param dataDir directory holding the json file, defaults to ./data
 * @param filmFile json file containing films, defaults to films.json
 */
export async function createFilmStateAsync(
  dataDir: string = "./data",
  filmFile: string = "films.json",
): Promise<IState<Film>> {
  const films = await loadDataFromFiles<Film>(dataDir, filmFile);
  return new ModelState<Film>(films);
}

/**
 * Creates and seeds a ModelState for Species.
 * @param dataDir directory holding the json file, defaults to ./data
 * @param speciesFile json file containing species, defautls to species.json
 */
export async function createSpecieStateAsync(
  dataDir: string = "./data",
  speciesFile: string = "species.json",
): Promise<IState<Specie>> {
  const species = await loadDataFromFiles<Specie>(dataDir, speciesFile);
  return new ModelState<Specie>(species);
}

/**
 * Creates and seeds a ModelState for Vehicles.
 * @param dataDir directory holding the json file, defaults to ./data
 * @param vehiclesFile json file containing species, defautls to vehicles.json
 */
export async function createVehicleStateAsync(
  dataDir: string = "./data",
  vehiclesFile: string = "vehicles.json",
): Promise<IState<Vehicle>> {
  const vehicles = await loadDataFromFiles<Vehicle>(dataDir, vehiclesFile);
  return new ModelState<Vehicle>(vehicles);
}

/**
 * Creates and seeds a ModelState for Starships.
 * @param dataDir directory holding the json file, defaults to ./data
 * @param starshipsFile json file containing starships, defaults to startships.json
 */
export async function createStarshipStateAsync(
  dataDir: string = "./data",
  starshipsFile: string = "starships.json",
): Promise<IState<Starship>> {
  const starships = await loadDataFromFiles<Starship>(dataDir, starshipsFile);
  return new ModelState<Starship>(starships);
}

/**
 * Creates and seeds a ModelState for Planets.
 * @param dataDir directory holding the json file, defaults to ./data
 * @param planetsFile json file containing planets, defaults to planets.json
 */
export async function createPlanetsStateAsync(
  dataDir: string = "./data",
  planetsFile: string = "planets.json",
): Promise<IState<Planet>> {
  const planets = await loadDataFromFiles<Planet>(dataDir, planetsFile);
  return new ModelState<Planet>(planets);
}

/**
 * Creates and Seeds a ModelState for People.
 * @param dataDir directory holding the json file, defaults to ./data
 * @param peopleFile json file containing people, defaults to people.json
 */
export async function createPeopleStateAsync(
  dataDir: string = "./data",
  peopleFile: string = "people.json",
): Promise<IState<Person>> {
  const people = await loadDataFromFiles<Person>(dataDir, peopleFile);
  return new ModelState<Person>(people);
}

Com tudo isso pronto, vamos aos endpoints!

Servindo os dados através de endpoints com o Oak

A premissa do Oak é que temos uma Application e podemos adicionar diversos Middlewares a ela. Desta maneira a própria camada do Oak irá gerar, para nós, as chamadas necessárias para fazer o Http-Server do Deno trabalhar conforme esperamos!

Para os fins da API vamos utilizar o RouterMiddleware. Este middleware nos permite especificar functions para lidar com os verbos http em rotas específicas.

Por exemplo, para os endpoints de listar e obter um específico a implementação com o Oak fica assim:

// Criando a Application do Oak
const app = new Application();

// Assuma que o filmsState já está criado
const filmsRouter = new Router({ prefix: "/api/films" });
filmsRouter
  // Indicando que este router deverá escutar na rota GET /
  .get("/", ({ response }) => {
    response.body = filmsState.list();
    response.status = Status.OK;
  })
  // E na rota GET /:id
  .get("/:id", ({ response, params }) => {
    const { id } = params;
    const result = filmsState.list().filter((f) =>
      f.url === parseInt(id as string)
    )[0];
    if (result) {
      response.status = Status.OK;
      response.body = result;
      return;
    }

    response.status = Status.NotFound;
  });

// Adicionando nossos middlewares à Aplicação
app.use(
  ...[
    filmsRouter.routes()
  ]
);

// e, finalmente, rodando nossa aplicação
await app.listen({ port: 8000 });

O resto dos endpoints seguem todos o mesmo padrão, salvo o endpoint que apresenta os arquivos do nosso frontend!

🤖 Svelte

Após terminar os 6 endpoints originais comecei a pensar como seria interessante ter um SwaggerUI ou alguma interface documentando a API. Porém, no momento, não existem bibliotecas para gerar a OpenApi spec a partir dos endpoints implementados.

Ou seja, não temos algo como o Swagger Plugin do NestJS ou o Swashbuckle do .NET Core.

Então, para aproveitar o embalo, decidi sair da zona de conforto de Vue + TS e dar a cara a tapa para testar outro framework Javascript que muitas pessoas estão adotando: Svelte

A ideia do Svelte é similar à do React e do Vue: Um único arquivo (chamado de component) agrega a lógica, o estilo visual e a estrutura para exibição.. Com a mesma "pegada" do Vue o Svelte é reativo por padrão. (Com algumas diferenças!)

Vindo do Vue as principais diferenças que senti ao usar o Svelte foram:

Menos "verboso" para declarar componentes
Não depender de um CLI para um kickstart da configuração
Utilização de 'blocos' para condicionais e loops, ao invés de atributos no HTML

No geral eu gostei, bastante, da breve experiência com o Svelte e pretendo utiliza-lo mais no futuro. Admito que fiquei tentado a ir atrás de como utilizar Typescript junto ao Svelte mas como a ideia era implementar logo, deixei de lado!

Components do Svelte

A sintaxe de components do Svelte é a seguinte:

<script>
// Código javascript
</script>

<style>
# CSS do component
</style>

<!-- Corpo HTML -->

O principal component do Frontend é o "Browse" genérico. A ideia aqui é que como a estrutura é sempre a mesma (afinal, não estou fazendo um Portal, apenas exibindo possíveis retornos!) um único component, configurável, dá conta de exibir o que é necessário!

Os elementos que notei que repetiam entre cada exibição de dados eram: O endpoint em si, o nome do endpoint, um emoji para exibir no heading e quais propriedades do elemento deviam ser exibidas na lista interna.

O component resultante dessa parametrização é:

<script>
  export let endpointName = "Generic Endpoint";
  export let endpointEmoji = "❓";
  export let displayProperties = ["url", "name"];
  export let endpoint;

  const endpointPromise = fetchData();

  let showJson = false;
  let showList = false;

  async function fetchData() {
    const response = await fetch(endpoint);
    return response.json();
  }

  function toggleList() {
    showList = !showList;
  }

  function toggleJson() {
    showJson = !showJson;
  }
</script>

<section container>
  <h3 id="{endpointName}">{endpointEmoji} {endpointName}</h3>
  <p>
    The {endpointName} endpoint is served on the route
    <code>{endpoint}</code>
  </p>
  {#await endpointPromise}
    <p>Please wait, loading data...</p>
  {:then dataResult}
    <p>
      There are {dataResult.length} objects of type {endpointName} on the API
    </p>
    <hr />
    <button on:click={toggleJson}>
      {showJson ? 'Hide Json' : 'Show Json'}
    </button>
    <button on:click={toggleList}>
      {showList ? 'Hide list' : 'Show list'}
    </button>
    {#if showJson}
      <h4>JSON</h4>
      <p>A {endpointName}'s JSON looks like this:</p>
      <pre>
        <code>{JSON.stringify(dataResult[0], null, '\t')}</code>
      </pre>
    {/if}
    {#if showList}
      <h4>Result from the API</h4>
      <ul>
        {#each dataResult as data}
          <li>{data[displayProperties[0]]}: {data[displayProperties[1]]}</li>
        {/each}
      </ul>
    {/if}
  {:catch _}
    <p>
      Ops, something went wrong while fetching data! Please refresh the page
    </p>
  {/await}
</section>

A cara final do portal ficou assim:

Servindo nossa SPA através do Oak

A última alteração necessária foi adicionar um novo Middleware ao Oak, apontando ao servidor que os arquivos do subdiretório ./portal/public deviam ser publicados na rota / do servidor!

O código resultante é:

// Criando o middleware
const servePortal: Middleware = async ctx => {
  await send(ctx, ctx.request.url.pathname, {
    root: Deno.cwd()+'/portal/public',
    index: 'index.html'
  })
};

// Indicando que ele deve ser utilizando, junto aos outros
app.use(
  ...[
    filmsRouter.routes(),
    speciesRouter.routes(),
    vehiclesRouter.routes(),
    starshipRouter.routes(),
    planetsRouter.routes(),
    peopleRouter.routes(),
  ],
  servePortal
);

❗ Considerações Finais

O projeto está longe de finalizado, ainda tenho alguns itens do Roadmap a ser sanados (como habilitar CORS, atualizar os dados e melhorar a tipagem!) porém estou satisfeito com o resultado atual!

Meu foco no futuro próximo será criar uma imagem Docker da aplicação e hospeda-la em algum lugar, espero que de graça 😅

Quem quiser ver o código completo, o roadmap e o histórico de alterações pode encontrar tudo isso no repositório GitHub.

Obrigado por lerem este post e até a próxima!

Cell CMS — Utilizando Docker para criar Containers

Rodolpho Alves — Sat, 18 Apr 2020 14:01:00 +0000

Cell CMS — Utilizando Docker para criar Containers

Photo by Jonas Smith on Unsplash

No último postfalamos sobre geração de logs , utilizando o Serilog e o ApplicationInsights para termos um monitoramento robusto, com métricas de performance e erros! No post de hoje vamos permitir que nossa API seja executada em um Container através do Docker! Além disso vamos dar uma olhada em como o Visual Studio 2019 permite a integração, durante o desenvolvimento, com os containers executados pelo Docker Desktop.

Os branches para o código de hoje serão 2: feature/dockerfile e feature/docker-compose.

O que são Containers e o qual problema eles resolvem

Mas na minha máquina funciona! — Vários desenvolvedores, circa sempre.

Quem nunca, em algum ponto, não soltou a exclamação acima? Quando estamos desenvolvendo costumamos estar no “melhor ambiente” possível. Todas as dependências estão instaladas (e normalmente atualizadas), temos todas as nossas ferramentas de Debug e temos acesso administrativo ao sistema operacional.

Eis que chega a hora de publicar a aplicação e… não dá certo. É erro aqui, erro ali, configuração faltante e assim vai. Isso pra não falarmos de problemas de rede, que ficam mais para o lado do pessoal de operações, normalmente.

Com a chegada de maior poder computacional começamos a utilizar Máquinas Virtuais para executar nossos sistemas de maneira mais isolada. Com máquinas virtuais ainda temos todo o trabalho de manter um sistema operacional e configura-lo, mas temos um isolamento melhor das dependências.

Nas clouds/vps temos essa opção que normalmente acaba sendo chamada de IAAS (Infrastructure As A Service), basicamente é assim:

“Aqui está uma máquina virtual com X processamento, Y ram e Z storage. A gente garante que ela fica no ar 99.99999% do tempo mas você fica responsável por instalar dependências, configurar e aplicar atualizações.”

Porém ainda temos um problema. Usar uma VM , completa, ainda requer muita manutenção e configuração , especialmente se nosso foco for agilidade. Eis que surgem o conceito de PAAS (Platform As A Service). Basicamente nesse modelo seu fornecedor de cloud/vps se encarrega de atualizar, manter e configurar o ambiente onde seu sistema será executado. Basicamente é assim:

“Aqui está um ambiente baseado em Linux, com NGINX instalado e com limites de X Y Z. A gente garante que estará sempre atualizado e ficará no ar 99.99999999% do tempo mas você ficará responsável por copiar sua aplicação e as configurações necessárias”

O pulo do gato aqui é que agora essa plataforma não necessariamente é dedicada a você. Não entrarei em detalhes mas neste modelo mas, através de configurações do sistema base e da máquina virtual, o fornecedor pode dedicar cotas de performance diferentes a aplicações diferentes e segregar o que está instalado para cada aplicação. Isso permite um custo mais baixo para o fornecedor e para você cliente!

E então temos, recentemente, a popularização do conceito de Containers. De maneira resumida:

Containers são “pacotes” para distribuição da sua aplicação junto com o ambiente e as dependências necessárias para sua execução. Ao contrário de máquinas virtuais, que simulam o Hardware, os Containers focam em simular o Sistema Operacional.

Em termos práticos: Você cria uma Imagem que irá conter todos os passos e dependências para rodar sua aplicação, como:

Compilar sua aplicação
Com o resultado da compilação, copiar para uma pasta X (por exemplo onde seu WebServer estará servindo)
Aplicar as configurações necessárias (seja por variáveis de ambiente dentro da imagem, cópia de arquivos ou linha de comando. Podemos inclusive utilizar apt get para instalar dependências embarcadas)
Executar a sua aplicação

Com a Imagem pronta você finalmente pode executa-la. Nesse ponto temos o Container da sua aplicação.

Agora vem a questão de um milhão de reais:

Mas Rodolpho, como criamos essas imagens!?

Meus amigos, como quase tudo em TI, temos diversas tecnologias para criarmos Imagens, algumas são:

Docker (o queridinho da vez!)
Rkt
Containerd

Então vamos falar, finalmente, sobre Docker!

Docker, Imagens, Containers e o DockerHub

Moby, o mascote do Docker (fonte: https://www.docker.com/sites/default/files/d8/2019-07/Moby-logo.png)

Antes de partirmos para os detalhes técnicos, vamos conhecer um pouco sobre a empresa. Docker é a desenvolvedora de duas soluções que facilitam, bastante, a utilização de containers por desenvolvedores:

Docker Desktop : Ferramenta para facilitar a instalação e uso de containers em ambiente Windows e Mac OS
DockerHub : Repositório central para publicação de imagens (um NuGet ou NPM para imagens Docker)

Existem várias outras contribuições da empresa para a comunidade Open Source e na criação da OCI (Open Container Initiative), porém essa parte escapa da ideia do post de focarmos em como utilizar! Recomendo uma boa lida no site da Docker e do OCI, vale a pena!

Anyway, vamos para a parte prática! Não vou abordar neste post como instalar e configurar o Docker Desktop porém se você precisa deste passo a passo pode conferir um tutorial muito bom no própio site da Docker.

Partiremos daqui, Docker Desktop instalado e pronto para rodar!

Vamos abrir um terminal e digitar a sugestão do Docker Desktop.

Executando a imagem do Tutorial

Após rodar o comando você poderá acessar http://localhost e acompanhar o propio tutorial do pessoal da Docker! Porém, vamos destrinchar aqui o comando que foi executado:

docker indica que vamos utilizar o docker-cli 😅
run indica que vamos executar uma imagem
-dp 80:80 indica duas coisas: -d sinaliza que o daemon execute em background e -p 80:80 indica que queremos que a porta 80 do sistema atual seja mapeada para a porta 80 do container (ou seja, quando acessarmos a porta 80 da nossa máquina a chamada será encaminhada para a porta 80 do container)
docker/getting-started sinaliza a imagem a ser executada. Podemos identificar que será uma imagem com o nome de getting-started e virá do repositório/usuário docker. Note que não descrevemos nenhuma tag (através de :tag no fim da imagem) então a tag latest será utilizada

Existem outros argumentos importantes e que utilizaremos bastante, eles são:

--volume ou -v: Permite mapearmos uma pasta/volume da nossa máquina para dentro do container
--env ou -e : Permite que definamos valores para variáveis de ambiente dentro do container
--network: Permite que defininamos uma rede (virtual) onde o container será conectado

A referência completa dos parâmetros pode ser encontrada aqui. Agora vamos discutir o local de onde pegamos a imagem: DockerHub.

O DockerHub é o Registry (ou seja um repositório de imagens) oficial da Docker. Existem outros e é possível executar seu próprio registry (inclusive atrás de Containers!), mas o mais famoso é o DockerHub. Nele podemos encontrar imagens para várias aplicações, como:

Antes de falarmos sobre como as imagens são criadas, vamos abordar mais uma questão:

“Como desenvolvedor, qual a vantagem de utilizar Containers ao invés de instalar tudo na minha máquina!?”

Do ponto de vista técnico eu diria que a principal vantagem é poder aproximar ao máximo seu ambiente de desenvolvimento ao ambiente de produção mantendo as mesmas versões das dependências. Inclusive, você pode garantir que todos os desenvolvedores estarão utilizando as mesmas versões de dependências para seu projeto!

Outra vantagem em qualidade de “vida”, especialmente no caso de quem utiliza o Windows, é que containers podem ser criados e deletados sob demanda e facilmente. Assim quando você estiver trabalhando em outro projeto basta parar ou remover os containers e os recursos serão liberados.

Por exemplo, eu gosto de experimentar com diferentes bancos de dados (inclusive armazeno vários docker-compose em meu GitHubpara facilitar o scaffold de projetos) e se eu fosse instalar todos em meu PC (que também uso para jogar! hahaha) seria um inferno de performance. Ter uma VM para cada um? Haja disco! Então, pra mim, a flexibilidade de poder subir e descer estes containers é algo que me ajudou bastante a estudar e utilizar diferentes bancos de dados em vários projetos .NET!

Bem, vamos agora ver como estas imagens são criadas?

Criando o Dockerfile para nossa API

Vamos realizar o processo da maneira fácil, utilizando o Visual Studio 2019 (também dá para fazer no 2017), mas pegarei o resultado e comentarei passo-a-passo o que está sendo feito 😄.

Abra a Solution no Visual Studio e no Solution Explorer clique com o direito sobre a API e escolha Add > Docker Support… e, quando aparecer o Dialog, escolha a opção de Linux Containers

Após finalizar o processo o Visual Studio fará as seguintes operações:

Um novo arquivo, Dockerfile, será criado na raiz do projeto
Uma nova entrada será adicionada no launchSettings.json do projeto
Algumas novas linhas serão adicionadas no .csproj do projeto
Um novo arquivo .dockerignore será criado na raiz da solution

Vamos por partes, primeiro olhando o mais importante de todos: o Dockerfile.

O Dockerfile é o passo-a-passo para que o Docker Daemon (processo que realiza a “compilação” das imagens) saiba de onde começar, o que realizar e para onde jogar os resultados. É uma receita de bolo a ser executada para disponibilizar nosso aplicativo.

https://medium.com/media/94df0ea7345472f920daea8ea38d2762/href

Basicamente o Dockerfile vai conter todos os passos que você executaria para publicar sua API através da linha de comando. Para quem está acostumado a executar as coisas sempre pelo Visual Studio os comandos podem parecer estranhos, mas rapidamente nos acostumamos com eles.

No começo da minha jornada com Docker passei duas semanas utilizando apenas o Visual Studio Code e o Powershell, para ficar mais familiar ao processo “manual” de compilar e distribuir aplicações .NET.

Algo interessante é que o padrão do Visual Studio já vem com uma otimização muito boa chamada de Multi-Stage Builds. Isso permite que o Docker utilize um cache entre cada passo do Dockerfile e dessa maneira tenha de recompilar apenas partes alteradas da Imagem.

Por exemplo: O step 8 (Restore dos NuGets) só será refeito caso ocorra alguma alteração nas dependências do csproj, que é copiado no step 7!

A segunda alteração, no launchSettings.json , nos permite executar e depurar o nosso container através do Visual Studio.

LaunchSettings.json com Docker

A adição das propriedades httpPort e sslPort nos permitem garantir que o container executado para Debug responda sempre nestas mesmas portas! Pessoalmente não sei por qual motivo estas configurações não são adicionadas automaticamente assim como são para um projeto executado da maneira convencional.

A alteração no .csproj permite a integração entre o Visual Studio e o Docker Desktop , vamos dar uma olhada:

.csproj com as Tags adicionais. A DockerfileTag grifada foi adicionada manualmente e será explicada quando formos publicar a imagem!

Finalmente o .dockerignore adicionado:

Algumas linhas foram adicionadas

O .dockerignore é para o Docker o que o .gitignore é para o Git. Um .dockerignore bem escrito permite que apenas os arquivos estritamente necessários sejam copiados para a nossa imagem.

Finalmente podemos ver a integração sendo executada através do Containers View. Caso ele não esteja visível por padrão em seu Visual Studio o menu para habilita-lo é View > Other Windows > Containers. O Container View nos permite visualizar rapidamente quais containers estão sendo executados , seus logs , portas expostas, arquivos dentro do container e as variáveis de ambiente definidas!

Logs do Container expostos no Containers View

A adição do Docker à API é simples assim utilizando o Visual Studio. Porém leia cuidadosamente o Dockerfile para entender o que está sendo feito.

Procure no GitHub exemplos de outros Dockerfiles de outras aplicações, dê uma boa olhada nos comandos do Docker. Existem vários conceitos (como Volumes e Networks) que precisam bem mais do que um post para serem explicados e são melhor vistos na prática do que na teoria! Eventualmente farei um post mais focado nos detalhes do Docker e, um dia, sobre Kubernetes. Porém o foco desta série é o Cell CMS ponta-a-ponta.

Criando o Orquestrador (Docker Compose) para a API

Antes de falarmos sobre a integração com o Visual Studio, vamos ver o que é um “Docker Compose”:

Um docker compose é um documento em formatoyaml que descreve quais imagens deve ser executadas , suas dependências , suas configurações e como devem se comunicar.

Apesar da ideia do Cell CMS ser uma aplicação “lobo solitário”, vamos adicionar suporte á Orquestração de Containers ao nosso Projeto! Será mais para demonstrar a utilidade do Docker Compose, e sua integração com o Visual Studio, durante o desenvolvimento. De maneira resumida a vantagem de adicionar um docker compose à sua Solution é garantir que desenvolvedores com Docker Desktop facilmente tenham um ambiente pronto para desenvolver (e debugar) assim que abrirem seu projeto.

Ou seja: junto com o seu código você armazenará um documento que descreve as dependências necessárias do ambiente de sua aplicação. Apesar de não serem muito recomendados para produção os composes facilitam, e muito, os ambientes de desenvolvimento e testes.

Vamos lá! Com o Solution Explorer aberto clique em sua Api com botão direito e escolha Add > Container Orchestrator Support… e escolha “Docker Compose” no primeiro dialog.

Para este exemplo escolha Docker Compose, em outro post falaremos sobre Kubernetes!

Caso você tenha editado o Dockerfile o seguinte Dialog será apresentado, caso queira substituir o arquivo clique em Yes.

O Visual Studio irá gerar as seguintes alterações no projeto (e solution):

Adicionar um novo projeto .dcproj à solution
Gerar um arquivo .docker-compose.yml, este será nosso compose para o ambiente normal
Gerar um arquivo .docker-compose.override.yml, este será nosso completamento (para ambientes de debug) ao compose principal
Adicionar, ao projeto da API, uma referência ao .dcproj

Vamos focar nos arquivos .yml, a sintaxe é bem simples e fácil de decorar e achar referências, o que é bom pois o suporte do Visual Studio aos arquivos deixa a desejar 😅

Vamos dar uma olhada nos arquivos gerados:

docker-compose.yml

docker-compose.override.yml

Note a semelhança dos parâmetros das chaves do nosso docker-compose com os parâmetros do docker run. Isso não é mera coincidência! No fundo podemos encarar que o docker-compose é uma maneira de organizar e unificar diversos docker run.

Finalmente note, através do Containers View ou do Dashboard do Docker Desktop, que o Visual Studio automaticamente botou todos serviços que estão no docker-compose.yml para rodar:

Para arrumar as portas, e mantendo a integração que nos permite Debug através do Visual Studio, seguimos a mesma ideia da alteração do launchSettings.json. Como queremos isso apenas para ambientes de desenvolvimento vamos abrir o arquivo docker-compose.override.yml e adicionar um mapeamento explícito para portas do nosso container:

Achando o override no Solution Explorer

Alteração para necessária

Relembrando a sintaxe lá do docker run: À esquerda temos a porta do host (sua máquina) e à direita temos a porta do container (nossa api). No caso a configuração está dizendo que sempre que acessarmos http://localhost :5000 e https://localhost :5001 na máquina local a chamada será redirecionada para a posta 80/443 dentro do container!

Agora vamos confirmar que o Debug funciona? Para demonstrar vou adicionar um Breakpoint em um dos meus métodos do Startup.cs e mandar o Visual Studio iniciar o Debug:

Breakpoint (no host) sendo ativado pelo container.

Note que meu IConfiguration está devidamente populado com as configurações do appsettings.json, appsettings.Development.json, variáveis de ambiente e meu secrets.json. O mapeamento dos appsettingsocorrem durante a criação da nossa imagem, porém o mapeamento do secrets.json é um “bonus” do Scaffold que o Visual Studio fez do docker-compose.override.yml. Em específico a linha de volume que mapeia o diretório ${APPDATA}/Microsoft/UserSecrets da minha máquina (host) para o diretório /root/.microsoft/usersecrets do container, com o modo ro (readonly).

Para demonstrar como podemos alterar as configurações presentes no IConfiguration através de variáveis de ambiente nos containers vou renomear nossa database sqlite para “outraStorage.db” através da ConnectionString no docker-compose.override.yml:

Alterando, por ambiente, a ConnectionString da Database

Colocando um breakpoint e analisando o IConfiguration podemos ver os diversos providers e ver que o valor definido pelo docker-compose está lá:

Identificando o Provider de Variáveis de Ambiente

Encontrando nossas alterações dentro do Provider!

Este é o básicão sobre o Docker Compose. Como sempre recomendo a leitura da documentação para ver melhor os detalhes e até dicas mais avançadas! A documentação está disponível aqui.

Considerações Finais

Hoje vimos, bem superficialmente, o que são Containers, quais suas utilidades e como podemos utilizar o Docker Desktop junto do Visual Studio para facilitar nossa vida durante o desenvolvimento de aplicações. Este foi, acredito, o maior post da série até agora e ainda assim ficou extremamente superficial. Espero que o post tenha sido o suficiente para atiçar a curiosidade daqueles que ainda estavam indecisos sobre as vantagens de containers!

Prometo fazer um post algum dia indo nos pormenores do Docker e, inclusive, trazendo exemplos mais complexos de Orquestração (como, por exemplo, subir uma api, um worker, Um frontend e um banco ao mesmo tempo) mas no momento estou dedicado em avançar com o Cell CMS!

Para o próximo post vamos dar uma olhada em Testes Unitários de maneira produtiva e prática! Utilizando as bibliotecas xUnit, AutoFixture, Moq e FluentAssertions.

Obrigado por lerem mais este post, até a próxima e abraços!

Cell CMS — Criando logs robustos e monitorando uma API

Rodolpho Alves — Mon, 13 Apr 2020 10:31:01 +0000

Cell CMS — Criando logs robustos e monitorando uma API

Photo by Luke Chesser on Unsplash

No último post falamos sobre duas bibliotecas para facilitar nossa vida o AutoMapper e o FluentValidation. No post de hoje vamos olhar mais algumas bibliotecas que facilitam a nossa vida, porém as bibliotecas de hoje irão nos auxiliar quando as coisas não saírem conforme o esperado!

Então hoje faremos três novos branches: feature/serilog, feature/app-insights e feature/healthcheck.

Por que devemos nos importar com Logs?

Debug é um crime onde o programador é, ao mesmo tempo, o Detetive, a Vítima e o Criminoso.

A clássica piadinha tem um belo fundo de verdade. Muitas vezes durante em ambientes de desenvolvimento (e até mesmo em produção, quem nunca?) precisamos parar features novas e ir caçar bugs.

O pior ainda é quando temos um bug que só acontece em um cenário complexo ou quando a descrição do bug se resume a alguém falar “Explodiu!” e sequer apontar o que estava fazendo na hora que “explodiu”. Nesses casos sua esperança é ter uma base de código organizada o suficiente para que seja possível, pelo menos, identificar os pontos de entrada que foram executados pelo usuário.

Agora imagine que sua base não é organizada. Ou é gigantesca. Ou você tem dezenas de microservices rodando ao mesmo tempo. Nesses casos você precisa sair caçando no código onde infernos a Exception aconteceu, sem muita esperança. É breakpoint pra tudo quanto é lado!

Não seria muito bom se tivessemos pelo menos um Rastro ou um Stacktrace decente e armazenado em algum lugar que não precisassemos fazer SSH, conectar em VPNs , etc?

Então, isso tudo existe já! E existem várias ferramentas para Produzir, Armazenar e Processar/Visualizar logs! Algumas das mais famosas para visualizar e extrair métricas são:

Kibana
Grafana
Seq
Prometheus
Azure Monitor

Para a parte de armazenamento temos:

Azure Log Analytics
Logstash
Stackify
Splunk

E boa parte destas ferramentas permitem que utilizemos um tipo de log mais “avançado”: o Log estruturado.

Um log estruturado é simplesmente um log que contem uma estrutura que facilita seu processamento. Esta estrutura pode ser um JSON ou XML por exemplo.

Com uma estrutura bem definida você pode utilizar todas estas ferramentas para buscar informações relevantes no meio de seus Logs. Por exemplo, imagine que em um Controller, ao capturar um erro, você faça o log de alguns dados da Request e os chame de @Request. Ao utilizar uma destas ferramentas você poderia filtrar , facilmente (nada de precisar de trocentas REGEX!), por eventos contendo apenas objetos do tipo “Request”.

Tudo isso é bem legal, mas e como podemos gerar logs neste formato? Faço um ConvertToJson toda vez que escrever no ILogger?

Bem… você poderia fazer isso! Mas pra que reinventar a roda? Existem várias bibliotecas no universo .NET que já fazem isso para nós e, uma delas, é o Serilog!

Gerandos logs estruturados em um sistema .NET — Serilog

Utilizando a biblioteca Serilogpodemos manter nossa utilização do ILogger apenas alterando as dependências e configurações da nossa API.

Primeiro vamos instalar o Serilog. Adicione o NuGet Serilog.AspNetCore e abra o Program.cs para adicionar as seguintes configurações:

https://medium.com/media/2065cedc7854461ecc2d0e2e22905116/href

Execute a API e já ficará evidente a diferença com o log padrão:

Padrão dos logs de Console do Serilog

Para finalizarmos a configuração vamos ao Startup.cs e adicionemos mais uma linha ao Configure:

https://medium.com/media/48630fb81d1ac13d76f661fa32f004a4/href

Agora sempre que utilizarmos os parâmetros (params object[]) ao escrever um evento seus dados serão armazenados junto da mensagem em nosso log! Por exemplo a seguinte utilização salvará os dados de uma request de POST /feed :

https://medium.com/media/dff87d30a34e56b22f1e960b6ab6dd56/href

Note a utilização do operador @Command ao invés de apenas Command . A presença do operador @ sinaliza que o Serilog deve serializar o objeto ao invés de utilizar o ToString para salva-lo!

Outro ponto legal sobre o Serilog são as diversas possibilidades de “Sinks”. Um sink é um “destino” para os seus logs. No exemplo acima utilizamos três sinks: Console, Debug e Arquivos (File). Porém a comunidade mantem mais de 20 diferentes sinks e para diversos destinos! Alguns são:

Amazon CloudWatch
ApplicationInsights
Console
Elasticsearch
Telegram
Microsoft Teams
Stackify

A lista completa pode ser encontrada na wiki.

Recomendo a leitura da documentação completa para mais informações sobre como o Serilog processa os dados de seus eventos: https://github.com/serilog/serilog/wiki/Writing-Log-Events

Monitoramento em Tempo Real — ApplicationInsights

Agora que temos logs estruturados em nossa api e alguns arquivos com os logs, podemos pensar em monitorar nossa API. Temos várias opções para realizar isso, porém a mais plug and play possível é, na minha opinião, utilizarmos o Azure Application Insights.

O Azure Application Insights é uma solução para ingestão, monitoramento e análise de logs. Através dele você poderá, em um único lugar, obter métricas sobre:

Disponibilidade (Quanto tempo fica rodando, sem erros)
Falhas (Exceptions sem tratamento)
Falhas em Dependências (por ex: chamadas a APIs de Terceiros)
Consumidores (quem está chamando sua API)

Além das métricas também podemos, graças ao Azure Monitor, definir regras para alertas e alarmes com base nestas métricas , ver (em tempo real e série histórica) as instâncias que estão executando e receber dicas sobre possíveis gargalos em nossa aplicação.

Os detalhes do Application Insights são vastos! Por isso, hoje, vamos focar em coloca-lo em ação! Em um post futuro podemos fazer um completão sobre esta solução e o Azure Monitor!

Para configurar o Application Insights SDK temos duas opções: Realizar a configuração manualmente ou Deixar que o Visual Studio realize a configuração para nós. Vou fazer o passo-a-passo para o Visual Studio, porém a ideia é a mesma para o manual:

Adicionar o NuGet Microsoft.ApplicationInsights.AspNetCore
Criar , no Portal do Azure , um novo recurso do Application Insights
Adicionar, via appsettings, variavel de ambiente ou hardcoded, a Instrumentation Key à API

Configurando o Application Insights através do Visual Studio

Com a Solution aberta clique com o direito em sua API, vá ao submenu Add e selecione a opção Application Insights Telemetry

Na tela que abrir clique em Get Started

Na próxima tela você deverá realizar login (caso ainda não o tenha feito) com sua conta do Azure, escolher uma subscription onde o recurso será utilizado/criado e, finalmente, escolher o resource. Feito isso, clique em Register.

As configurações default para criar o resource

Após confirmar tudo será configurado para você e uma nova tela será apresentada:

E se acessarmos nossa conta no Azure poderemos ver o recurso criado:

Se executarmos a API e esperarmos alguns minutos (pode levar até 5 minutos) poderemos ver os dados sendo enviados para o Azure. Abra o Application Insights criado e você poderá visualizar, de cara, algumas métricas:

Métricas comuns do Application Insights

O application map, que nos permite visualizar um Grafo com os clients da API e suas dependências

Importante : O padrão salvará uma Instrumentation Key em seu AppSettings. Eu recomendo mover para o secrets.json ou para uma variável de ambiente. Feito isso, atualize a chamada ao AddAplicationInsightsTelemetry com um IConfiguration contendo todas as fontes desejadas de configurações! Isso é importante pois por padrão o SDK olha apenas o appsettings.json!

Quase tudo configurado, apenas nos falta integrar o Serilog e o ApplicationInsights!

Enviando logs do Serilog para o ApplicationInsight

Lembra das Sinks que comentei no começo do post? Iremos utilizar uma nova sink para integrar com o ApplicationInsights!

Adicione em sua API uma referência ao NuGet Serilog.Sinks.ApplicationInsights e voltemos ao Program.cs para configurar a escrita ao ApplicationInsights:

https://medium.com/media/afed5cabf4244eb68db65c8e1d3920c8/href

Importante: Dependendo das versões das bibliotecas um Warning poderá ser emitido para a TelemetryConfiguration.Active . Até o momento da escrita deste post (abril de 2020) a documentação não foi alterada para informar a melhor maneira de contornar isso, porém existe uma issue no GitHub do projeto contendo workarounds e sua possíveis alterações. Uma delas é utilizar TelemetryConfiguration.CreateDefault() ao inves do TelemetryConfiguration.Active.

Agora, se você acessar os traces em seu ApplicationInsights poderá ver os logs da API:

Logs (comuns) da API dentro do ApplicationInsights

Verificando se a API está no ar — Healthchecks

A cereja no bolo 🍰 para “finalizarmos” esta parte da API será adicionar (e configurar) um HealthCheck para a API.

Um Healthcheck é , basicamente, um endpoint que outros programas (normalmente balanceadores de carga) podem chamar para saber se a API está funcionando!

No universo .NET temos uma biblioteca já pronta para isso e que vem embutida com os projetos .NET Core: Microsoft.AspNetCore.Diagnostics.HealthChecks. Então só precisamos adicionar os serviços à injeção de dependência e configurar qual será a rota do endpoint!

Para isso vamos alterar nosso Startup.cs da seguinte maneira:

https://medium.com/media/2b09a9462aeb2e5a8322786a664510f3/href

Para testar que deu certo execute a API e acesse a rota /health, você deverá ser recebido com uma mensagem: Healthy.

Podemos condicionar o nosso Healthy/Unhealthy também ao status da conexão da nossa API com o banco de dados! Caso você utilize o EntityFrameworkCore é só adicionar o NuGet Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore e encadear uma chamada ao .AddDbContext() após o AddHealthChecks(), por exemplo:

https://medium.com/media/a40d8ad6c46fcc13be78563de9c114ba/href

Considerações Finais

Hoje vimos algumas bibliotecas que facilitam com o monitoramento da nossa API. Antes de publicarmos pode parecer overkill ter tudo isso porém é um esforço não muito grande e com um payoff absurdo quando você precisar descobrir o motivo de seu app/site/api está fora do ar ou quais são aqueles gargalos que te custam seus leads.

Para o próximo posts vamos dar uma olhada em Docker, Docker Compose , a Integração deles com o Visual Studio, e algumas configurações finais antes de botarmos a API no ar!

Obrigado por lerem mais este post, até a próxima e Abraços!

Cell CMS — Validando Inputs e Mapeamento Automático

Rodolpho Alves — Thu, 09 Apr 2020 01:45:40 +0000

Cell CMS — Validando Inputs e Mapeamento Automático

Cell-CMS, rodando no Kestrel

No último post falamos sobre o MediatR e o design pattern Mediator, implementando os endpoints com Commands e Queries. No post de hoje vamos continuar de onde paramos e adicionar validação aos nossos Commands e realizar o mapeamento automático dos Commands e seus campos para nossos Models.

Hoje faremos dois novos branches: feature/fluent-validation e feature/auto-mapper, um deles será para a instalação e configuração do FluentValidation e o outro para a instalação de configuração do AutoMapper.

Validando inputs com a sintaxe padrão

Por padrão, no universo .NET, temos os DataAnnotations para realizar a validação automática de nossos objetos. A documentação completa para eles pode ser encontrada neste link.

Utilizando estes componentes temos de, em nossas classes, adicionar alguns Attributes para realizar as validações. Por exemplo, em um Command, eu poderia realizar a validação da seguinte maneira:

https://medium.com/media/0b97caf17dadc5cb014839cb690dbf6d/href

A vantagem desta abordagem é que o .NET MVC automaticamente identifica estas anotações e as executa , permitindo que acessemos seu status através do ModelState! Desta maneira podemos, por exemplo, verificar o ModelState em nossos endpoints e retornar erros de validação como BadRequests.

https://medium.com/media/a16692cc8c37122cd620e1225ccbdb0e/href

A desvantagem desta abordagem é que estamos misturando lógicas de validação com lógicas de armazenamento de nossas classes (se você for da galera SOLID, podemos dizer que fere o Single Resposability de nossa classe). Outra desvantagem é que esta abordagem é prática apenas para validações mais simples. Se, em algum momento, você decidir realizar uma validação assincrona ou mais complexa deverá criar seu próprio Attribute.

Mas Rodolpho, existe outra maneira que possamos realizar validações sem criar nosso próprio framework ou poluir o código de execução com infinitos IFs!?

Sim! Existem alternativas prontas para utilizarmos! Uma delas é o FluentValidation!

Validando inputs com sintaxe Fluent — FluentValidation

Utilizando a biblioteca FluentValidation podemos escrever nossas validações em classes separadas , integrar estas validações com o middleware MVC e utilizar o mesmo ModelState para armazenar nossos resultados e erros de validação!

No Projeto da API adicione o NuGetFluentValidation.AspNetCore às dependências. Primeiros vamos configurar a integração com o MVC! Acesse o seu Startup.cs e realize as seguintes alterações:

https://medium.com/media/621794af1d506a884da60c4d6796ffe0/href

Agora precisamos escrever nossas regras de validação. Utilizarei o CreateFeed como exemplo. Crie uma nova classe (pode ser em um novo arquivo ou no CreateFeed.cs) chamada CreateFeedValidator e herde a classe AbstractValidator. Agora, graças ao AbstractValidator temos acesso à sintaxe Fluent dentro do Construtor da nossa classe. Com isso podemos escrever nossas regras de validação:

https://medium.com/media/98defd0c7d54db49279ec9b18cfd1ed6/href

Outras vantagens do FluentValidations são:

Criação de Rulesets para agrupar as validações (por exp: Ruleset para validações síncronas e assíncronas)
Validação condicionais (por exp: Se informar X, Y não pode ser null)
Validações assíncronas (por exp: Consultar no Context se existe alguém com a Propriedade X ou Y)

Por exemplo uma regra assíncrona para verificar que não existe um Content com o mesmo Nome na base de dados:

https://medium.com/media/f3f0c67e78fd87ceb07c796f20460aa0/href

A documentação completa está disponível em https://fluentvalidation.net/ e sugerido uma boa olhada! A biblioteca é bem ampla e possui várias funcionalidades úteis.

Só para não deixar passar vazio temos um exemplo da validação para uma request inválida:

https://medium.com/media/ab5dfc1ca3fd881ee8ec443921ccb36b/href

Mapeando propriedades manualmente

Atualmente realizamos a “tradução” de nossos Commands de maneira manual. Ou seja, criamos um novo Model e o preenchemos com os valores que vieram do nosso Command. Por exemplo, na atualização de uma Tag:

https://medium.com/media/600dce8952265d1131f6521cba29bd28/href

Isso, com o passar do tempo, torna-se repetitivo e meio braçal. Uma solução seria escrevermos Adaptors ou Factories (design patterns) para separar a lógica do mapeamento da lógica de execução, porém ainda temos o problema original , salvo que escrevamos algo que realiza o mapeamento através de Reflection, com base nos nomes das Propriedades de Origem e Destino.

Felizmente alguém já escreveu isto para nós! Do mesmo criador que o MediatR temos o famosíssimo AutoMapper!

Mapeando propriedades automaticamente — AutoMapper

Utilizando a biblioteca AutoMapper podemos contar com o mapeamento automático de propriedades através de padrões de nomenclatura e Reflection.

Para começarmos vamos adicionar o NuGet AutoMapper.Extensions.Microsoft.DependencyInjection à API e alterar nosso Startup.cs para registrar o AutoMapper nos services injetáveis:

https://medium.com/media/c911a184182bfb24c2616d1f2a844ae9/href

Agora precisamos criar nossos Mapeamentos. O AutoMapper, ao ser utilizado com injeção de dependência, requer que criemos “Profiles” para organizar nossos mapeamentos. Estes Profiles irão conter o “registro” para que o IMapper saiba entre quais objetos pode atuar!

Comecei criando o Profile para nossos Feeds no arquivo Features/Feeds/FeedProfile.cs:

https://medium.com/media/2417ce1e26aa2c545339673cbe8f76a5/href

Para utilizarmos o Profile basta injetar o IMapper através do construtor e utilizar os métodos Map() para delegar ao AutoMapper o trabalho de popular as propriedades!

https://medium.com/media/8f1c8241899635e2fa32d1423c30aa93/href

Assim como o FluentValidation o AutoMapper é amplamente customizável e você pode dar uma olhada na documentação completa em https://automapper.org/!

Considerações Finais

Hoje vimos duas bibliotecas bem úteis para o universo .NET, seja para o Frontend ou para o Backend estas bibliotecas nos auxiliam a manter o código limpo e organizado!

Para o próximo post a ideia será melhorarmos o processo de Log de Erros utilizando o Serilog, obter métricas automaticamente com o Application Insights e adicionarmos Healthchecks à nossa API e banco de dados!

Obrigado por lerem mais este post e até a próxima! Abraços!

DEV Community: Rodolpho Alves

A brief intro to SLF4J and the Java logging hell

Intro

A brief history of logging in Java

log4j is born

The ‘native’ library enters the fray

I need to switch loggers! Now what?

SLF4J to the Rescue

What is a “Facade”

Sample - Logback on Android!

Additional Resources

Mantendo a sanidade no mundo de Tecnologia

Mantendo a sanidade no mundo de Tecnologia

As ferramentas para manter a Sanidade!

Entenda que ninguém é perfeito

Saiba pesquisar por informação

Confie na sua equipe

Celebre pequenas vitórias

Tenha válvulas de escape

As Vantagens de estar bem

Configurando um ambiente Windows para desenvolvimento

💭 Introdução

🤔 Planejando!

1 - Escolhendo sua ferramentas para Packages

2 - Escolhendo um Package Manager com base nas suas necessidades

🛠 Preparando!

3 - Automatizando os básicos

4 - dotfiles no Windows

O PROFILE do Powershell

rodolphocastro / dotfiles

Dotfiles for my Windows and Linux environments

Rodolpho Alves' dotFiles

What are dotfiles

▶ Executando!

5 - Rodando scripts

6 - Baixando nossos dotfiles

7 - Usando o OpenSSH do Windows 10 com o Git

Ligando o OpenSSH Agent

Com Powershell

Sem Powershell

Criando e Adicionando Chaves SSH

Dizendo para o Git usar o OpenSSH

8 - Windows Subsystem for Linux (WSL)

Habilitando o Windows Subsystem for Linux

Pré-Requisitos

Com Powershell

Sem Powershell

Habilitando Virtualização no Windows

Com Powershell

Sem Powershell

Atualizando o Kernel do Linux

Ativando o WSL2

Instalando sua Distro favorita

9 - Docker Desktop

Alterações recentes (2021) na licença do Docker Desktop

Notas Finais

rodolphocastro / dotfiles

Dotfiles for my Windows and Linux environments

Rodolpho Alves' dotFiles

What are dotfiles

Cell CMS - Organizando, reutilizando e testando consultas do EntityFramework Core

Cell CMS - Organizando, reutilizando e testando consultas do EntityFramework Core

Intro

rodolphocastro / cell-cms

CMS leve, self-contained e prático de utilizar! Feito por desenvolvedores e para desenvolvedores!

Cell CMS

📚 Instruções

Utilizando uma Versão publicada

Compilando

Testando

⚙ Configurações

Autenticação/Autorização

Motivação para Abstrair o EF Core

Abordagem "clássica" - UnitOfWork + Repositories

Vantagens

Desvantagens

Exemplos

Abordagem funcional - Extension Methods

Extension Methods 101

Vantagens

4 - `dotfiles` no Windows

6 - Baixando nossos `dotfiles`