DEV Community: Daniel Genezini

Down the Rabbit Hole of creating a Home Lab

Daniel Genezini — Wed, 23 Apr 2025 14:00:00 +0000

Introduction

Setting up a home lab is an incredible journey that opens up countless learning opportunities in system administration, networking, security, and modern deployment practices. While it might seem daunting at first, the knowledge gained is invaluable for any tech enthusiast or IT professional.

In this post, I'll share a practical overview of how I use my home lab, highlighting the real-world projects I've tackled and the key lessons learned along the way. From self-hosting essential services to experimenting with automation, networking, and security, I'll focus on the hands-on experiences that have shaped my understanding of home server management and modern IT practices.

Why Set Up a Home Lab?

Before diving into the technical aspects, let's explore why you might want to invest time in setting up a home lab:

Hands-on Learning and Career Development: Theory is great, but nothing beats practical experience. A home lab provides a safe environment to experiment and learn from mistakes. The skills you develop are directly applicable to enterprise environments, making you more valuable as an IT professional. I'll dive into this learning topic below;
Control Over Your Data: Self-hosting gives you complete control over your data and privacy, reducing dependency on third-party services.
Some examples are:

Running VaultWarden (a self-hosted Bitwarden alternative) locally, which keeps your password data under your control and reduces exposure to online threats. By self-hosting, you can avoid risks such as polymorphic extension attacks that target cloud-based password managers;
Running Adguard Home to provide DNS over HTTPS (DoH), which encrypts your DNS queries and prevents your internet provider from seeing or logging your browsing activity. This enhances privacy and security for all devices on your network.

Cost Efficiency: Although setting up a home lab requires some upfront investment in hardware, it can be significantly more cost-effective over time compared to subscribing to multiple cloud services. By self-hosting solutions like Nextcloud for file storage and synchronization, or Immich for photo management, you gain virtually unlimited storage, constrained only by your own hardware, without recurring subscription fees. This approach allows you to scale your storage as needed, paying only for additional drives or upgrades, and often results in substantial long-term savings;
Customization: A home lab lets you tailor every aspect of your environment to your unique needs—something rarely possible with commercial solutions. For example, Home Assistant is a highly customizable alternative to Google Home or Apple HomeKit. It supports thousands of integrations, allowing you to connect and automate devices exactly as you want. You can create complex automations, dashboards, and routines that fit your lifestyle, rather than being limited by the features or restrictions of proprietary platforms;
Gives You New Ideas and Insights: Experimenting in your own environment exposes you to new technologies, workflows, and problem-solving approaches that you might not encounter otherwise. This often leads to creative solutions and a deeper understanding of IT concepts;
It's Fun: Building and managing your own home lab is genuinely enjoyable. It’s a rewarding hobby that lets you tinker, experiment, and see immediate results from your efforts.

What do you need / How to start?

You can begin your home lab journey by experimenting with a virtual machine on your computer or in the cloud, which is a low-risk way to get started and learn the basics. However, the real benefits come from setting up a dedicated local server. Repurposing an old PC or laptop is a great, cost-effective option—many home lab enthusiasts start this way. For example, I began with a Chromebox: I replaced ChromeOS with Alpine Linux, and it has been running reliably for over six years. As my needs grew, I transitioned to using my old notebook as the primary server. This approach lets you make the most of existing hardware while building hands-on experience with real-world setups.

Some home lab enthusiasts experiment with single-board computers like the Raspberry Pi, Orange Pi, or Banana Pi. Some even build clusters of multiple boards to explore distributed computing or container orchestration at a small scale. While I personally find them less cost-effective compared to repurposing old PCs or laptops—especially given recent price increases and performance limitations—they can be a fun and educational platform if you enjoy tinkering with hardware.

While specialized operating systems like CasaOS or Umbrel OS designed specifically to home servers, I recommend using a standard Linux distribution. This approach offers learning opportunities and greater applicability in professional environments.

What can you learn?

Here are some of the key areas you can explore and learn:

Operating Systems: Deepen your understanding of Linux distributions, command-line tools, and system internals;
Containers and Orchestration: Get hands-on with Docker, Docker Compose, and Kubernetes to deploy and manage containerized applications;
Service Hosting: Self-host applications like wikis, media servers, password managers, and more;
Storage and File Systems: Explore RAID, LVM, and network file sharing protocols;
Backup and Recovery: Develop backup/recovery strategies;
Security: Practice hardening your systems, managing firewalls, setting up VPNs, and implementing authentication mechanisms;
Networking: Learn about IP addressing, routing, VLANs, DNS, DHCP, and network security;
Monitoring and Logging: Set up monitoring stacks (Prometheus, Grafana), alerts and log aggregation tools to keep your environment healthy;
Automation: Use tools like Bash scripts and CI/CD pipelines to automate repetitive tasks and deployments.

Each of these areas offers practical, hands-on experience that builds both foundational and advanced skills, making your home lab an invaluable resource for continuous learning.

Linux

Of course that if we are building a server we are going to use Linux, and this is a rabbit hole by itself: the file system structure, commands, files permissions, systemd and daemons are just some examples.

Setting up a home lab on Linux teaches you:

System administration fundamentals;
Package management;
Service management with systemd;
Log analysis and system monitoring;
Shell scripting for automation.

Containers

Containers are the go-to way to spin up applications. It's easier, more secure and more maintainable. We can use compose files with Docker Compose and have the benefits of Infrastructure as Code (IaC).

The container journey teaches you:

Container lifecycle management (starting, healthy, unhealthy);
Volume management and data persistence;
Docker Compose for multi-container applications;
Container security best practices, such as running containers as non-root users and minimizing container privileges;
Image building and optimization;
Docker networking concepts (host, bridge, shared networks, etc).

A useful networking strategy in Docker Compose is to create a shared network for all applications, while also assigning each application its own private network for internal communication between its components. For example, a web application and its database can communicate over a dedicated private network, isolating sensitive traffic from other services. At the same time, the web application can be attached to a shared network, allowing it to interact with reverse proxies or other shared infrastructure. This approach improves security and organization by limiting cross-application access and making network policies easier to manage.

  networks:
    network_shared:
      external: true
    paperless:
      driver: bridge

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    depends_on:
      - db
    networks:
      - network_shared
      - paperless

  db:
    image: docker.io/library/postgres:15
    networks:
      - paperless

Container orchestration

There are lightweight Kubernetes distributions like K3s and K3d (K3s in Docker) that are ideal for a home server, because they require fewer resources and are easier to set up compared to a full Kubernetes installation.

With container orchestration, you'll learn:

Automated deployment and scaling of applications;
Load balancing;
Rolling updates and rollbacks;
Managing persistent storage for containers;
Use of Helm charts.

This will give you some hands-on experience with kubernetes and modern DevOps practices.

File Sharing and Storage

Understanding storage solutions is crucial for a home lab. You'll learn about:

Different file sharing protocols (SMB/CIFS and NFS) and how to expose and mount those protocols;
How to mount file systems at startup and configurations to abort on or ignore errors;
Storage pooling with LVM (combining multiple physical drives into a single logical volume);
Software RAID for redundancy;
File system permissions (and how they differ in SMB and NFS).

Backup Strategies

A solid backup strategy is essential to protect your data from accidental loss, hardware failure, or security incidents. In a home lab, you'll likely experiment with several backup tools and approaches:

Borg: Efficient, deduplicating, and encrypted backups. Great for incremental backups and remote storage.
Rsync: Flexible file synchronization and backup tool, ideal for local and remote backups with minimal bandwidth usage.
Rclone: Syncs files and directories to and from many cloud storage providers, making offsite backups easy. It allows layering virtual encrypted storage on top of any storage provider, ensuring data privacy and security.

Key concepts you'll learn:

Backup scheduling and automation;
Incremental and differential backups;
Encryption and data integrity verification;
Retention policies to manage storage usage.

Experimenting with these tools will help you design a backup solution tailored to your needs and ensure your data is always safe.

In my setup, I use Borg to create deduplicated backups of both my servers and personal computer. Once the backups are complete, I leverage Rsync to securely sync these archives to Google Drive (encrypting them at rest) for offsite redundancy. For local photo backups, I rely on Rsync to efficiently mirror and synchronize photo directories between multiple hard drives, ensuring quick recovery and data integrity.

Reverse Proxy and SSL

A crucial component for secure service access:

NGINX or Traefik configuration;
SSL/TLS certificate management;
Let's Encrypt automation.

In my setup, I use NGINX Proxy Manager together with DuckDNS (pointing to my local IP, meaning it is only accessible by my local network or VPN) and Let's Encrypt for automated SSL certificate provisioning. This combination allows me to expose my self-hosted services over HTTPS, routing all access exclusively through NGINX Proxy Manager, which acts as a reverse proxy—ensuring that only authenticated and encrypted traffic reaches my internal services.

Authentication and Security

Security is critical in any server environment, so I'll learn:

OpenID and OAuth2;
Single Sign-On (SSO) implementation;
Network segmentation;
Firewall configuration.

I use Authentik to handle OpenID authentication, integrating it with NGINX to secure proxied services.

Networking

Essential networking concepts you'll learn:

DNS management and local DNS resolution;
Port forwarding (and why not to do it);
Network troubleshooting.

In my setup, I use DuckDNS to obtain a free domain name, resolving to a local IP, so it is only accessible in my local network. For local DNS resolution and caching, AdGuard Home acts as my DNS server, providing fast lookups and enhanced privacy for all devices on my network. To securely access my home lab from anywhere without exposing ports or relying on traditional port forwarding, I leverage ZeroTier—a peer-to-peer VPN solution that uses UDP hole punching to create encrypted, direct connections between devices, even behind NAT or firewalls. This combination ensures secure, reliable, and private connectivity to my services, both locally and remotely.

Monitoring and Maintenance

Keeping your services healthy:

System monitoring and resource usage with Prometheus/Grafana;
Application health-check monitoring;
Log aggregation and analysis;
Alerts configuration.

For monitoring the health and performance of my home lab, I use a combination of tools:

Uptime Kuma provides real-time health checks for all my services, alerting me immediately via Telegram if any become unreachable.
Prometheus collects detailed metrics from both containers and the host system, using cAdvisor for container-level insights and Node Exporter for system metrics. These metrics are visualized in Grafana dashboards, giving me a comprehensive view of resource usage and trends.
I’ve set up alerting rules in Grafana to notify me via Telegram whenever critical thresholds are breached, ensuring I can respond quickly to issues.
For log monitoring, I rely on Dozzle to view container logs in real time. It’s lightweight and simple, which suits my needs since I don’t require long-term log retention.

Automation and Scheduling

Automation is the secret sauce that transforms a home lab from a collection of services into a streamlined, low-maintenance environment. By automating routine tasks, you reduce manual effort, minimize human error, and ensure your services remain reliable and up-to-date.

Some practical automation strategies include:

Automated Backups: Schedule regular backups using tools like cron, or backup software with built-in schedulers (Pika Backup, Vorta). This ensures your data is always protected without manual intervention;
Scripted Automations: Use shell scripts, or CI/CD pipelines (e.g., GitHub Actions) to deploy and update your applications consistently;
Scheduled Maintenance: Automate cache cleanups, and other housekeeping tasks to keep your environment running smoothly.

Conclusion

Setting up a home lab is an ongoing journey of learning and discovery. While it requires time and dedication, the knowledge and skills gained are invaluable. Start small, focus on one area at a time, and gradually expand your infrastructure as you learn.

Remember that mistakes are part of the learning process - having a good backup strategy means you can experiment freely without fear of losing data.

Applications/Tools

Here's a comprehensive list of tools mentioned in this article:

AdGuard Home - Network-wide DNS privacy and ad blocking
DuckDNS - Free dynamic DNS service
Let's Encrypt - Free SSL certificate authority
NGINX - Web server and reverse proxy
NGINX Proxy Manager - GUI for NGINX proxy management
Traefik - Modern reverse proxy and load balancer
ZeroTier - P2P VPN for secure remote access
K3s - Lightweight Kubernetes distribution
K3d - K3s in Docker for local development
cAdvisor - Container resource usage metrics
Dozzle - Real-time container log viewer
Grafana - Metrics visualization and alerting
Node Exporter - Hardware and OS metrics
Prometheus - Metrics collection and storage
Uptime Kuma - Uptime monitoring
Borg - Deduplicating backup program
Pika Backup - User-friendly Borg backup frontend for GNOME
Rclone - Cloud storage sync tool
Rsync - Fast file copying and syncing
Vorta - Desktop backup client for Borg
Home Assistant - Home automation platform
Immich - Self-hosted photo backup solution
Nextcloud - File hosting and collaboration
Vaultwarden - Password management server
Authentik - Open-source Identity Provider focused on flexibility and versatility.

References

Integration tests with AWS S3 buckets using Localstack and Testcontainers

Testing AWS integrations with a local AWS emulator

blog.genezini.com

Liked this post?

I post extra content in my personal blog.

Daniel Genezini | It works on my machine

My blog where I share my experiences about .NET, Blazor, AWS, and other tech stuff. Very important note: Everything that I post works on my machine!

blog.genezini.com

Follow me

Server-side rendered SPAs with ASP.NET and no Javascript

Daniel Genezini — Mon, 16 Sep 2024 14:59:00 +0000

Introduction

Single-page applications (SPA) provide better user experience by removing full-page loads, giving smooth transitions between pages and performance improvements depending on the scale of the application, but they come at some costs which may not be worth for some application types. The main cost is the added complexity of a SPA framework like Angular or Vue.

In this post, I'll show how to use ASP.NET and HTMX to build single-page applications without using JavaScript and SPA frameworks.

What is HTMX

HTMX is a library that allows us to access modern browser features by extending HTML, without needing to use Javascript directly. It gives us access to AJAX, CSS Transitions, WebSockets and more, including extensions.

It simplifies making responsive apps that give our users a better experience without the complexity of Javascript.

HTMX is really powerfull, but in this post I'll focus on the hx-boost attribute.

Base application

I'll use an old Razor Pages Sample Application by Damian Edwards to show how easy it is to make an SPA with ASP.NET and HTMX.

I've made some changes in his sample, including upgrading from .NET Core 2.0 to .NET 7. These changes are in the branch sample-base of the sample repository: AspNetCoreSPAHtmx.

💡 I'm using Razor pages but what I'll show is also aplicable to ASP.NET MVC.

Including the HTMX lib and menu links configurations

Let's open the _Layout.cshtml and add the reference to HTMX at the end of the <body> tag:

    ...

    <script src="https://unpkg.com/htmx.org@1.9.6"></script>
</body>

HTMX has an attribute hx-boost that enable us to transform our Multi-Page Application in a Single Page Application (SPA) with just some tweaks, making <a> and <form> tags use AJAX requests instead of page reloads.

It works on all the children of the element it is applied to, so let's include it in the <nav> tag so all the menu links use AJAX:

<nav class="navbar navbar-inverse navbar-fixed-top" hx-boost="true" hx-target="#main-content">

By default, hx-boost applies the AJAX response to the <body> tag, so we need to specify the id of target (in this sample, #main-content) in the hx-target attribute.

Now, let's create a div with id main-content to receive the response content inside the body-content div:

<div class="container body-content">
    <div id="main-content">
        @RenderBody()
    </div>

    <hr />

    <footer>
        <p>Full-page load at @DateTime.Now</p>
        <p>&copy; 2017 - Razor Pages</p>
    </footer>
</div>

ℹ️ Note that the time of the full-page load is in the footer, so we can check that the requests are done with AJAX.

Removing the layout for HTMX requests

All requests done with HTMX will have a Hx-Request header set to true.

We will check for it in the _ViewStart.cshtml file and remove the page layout for HTMX requests:

@{
    @if (!ViewContext.HttpContext.Request.Headers["Hx-Request"].Contains("true"))
    {
        Layout = "_Layout";
    }
    else
    {
        Layout = "";
    }
}

Setting up the forms

Now, we also need to include the hx-boost and hx-target attributes in the <form> tags in the Index.cshtml, New.cshtml and Edit.cshtml files:

<form method="post" class="form-horizontal" hx-boost="true" hx-target="#main-content">

Now we can test the application. Note that the time of the page load in the footer doesn't change:

Looking at the browser's console, we can see the request was done:

The form content in the request payload:

The response without the _Layout.cshtml content:

The response rendered in the page:

💡 ASP.NET Form Validation will also work:

Changing the page title according to the page load

Until now, the page title is not being changed, because it is set in the _Layout.cshtml file, that is loaded just on the first page load:

<title>@ViewData["Title"] - Razor Pages Sample + HTMX</title>

The hx-boost attribute will automatically change the page title if the response returns a <title> tag. To do this, let's create a new layout for the HTMX requests.

Create a _LayoutHtmxBoost.cshtml with the below:

@if (!string.IsNullOrEmpty(ViewData["Title"]!.ToString()))
{
    <head>
        <title>@ViewData["Title"] - Razor Pages Sample + HTMX</title>
    </head>
}

@RenderBody()

@RenderSection("Scripts", required: false)

Note that we return a <title> tag if the ViewData["Title"] has any value.

Now, let's change the _ViewStart.cshtml file to use the _LayoutHtmxBoost layout for HTMX requests:

@{
    @if (!ViewContext.HttpContext.Request.Headers["Hx-Request"].Contains("true"))
    {
        Layout = "_Layout";
    }
    else if (ViewContext.HttpContext.Request.Headers["Hx-Boosted"].Contains("true"))
    {
        Layout = "_LayoutHtmxBoost";
    }
    else
    {
        Layout = "";
    }
}

⚠️ We are checking for the Hx-Boosted header non-boosted HTMX requests don't use this layout.

💡 HTMX automatically pushes the pages to the browser's history:

Indicating the loading status

That's cool, but we don't have an indicator of the request being processed. For this, we can use the hx-indicator attribute, specifying the id of the element to show while awaiting for the request.

The hx-indicator works by adding the htmx-request css class to the element specified, that will set the opacity to 1. For this to work, we first need to hide the element with an opacity of 0, or use the htmx-indicator css class that does this with a css transaction.

First, I created a partial page with a loader from Pure CSS Loaders with the name _LoadSpinner, and set the id to spinner and added the htmx-indicator css class:

<div id="spinner" class="htmx-indicator">
    <div class="lds-ring"><div></div><div></div><div></div><div></div></div>
</div>

Then, I added it in the menu:

<div class="collapse navbar-collapse" id="header-navbar-collapse">
    <ul class="nav navbar-nav">
        <li><a asp-page="/Index">Home</a></li>
        <li><a asp-page="/Customers/Index">Customers</a></li>
        <li><partial name="_LoadSpinner" /></li>
    </ul>
</div>

Lastly, I add the hx-indicator attribute with the value #spinner to the <nav> element:

<nav class="navbar navbar-inverse navbar-fixed-top" hx-boost="true" hx-target="#main-content" hx-indicator="#spinner">

and all <form> elements:

<form method="post" class="form-horizontal" hx-boost="true" hx-target="#main-content" hx-indicator="#spinner">

💡 To make it easier to see the indicator, I included a delay of 500 milliseconds to all pages GET/POST methods:
public async Task<IActionResult> OnGetAsync(int id)
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));

    ...
}

Running the app again, we can see the indicator showing in every actions:

Full source code

GitHub Repository

References and Links

Integration tests without API dependencies with ASP.NET Core and WireMock.Net

Mockings APIs with WireMock.Net

blog.genezini.com

Liked this post?

I post extra content in my personal blog.

Daniel Genezini | It works on my machine

My blog where I share my experiences about .NET, Blazor, AWS, and other tech stuff. Very important note: Everything that I post works on my machine!

blog.genezini.com

Follow me

Colorful terminals with Oh My Posh and Windows Terminal

Daniel Genezini — Tue, 27 Aug 2024 15:00:00 +0000

Introduction

Oh My Posh is a tool that not only enhance the appearance of your shell, but also offers useful integrations that makes the use more intuitive and helps us be more productive.

I use it in WSL and in my home server and customized it to easily identify what shell I'm in:

Quick definition

Just a quick definition of the terms Shell and Terminal:

Shell: the software that receives the input, process and returns and output (Examples: zsh, bash, PowerShell, cmd);
Terminal: the software that takes the input and passes on to the shell and then prints the shell output (Windows Terminal, VS Code Terminal, cmder).

Installing Oh My Posh

To install Oh My Posh, we need to download the install script and run it:

curl -s https://ohmyposh.dev/install.sh | bash -s

And include its configuration in the run commands file of the shell you use.

In my case, I use zsh, so I include the following line to my ~/.zshrc file:

eval "$(oh-my-posh init zsh)"

Then exit the shell and enter again to load the configuration.

ℹ️ Here there is a list of configurations for the supported shells, including PowerShell and Cmd.

Installing a Nerd Font

To use everything Oh My Posh offers, its essential to install a custom font that includes icons.
Oh My Posh recommends one of the Nerd Fonts.

To install the fonts on Windows:

Download the font you like (I use Caskaydia Cove) from their page;
Extract it in a temporary directory;
Select all .ttf files;
Right click and click Install or Install for all users.

Configuring The Terminal

Then, we need to configure the terminal to use the font

⚠️ The fonts are needed in the system where you use the terminal. If you access a server via SSH, you only need the fonts in the system where you access it from.

Windows Terminal

Enter the Settings;
Select the profile to configure;
Click in Appearance;
Select the font in Font face
Click Save.

Then we can see that the icons are shown correctly:

VS Code

Enter the Settings (File > Preferences > Settings);
Search for terminal font;
Type the font name in Terminal > Integrated > Font Family. For Caskaydia Cove it can be CaskaydiaCove Nerd Font Mono.

Then we can see that the icons are shown correctly:

Themes

Oh My Posh is highly customizable and has many themes (List here).

To use a theme, just download its json and use it when starting Oh My Posh.

In the example below, the theme is in ~/.poshthemes/aliens.omp.json:

eval "$(oh-my-posh init zsh --config ~/.poshthemes/aliens.omp.json)"

Then exit the shell and enter again to load the configuration.

Customizing your theme

Oh My Posh has many segments that can be used. Some that I find interesting are:

Git: Can show the status of the git repo, files changed, rebase/merge status and many more;
Status Code: Shows the status of the last command executed, if they succeeded or not;
Root: Show if the logged user is root.

We can also use the Command segment to run any command and print the output.

As well as some configurations, for example:

Console title: Customize what is shown in the terminal title bar. I use it with a fixed text in my home server to easily identify when I'm connected to it;
Transient Prompt: Replaces the template for the shell history with a simpler one;
Tooltip: Show information on the right when a specified command is type. For example, show the git branch when "git" is typed.

💡 Oh My Posh is written in Go, so we can use Go Templates to customize many of its features with conditions, access environment variables and format texts. You can see some examples in my theme below.

Here there is an Unicode cheat sheet for Nerd Fonts to use when customizing the theme.

My theme

In my theme I use 4 segments:

Session: Shows an icon, the logged in user and the hostname;
Path: Shows the current directory (I use the Agnoster Short style, but there are others);
Status: Shows an colored icon for the status of the last shell command (Successful/Failed);
Git: Shows the git status for the repository if the directory is one.

ℹ️ I change the color and the icon of the session segment according to what shell I'm using (server icon for home server, Ubuntu icon for Ubuntu in WSL).

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
  "version": 2,
  "final_space": true,
  "blocks": [
    {
      "type": "prompt",
      "alignment": "left",
      "segments": [
        {
          "type": "session",
          "style": "diamond",
          "foreground": "#FFFFFF",
          "background": "#dd4a14",          
          "leading_diamond": "\ue0b6",
          "template": "\ue73a {{ .UserName }}@{{ .HostName }} "
        },
        {
          "type": "path",
          "style": "powerline",
          "powerline_symbol": "\ue0b0",
          "foreground": "#ffffff",
          "background": "#207a26",
          "template": " {{ .Path }} ",
          "properties": {
            "folder_icon": "\uf6d7",
            "folder_separator_icon": "<transparent> \ue0bd </>",
            "home_icon": "\uf7db",
            "style": "agnoster_short"
          }
        },
        {
          "type": "status",
          "style": "powerline",
          "powerline_symbol": "\ue0b0",
          "foreground": "#ffffff",
          "background": "#00897b",
          "background_templates": [
            "{{ if .Error }}#890017{{ end }}"
          ],
          "template": " {{ if .Error }}\uea87{{ else }}\uf05d{{ end }} ",
          "properties": {
            "always_enabled": true
          }
        },
        {
          "type": "git",
          "style": "powerline",
          "powerline_symbol": "\ue0b0",
          "foreground": "#193549",
          "background": "#95ffa4",
          "template": " {{ .HEAD }}{{if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Working.Changed }} \uf044 {{ .Working.String }}{{ end }}{{ if and (.Staging.Changed) (.Working.Changed) }} |{{ end }}{{ if .Staging.Changed }} \uf046 {{ .Staging.String }}{{ end }} "
        }
      ]
    }
  ]
}

References

Liked this post?

I post extra content in my personal blog.

Daniel Genezini | It works on my machine

My blog where I share my experiences about .NET, Blazor, AWS, and other tech stuff. Very important note: Everything that I post works on my machine!

blog.genezini.com

Follow me

Integration tests with AWS S3 buckets using Localstack and Testcontainers

Daniel Genezini — Tue, 07 Nov 2023 14:00:00 +0000

As I explained previously in this article, in integration tests, we should mock unmanaged dependencies (dependencies that are external to our system and not controlled by us, like APIs) but test against real managed dependencies (dependencies that are controlled by our system, like databases, queues, etc). This improves the reliability of the integration tests because the communication with these dependencies are a complex part of the system and can break with a package update, a database update or a change in a queue message format.

In this post, I'll show how to use Localstack and Testcontainers to emulate an AWS environment for use in integration tests.

Why use Localstack for integration tests?

Reduced Costs: Using LocalStack eliminates the use of AWS resources during tests and development. It also avoids accidental charges during development, for example, in cases of incorrect logic;
Development speed: Using LocalStack allows developer to test without having to deploy or configure AWS credentials on the local environment. It also remove external factors, as other people using the same AWS resources on the environment;
Reproducibility and less flaky tests: Integration tests run in an isolated environment, avoiding any interference with the production or staging environment. This makes tests reproducible in any developer's machine and less flaky because there is no dependency with the network and a shared AWS environment, that can change frequently;
Cleanup: LocalStack environment is automatically cleaned up after the tests, making easier to use in automated tests;
Test of Edge Cases: We can customize LocalStack's configuration, allowing us to test edge cases that may not be tested on an AWS environment, like rate limits and permissions errors.

What is Testcontainers?

Testcontainers is a library that manages containers' lifecycle to be used in automated tests. These containers are useful for testing applications against real managed dependencies, like databases, or AWS resources (using LocalStack) that can be created and disposed of after the tests.

Running a disposable container with Testcontainers

To use Testcontainers, you will need to have a container runtime (Docker, Podman, Rancher, etc) installed on your machine.

Then, you need to add the Testcontainers NuGet package to your test project:

```bash {linenos=false}
dotnet add package Testcontainers




To run a LocalStack container, we first need to use the `ContainerBuilder` class to build an `IContainer`:



```csharp
const int LocalStackPort = 4566;
const string LocalStackImage = "localstack/localstack:1.3.1";

await using var LocalStackTestcontainer = new ContainerBuilder()
    .WithImage(LocalStackImage)
    .WithExposedPort(LocalStackPort)
    .WithPortBinding(LocalStackPort, true)
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilHttpRequestIsSucceeded(request => request
            .ForPath("/_localstack/health")
            .ForPort(LocalStackPort)))
    .Build();

Then, we start the container and use the Hostname property and GetMappedPublicPort() method to create the ServiceUrl that will be used by the AWS Clients:

const int LocalStackPort = 4566;
const string LocalStackImage = "localstack/localstack:1.3.1";

await using var LocalStackTestcontainer = new ContainerBuilder()
    .WithImage(LocalStackImage)
    .WithExposedPort(LocalStackPort)
    .WithPortBinding(LocalStackPort, true)
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilHttpRequestIsSucceeded(request => request
            .ForPath("/_localstack/health")
            .ForPort(LocalStackPort)))
    .Build();

await LocalStackTestcontainer.StartAsync();

var localstackUrl = $"http://{_localStackTestcontainer.Hostname}:{_localStackTestcontainer.GetMappedPublicPort(4566)}";

❗ The IContainer interface extends IAsyncDisposable and needs to be disposed of after use. We can use the await using syntax, as in the example above, or call the DisposeAsync method, as in the fixture shown below.

Example context

In the example from Part 1, I have a controller with a POST method that uploads an image to an S3 bucket and a GET method that finds an image from the S3 bucket by its file name:

app.MapPost("/upload", async (IAmazonS3 s3Client, IFormFile file) =>
{
    var bucketName = builder.Configuration["BucketName"]!;

    var bucketExists = await s3Client.DoesS3BucketExistAsync(bucketName);

    if (!bucketExists)
    {
        return Results.BadRequest($"Bucket {bucketName} does not exists.");
    }

    using var fileStream = file.OpenReadStream();

    var putObjectRequest = new PutObjectRequest()
    {
        BucketName = bucketName,
        Key = file.FileName,
        InputStream = fileStream
    };

    putObjectRequest.Metadata.Add("Content-Type", file.ContentType);

    var putResult = await s3Client.PutObjectAsync(putObjectRequest);

    return Results.Ok($"File {file.FileName} uploaded to S3 successfully!");
});

app.MapGet("/object/{key}", async (IAmazonS3 s3Client, string key) =>
{
    var bucketName = builder.Configuration["BucketName"]!;

    var bucketExists = await s3Client.DoesS3BucketExistAsync(bucketName);

    if (!bucketExists)
    {
        return Results.BadRequest($"Bucket {bucketName} does not exists.");
    }

    try
    {
        var getObjectResponse = await s3Client.GetObjectAsync(bucketName,
            key);

        return Results.File(getObjectResponse.ResponseStream,
            getObjectResponse.Headers.ContentType);
    }
    catch (AmazonS3Exception ex) when (ex.ErrorCode.Equals("NotFound", StringComparison.OrdinalIgnoreCase))
    {
        return Results.NotFound();
    }
});

⚠️ The business logic in the controller is just for the sake of simplicity. In a real-world application, the logic should be in a Use Case/Interactor or something with the same purpose.

Creating integration tests with Testcontainers

In this example, I'm using xUnit and the WebApplicationFactory<T> class from ASP.NET Core.

If you don't know how to use the WebApplicationFactory<T> class, I explained in this post.

When running in AWS, the AmazonS3Client will get its access data from the IAM Role attached to the service running it. When running locally, it will get from the AWS CLI profile named default or from the settings we pass to it.

ℹ️ The default profile is read from the AWSCLI credentials file (%userprofile%\.aws\credentials on Windows and ~/.aws/credentials on Linux).

In the code below, I'm checking for a configuration section with the name AWS, that is not present in the production environment. If it's found, I set the Region, ServiceURL and ForcePathStyle properties of the AmazonS3Config and pass it to the creation of the AmazonS3Client:

builder.Services.AddSingleton<IAmazonS3>(sc =>
{
    var configuration = sc.GetRequiredService<IConfiguration>();
    var awsConfiguration = configuration.GetSection("AWS").Get<AwsConfiguration>();

    if (awsConfiguration?.ServiceURL is null)
    {
        return new AmazonS3Client();
    }
    else
    {
        return AwsS3ClientFactory.CreateAwsS3Client(
            awsConfiguration.ServiceURL,
            awsConfiguration.Region, awsConfiguration.ForcePathStyle,
            awsConfiguration.AwsAccessKey, awsConfiguration.AwsSecretKey);
    }
});

For the integration tests, those settings (except for the ServiceURL) will be configured in appsettings.IntegrationTest.json file, that is injected by the WebApplicationFactory<T> class:

{
  ...

  "AWS": {
    "Region": "us-east-1",
    "ForcePathStyle": "true",
    "AwsAccessKey": "test",
    "AwsSecretKey": "test"
  }
}

ℹ️ As the container will have a random public port, the AWS:ServiceURL configuration has to be passed after Testcontainers starts the LocalStack container, using the Hostname and GetMappedPublicPort(4566) to create the full URL.

LocalStack/Testcontainer Fixture

This fixture will start and dispose of the Localstack container, sharing it with all tests.

I recommend using the same container instance for all tests, instead of one per test. It will require more attention to avoid cause between the tests, but will save time in executing them.

[CollectionDefinition("LocalStackTestcontainer Collection")]
public class LocalStackTestcontainerCollection : 
    ICollectionFixture<LocalStackTestcontainerFixture>
{
}

public class LocalStackTestcontainerFixture : IAsyncLifetime
{
    public const int LocalStackPort = 4566;
    public const string LocalStackImage = "localstack/localstack:1.3.1";

    public IContainer LocalStackTestcontainer { get; private set; } = default!;

    public async Task InitializeAsync()
    {
        LocalStackTestcontainer = new ContainerBuilder()
            .WithImage(LocalStackImage)
            .WithExposedPort(LocalStackPort)
            .WithPortBinding(LocalStackPort, true)
            .WithWaitStrategy(Wait.ForUnixContainer()
                .UntilHttpRequestIsSucceeded(request => request
                    .ForPath("/_localstack/health")
                    .ForPort(LocalStackPort)))
            .Build();

        await LocalStackTestcontainer.StartAsync();
    }

    public async Task DisposeAsync()
    {
        await LocalStackTestcontainer.DisposeAsync();
    }
}

Upload an image test

The test reads the configurations with IConfiguration to create an AmazonS3Client and create the bucket in the LocalStack environment and to assert the test condition (the object was created in the bucket):

[Collection("LocalStackTestcontainer Collection")]
public class UploadTests : IClassFixture<CustomWebApplicationFactory>
{
    private readonly CustomWebApplicationFactory _factory;
    private readonly IContainer _localStackTestcontainer;

    public UploadTests(CustomWebApplicationFactory factory,
        LocalStackTestcontainerFixture localStackTestcontainerFixture)
    {
        _factory = factory;
        _localStackTestcontainer = localStackTestcontainerFixture.LocalStackTestcontainer;
    }

    [Fact]
    public async Task UploadObject_Returns200()
    {
        //Arrange
        var localstackUrl = $"http://{_localStackTestcontainer.Hostname}:{_localStackTestcontainer.GetMappedPublicPort(4566)}";

        var HttpClient = _factory
            .WithWebHostBuilder(builder =>
            {
                builder.UseSetting("AWS:ServiceURL", localstackUrl);
            })
            .CreateClient();

        var configuration = _factory.Services.GetRequiredService<IConfiguration>();
        var awsConfiguration = configuration.GetSection("AWS").Get<AwsConfiguration>()!;

        var s3Client = AwsS3ClientFactory.CreateAwsS3Client(localstackUrl, 
            awsConfiguration.Region, awsConfiguration.ForcePathStyle,
            awsConfiguration.AwsAccessKey, awsConfiguration.AwsSecretKey);

        await s3Client.PutBucketAsync(configuration["BucketName"]);

        const string fileName = "upload.jpg";

        var filePath = Path.Combine(Directory.GetCurrentDirectory(),
            "Assets", fileName);

        //Act
        using var multipartFormContent = new MultipartFormDataContent();

        var fileStreamContent = new StreamContent(File.OpenRead(filePath));
        fileStreamContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpg");

        multipartFormContent.Add(fileStreamContent, name: "file", fileName: fileName);

        var httpResponse = await HttpClient.PostAsync($"/upload", multipartFormContent);

        //Assert
        httpResponse.StatusCode.Should().Be(HttpStatusCode.OK);

        var bucketFile = await s3Client.GetObjectAsync(configuration["BucketName"],
            fileName);

        bucketFile.HttpStatusCode.Should().Be(HttpStatusCode.OK);
    }
}

ℹ️ We could also create the S3 bucket using the ExecAsync method from Testcontainer's IContainer to execute AWS CLI commands in the Localstack container, but I find it easier and less error prone to do it with the AWS SDK.

Upload an existing image test

This test uses the ListObjectsAsync method of the AmazonS3Client to assert that uploading an image with the same file name will override the image instead of creating another:

[Fact]
public async Task UploadExistentObject_Returns200AndOverride()
{
    //Arrange
    var localstackUrl = $"http://{_localStackTestcontainer.Hostname}:{_localStackTestcontainer.GetMappedPublicPort(4566)}";

    var HttpClient = _factory
        .WithWebHostBuilder(builder =>
        {
            builder.UseSetting("AWS:ServiceURL", localstackUrl);
        })
        .CreateClient();

    var configuration = _factory.Services.GetRequiredService<IConfiguration>();
    var awsConfiguration = configuration.GetSection("AWS").Get<AwsConfiguration>()!;

    var s3Client = AwsS3ClientFactory.CreateAwsS3Client(localstackUrl,
        awsConfiguration.Region, awsConfiguration.ForcePathStyle,
        awsConfiguration.AwsAccessKey, awsConfiguration.AwsSecretKey);

    await s3Client.PutBucketAsync(configuration["BucketName"]);

    const string fileName = "upload.jpg";

    var filePath = Path.Combine(Directory.GetCurrentDirectory(),
        "Assets", fileName);

    //Act
    using var multipartFormContent = new MultipartFormDataContent();

    var fileStreamContent = new StreamContent(File.OpenRead(filePath));
    fileStreamContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpg");

    multipartFormContent.Add(fileStreamContent, name: "file", fileName: fileName);

    var httpResponse1 = await HttpClient.PostAsync($"/upload", multipartFormContent);

    var httpResponse2 = await HttpClient.PostAsync($"/upload", multipartFormContent);

    //Assert
    httpResponse1.StatusCode.Should().Be(HttpStatusCode.OK);

    httpResponse2.StatusCode.Should().Be(HttpStatusCode.OK);

    var bucketObjects = await s3Client.ListObjectsAsync(configuration["BucketName"]);

    bucketObjects.S3Objects.Count.Should().Be(1);

    var bucketFile = await s3Client.GetObjectAsync(configuration["BucketName"],
        fileName);

    bucketFile.HttpStatusCode.Should().Be(HttpStatusCode.OK);
}

Get an image test

To test the endpoint that returns the image, I use the AmazonS3Client to create the bucket and upload an image, and then, call the endpoint and assert that it returns the image:

[Collection("LocalStackTestcontainer Collection")]
public class GetObjectTests : IClassFixture<CustomWebApplicationFactory>
{
    private readonly CustomWebApplicationFactory _factory;
    private readonly IContainer _localStackTestcontainer;

    public GetObjectTests(CustomWebApplicationFactory factory,
        LocalStackTestcontainerFixture localStackTestcontainerFixture)
    {
        _factory = factory;
        _localStackTestcontainer = localStackTestcontainerFixture.LocalStackTestcontainer;
    }

    [Fact]
    public async Task GetExistingObject_Returns200()
    {
        //Arrange
        var localstackUrl = $"http://{_localStackTestcontainer.Hostname}:{_localStackTestcontainer.GetMappedPublicPort(4566)}";

        var HttpClient = _factory
            .WithWebHostBuilder(builder =>
            {
                builder.UseSetting("AWS:ServiceURL", localstackUrl);
            })
            .CreateClient();

        var configuration = _factory.Services.GetRequiredService<IConfiguration>();
        var awsConfiguration = configuration.GetSection("AWS").Get<AwsConfiguration>()!;

        var s3Client = AwsS3ClientFactory.CreateAwsS3Client(localstackUrl,
            awsConfiguration.Region, awsConfiguration.ForcePathStyle,
            awsConfiguration.AwsAccessKey, awsConfiguration.AwsSecretKey);

        await s3Client.PutBucketAsync(configuration["BucketName"]);

        const string fileName = "upload.jpg";

        var filePath = Path.Combine(Directory.GetCurrentDirectory(),
            "Assets", fileName);

        var putObjectRequest = new PutObjectRequest()
        {
            BucketName = configuration["BucketName"],
            Key = fileName,
            FilePath = filePath
        };

        putObjectRequest.Metadata.Add("Content-Type", "image/jpg");

        var putResult = await s3Client.PutObjectAsync(putObjectRequest);

        //Act
        var httpResponse = await HttpClient.GetAsync($"/object/{fileName}");

        //Assert
        httpResponse.StatusCode.Should().Be(HttpStatusCode.OK);

        httpResponse.Content.Headers.ContentType.Should().Be(MediaTypeHeaderValue.Parse("image/jpeg"));
    }
}

Image not found test

To test the behavior when the image doesn't exist, I use the AmazonS3Client to create the bucket, and then, call the endpoint that returns the image with a file name that doesn't exist in the bucket:

[Fact]
public async Task GetInexistingObject_Returns404()
{
    //Arrange
    var localstackUrl = $"http://{_localStackTestcontainer.Hostname}:{_localStackTestcontainer.GetMappedPublicPort(4566)}";

    var HttpClient = _factory
        .WithWebHostBuilder(builder =>
        {
            builder.UseSetting("AWS:ServiceURL", localstackUrl);
        })
        .CreateClient();

    var configuration = _factory.Services.GetRequiredService<IConfiguration>();
    var awsConfiguration = configuration.GetSection("AWS").Get<AwsConfiguration>()!;

    var s3Client = AwsS3ClientFactory.CreateAwsS3Client(localstackUrl,
        awsConfiguration.Region, awsConfiguration.ForcePathStyle,
        awsConfiguration.AwsAccessKey, awsConfiguration.AwsSecretKey);

    await s3Client.PutBucketAsync(configuration["BucketName"]);

    const string fileName = "inexisting.jpg";

    //Act
    var httpResponse = await HttpClient.GetAsync($"/object/{fileName}");

    //Assert
    httpResponse.StatusCode.Should().Be(HttpStatusCode.NotFound);
}

Full source code

GitHub repository

References and Links

How to run disposable databases for your tests. Improve your integration tests accuracy with Testcontainers

Spining up disposable databases with Testcontainers

blog.genezini.com

Liked this post?

I post extra content in my personal blog.

Daniel Genezini | It works on my machine

My blog where I share my experiences about .NET, Blazor, AWS, and other tech stuff. Very important note: Everything that I post works on my machine!

blog.genezini.com

Follow me

Lessons learned from building a static code analyzer for C#

Daniel Genezini — Wed, 11 Oct 2023 11:54:10 +0000

Introduction

Static code analyzers are tools used to analyze software code without executing it. They can examine the code to find code smells, vulnerabilities, potential errors, and code out of a defined standard, for example. They work by parsing the source code and evaluating its syntax (structure of the code) and semantic (meaning of the code).

Roslyn, the C# compiler, provides tools for developing Roslyn Analyzers (Static code analyzers for Roslyn), giving access to the syntax and semantic of the code, that can be executed at development and build time, providing feedback in near real-time to the developers.

In this post, I'll show a Roslyn Analyzer I built for using Discriminated Unions in C#, requiring to check the union type before access, and talk about some lessons learned while developing it.

DiscriminatedUnions.Net package

The package allows the use of Discriminated Unions by enforcing two rules:

The type of a Union must be checked before access;
All types of a Union must be checked (or have an else/default/discard case).

To use the package, install it in the project:

<PackageReference Include="DiscriminatedUnions.Net" Version="1.0.0.19" />

Extend UnionValue when declaring the types that will be used in the Discriminated Union:

public class Bird: UnionValue
{
}

public class Dog : UnionValue
{
}

Declare the Union member passing the possible value types:

Union<Dog, Bird> animal = new Dog();

And access it checking for the type with If, Switch/Case or Pattern Matching:

if (animal.Value is Dog)
{
    Console.WriteLine($"Dog: {animal.Value}");
}
else
...

Accessing the object without checking will yield an error DUN002 - 'animal.Value' not checked before access:

Not checking for all possible types will yield an error DUN001 - 'animal' not being evaluated for all possible types:

⚠️ This package was made for study purposes only. Feel free to test it, but won't use it for production code as it won't be maintained and may not cover all edge cases.

DiscriminatedUnions.NET Source Code

https://github.com/dgenezini/DiscriminatedUnions.NET

Lessons learned

Development-time only nuget packages

Roslyn analyzers can be distributed as nuget packages, but it is important to generate the package as a Development Dependency only, setting the property DevelopmentDependency as true on the csproj file:

<DevelopmentDependency>true</DevelopmentDependency>

This will generate two tags in the nuget package properties of the consumer projects:

<PackageReference Include="DiscriminatedUnions.Net.Analyzers" Version="1.0.0.1">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

PrivateAssets with the value all, indicating that this package won't flow to projects depending on the consumer project. For example, in a scenario where Project1 depends on the DiscriminatedUnions.Net.Analyzers package and Project2 depends on Project1, the analyzer won't be available for Project2;
IncludeAssets without the compile value in its value, indicating the consumer of the package won't have access to its compiled assemblies.

Roslyn Analyzers can be used to enforce rules on how to use a package

A great use case for Roslyn Analyzers is to enforce rules on nuget packages.

The DistributedUnion.Net package is one example. It has the Union and UnionValue types and analyzers to enforce the rules on its use.

Because classes inside Analyzers packages are not accessible by consumers (and shouldn't be), the most correct way, in my opinion, is to have the public classes in one package and this package will consume another package with the analyzers, but removing the PrivateAssets configuration. This way, the analyzers will be available for consumers of the parent package:

<PackageReference Include="DiscriminatedUnions.Net.Analyzers" Version="0.1.0.0-beta">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

Analyzers have to evolve together with the language

Because analyzers use the code syntax, as new ways of doing something are added to the language, analyzers have to be updated to treat them also. For example:

An analyzer checking for conditions before pattern matching was release, would need to be updated to consider this new syntax;
An analyzer using types for its rules, would need to be updated to consider nullable reference types in its logic.

TDD is your friend

The Roslyn Analyzers project template comes with a VSIX project that can be run to test the analyzers, but I couldn't get them to work and decided it wasn't worth the time.

Turns out the best and easiest way to run and experiment with the analyzer is by running automated tests. Create the test, run the test and change the analyzer until the test passes.

Example of an automated test that expects the error code DUN001 at the location 0 with the argument unionBird:

[TestMethod]
        public async Task Notify_If_NotCheckingAllCases_Many()
        {
            var test = @"
using DiscriminatedUnionsNet;

class Program
{
    static string GetValue()
    {
        Union<Duck, Goose, Eagle, Crow> unionBird = new Duck();

        if ({|#0:unionBird|}.Value is Goose)
        {
            return ""Goose"";
        }

        return null;
    }
}" + defineUnion;

            var expected = VerifyCS
                .Diagnostic("DUN001")
                .WithLocation(0)
                .WithArguments("unionBird");

            await VerifyCS.VerifyAnalyzerAsync(test, expected);
        }

The location and argument are marked with the {|#location:argument|} syntax.

ℹ️ The project template comes with some basic tests as examples that are easy to change.

Casts... Casts everywhere

The analyzers methods and properties define general interface types that need to be cast to the specific type before accessing its properties.

This is an excerpt from the DiscriminatedUnions.Net package:

var namedType = (INamedTypeSymbol)typeInfo.Type; //typeInfo.Type is ITypeSymbol

if ((!namedType.Name.Equals("UnionValue")) ||
    (!namedType.ContainingNamespace.Name.Equals("DiscriminatedUnionsNet")))
{
    return;
}

...

if (parent is ISwitchOperation switchOperation) //parent is IOperation
{
    if (!(switchOperation.Value is IPropertyReferenceOperation propertyReferenceOperation) || //switchOperation.Value is IOperation
        !(propertyReferenceOperation.Instance is ILocalReferenceOperation parentReferenceOperation))
    {
        parent = parent.Parent;

        continue;
    }
    ...
}
else if (parent is ISwitchExpressionOperation switchExpressionOperation) //parent is IOperation
{
    ...
}

Understanding the syntax tree and finding the correct interfaces

The easiest way to understand the syntax tree is by using the Visual Studio's Syntax Visualizer (Installation instructions).

Just click anywhere in the code and it will show the syntax tree up to that point:

Another tip is to type ISymbol, IOperation, or any base interface to see all the specific interfaces in the intellisense:

Not many material to help beginners

Because Roslyn Analyzers have very specific use cases, there is not a lot of materials and documentation online. Here are some links that helped me learn (specially Josh Varty's and Meziantou's Blog):

Josh Varty's Blog - Learn Roslyn Now series

Meziantou's Blog - Writing a Roslyn analyzer series

Roslyn docs - How to start

Roslyn GitHub docs - How to write a C# Analyzer and Code Fix

Roslyn GitHub docs - Analyzer Actions Semantics

Compile-time null safety: How to avoid NullReferenceException in C#

Catching null errors at compile time

blog.genezini.com

Liked this post?

I post extra content in my personal blog. Click here to see.

Follow me

Building a Who's that Pokémon game for Android with .NET MAUI and Blazor Hybrid

Daniel Genezini — Wed, 12 Jul 2023 11:25:18 +0000

Introduction

Blazor was initially developed to build interactive web applications using C#, but can now be used in many platforms when used together with .NET MAUI.

In this post, I'll show how to use Blazor Hybrid to develop a Who's that Pokémon game for Android.

What is MAUI?

MAUI (Multi-platform App UI) is a cross-platform framework to create native mobile apps and desktop apps with .NET.

Using MAUI, we can create apps that run on multiple platforms (Windows, MacOS, Android and iOS) with the same codebase (and some specific code for each platform, if necessary).

What is Blazor Hybrid?

Blazor Hybrid allows us to run Blazor components natively in mobile and desktop apps using a Web View with full access to the devices capabilities. There is no need for a server to render the components and WebAssembly isn't involved.

Installing MAUI

MAUI doesn't come with Visual Studio or the .NET SDK by default. We need to install its workload manually using the dotnet workload install command:

dotnet workload install maui

ℹ️ The installation process may take some time to complete.

After installing, the MAUI templates will show in Visual Studio. We'll use the .NET MAUI Blazor Hybrid App.

The components

The app is composed mainly of the four components marked in the image and described below.

WhosThatPokemon: Renders the other components + logic to select a random pokemon and check if Pokémon selected by the user is correct;
WhosThatPokemonData: Renders the Pokémon image and name;
PokemonSelector: Component to search and select a Pokémon;
WhosThatPokemonResult: Show if the selected Pokémon was the right one.

Creating a service to store the Pokémon information

First, I created a service to get the list of Pokémon from a public API (PokéAPI) using Refit and cache it locally to be used by any component. This information is static, so there is no need to go to the API every time.

using BlazorHybridApp.Components.Domain;
using BlazorHybridApp.Components.Interfaces.APIEndpoints;
using Microsoft.Extensions.Configuration;
using Refit;

namespace BlazorHybridApp.Components.Services;

public class PokemonDataService
{
    private List<PokemonInfo>? _pokemonList;
    private readonly IPokeApi _pokeApi;

    public PokemonDataService(IConfiguration configuration)
    {
        _pokeApi ??= RestService.For<IPokeApi>(configuration!["PokeApiBaseUrl"]!);
    }

    public async Task<List<PokemonInfo>> GetPokemonListAsync()
    {
        if (_pokemonList == null)
        {
            var species = await _pokeApi.GetAllPokemonSpecies();

            _pokemonList = species.Results
                .Select(pokemonSpecie => new PokemonInfo()
                {
                    Id = GetPokemonIdFromUrl(pokemonSpecie.Url),
                    Name = pokemonSpecie.Name.ToUpperInvariant()
                })
                .ToList();
        }

        return _pokemonList;
    }

    public async Task<PokemonInfo> GetPokemonByIdAsync(int id)
    {
        _pokemonList ??= await GetPokemonListAsync();

        return _pokemonList.Single(a => a.Id == id);
    }

    public async Task<int> GetPokemonCountAsync()
    {
        _pokemonList ??= await GetPokemonListAsync();

        return _pokemonList.Count;
    }

    private static int GetPokemonIdFromUrl(string url)
    {
        return int.Parse(new Uri(url).Segments.LastOrDefault()?.Trim('/') ?? "0");
    }
}

And added it as a singleton in the dependency injection container:

builder.Services.AddSingleton<PokemonDataService>();

Installing MudBlazor components

The app uses the MudBlazor library, a free open-source component library for Blazor build entirely with C# (not Javascript wrapped components). The list of components and how to use them can be seen here.

Instructions on how to install may change for newer versions, so I'll link the official docs.

Configuring the app layout

The Blazor Hybrid app template comes with a MAUI app rendering an Index.razor component page.

Let's edit it to render the WhosThatPokemon component we'll create:

@page "/"

<WhosThatPokemon></WhosThatPokemon>

Then, let's modify the MainLayout.razor removing the menu:

@inherits LayoutComponentBase

<MudThemeProvider />

<div class="page">
    <main>
        @Body
    </main>
</div>

And add some customizations in the app.css:

body {
    overflow-y: scroll;
    background-color: red;
}
...

Creating the components

Now, let's create the components in a Components folder.

WhosThatPokemonData

WhosThatPokemonData.razor

Here we check the Show variable to decide if we should show the pokemon image and name.

<div class="container">
    @if (!Show)
    {
        <div>
            <img src="https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/@(PokemonId).png"
                 class="pokemon-image pokemon-image-hidden" />
        </div>
        <div class="pokemon-name">
            <p>?????</p>
        </div>
    }
    else
    {
        <div>
            <img src="https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/@(PokemonId).png"
                 class="pokemon-image" />
        </div>
        <div class="pokemon-name">
            <p>@PokemonName (#@PokemonId)</p>
        </div>
    }
</div>

WhosThatPokemonData.razor.css

Here we have the "magic" to hide the Pokémon image using filter: brightness(0).

.container {
    font-family: Verdana;
    color: black;
}

.pokemon-image {
    width: 200px;
    height: 200px;
    filter: drop-shadow(2px 4px 6px black);
    margin: auto;
    display: block;
}

.pokemon-image-hidden {
    filter: brightness(0) drop-shadow(2px 4px 6px black)
}

.pokemon-name {
    font-size: large;
}

WhosThatPokemonData.razor.cs

No logic, just parameters used to render the component.

using Microsoft.AspNetCore.Components;

namespace BlazorHybridApp.Components;

public partial class WhosThatPokemonData
{
    [Parameter]
    public int PokemonId { get; init; }
    [Parameter]
    public required string PokemonName { get; init; }
    [Parameter]
    public bool Show { get; init; }
}

PokemonSelector

PokemonSelector.razor

I used the MudAutocomplete component from MudBlazor. The value selected is binded to the SelectedPokemon property.

@using BlazorHybridApp.Components.Domain;

<div class="container">
    @if (_pokemon == null)
    {
        <MudSkeleton SkeletonType="SkeletonType.Rectangle" Width="100%" Height="30px" />
    }
    else
    {
        <MudAutocomplete @ref="_selectedPokemon"
                         T="PokemonInfo" @bind-Value="SelectedPokemon"
                         ResetValueOnEmptyText="true"
                         Label="Who's that pokémon?"
                         ToStringFunc="@(e => e?.Name)"
                         SearchFunc="@Search" />
    }
</div>

PokemonSelector.razor.cs

using BlazorHybridApp.Components.Domain;
using BlazorHybridApp.Components.Services;
using Microsoft.AspNetCore.Components;
using MudBlazor;

namespace BlazorHybridApp.Components;

public partial class PokemonSelector
{
    [Inject]
    private PokemonDataService PokemonDataService { get; init; } = default!;

    private MudAutocomplete<PokemonInfo> _selectedPokemon = default!;
    private List<PokemonInfo>? _pokemon;

    public PokemonInfo? SelectedPokemon { get; set; }

    public void Clear()
    {
        _selectedPokemon.Clear();
    }

    protected override async Task OnInitializedAsync()
    {
        await GetPokemonListAsync();
    }

    private Task<IEnumerable<PokemonInfo>?> Search(string value)
    {
        // if text is null or empty, show complete list
        if (string.IsNullOrEmpty(value))
            return Task.FromResult(_pokemon?.Take(10));

        return Task.FromResult(_pokemon?
            .Where(pokemon => pokemon.Name.Contains(value, StringComparison.InvariantCultureIgnoreCase))
            .Take(10));
    }

    protected async Task GetPokemonListAsync()
    {
        _pokemon = await PokemonDataService.GetPokemonListAsync();
    }
}

WhosThatPokemonResult

WhosThatPokemonResult.razor

Nothing fancy here, this component just shows the result after selecting a Pokémon.

<div class="container">
    @if (Show)
    {
        @if (Correct)
        {
            <div class="game-result-correct">
                That's right!
            </div>
        }
        else
        {
            <div class="game-result-wrong">
                Sorry, it's not
            </div>
        }
    }
</div>

WhosThatPokemonResult.razor.cs

using Microsoft.AspNetCore.Components;

namespace BlazorHybridApp.Components;

public partial class WhosThatPokemonResult
{
    [Parameter]
    public bool Show { get; init; }
    [Parameter]
    public bool Correct { get; init; }
}

WhosThatPokemon

WhosThatPokemon.razor

This component uses all the other components, orchestrating their parameter values and events:

<div class="container">
    @if (_loading)
    {
        <Loader></Loader>
    }
    else
    {
        <div class="title">
            Who's that Pokémon?!
        </div>

        <WhosThatPokemonData PokemonId="_pokemonData.Id" PokemonName="@_pokemonData.Name" Show="_showResult"></WhosThatPokemonData>

        <PokemonSelector @ref="_pokemonSelector"></PokemonSelector>

        <MudButton @onclick="Confirm" class="confirm-button"
                   Variant="Variant.Filled">Confirm</MudButton>

        <WhosThatPokemonResult Correct="_correct" Show="_showResult"></WhosThatPokemonResult>

        <MudButton class="confirm-button" Variant="Variant.Filled" @onclick="ShowNextAsync">Show Next</MudButton>
    }
</div>

WhosThatPokemon.razor.css

Here we have to use ::deep to set the css properties for the MudButton. This is necessary because Blazor CSS isolation only works for elements directly below its component hierarchy in the DOM.

.container {
    border-radius: 3px;
    background-color: rgba(255, 255, 255, 0.9);
    margin: 15px;
    padding: 10px;
    text-align: center;
    max-width: 280px;
    margin-left: auto;
    margin-right: auto;
    height: calc(100vh - 30px);
}

::deep button.confirm-button {
    margin-top: 10px;
    background-color: red;
    color: white;
    margin: 5px;
}

.title {
    font-size: large;
}

WhosThatPokemon.razor.cs

In the OnInitializedAsync and ShowNextAsync method, we select a random Pokémon that is passed to the other components.

In the Confirm method, we check if the Pokémon selected is the right one and pass the result to the WhosThatPokemonResult component.

using BlazorHybridApp.Components.Domain;
using BlazorHybridApp.Components.Services;
using Microsoft.AspNetCore.Components;

namespace BlazorHybridApp.Components;

public partial class WhosThatPokemon
{
    [Inject]
    private PokemonDataService PokemonDataService { get; init; } = default!;

    private PokemonInfo _pokemonData = default!;
    private PokemonSelector _pokemonSelector = default!;
    private bool _correct;
    private bool _showResult;
    private bool _loading;

    protected override async Task OnInitializedAsync()
    {
        _pokemonData = await GetRandomPokemon();
    }

    private async Task<PokemonInfo> GetRandomPokemon()
    {
        try
        {
            _loading = true;

            var pokemonCount = await PokemonDataService.GetPokemonCountAsync();

            Random r = new Random();
            var pokemonId = r.Next(1, pokemonCount);

            return await PokemonDataService.GetPokemonByIdAsync(pokemonId);
        }
        finally
        {
            _loading = false;
        }
    }

    protected void Confirm()
    {
        _correct = _pokemonSelector?.SelectedPokemon?.Id == _pokemonData?.Id;

        _showResult = true;
    }

    protected async Task ShowNextAsync()
    {
        _showResult = false;
        _pokemonSelector.Clear();

        _pokemonData = await GetRandomPokemon();
    }    
}

Other customizations

Status bar color

To change the status bar color for the app, we have to create a style tag and define the android:statusBarColor and android:navigationBarColor elements in the Platforms/Android/Resources/values/colors.xml file:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="colorPrimary">#FF0000</color>
    <color name="colorPrimaryDark">#DD0000</color>
    <color name="colorAccent">#BB0000</color>

    <style name="MainTheme" parent="@style/Maui.SplashTheme">
        <item name="android:statusBarColor">#FF0000</item>
        <item name="android:navigationBarColor">#FF0000</item>
    </style>
</resources>

Then, set the Theme property of the Activity attribute to the style name (@style/MainTheme, in this example) in the MainActivity.cs file:

[Activity(Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity
{
}

Running the app

Since MAUI applications run on multiple platforms, we can run the app on Windows to debug or do quicker tests. Just select Windows Machine from the Run menu:

💡 I recommend using an Android physical device when running/debugging on Android, as it is many times faster than running on an emulator. Just connect the device to the computer using an USB cable and the ADB drivers installed, and it will show up in the Run menu:

Full source code

GitHub repository

Real-time charts with Blazor, SignalR and ApexCharts

Streaming currency prices with SignalR

blog.genezini.com

Liked this post?

I post extra content in my personal blog. Click here to see.

Follow me

References and Links

Easier Git rebase of messy branches

Daniel Genezini — Tue, 25 Apr 2023 09:00:00 +0000

Introduction

Even when working with short lived branches, repositories with constant changes can cause lots of conflicts and result in outdated branches hard to rebase.

In this post, I'll show a way to rebase those branches with much less effort.

Messy rebase branches

In this example, trying to rebase branch-to-rebase on origin/main will yield conflicts:

> git rebase origin/main

Auto-merging SomeFile.cs

CONFLICT (content): Merge conflict in SomeFile.cs
error: could not apply 57511bd... Change SomeFile
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".

hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 57511bd... Change SomeFile

If we run git status, we can can see the conflict is in the first of 16 commits:

> git status

interactive rebase in progress; onto 066147e

Last command done (1 command done):

   pick 57511bd Change SomeFile

Next commands to do (16 remaining commands):

   pick 2fcd87b Other Commit

   pick 7ffc7f5 Change other file

  (use "git rebase --edit-todo" to view and edit)

You are currently rebasing branch 'branch-to-rebase' on '066147e'.

  (fix conflicts and then run "git rebase --continue")

  (use "git rebase --skip" to skip this patch)

  (use "git rebase --abort" to check out the original branch)

This may be a conflict only in the first commit, but in general, these conflicts occur in most of the commits, and rebase will ask you to resolve them for each of the commits, which is impractical.

How to easily rebase messy branches

First, we checkout the branch we want to rebase and fetch all branches:

> git checkout branch-to-rebase

> git fetch --all

Then, we have to identify the last commit prior to the changes in the branch.

To find it, we use the merge-base command, passing the branch we will rebase (branch-to-rebase) and the branch to rebase onto (origin/main):

> git merge-base branch-to-rebase origin/main

With the commit in hand, we do a git reset to that commit. This will set the branch index to be equal to the commit's index:

> git reset f9fb326cb6cd58e0f31b433389b4a76f60319db1

Unstaged changes after reset:
M       SomeFile.cs
...

This means all the differences from the branch to the commit will be unstaged.

Now, we can stash the changes and rebase the branch. This will yield no conflicts, because there is no changes in the branch (all changes will be in the stash):

> git stash

Saved working directory and index state WIP on branch-to-rebase: d8dd56f ...

> git rebase origin/main

Successfully rebased and updated refs/heads/branch-to-rebase

⚠️ Instead of a rebase, we can create a new branch to keep the branch-to-rebase as a backup.

This can be achieved using git checkout -b clean-branch origin/main instead of git rebase origin/main.

The next step is to pop the changes from the stash and resolve the conflicts, but now we just need to resolve the conflicts one time (from our stashed changes to origin/main)

git stash pop

# Resolve conflicts

Finally, just commit and push the branch to the remote repository.

git commit

git push --force

ℹ️ A bonus benefit is that this will have the effect of a squash rebase, because it will produce just one commit.

Git Alias

In this post, I explained how useful Git aliases are.

To make these workflow for rebase easier, I've created two aliases:

1 - git mb

This alias gets the name of the checked in branch and passes it to merge-base.

Usage:

> git mb origin/main

f2732648ef5b6804a63d44f1b498f19ddf01eeb6

Configuration:

mb = "!f() { git branch --show-current | xargs git merge-base $1; }; f"

2 - git reset-base

This alias gets the common base for the branch and the rebase target branch using the mb alias defined above and passes it to reset.

Usage:

> git reset-to-base origin/main

Successfully rebased and updated refs/heads/branch-to-rebase

Configuration:

reset-to-base = "!f() { git mb $1 | xargs git reset; }; f"

Liked this post?

I post extra content in my personal blog. Click here to see.

Follow me

References and Links

Why my WireMock mocks aren't working?

Daniel Genezini — Wed, 12 Apr 2023 09:10:30 +0000

Introduction

WireMock.Net is a great tool to remove external dependencies when writing integration tests, but because it is highly configurable, it can be hard to find why its mocks aren’t working.

In this post, I’ll explain how to troubleshoot problems in its configuration and show some common problems that happen in my day-to-day work.

What is WireMock.Net?

WireMock.Net is a library for stubbing and mocking HTTP APIs. I wrote about how and why to use it previously, and will use the previous post examples in this one.

WireMock.Net's Admin API

WireMock.Net has an Admin API that is essential for debugging problems in our mocks.

The API offers many endpoints, but I'll show the two that will be used to find problems in the mocks.

ℹ️ The complete list of endpoints can be seen in the WireMock.Net's documentation.

Mappings endpoint

The endpoint /__admin/mappings returns the mappings configured for the mocks, including all the matchers that need to be fulfilled for the mock to respond, and the response that will be returned.

Here is an example of the return:

[
  {
    "Guid": "4dbbabf7-aac9-4f31-9fb9-a02360a454ea",
    "Request": {
      "Path": {
        "Matchers": [
          {
            "Name": "WildcardMatcher",
            "Pattern": "/pokemon/charmander",
            "IgnoreCase": false
          }
        ]
      },
      "Methods": [
        "GET"
      ]
    },
    "Response": {
      "StatusCode": 200,
      "BodyDestination": "SameAsSource",
      "Body": "{\"abilities\":[{\"ability\":{\"name\":\"name8f22045d-c183-4f1c-a32d-aaa6d337a9b7\",\"url\":\"url768c48e4-0dec-4952-b810-06472f602b4d\"},\"is_hidden\":true,\"slot\":192},
      ...
      \"url\":\"url716f6971-abd8-4e35-a9af-b7bd7a9a9cd6\"}}],\"weight\":128}",
      "Headers": {
        "Content-Type": "application/json"
      }
    },
    "UseWebhooksFireAndForget": false
  }
]

Requests endpoint

The endpoint /__admin/requests returns the history of requests made to WireMock. It includes information about the request made and the response received by the requester.

It also includes the PartialRequestMatchResult property, that shows which matcher was successful and which was not.

Here is an example of a request that reached the mock:

[
  {
    "Guid": "d2759bea-e4cc-442b-a63c-506ac6d61527",
    "Request": {
      "ClientIP": "::1",
      "DateTime": "2023-04-09T21:23:52.2879698Z",
      "Path": "/pokemon/charmander",
      "AbsolutePath": "/pokemon/charmander",
      "Url": "http://localhost:64378/pokemon/charmander",
      "AbsoluteUrl": "http://localhost:64378/pokemon/charmander",
      "Query": {},
      "Method": "GET",
      "Headers": {
        "Host": [
          "localhost:64378"
        ],
        "traceparent": [
          "00-fc2bc88c5bfc8b273e12d5a64cfd67cc-4ffca316becbeb2b-00"
        ]
      },
      "Cookies": {}
    },
    "Response": {
      "StatusCode": 200,
      "Headers": {
        "Content-Type": [
          "application/json"
        ]
      },
      "BodyDestination": "SameAsSource",
      "Body": "{\"abilities\":[{\"ability\":{\"name\":\"name8f22045d-c183-4f1c-a32d-aaa6d337a9b7\",\"url\":\"url768c48e4-0dec-4952-b810-06472f602b4d\"},\"is_hidden\":true,\"slot\":192},{\"ability\":{\"name\":\"name7e833a25-8050-4369-a5b9-811b4b00ee69\",
      ...
      \"url\":\"url716f6971-abd8-4e35-a9af-b7bd7a9a9cd6\"}}],\"weight\":128}",
      "BodyEncoding": {
        "CodePage": 65001,
        "EncodingName": "Unicode (UTF-8)",
        "WebName": "utf-8"
      },
      "DetectedBodyType": 1
    },
    "MappingGuid": "4dbbabf7-aac9-4f31-9fb9-a02360a454ea",
    "RequestMatchResult": {
      "TotalScore": 2.0,
      "TotalNumber": 2,
      "IsPerfectMatch": true,
      "AverageTotalScore": 1.0,
      "MatchDetails": [
        {
          "Name": "PathMatcher",
          "Score": 1.0
        },
        {
          "Name": "MethodMatcher",
          "Score": 1.0
        }
      ]
    },
    "PartialMappingGuid": "4dbbabf7-aac9-4f31-9fb9-a02360a454ea",
    "PartialRequestMatchResult": {
      "TotalScore": 2.0,
      "TotalNumber": 2,
      "IsPerfectMatch": true,
      "AverageTotalScore": 1.0,
      "MatchDetails": [
        {
          "Name": "PathMatcher",
          "Score": 1.0
        },
        {
          "Name": "MethodMatcher",
          "Score": 1.0
        }
      ]
    }
  }
]

The RequestMatchResult shows that the mock has 2 matchers configured (TotalNumber) and the total score was 2 (TotalScore). The MatchDetails also shows a score of 1.0 (100%) for all the matchers.

Here is an example of a request that didn't fulfill all of the matchers:

[
  {
    "Guid": "60812be4-2d28-436b-afe3-4597b57e1995",
    "Request": {
      "ClientIP": "::1",
      "DateTime": "2023-04-10T22:09:24.4115811Z",
      "Path": "/pokemon/squirtle",
      "AbsolutePath": "/pokemon/squirtle",
      "Url": "http://localhost:57546/pokemon/squirtle",
      "AbsoluteUrl": "http://localhost:57546/pokemon/squirtle",
      "Query": {},
      "Method": "GET",
      "Headers": {
        "Host": [
          "localhost:57546"
        ],
        "traceparent": [
          "00-f89a0136b596e297767aea9602ed6df2-3e4ef33765b915d1-00"
        ]
      },
      "Cookies": {}
    },
    "Response": {
      "StatusCode": 404,
      "Headers": {
        "Content-Type": [
          "application/json"
        ]
      },
      "BodyAsJson": {
        "Status": "No matching mapping found"
      },
      "DetectedBodyType": 2
    },
    "PartialMappingGuid": "bab89116-6318-4ecb-8460-39e5116aeaec",
    "PartialRequestMatchResult": {
      "TotalScore": 1.0,
      "TotalNumber": 2,
      "IsPerfectMatch": false,
      "AverageTotalScore": 0.5,
      "MatchDetails": [
        {
          "Name": "PathMatcher",
          "Score": 0.0
        },
        {
          "Name": "MethodMatcher",
          "Score": 1.0
        }
      ]
    }
  }
]

The PartialRequestMatchResult shows that the mock has 2 matchers configured (TotalNumber) and the total score was 1 (TotalScore). In the MatchDetails we can see that the problem was on the PathMatcher.

Looking in the mappings endpoint, we see that the path was configured to /pokemon/charmander, instead of the /pokemon/squirtle that was in the request.

Configuring the Admin Interface

To use the admin interface, we just need to start WireMock's server with the StartWithAdminInterface method instead of the Start method:

```csharp {linenos=false}
var wiremockServer = WireMockServer.StartWithAdminInterface();




Then, to be able to access the admin interface, we include a delay after the **Act** part of the test:



```csharp {linenos=false}
await Task.Delay(TimeSpan.FromMinutes(100));

Lastly, we access the endpoint using the URL returned by the Url property of the wireMockSvr object:

Full test code:

[Fact]
public async Task Get_Existing_Pokemon_Returns_200()
{
    //Arrange
    var wireMockSvr = WireMockServer.StartWithAdminInterface(); //Start WireMock with Admin Interface

    var Factory = _factory
        .WithWebHostBuilder(builder =>
        {
            builder.UseSetting("PokeApiBaseUrl", wireMockSvr.Url);
        });

    var HttpClient = Factory.CreateClient();

    Fixture fixture = new Fixture();

    var ResponseObj = fixture.Create<PokemonInfo>();
    var ResponseObjJson = JsonSerializer.Serialize(ResponseObj);

    wireMockSvr
        .Given(Request.Create()
            .WithPath("/pokemon/charmander")
            .UsingGet())
        .RespondWith(Response.Create()
            .WithBody(ResponseObjJson)
            .WithHeader("Content-Type", "application/json")
            .WithStatusCode(HttpStatusCode.OK));

    //Act
    var HttpResponse = await HttpClient.GetAsync("/pokemoninfo/charmander");

    await Task.Delay(TimeSpan.FromMinutes(30)); //Delay to be able to examine the admin interface

    //Assert
    HttpResponse.StatusCode.Should().Be(HttpStatusCode.OK);

    var ResponseJson = await HttpResponse.Content.ReadAsStringAsync();
    var PokemonInfo = JsonSerializer.Deserialize<PokemonInfo>(ResponseJson);

    PokemonInfo.Should().BeEquivalentTo(ResponseObj);

    wireMockSvr.Stop();
}

Common problems

Query string params

Let's take the endpoint /pokemon?type={typeName} as an example.

The mock below won't work:

WireMockSvr
    .Given(Request.Create()
        .WithPath("/pokemon?type=fire")
        .UsingGet())
    .RespondWith(Response.Create()
        .WithBody(ResponseObjJson)
        .WithHeader("Content-Type", "application/json")
        .WithStatusCode(HttpStatusCode.OK));

To create a mock for endpoints with query strings, we have to use the WithParam property:

WireMockSvr
    .Given(Request.Create()
        .WithPath("/pokemon")
        .WithParam("type", "fire")
        .UsingGet())
    .RespondWith(Response.Create()
        .WithBody(ResponseObjJson)
        .WithHeader("Content-Type", "application/json")
        .WithStatusCode(HttpStatusCode.OK));

Params in the route

Contrary to params in the query string, params in the path won't work when configured with WithParam. For example, the endpoint /pokemon/{pokemonName} won't be reached with:

WireMockSvr
    .Given(Request.Create()
        .WithPath("/pokemon")
        .WithParam("pokemonName", "charmander")
        .UsingGet())
    .RespondWith(Response.Create()
        .WithBody(ResponseObjJson)
        .WithHeader("Content-Type", "application/json")
        .WithStatusCode(HttpStatusCode.OK));

It has to be set in the WithPath method:

WireMockSvr
    .Given(Request.Create()
        .WithPath("/pokemon/charmander")
        .UsingGet())
    .RespondWith(Response.Create()
        .WithBody(ResponseObjJson)
        .WithHeader("Content-Type", "application/json")
        .WithStatusCode(HttpStatusCode.OK));

Running behind a network proxy

When running behind a network proxy, WireMock may be unreachable, causing a timeout in the application.

To ignore the proxy for localhost, we need to configure the no_proxy environment variable, adding localhost to its value (more values can be included, separated by comma):

Shared WireMock server for all tests

Sharing WireMock's server instance between tests can cause random problems because mock definitions are overridden when configured for the second time. For example, take two tests running in parallel:

Test 1 configures /pokemon/charmander to return status 200;
Test 2 configures /pokemon/charmander to return status 404.

The first test to configure the mock will break because its mock will be overridden and the result won't be as expected.

To avoid this random problems, we need to use one WireMock instance for each test:

[Fact]
public async Task Get_Existing_Pokemon_Returns_200()
{
    var WireMockSvr = WireMockServer.StartWithAdminInterface();

    ...

    WireMockSvr.Stop();
}

[Fact]
public async Task Get_NotExisting_Pokemon_Returns_404()
{
    var WireMockSvr = WireMockServer.StartWithAdminInterface();

    ...

    WireMockSvr.Stop();
}

References and Links

WireMock's Admin API Documentation

.NET and AWS S3 with LocalStack: How to develop with local S3 buckets

Daniel Genezini — Tue, 14 Feb 2023 09:19:50 +0000

Introduction

LocalStack is an open-source framework that allows us to emulate the major AWS services locally, making it easier to develop and test cloud applications without incurring the cost and complexity of deploying to a real cloud environment.

In this post, I'll show how to configure it to emulate S3 buckets and how to interact with those buckets from a C# application.

Running LocalStack

LocalStack can be run as a CLI or using a container. In this post, I'll explain how to run it in a container with docker run and docker-compose.

ℹ️ If you don't have docker or other container runtime installed, click here for Docker installation instructions or here for Podman installation instructions.

Container

To start a container with a LocalStack instance, run the following command:

docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 -e EXTRA_CORS_ALLOWED_ORIGINS=https://app.localstack.cloud. localstack/localstack:1.3.1

Note that it is exposing port 4566 and ports 4510 to 4559 and allowing CORS access from https://app.localstack.cloud. (to allow access from the LocalStack dashboard).

🚨 It's recommended to use a specific version instead of latest to avoid problems with new versions updated automatically.

Docker compose

Starting LocalStack from docker compose is just as easy. Just add the localstack service, as below, to a docker-compose.yaml file:

version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack
    ports:
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
      - "127.0.0.1:4510-4559:4510-4559"  # external services port range
    environment:
      - DEBUG=${DEBUG-}
      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR-}
      - DOCKER_HOST=unix:///var/run/docker.sock
      - EXTRA_CORS_ALLOWED_ORIGINS=https://app.localstack.cloud. # Enable access from the dashboard
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Then run the following command:

docker-compose up

🚨 It's recommended to use a specific version instead of latest to avoid problems with new versions updated automatically.

⚠️ I've added the environment variable EXTRA_CORS_ALLOWED_ORIGINS with the value https://app.localstack.cloud. to allow access from the LocalStack dashboard.

💡 The updated docker-compose.yaml file can be found here, in the LocalStack repo.

LocalStack Dashboard

LocalStack has a web-based dashboard that allows us to manage and configure its services and visualize its logs.

Access https://app.localstack.cloud. and it will connect to the LocalStack instance running locally.

It runs in the browser, so there is no need to expose any ports to the internet.

🚨 If the dashboard says "Please start LocalStack to check the System Status" and the container log shows Blocked CORS request from forbidden origin https://app.localstack.cloud., the EXTRA_CORS_ALLOWED_ORIGINS environment variable was not correctly set to https://app.localstack.cloud.. See here.

Interacting with LocalStack using the AWS CLI

We'll use the AWS CLI to interact with LocalStack. If you don't have the AWS CLI, look here for instructions on how to install it.

Configuring a profile for LocalStack

The AWS CLI requires credentials when running. LocalStack doesn't validate the credentials by default, so will create a profile with anything as access key and secret key just to make the CLI happy.

In a terminal, type aws configure --profile localstack;
For AWS Access Key ID [None]:, type anything;
For AWS Secret Access Key [None]:, type anything;
For Default region name [None]:, type the region you prefer (for example, us-east-1);
For Default output format [None]:, type json.

How to create a bucket using the AWS CLI

To create a S3 bucket in LocalStack, we'll use the aws s3 mb command (mb is short for Make Bucket).

The command below will create a bucket with the name local-bucket-name using the AWS CLI profile we previously created with the name localstack. It's important to pass the --endpoint parameter or else it will try to create the bucket in AWS.

aws s3 mb s3://local-bucket-name --endpoint http://localhost:4566 --profile localstack

Looking at LocalStack dashboard we can see the bucket was created:

How to list a bucket contents using the AWS CLI

To look the contents of a bucket, we can use the aws s3 ls command:

aws s3 ls s3://local-bucket-name --endpoint http://localhost:4566 --profile localstack

Or use the LocalStack dashboard:

Accessing LocalStack from .NET

To access an S3 bucket from LocalStack in .NET we use the same libraries we use to access it in AWS.

In this example, I'll use the AWSSDK.S3 and the AWSSDK.Extensions.NETCore.Setup NuGet packages, both from AWS.

How does the AmazonS3Client get AWS access data?

Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.AddAwsS3Service();

var app = builder.Build();

AwsExtensions.cs

public static class AwsExtensions
{
    public static void AddAwsS3Service(this WebApplicationBuilder builder)
    {
        if (builder.Configuration.GetSection("AWS") is null)
        {
            builder.Services.AddAWSService<IAmazonS3>();
        }
        else
        {
            builder.Services.AddSingleton<IAmazonS3>(sc =>
            {
                var awsS3Config = new AmazonS3Config
                {
                    RegionEndpoint = RegionEndpoint.GetBySystemName(builder.Configuration["AWS:Region"]),
                    ServiceURL = builder.Configuration["AWS:ServiceURL"],
                    ForcePathStyle = bool.Parse(builder.Configuration["AWS:ForcePathStyle"]!)
                };

                return new AmazonS3Client(awsS3Config);
            });
        }
    }
}

The appsettings.Development.json has the configurations pointing to the LocalStack instance:

appsettings.Development.json

{
  "BucketName": "local-bucket-name",

  "AWS": {
    "Region": "us-east-1",
    "ServiceURL": "http://localhost:4566",
    "ForcePathStyle": "true"
  }
}

⚠️ The ForcePathStyle forces the use of https://s3.amazonaws.com/<bucket-name>/<object-key> styled URLs instead of https://<bucket-name>.s3.amazonaws.com/<object-key> URLs.

The ForcePathStyle needs to be set to true for the AmazonS3Client to work with LocalStack.

Upload an image to the S3 Bucket

Using Minimal APIs, I created an endpoint that receives a file and saves it in the S3 bucket.

The code is straight forward:

Program.cs

app.MapPost("/upload", async (IAmazonS3 s3Client, IFormFile file) =>
{
    var bucketName = builder.Configuration["BucketName"]!;

    var bucketExists = await s3Client.DoesS3BucketExistAsync(bucketName);

    if (!bucketExists)
    {
        return Results.BadRequest($"Bucket {bucketName} does not exists.");
    }

    using var fileStream = file.OpenReadStream();

    var putObjectRequest = new PutObjectRequest()
    {
        BucketName = bucketName,
        Key = file.FileName,
        InputStream = fileStream
    };

    putObjectRequest.Metadata.Add("Content-Type", file.ContentType);

    var putResult = await s3Client.PutObjectAsync(putObjectRequest);

    return Results.Ok($"File {file.FileName} uploaded to S3 successfully!");
});

Now, we can test it from Postman:

Get an image from the S3 Bucket

I also created an endpoint that returns the file with the key passed by parameter from the S3 bucket:

app.MapGet("/object/{key}", async (IAmazonS3 s3Client, string key) =>
{
    var bucketName = builder.Configuration["BucketName"]!;

    var bucketExists = await s3Client.DoesS3BucketExistAsync(bucketName);

    if (!bucketExists)
    {
        return Results.BadRequest($"Bucket {bucketName} does not exists.");
    }

    try
    {
        var getObjectResponse = await s3Client.GetObjectAsync(bucketName,
            key);

        return Results.File(getObjectResponse.ResponseStream,
            getObjectResponse.Headers.ContentType);
    }
    catch (AmazonS3Exception ex) when (ex.ErrorCode.Equals("NotFound", StringComparison.OrdinalIgnoreCase))
    {
        return Results.NotFound();
    }
});

Testing from Postman, we can see the image previously uploaded:

Full source code

GitHub repository

Liked this post?

I post extra content in my personal blog. Click here to see.

Follow me

References and Links

How to use C# 11 features in .NET 6 or older versions (even .NET Framework 2.0)

Daniel Genezini — Mon, 06 Feb 2023 23:16:48 +0000

Introduction

At each release, C# adds features that help us make our codes cleaner, more readable and more maintainable. The problem is that, because some features are dependent of runtime implementations, C# versions are generally tied to .NET runtime versions. For example, C# 11 is enabled only in .NET 7 and above.

In this post, I'll show how to use C# 11 in older runtime version (even .NET Framework 2.0).

Why not upgrade the .NET version?

Upgrading to the newest .NET version is the best option. Not only we benefit from new C# features, but also from performance and security improvements.

But there are some scenarios where upgrading is not an option because of compatibility or because the cost of upgrading would be too high.

Some examples are:

AWS Lambda Functions running on .NET 6 (AWS Lambda doesn't support .NET 7 at the time of this post);
Plugins or extensions for proprietary software, such as Dynamics/Dataverse plugins that are not compatible with .NET Core
Legacy systems with a large codebase that still receive frequent updates.

What C# 11 features can be used?

C# features are divided in features that require runtime support and features that are just syntactic sugar.

Features that require runtime support cannot be used in older .NET versions, but most of the features that are syntactic sugar are compiled to IL (.NET Intermediate Language) and interpreted by older .NET versions at runtime (Even .NET Framework 2.0), depending only on an updated version of Roslyn (the .NET compiler) to work.

How to use C# 11 features in .NET 6 and previous versions

Some features will work just by having the .NET 7 SDK installed and adding (or updating) the LangVersion tag to 11 in the csproj file.

<LangVersion>11</LangVersion>

Examples

Here are some examples of the most useful features of latest versions of C# (not only C# 11).

Top-level statements

No need to static void Main:

using System;

Console.WriteLine("Hello World");

Console.ReadKey();

Nullable reference types

This is a working example of nullable reference types and top-level statements in .NET Framework 2.0:

#nullable enable

using System;

string? nullHere = null;

Console.WriteLine($"Length: {nullHere?.Length}");

Console.ReadKey();

💡 We can even treat warnings as errors, as I explained in this post.

ℹ️ If the project doesn't use the new csproj format, the <Nullable>enable</Nullable> won't be interpreted and the use of the #nullable enable directive at the start of each file is required.

⚠️ One caveat of using nullable types in older .NET versions is that framework functions won't inform us if they return nullable reference types because these changes were implemented only in the newer .NET versions.

EDIT: A reader reached me about this cool package that partially solves this problem by injecting nullable reference type annotations in CLR's methods of some assemblies (check the docs for more details): ReferenceAssemblyAnnotator.

Pattern Matching

Pattern matching also works in .NET Framework 2.0:

using System;

Console.WriteLine($"Enter the water temperature in Fahrenheit:");

var isNumber = int.TryParse(Console.ReadLine(), out var number);

string GetWaterState(int tempInFahrenheit) =>
    tempInFahrenheit switch
    {
        (> 32) and (< 212) => "liquid",
        < 32 => "solid",
        > 212 => "gas",
        32 => "solid/liquid transition",
        212 => "liquid / gas transition"
    };

if (isNumber)
{
    var waterState = GetWaterState(number);

    Console.WriteLine(waterState);
}
else
{
    Console.WriteLine("Invalid number");
}

Console.ReadKey();

⚠️ List pattern matching won't work just by changing the LangVersion tag. It needs specific types that I'll explain in the next section.

Features that need specific types

Even for features that are syntactic sugar, some depend on types and attributes implemented in the newer CLRs (for instance, the list pattern matching and the required keyword).

If we copy those types from the CLR source code or reference them from NuGet packages, the compilation will succeed and the features will be available.

But there is a better alternative...

Enter PolySharp

PolySharp is a NuGet package created by Sergio Pedri, Software Engineer at Microsoft, that generates polyfills for those types at compile time, only for the features being used in the code and that are not present in the targeted runtime.

Features enabled by PolySharp

This is a shortened list of some C# features enabled by PolySharp:

Nullability attributes
Index and Range
List pattern matching
Required members
Init-only properties
[CallerArgumentExpression]
[StringSyntax]

To install it, just add its NuGet package:

Install-Package PolySharp

⚠️ Because PolySharp uses source generators, it doesn't work with the package.config file as stated in this issue. The issue says we need to use the SDK style .csproj, but just changing from package.config to Package Reference worked for me.

On Visual Studio, click with the right mouse button in References and select Migrate package.config to Package Reference, confirm the changes and we are done:

Required keyword, init-only properties and records

Here is an example of a .NET Framework 4.7.2 application using the the required keyword, init-only properties and records:

#nullable enable

using System;

var person = new Person() { FirstName= "Sherlock", LastName = "Holmes" };

var address = new Address("Baker Street 221b", "London");

Console.WriteLine($"Person: {person.FirstName} {person.LastName}");
Console.WriteLine($"Address: {address}");

Console.ReadKey();

record Address (string StreetName, string City);

class Person
{
    public required string FirstName { get; init; }
    public required string LastName { get; init; }
}

If we inspect the RequiredMemberAttribute and IsExternalInit, we can see they were generated by PolySharp:

⚠️ Record types require .NET Framework 4 or superior runtimes.

Source code of the examples

https://github.com/dgenezini/CSharpNewestFeatures

Liked this post?

I post extra content in my personal blog. Click here to see.

Follow me

References and Links

Improve your coding experience: More 10 VS Code extensions to try

Daniel Genezini — Mon, 23 Jan 2023 05:00:00 +0000

Introduction

One of the reasons VS Code is so popular is because of its extensibility. It allows us to install extentions that can do basicaly anything and improve our productivity and workflow.

In this post, I'll increase the list of extensions from my previous post and show more 10 extensions that are worth trying.

1 - Project Dashboard

Project Dashboard is an alternative to the Project Manager extension that I added to the previous list. It allows us to save and organize our projects, grouping and adding color to them, in a centralized panel.

Download

2 - Polyglot Notebooks

Polyglot Notebooks is an extension that lets us create notebooks for different languages inside VS Code. We can also use many languages in the same notebook file. It's really good to run code to try something without having to create a console app, for example.

Download

3 - Luna Paint

Luna Paint lets us edit images inside VS Code. It is still in preview and I find it a little slow, but it may help with some basic image edits.

Download

4 - Nuget Gallery

Nuget Gallery is a nuget package manager for .NET projects, kind of like the Manage Nuget Packages feature of Visual Studio, but lighter.

Download

5 - Markmap

Markmap generates mindmaps from markdown files (headers and lists become elements in the mindmap). It helps to visualize and organize the ideas of long and complex posts.

Download

6 - Random Everything

This extension generates random data of various types (Country names, Hex colors, Dates, etc). Just open the command pallete and select Random: Type of data to generate the data.

💡 Tip 1: Use the alt key to put the cursor in more than one position and generate more than one item at a time like in the image below.

💡 Tip 2: To generate data for a CSV file, start generating the data from right to left.

Download

7 - Resource Monitor

Just shows the system resources information (CPU, Free memory and batery status) in the VS Code status bar.

Download

8 - Rainbow CSV

This extension helps us visualize CSV files, highlighting every column with a different color.

Download

9 - Diff Folders

Diff Folders is an alternative to the Compare Folders extension from my previous list. I use both, but this is better for comparing folders that are not in the same parent directory because it doesn't require us to open then before comparing.

Download

10 - Web Accessibility Extension

Web Accessibility is hard. This extension helps showing warning about basic accessibility problems in the HTML.

Download

Liked this post?

I post extra content in my personal blog. Click here to see.

Follow me

How to run disposable databases for your tests. Improve your integration tests accuracy with Testcontainers

Daniel Genezini — Mon, 09 Jan 2023 16:03:11 +0000

Introduction

Integration tests are essential to ensure that the different components of our system work together as expected and continue to work after changes.

In this post, I'll explain how to spin up disposable database containers to use in integration tests.

Integration tests and managed resources

As explained in this article, in integration tests, we should mock unmanaged dependencies (dependencies that are external to our system and not controlled by us, like APIs) but test against real managed dependencies (dependencies that are controlled by our system, like databases). This improves the reliability of the integration tests because the communication with these dependencies are a complex part of the system and can break with a package update, a database update or even a simple change in a SQL command.

What is Testcontainers?

Testcontainers is a that provides lightweight, throwaway instances of databases, selenium web browsers, or anything that can run in a container. These instances can be especially useful for testing applications against real dependencies, like databases, that can be created and disposed of after the tests.

Why not run the containers manually?

One key benefit of using Testcontainers instead of running the containers manually is that we can make use of libraries such as AutoFixture to generate data to seed the database instead of running scripts to insert the data. This also helps in avoiding collision between data used in different tests because the data is random.

Also, there are other advantages in usings Testcontainers:

To run the tests locally, you don't need any extra steps, like running a docker-compose command;
You don't have to wait or implement a waiting strategy to check if the containers are running before accessing them. Testcontainers already implements this logic;
Testcontainers have properties to access the port in which the container is running, so you don't need to specify a fixed port, avoiding port conflict when running in the CI/CD pipeline or other machines;
Testcontainers stops and deletes the containers automatically after running, free resources on the machine.

Running a disposable container with Testcontainers

To use Testcontainers, you will need to have a container runtime (Docker, Podman, Rancher, etc) installed on your machine.

Then, you need to add the Testcontainers NuGet package to your test project:

dotnet add package Testcontainers

To run a container, we first need to use the TestcontainersBuilder<T> class to build a TestcontainersContainer or a derived class, for instance, MySqlTestcontainer:

await using var mySqlTestcontainer = new TestcontainersBuilder<MySqlTestcontainer>()
    .WithDatabase(new MySqlTestcontainerConfiguration
    {
        Password = "Test1234",
        Database = "TestDB"
    })
    .Build();

Then, we start the container and use the ConnectionString property where needed:

await using var mySqlTestcontainer = new TestcontainersBuilder<MySqlTestcontainer>()
    .WithDatabase(new MySqlTestcontainerConfiguration
    {
        Password = "Test1234",
        Database = "TestDB"
    })
    .Build();

await mySqlTestcontainer.StartAsync();

await using var todoContext = TodoContext
    .CreateFromConnectionString(mySqlTestcontainer.ConnectionString);

❗ TestcontainersContainer implements IAsyncDisposable and needs to be disposed of after use. We can use the await using syntax or call the DisposeAsync method.

Testcontainers have classes for many different databases (called modules), for example:

Elasticsearch;
MariaDB;
Microsoft SQL Server;
MySQL;
Redis.

The full list can be seen here.

But we can also create containers from any image, as in the example below, where it creates a Memcached instance:

await using var MemCachedTestcontainer = new TestcontainersBuilder<TestcontainersContainer>()
    .WithImage("memcached:1.6.17")
    .Build();

await mySqlTestcontainer.StartAsync();

More details in the official documentation.

Creating integration tests with Testcontainers

In this example, I'm using the xUnit and the WebApplicationFactory<T> class from ASP.NET Core.

If you don't know how to use the WebApplicationFactory<T> class, I explained in this post.

In this example, I have a controller with a GET method that returns a ToDo item and a POST method that add a ToDo item:

[ApiController]
[Route("[controller]")]
public class TodoController : ControllerBase
{
    private readonly TodoContext _todoContext;

    public TodoController(TodoContext todoContext)
    {
        _todoContext = todoContext;
    }

    [HttpGet("{itemId}", Name = "GetTodoItem")]
    public async Task<ActionResult<TodoItem?>> GetByIdAsync(int itemId)
    {
        var item = await _todoContext.TodoItems.SingleOrDefaultAsync(a => a.ItemId == itemId);

        if (item is null)
        {
            return NotFound();
        }

        return Ok(item);
    }

    [HttpPost]
    public async Task<ActionResult<int>> PostAsync(TodoItem todoItem)
    {
        _todoContext.Add(todoItem);

        await _todoContext.SaveChangesAsync();

        return CreatedAtRoute("GetTodoItem", new { itemId = todoItem.ItemId }, todoItem);
    }
}

⚠️ The business logic is in the controller just for the sake of simplicity. In a real-world application, the logic should be in another layer.

Testing the GET method

The test does the following actions:

Create and start a MySql container;
Create a Entity Framework DbContext using the ConnectionString from the MySql in the container;
Create the database tables using Entity Framework; (Can also be done passing a script to the ExecScriptAsync method from the mySqlTestcontainer object);
Create a random object with AutoFixture and add it to the database table;
Override our application configuration with the connection string from the container;
Create an HttpClient pointing to our application;
Make a request to the GET endpoint passing the Id of the random object we added to the database;
Validate that the Status Code is 200 and the object returned is the same we added to the database.

public class TodoIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;

    public TodoIntegrationTests(WebApplicationFactory<Program> factory)
    {
        _factory = factory;
    }

    [Fact]
    public async Task GetOneItem_Returns200WithItem()
    {
        //Arrange
        await using var mySqlTestcontainer = new TestcontainersBuilder<MySqlTestcontainer>()
            .WithDatabase(new MySqlTestcontainerConfiguration
            {
                Password = "Test1234",
                Database = "TestDB"
            })
            .WithImage("mysql:8.0.31-oracle")
            .Build();

        await mySqlTestcontainer.StartAsync();

        await using var todoContext = TodoContext
            .CreateFromConnectionString(mySqlTestcontainer.ConnectionString);

        // Creates the database if not exists
        await todoContext.Database.EnsureCreatedAsync();

        Fixture fixture = new Fixture();
        var todoItem = fixture.Create<TodoItem>();

        todoContext.TodoItems.Add(todoItem);

        await todoContext.SaveChangesAsync();

        var HttpClient = _factory
            .WithWebHostBuilder(builder =>
            {
                builder.UseSetting("MySqlConnectionString", mySqlTestcontainer.ConnectionString);
            })
            .CreateClient();

        //Act
        var HttpResponse = await HttpClient.GetAsync($"/todo/{todoItem.ItemId}");

        //Assert
        HttpResponse.StatusCode.Should().Be(HttpStatusCode.OK);

        var responseJson = await HttpResponse.Content.ReadAsStringAsync();
        var todoItemResult = JsonSerializer.Deserialize<TodoItem>(responseJson);

        todoItemResult.Should().BeEquivalentTo(todoItem);
    }
}

❗ Be aware that I pass the container tag version in the WithImage method even when using the typed MySqlTestcontainer container class. This is very important because when we don't pass the tag, the container runtime will use the latest tag and a database update may break the application and the tests.

Testing the POST method

First, let's migrate the MySqlTestcontainer and the DbContext creation to a Fixture and a Collection so they can be shared between all tests. This is recommended because unless we do this, all tests will spin up and dispose of the container, making our tests slower than needed.

[CollectionDefinition("MySqlTestcontainer Collection")]
public class MySqlTestcontainerCollection: ICollectionFixture<MySqlTestcontainerFixture>
{
}

public class MySqlTestcontainerFixture : IAsyncLifetime
{
    public MySqlTestcontainer MySqlTestcontainer { get; private set; } = default!;
    public TodoContext TodoContext { get; private set; } = default!;

    public async Task InitializeAsync()
    {
        MySqlTestcontainer = new TestcontainersBuilder<MySqlTestcontainer>()
            .WithDatabase(new MySqlTestcontainerConfiguration
            {
                Password = "Test1234",
                Database = "TestDB"
            })
            .WithImage("mysql:8.0.31-oracle")
            .Build();

        await MySqlTestcontainer.StartAsync();

        TodoContext = TodoContext
            .CreateFromConnectionString(MySqlTestcontainer.ConnectionString);

        // Creates the database if it does not exists
        await TodoContext.Database.EnsureCreatedAsync();
    }

    public async Task DisposeAsync()
    {
        await MySqlTestcontainer.DisposeAsync();

        await TodoContext.DisposeAsync();
    }
}

The test does the following actions:

MySql container and DbContext are injected by the xUnit fixture;
Create a random object with AutoFixture;
Override our application configuration with the connection string from the container;
Create an HttpClient pointing to our application;
Make POST request to the endpoint passing the random object previously created;
Validate that the Status Code is 200 and that the Location header has the correct URL for the GET endpoint of the created object;
Query the database and validate that the object created is equal to the randomly created object.

[Collection("MySqlTestcontainer Collection")]
public class TodoIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    private readonly MySqlTestcontainer _mySqlTestcontainer;
    private readonly TodoContext _todoContext;

    public TodoIntegrationTests(WebApplicationFactory<Program> factory, 
        MySqlTestcontainerFixture mySqlTestcontainerFixture)
    {
        _factory = factory;
        _mySqlTestcontainer = mySqlTestcontainerFixture.MySqlTestcontainer;
        _todoContext = mySqlTestcontainerFixture.TodoContext;
    }

    //Other tests
    //...

    [Fact]
    public async Task PostOneItem_Returns201AndCreateItem()
    {
        //Arrange
        Fixture fixture = new Fixture();
        var todoItem = fixture.Build<TodoItem>()
                .With(x => x.ItemId, 0)
                .Create();

        var HttpClient = _factory
            .WithWebHostBuilder(builder =>
            {
                builder.UseSetting("MySqlConnectionString", _mySqlTestcontainer.ConnectionString);
            })
            .CreateClient();

        //Act
        var HttpResponse = await HttpClient.PostAsJsonAsync($"/todo", todoItem);

        //Assert
        HttpResponse.StatusCode.Should().Be(HttpStatusCode.Created);

        var responseJson = await HttpResponse.Content.ReadAsStringAsync();
        var todoItemResult = JsonSerializer.Deserialize<TodoItem>(responseJson);

        HttpResponse.Headers.Location.Should().Be($"{HttpClient.BaseAddress}Todo/{todoItemResult!.ItemId}");

        var dbItem = await _todoContext.TodoItems
            .SingleAsync(a => a.ItemId == todoItemResult!.ItemId);

        dbItem.Description.Should().Be(todoItem.Description);
    }
}

DEV Community: Daniel Genezini

Down the Rabbit Hole of creating a Home Lab

Introduction

Why Set Up a Home Lab?

What do you need / How to start?

What can you learn?

Linux

Containers

Container orchestration

File Sharing and Storage

Backup Strategies

Reverse Proxy and SSL

Authentication and Security

Networking

Monitoring and Maintenance

Automation and Scheduling

Conclusion

Applications/Tools

References

Related

Liked this post?

Follow me

Server-side rendered SPAs with ASP.NET and no Javascript

Introduction

What is HTMX

Base application

Including the HTMX lib and menu links configurations

Removing the layout for HTMX requests

Setting up the forms

Changing the page title according to the page load

Indicating the loading status

Full source code

References and Links

Related

Liked this post?

Follow me

Colorful terminals with Oh My Posh and Windows Terminal

Introduction

Quick definition

Installing Oh My Posh

Installing a Nerd Font

Configuring The Terminal

Windows Terminal

VS Code

Themes

Customizing your theme

My theme

References

Liked this post?

Follow me

Integration tests with AWS S3 buckets using Localstack and Testcontainers

Why use Localstack for integration tests?

What is Testcontainers?

Running a disposable container with Testcontainers

Example context

Creating integration tests with Testcontainers

LocalStack/Testcontainer Fixture

Upload an image test

Upload an existing image test

Get an image test

Image not found test

Full source code

References and Links

Related

Liked this post?

Follow me

Lessons learned from building a static code analyzer for C#

Introduction

DiscriminatedUnions.Net package

DiscriminatedUnions.NET Source Code

Lessons learned

Development-time only nuget packages

Roslyn Analyzers can be used to enforce rules on how to use a package

Analyzers have to evolve together with the language

TDD is your friend

Casts... Casts everywhere

Understanding the syntax tree and finding the correct interfaces

Not many material to help beginners

Related

Liked this post?