DEV Community: Raul Naupari

MockServer: Easy mocking of any system you integrate (HTTP or HTTPS)

Raul Naupari — Sun, 13 Oct 2024 13:41:21 +0000

From time to time, when we have a dependency or dependencies against an API, a subtle need arises:

We want a specific response from the dependency to test a particular flow in our application.

There are several strategies to solve this kind of challenge, but today we will see MockServer as a tool to resolve it.

What is MockServer?

For any system you integrate with via HTTP or HTTPS, MockServer can be used as:

A mock configured to return specific responses for different requests.
A proxy recording and optionally modifying requests and responses.
Both a proxy for some requests and a mock for other requests.

Why use MockServer?

Testing

Easily recreate all types of responses for HTTP dependencies.
Isolate the system-under-test to ensure tests run reliably.
Easily set up mock responses independently for each test to ensure test data is encapsulated with each test.
Create test assertions that verify the requests the system-under-test has sent.

De-coupling development

Start working against a service API before the service is available.
Isolate development teams during the initial development phases when the APIs may be volatile.

Running MockServer

There are several ways to run MockServer. We are going to use the Docker container option:

docker run -d --rm -p 6002:1080 mockserver/mockserver

Then go to http://localhost:6002/mockserver/dashboard to see your MockServer up and running. Now, we are ready to create expectations. An expectation is how we say to MockServer, get me this response when you receive that request. Here is an expectation example:

{
    "httpRequest": {
        "path": "/hello-world-mock",
        "method": "GET"
    },
    "httpResponse": {
        "body": "Hello world!!"
    }
}

We are going to register the expectation using the following statement:

curl -X PUT "http://localhost:6002/mockserver/expectation" -H "Content-Type: application/json" -d "{\"httpRequest\":{\"path\":\"/hello-world-mock\",\"method\":\"GET\"},\"httpResponse\":{\"body\":\"Hello world!!\"}}"

Let's call the endpoint to see the result:

curl -X GET "http://localhost:6002/hello-world-mock" -H "accept: text/plain"
Hello world!!

Here, you can find the complete MockServer API surface.

MockServer in practice

We are going to develop an API to get the weather from a city using the following ranges:

Cold: 55 degrees and below
Cool: 56 to 65 degrees
Mild: 66 to 75 degrees
Warm: 75 to 85 degrees
Hot: Above 85 degrees

To get the real weather, we will use the Weather API that gives us a generous free plan. Let's start creating a .NET ASP Core Web API. Add a file called WeatherApiClient.cs

public class WeatherApiClient
{
    private readonly IHttpClientFactory _factory;

    private readonly Settings _settings;

    public WeatherApiClient(IHttpClientFactory factory, Settings settings)
    {
        _factory = factory;
        _settings = settings;
    }

    public async Task<decimal?> GetTemperature(string city, string provider)
    {
        var client = _factory.CreateClient(provider);

        var httpResponse = await client.GetAsync($"v1/current.json?key={_settings.Key}&q={city}&aqi=no");

        var options = new JsonSerializerOptions() { PropertyNameCaseInsensitive = true };

        httpResponse.EnsureSuccessStatusCode();

        var responseBody = await httpResponse.Content.ReadAsStringAsync();

        var response = JsonSerializer.Deserialize<Response>(responseBody, options);

        return response?.Current?.TemperatureF;
    }

    public class Settings
    {
        public string? Uri { get; set; }
        public string? Key { get; set; }
        public string? MockUri { get; set; }
    }

    public class Response
    {
        public Current? Current { get; set; }
    }

    public class Current
    {
        [JsonPropertyName("temp_f")]
        public decimal TemperatureF { get; set; }
    }
}

Create a new controller to use this class:

[ApiController]
[Route("[controller]")]
public class CurrentWeatherController : ControllerBase
{
    private WeatherApiClient _client;

    private readonly Range[] _ranges;

    public CurrentWeatherController(WeatherApiClient client)
    {
        _client = client;
        _ranges = new[] {
            new Range(-459, 55,"Cold"),
            new Range(56, 65,"Cool"),
            new Range(66, 75,"Mild"),
            new Range(76, 85,"Warm"),
            new Range(85, 459,"Hot")
        };
    }

    [HttpGet()]
    public async Task<string> Get(string city, string provider="api")
    {
        var temperature = await _client.GetTemperature(city, provider);

        if(temperature == null)
        {
            return "None";
        }

        foreach (var range in _ranges)
        {
            if(range.Min <= temperature && temperature <= range.Max)
            {
                return $"{range.Name}({temperature}°F)";
            }
        }

        return "None";
    }
}

public record Range (int Min, int Max, string Name);

In the appsetting.json file, add the following:

"WeatherApi": {
  "Uri": "http://api.weatherapi.com",
  "Key": "<put-your-api-key-here>",
  "MockUri": "http://localhost:6002"
}

And finally, in the Program.cs add:

var setttings = builder.Configuration.GetSection("WeatherApi").Get<Settings>();

builder.Services.AddHttpClient("api", httpClient =>
{
    httpClient.BaseAddress = new Uri(setttings.Uri);
});

builder.Services.AddHttpClient("mock", httpClient =>
{
    httpClient.BaseAddress = new Uri(setttings.MockUri);
});

builder.Services.AddSingleton(setttings);

builder.Services.AddSingleton<WeatherApiClient>();

Run the application and send a request to see if it's working (in our case is running under the port 5280):

curl -X GET "http://localhost:5280/CurrentWeather?city=Miami&provider=api" -H "accept: text/plain"
Warm(82.0°F)

Now let's imagine that we want to get a response under the **Cold **range. Sending requests using different cities to get the desired response could take a while. Here is where MockServer is going to shine. First, we are going to create a new expectation with the following body:

{
  "httpRequest": {
    "path": "/v1/current.json",
    "method": "GET",
    "queryStringParameters": {
      "q": [ "Toronto" ],
      "key": [ "[A-Z0-9\\-]+" ],
      "aqi": [ "no" ]
    }
  },
  "httpResponse": {
    "headers": {
      "Content-Type": [
        "application/json"
      ]
    },
    "body": "{\"current\":{\"temp_f\":50}}"
  }
}

And then, we are going to send a new request to our API but replacing the provider query string parameter from api to mock:

curl -X GET "http://localhost:5280/CurrentWeather?city=Toronto&provider=mock" -H "accept: text/plain"
Cold(50°F)

And the expected response is there. The potential use cases for MockServer are huge, but for sure will help us to speed up our development and increase the quality of the software we build. Here, you can find the solution used in this post.

If you are a .NET developer here, you will find a non-official client to interact with the MockServer.

Nuke: Deploy Helm package locally (special guest, GitVersion)

Raul Naupari — Sun, 29 Sep 2024 14:53:53 +0000

Today, we will continue our journey with Nuke by adding new targets to the solution presented in Nuke: Deploy ASP.NET Web App to Azure. This time, we will deploy our application to a local Kubernetes cluster using Helm.

But first, we will need the following:

A standalone Kubernetes server and client.
Helm CLI.

Generating the build number

Our first target will get the build number using GitVersion (we discussed it in Semantic Versioning with GitVersion). Let's start by adding the following NuGet package:

GitVersion.CommandLine

Next, add the following namespaces to access all gitversion commands:

using static Nuke.Common.Tools.GitVersion.GitVersionTasks;
using Nuke.Common.Tools.GitVersion;

Add a variable to store the generated build number:

private string BuildNumber;

And now, the target itself:

Target GetBuildNumber => _ => _
    .Executes(() =>
    {
        var (result, _) = GitVersion();
        BuildNumber = result.SemVer;
    });

Building the Docker image

The first step is to create a Dockerfile in our project folder as follows:

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build-env
WORKDIR /app

# Copy everything
COPY . ./
# Restore as distinct layers
RUN dotnet restore "./nuke-sandbox-app/nuke-sandbox-app.csproj"
# Build and publish a release
RUN dotnet publish "./nuke-sandbox-app/nuke-sandbox-app.csproj" -c Release -o out

# Build runtime image
FROM mcr.microsoft.com/dotnet/aspnet:6.0
WORKDIR /app
COPY --from=build-env /app/out .
ENTRYPOINT ["dotnet", "nuke-sandbox-app.dll"]

Add the following namespaces to access all docker commands:

using static Nuke.Common.Tools.Docker.DockerTasks;
using Nuke.Common.Tools.Docker;

Add a variable to store the Docker image repository used in the project:

private readonly string Repository = "raulnq/nuke-sandbox-app";

And for the final step, add the target:

Target BuildImage => _ => _
    .DependsOn(GetBuildNumber)
    .Executes(() =>
    {
        var dockerFile = RootDirectory / "nuke-sandbox-app" / "Dockerfile";
        var image = $"{Repository}:{BuildNumber}";

        DockerBuild(s => s
            .SetPath(RootDirectory)
            .SetFile(dockerFile)
            .SetTag(image)
            );
    });

Installing the Helm package

And finally, here is the step to install the Helm package in the Kubernetes cluster. You can first check Useful commands for Helm. Go to your solution folder and run the following commands to create the Helm package:

mkdir helm
cd helm
helm create nuke-sandbox-app

Keep only these files in your Helm package:

helm\nuke-sandbox-app
|-- templates
|   |-- _helpers.tpl
|   |-- deployment.yaml
|   `-- service.yaml
|-- .helmignore
|-- Chart.yaml
`-- values.yaml

Modify the deployment.yaml file as follows:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "nuke-sandbox-app.fullname" . }}
  labels:
    {{- include "nuke-sandbox-app.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "nuke-sandbox-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "nuke-sandbox-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - name: http
              containerPort: 80
              protocol: TCP

The service.yaml file:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "nuke-sandbox-app.fullname" . }}
  labels:
    {{- include "nuke-sandbox-app.labels" . | nindent 4 }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "nuke-sandbox-app.selectorLabels" . | nindent 4 }}

And the values.yaml file:

replicaCount: 1

image:
  repository: raulnq/nuke-sandbox-app
  pullPolicy: IfNotPresent
  tag: "1.0"

nameOverride: ""
fullnameOverride: ""

service:
  type: ClusterIP
  port: 80

Go back to the build.cs file and add:

using static Nuke.Common.Tools.Helm.HelmTasks;
using Nuke.Common.Tools.Helm;
using System.Collections.Generic;

Add a variable to store the Helm release name used in the project:

private readonly string ReleaseName = "release-nuke-sandbox-app";

To wrap up, we will add two targets: one to install and the other to uninstall the Helm package:

Target HelmInstall => _ => _
    .DependsOn(BuildImage)
    .Executes(() =>
    {
        var chart = HelmDirectory / "nuke-sandbox-app";

        HelmUpgrade(s => s
            .SetRelease(ReleaseName)
            .SetSet(new Dictionary<string, object>() { { "image.tag", BuildNumber }, { "image.repository", Repository } })
            .SetChart(chart)
            .EnableInstall()
        );
    });

Target HelmUninstall => _ => _
    .Executes(() =>
    {
        HelmDelete(s => s
        .SetReleaseNames(ReleaseName)
        );
    });

That's it! Now it's time to run our Nuke command:

nuke HelmInstall

We can check our deployment with kubectl get deployments:

NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
release-nuke-sandbox-app   1/1     1            1           18s

And uninstall when needed:

nuke HelmUninstall

You can find the updated solution here.

Useful commands for Helm

Raul Naupari — Mon, 16 Sep 2024 00:43:07 +0000

Helm is an open source package manager for Kubernetes. It provides the ability to provide, share, and use software built for Kubernetes.

In this post, we will cover the most common Helm commands (and their most common parameters) from our daily work and provide a brief review of the core concepts. You can review the official documentation here.

Helm core concepts

The Chart is a Helm package that contains information sufficient for installing a set of Kubernetes resources into a Kubernetes cluster.
The Repository is a simple HTTP server to store collection of charts. You can search, download and install charts from a repository.
The Release is an instance or a deployment of a chart. When you perform a helm install command, you are creating a new release of that chart on your Kubernetes cluster.

Helm commands

Repository management

List chart repositories:

helm repo list

helm repo list
NAME            URL
bitnami         https://charts.bitnami.com/bitnami
ingress-nginx   https://kubernetes.github.io/ingress-nginx

Search for charts in the local repositories:

helm search repo [keyword]

helm search repo rabbitmq
NAME                                    CHART VERSION   APP VERSION     DESCRIPTION
bitnami/rabbitmq                        9.0.0           3.9.16          RabbitMQ is an open source general-purpose mess...
bitnami/rabbitmq-cluster-operator       2.6.0           1.12.1          The RabbitMQ Cluster Kubernetes Operator automa...

Search for charts in the Artifact Hub:

helm search hub [keyword] -o yaml

helm search hub jaeger -o yaml
- app_version: 1.17.1
  description: A Jaeger Helm chart for Kubernetes
  repository:
    name: hkube
    url: https://hkube.io/helm/
  url: https://artifacthub.io/packages/helm/hkube/jaeger
  version: 0.27.2006
- app_version: 1.30.0
  description: A Jaeger Helm chart for Kubernetes
  repository:
    name: jaegertracing
    url: https://jaegertracing.github.io/helm-charts
  url: https://artifacthub.io/packages/helm/jaegertracing/jaeger
  version: 0.56.1

Add a repository:

helm repo add [repository] [repository-url]

helm repo add jaegertracing https://jaegertracing.github.io/helm-charts
"jaegertracing" has been added to your repositories

Update information of charts in local repositories:

helm repo update

helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "ingress-nginx" chart repository
...Successfully got an update from the "jaegertracing" chart repository

Chart management

Using packages created by us

Create a directory containing the common chart files and directories:

helm create [chart]

helm create demo-app
Creating demo-app

Examine a chart for possible issues:

helm lint [chart]

helm lint demo-app
==> Linting demo-app
[INFO] Chart.yaml: icon is recommended

Upgrade a release:

helm upgrade [release] [chart]

--namespace           namespace scope for this request
--install             if a release by this name doesn't already exist, run an install
--dry-run             simulate an upgrade
--debug               enable verbose output
--values              specify values in a YAML file or a URL (can specify multiple)
--set                 set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--create-namespace    if --install is set, create the release namespace if not present

helm upgrade release-demo demo-app --debug --install --values values.local.yaml --set image.tag=1.0.0

Package a chart directory into a chart archive:

helm package [chart] --app-version

helm package demo-app --app-version 1.0.0
Successfully packaged chart and saved it to: C:\demo-app-1.0.0.tgz

Push a chart to a remote repository (depending on the server):

Using packages from a remote repository

Show the chart's definition:

helm show chart [chart]

helm show chart ingress-nginx/ingress-nginx
apiVersion: v2
appVersion: 1.2.0
description: Ingress controller for Kubernetes using NGINX as a reverse proxy and
  load balancer
home: https://github.com/kubernetes/ingress-nginx
icon: https://upload.wikimedia.org/wikipedia/commons/thumb/c/c5/Nginx_logo.svg/500px-Nginx_logo.svg.png
keywords:
- ingress
- nginx
kubeVersion: '>=1.19.0-0'
maintainers:
- name: rikatz
- name: strongjz
- name: tao12345666333
name: ingress-nginx
sources:
- https://github.com/kubernetes/ingress-nginx
type: application
version: 4.1.0

Show the chart's values:

helm show values [chart]

Download a chart from a repository:

helm pull [chart]

helm pull ingress-nginx/ingress-nginx

Install a chart:

helm install [release] [chart]

helm install ingress-nginx/ingress-nginx

Release management

List releases:

helm list --namespace [namespace]

helm list --namespace default
NAME            NAMESPACE       REVISION        UPDATED                                 STATUS  CHART                   APP VERSION
release-demo    default         3               2022-04-27 14:09:35.2202953 -0500 -05   failed  demo-app-1.0.0          1.16.0

Fetch release history:

helm history [release]

helm history release-demo
REVISION        UPDATED                         STATUS          CHART                   APP VERSION     DESCRIPTION
1               Wed Apr 27 08:52:02 2022        superseded      demo-app-0.1.0          1.16.0          Upgrade complete
2               Wed Apr 27 12:53:03 2022        deployed        demo-app-0.1.0          1.16.0          Upgrade complete
3               Wed Apr 27 14:09:35 2022        failed          demo-app-1.0.0          1.16.0          Upgrade "demo-app" failed: pre-upgrade hooks failed: timed out waiting for the condition

Rollback a release to a previous revision:

helm rollback [release] [revision]

helm rollback demo-app 2
Rollback was a success! Happy Helming!

Uninstall a release:

helm uninstall [release]

helm uninstall demo-app
release "demo-app" uninstalled

AWS IAM Database Authentication with EF Core

Raul Naupari — Sat, 07 Sep 2024 06:49:35 +0000

AWS Aurora (both MySQL and Postgres) and MariaDB allow IAM authentication. With this authentication method, you don't need to use a password when you connect to a database. Instead, you use an authentication token. In this post, we are going to explore how to use IAM database authentication with EF Core and Aurora Postgres.

Before starting, you need to fulfill a few pre-requisites:

Enabling IAM Authentication in your Aurora Postgres database.
Have an IAM User with programmatic access.
Set up your AWS CLI locally.

The first step is to create an IAM policy using this template:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
             "rds-db:connect"
         ],
         "Resource": [
             "arn:aws:rds-db:[region]:[account-id]:dbuser:[db-cluster-resourceId]/[db-user-name]"
         ]
      }
   ]
}

[region] is the AWS Region for the database cluster. An example of a region is us-east-2.
[account-id] is the AWS account number for the database cluster. An example of an account number is 1234567890.
[db-cluster-resourceId] is the identifier for the database cluster. An example of this identifier is cluster-ABCDEFGHIJKL01234.
[db-user-name] is the name of the database account associated with IAM authentication.

Once we have that, we attach it to our IAM user. The next step is to create a database (we are using the postgres user to run the following scripts):

CREATE DATABASE tasksmanager
WITH 
ENCODING = 'UTF8';

And then a table inside this new database:

CREATE TABLE tasks(
  id UUID PRIMARY KEY,
  name VARCHAR(255)
);

And finally, the database user:

CREATE USER db_iam_user; 
GRANT rds_iam TO db_iam_user;
GRANT postgres TO db_iam_user;

Now, we will create a .NET ASP Core Web API application. Add the following NuGet packages to that application:

In our appsetting.json, we are going to add a ConnectionString property:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ConnectionString": "host=[aurora-database-endpoint];Database=tasksmanager;Username=db_iam_user;SSL Mode=Require;TrustServerCertificate=true"
}

Add a file with the following content:

    public class Task
    {
        public Guid Id { get; set; }
        public string Name { get; set; }

        private Task()
        {

        }

        public Task(string name)
        {
            Id = Guid.NewGuid();
            Name = name;
        }
    }

With that, we can create our DbContext class:

    public class ApplicationDbContext : DbContext
    {
        public DbSet<Task> Tasks { get; set; }

        public ApplicationDbContext(DbContextOptions options) : base(options)
        {

        }
    }

Now, add a ServiceCollectionExtensions.cs file. Here is where all the magic happens:

    public static class ServiceCollectionExtensions
    {
        public static IServiceCollection AddPostgreSQL(this IServiceCollection services, IConfiguration configuration)
        {
            services.AddDbContext<ApplicationDbContext>(options =>
            {
                var connectionString = configuration["ConnectionString"];
                options.UseNpgsql(connectionString, npgsqlOption => { npgsqlOption.UseAwsIamAuthentication(); });
                options.UseLowerCaseNamingConvention();
            });
            return services;
        }

        public static NpgsqlDbContextOptionsBuilder UseAwsIamAuthentication(this NpgsqlDbContextOptionsBuilder optionsBuilder)
        {
            optionsBuilder.ProvidePasswordCallback(RequestAwsIamAuthToken);
            return optionsBuilder;
        }

        static string RequestAwsIamAuthToken(string host, int port, string database, string username)
        {
            return RDSAuthTokenGenerator.GenerateAuthToken(host, port, username);
        }
    }

Then, add the following line to your Program.cs file:

builder.Services.AddPostgreSQL(builder.Configuration);

Add a couple of models for our request and response:

    public class RegisterTaskCommand
    {
        public string Name { get; set; }
    }

    public class ListTasksResult
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
    }

And finally, our TaskController.cs file:

    [ApiController]
    [Route("[controller]")]
    public class TasksController : ControllerBase
    {
        private readonly ApplicationDbContext _context;
        public TasksController(ApplicationDbContext context)
        {
            _context = context;
        }

        [HttpGet()]
        public Task<ListTasksResult[]> ListTasks()
        {
            return _context.Tasks.Select(t => new ListTasksResult() { Id = t.Id, Name = t.Name }).ToArrayAsync();
        }

        [HttpPost()]
        public async Task<Guid> RegisterTask(RegisterTaskCommand command)
        {
            var task = new Task(command.Name);
            _context.Tasks.Add(task);
            await _context.SaveChangesAsync();
            return task.Id;
        }
    }

Run your application and test your passwordless connection against your database. Here, you can find all the code and database scripts.

Semantic Versioning with GitVersion (GitFlow)

Raul Naupari — Sat, 31 Aug 2024 04:59:56 +0000

Versioning software artifacts (Assemblies, NuGet, or NPM packages) has been proved to be a challenging procedure. Today, Semantic Versioning is a practice that has been on the rise over the last few years, but how to apply it to your projects?. Here is were GitVersion come in place.

GitVersion is a tool that generates a Semantic Version number based on your Git history. The version number generated from GitVersion can then be used for various different purposes.

To test how GitVersion helps us get version numbers, today we are going to use GitFlow as a branching strategy. There are several ways to install GitVersion. Here we are using the .NET global tool option:

dotnet tool install --global GitVersion.Tool --version 5.*

Let's create a new Git repository:

mkdir gitversion-giflow
cd .\gitversion-giflow\
git init

Now it is time to see our first GitVersion command:

dotnet-gitversion init

We are going thru the configuration process depending on the branch strategy mentioned before:

GitVersion init will guide you through setting GitVersion up to work for you

Which would you like to change?

0) Save changes and exit
1) Exit without saving

2) Run getting started wizard

3) Set next version number
4) Branch specific configuration
5) Branch Increment mode (per commit/after tag) (Current: )
6) Assembly versioning scheme (Current: )
7) Setup build scripts

Select the option 2:

The way you will use GitVersion will change a lot based on your branching strategy. What branching strategy will you be using:

1) GitFlow (or similar)
2) GitHubFlow
3) Unsure, tell me more

Select the option 1:

By default GitVersion will only increment the version of the 'develop' branch every commit, all other branches will increment when tagged

What do you want the default increment mode to be (can be overriden per branch):

1) Follow SemVer and only increment when a release has been tagged (continuous delivery mode)
2) Increment based on branch config every commit (continuous deployment mode)
3) Each merged branch against main will increment the version (mainline mode)
4) Skip

Again option 1. As the last step, the wizard is going to show us to the first menu, select option 0 (Save changes and exit). Run the following command to see the current GitVersion configuration:

dotnet-gitversion /showconfig

GitVersion added a file called GitVersion.yml.

mode: ContinuousDelivery
branches: {}
ignore:
  sha: []
merge-message-formats: {}

Let's add the first commit with this file:

git add .
git commit -m 'initial commit'

Then run the dotnet-gitversion command:

{
  "Minor": 1,
  "Patch": 0,
  "PreReleaseTag": "",
  "PreReleaseTagWithDash": "",
  "PreReleaseLabel": "",
  "PreReleaseLabelWithDash": "",
  "PreReleaseNumber": null,
  "WeightedPreReleaseNumber": 60000,
  "BuildMetaData": 0,
  "BuildMetaDataPadded": "0000",
  "FullBuildMetaData": "0.Branch.master.Sha.17de78f354ad96dc7766c2d1242634cc903d8e2f",
  "MajorMinorPatch": "0.1.0",
  "SemVer": "0.1.0",
  "LegacySemVer": "0.1.0",
  "LegacySemVerPadded": "0.1.0",
  "AssemblySemVer": "0.1.0.0",
  "AssemblySemFileVer": "0.1.0.0",
  "FullSemVer": "0.1.0+0",
  "InformationalVersion": "0.1.0+0.Branch.master.Sha.17de78f354ad96dc7766c2d1242634cc903d8e2f",
  "BranchName": "master",
  "EscapedBranchName": "master",
  "Sha": "17de78f354ad96dc7766c2d1242634cc903d8e2f",
  "ShortSha": "17de78f",
  "NuGetVersionV2": "0.1.0",
  "NuGetVersion": "0.1.0",
  "NuGetPreReleaseTagV2": "",
  "NuGetPreReleaseTag": "",
  "VersionSourceSha": "17de78f354ad96dc7766c2d1242634cc903d8e2f",
  "CommitsSinceVersionSource": 0,
  "CommitsSinceVersionSourcePadded": "0000",
  "UncommittedChanges": 0,
  "CommitDate": "2022-05-22"
}

There is a lot of information, but the one that we will use will be FullSemVer. Notice that GitVersion uses by default version number 0.1.0. Create a develop branch from master:

git checkout -b develop

And then create a feature branch from develop:

git checkout -b feature/myFeatureA

Run the command dotnet-gitversion /showvariable FullSemVer:

0.1.0-myFeatureA.1+0

Add another commit (we are going to use empty commits by practicality):

git commit -m 'featurea A: change 1' --allow-empty

Run again dotnet-gitversion /showvariable FullSemVer to see how the last number is moving:

0.1.0-myFeatureA.1+1

Time to finalize the feature branch:

git checkout develop
git merge --no-ff feature/myFeatureA
git branch -d feature/myFeatureA

Run dotnet-gitversion /showvariable FullSemVer:

0.1.0-alpha.2

Create a new feature branch and repeat all steps until finalizing it and see how the version number changes in the develop branch:

0.1.0-alpha.4

Run the command git log --oneline --graph to see the log history for the develop branch:

*   fe48f23 (HEAD -> develop) Merge branch 'feature/myFeatureB' into develop
|\
| * 4ad9aa8 featurea B: change 1
|/
*   20481b3 Merge branch 'feature/myFeatureA' into develop
|\
| * df2170f featurea A: change 1
|/
* 17de78f (master) initial commit

Now it is time to create a release branch:

git checkout -b release/1.0.0 develop

Run dotnet-gitversion /showvariable FullSemVer:

1.0.0-beta.1+0

Add a commit to simulate a bug fix under the release branch:

git commit -m 'bug fix' --allow-empty

And check the version number:

1.0.0-beta.1+1

Assume that we want to release this branch to production:

git checkout master
git merge --no-ff release/1.0.0
git tag '1.0.0'
git checkout develop
git merge --no-ff release/1.0.0
git branch -d release/1.0.0

Now running dotnet-gitversion /showvariable FullSemVer under master will see 1.0.0 because the tag tells GitVersion that this is the new version number. If you check the version number in the develop branch, GitVersion figures out 1.1.0-alpha.2 as a new value. Let's do a hotfix now:

git checkout master
git checkout -b hotfix/1.0.1

Add a commit:

git commit -m 'bug fix' --allow-empty

Run dotnet-gitversion /showvariable FullSemVer:

1.0.1-beta.1+7

And finalize a hotfix branch:

git checkout master
git merge --no-ff hotfix/1.0.1
git tag  '1.0.1'
git checkout develop
git merge --no-ff hotfix/1.0.1
git branch -d hotfix/1.0.1

Run dotnet-gitversion /showvariable FullSemVer under master branch to see 1.0.1 as version number.

To see more examples using GitFlow, you can check the official documentation here.

Nuke: Deploy ASP. NET Web App to Azure

Raul Naupari — Tue, 13 Aug 2024 00:12:07 +0000

In this post, we will explore the benefits of Nuke and its most common features as we deploy a web app to Azure. Our goal is to achieve a flexible, maintainable, automated build process.

Nuke is an open source, cross-platform build automation solution for .NET projects. Nuke prides itself on its simplicity and extensibility that makes build automation approachable for everyone.

Today, tools like Continuous Integration Servers perform the same job. So, why should we move the build process from CI Servers to Nuke and use them as simple runners?

Reduce Vendor Lock-In: Switching from one CI platform to another requires a significant effort.
Democratize DevOps: If something breaks or a developer adds a feature that needs changes in the build process, progress halts until the build manager is available.
Reduce Mismatch: Occasionally, a change affects the code and the build process. When you move the feature to the development branch, you must to remember to update the related build process.
Simplify Debugging: When things go wrong on a CI server with custom logic, you can't set breakpoints, you can't access environmental differences, logging options are limited, and you often have to wait a long time to see the results of any changes.

Concepts

Target

A target is something that must happen. A collection of targets defines your build process. They are similar to the build steps in your CI server.

Target Restore => _ => _
    .Executes(() =>
    {
        DotNetRestore(s => s
            .SetProjectFile(Solution));
    });

Parameters

A parameter is a value provided by the command line.

[Parameter("Configuration to build - Default is 'Debug' (local) or 'Release' (server)")]
readonly Configuration Configuration = IsLocalBuild ? Configuration.Debug : Configuration.Release;

Dependencies

A dependency specifies which targets need to run first.

Target Compile => _ => _
    .DependsOn(Restore)
    .Executes(() =>
    {
        DotNetBuild(s => s
            .SetProjectFile(Solution)
            .SetConfiguration(Configuration)
            .EnableNoRestore());
    });

Code

Let's start by installing Nuke:

dotnet tool install Nuke.GlobalTool --global

Then, in the same directory as your solution, run:

 nuke :setup

Nuke will start asking questions to set up your build project:

NUKE Global Tool version 6.0.1 (Windows,.NETCoreApp,Version=v3.1)
How should the build project be named?
¬  _build
Where should the build project be located?
¬  ./build
Which NUKE version should be used?
¬  6.0.3 (latest release)
Which solution should be the default?
¬  nuke-sandbox-app.sln
Do you need help getting started with a basic build?
¬  No, I can do this myself...

At this point, Nuke will add a new project named _build to your solution. Find the Build.cs file and open it. Add the following namespaces to access all dotnet commands:

using Nuke.Common.Tools.DotNet;
using static Nuke.Common.Tools.DotNet.DotNetTasks;

Delete all the targets and replace them with the following code:

Target Restore => _ => _
    .Executes(() =>
    {
        DotNetRestore(s => s
            .SetProjectFile(Solution));
    });

Target Compile => _ => _
    .DependsOn(Restore)
    .Executes(() =>
    {
        DotNetBuild(s => s
            .SetProjectFile(Solution)
            .SetConfiguration(Configuration)
            .EnableNoRestore());
    });

Open a console in the same directory as your solution and run:

nuke Compile

╬════════════
║ Restore
╬═══

09:23:21 [INF] > "C:\Program Files\dotnet\dotnet.exe" restore D:\Source\Github\nuke-sandbox\nuke-sandbox-app.sln
09:23:21 [DBG]   Determining projects to restore...
09:23:22 [DBG]   Restored D:\Source\Github\nuke-sandbox\nuke-sandbox-app\nuke-sandbox-app.csproj (in 87 ms).

╬════════════
║ Compile
╬═══

09:23:22 [INF] > "C:\Program Files\dotnet\dotnet.exe" build D:\Source\Github\nuke-sandbox\nuke-sandbox-app.sln --configuration Debug --no-restore
09:23:22 [DBG] Microsoft (R) Build Engine version 17.1.0+ae57d105c for .NET
09:23:22 [DBG] Copyright (C) Microsoft Corporation. All rights reserved.
09:23:22 [DBG]
09:23:25 [DBG]   nuke-sandbox-app -> D:\Source\Github\nuke-sandbox\nuke-sandbox-app\bin\Debug\net6.0\nuke-sandbox-app.dll
09:23:26 [DBG]
09:23:26 [DBG] Build succeeded.
09:23:26 [DBG]     0 Warning(s)
09:23:26 [DBG]     0 Error(s)
09:23:26 [DBG]
09:23:26 [DBG] Time Elapsed 00:00:03.33

═══════════════════════════════════════
Target             Status      Duration
───────────────────────────────────────
Restore            Succeeded     < 1sec
Compile            Succeeded       0:03
───────────────────────────────────────
Total                              0:04
═══════════════════════════════════════

Congratulations, you are compiling your solution with Nuke. To deploy the web app to Azure, we will use the Kudu's zip API. We must create a target to run the dotnet publish command and another to zip the results. Add two AbsolutePath variables to store the results of these commands:

AbsolutePath OutputDirectory => RootDirectory / "output";

AbsolutePath ArtifactDirectory => RootDirectory / "artifact";

And add the following targets:

Target Clean => _ => _
    .Before(Restore)
    .Executes(() =>
    {
        EnsureCleanDirectory(OutputDirectory);
        EnsureCleanDirectory(ArtifactDirectory);
    });

Target Publish => _ => _
    .DependsOn(Compile)
    .DependsOn(Clean)
    .Executes(() =>
    {
        DotNetPublish(s => s
            .SetProject(Solution)
            .SetConfiguration(Configuration)
            .SetOutput(OutputDirectory)
            .EnableNoRestore()
            .SetNoBuild(true));
    });

Target Zip => _ => _
    .DependsOn(Publish)
    .Executes(() =>
    {
        ZipFile.CreateFromDirectory(OutputDirectory, ArtifactDirectory / "deployment.zip");
    });

Run the nuke command and check the output and artifact folders:

nuke Zip

Let's move to the final step and add three parameters:

[Parameter()]
public string WebAppUser;

[Parameter()]
public string WebAppPassword;

[Parameter]
public string WebAppName;

And copy this target:

Target Deploy => _ => _
    .DependsOn(Zip)
    .Requires(() => WebAppUser)
    .Requires(() => WebAppPassword)
    .Requires(() => WebAppName)
    .Executes(async () =>
    {
        var base64Auth = Convert.ToBase64String(Encoding.Default.GetBytes($"{WebAppUser}:{WebAppPassword}"));
        using (var memStream = new MemoryStream(File.ReadAllBytes(ArtifactDirectory / "deployment.zip")))
        {
            memStream.Position = 0;
            var content = new StreamContent(memStream);
            var httpClient = new HttpClient();
            httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", base64Auth);
            var requestUrl = $"https://{WebAppName}.scm.azurewebsites.net/api/zipdeploy";
            var response = await httpClient.PostAsync(requestUrl, content);

            if (!response.IsSuccessStatusCode)
            {
                Assert.Fail("Deployment returned status code: " + response.StatusCode);
            }

        }
    });

To get the user and password, go to the Azure portal and find the Deployment Center option:

For the user, use the last part after the backslash. Run the help command to see all the available options:

nuke --help

NUKE Execution Engine version 6.0.3 (Windows,.NETCoreApp,Version=v6.0)

Targets (with their direct dependencies):

  Restore
  Compile (default)    -> Restore
  Clean
  Publish              -> Compile, Clean
  Zip                  -> Publish
  Deploy               -> Zip

Parameters:

  --configuration         Configuration to build - Default is 'Debug' (local) or
                          'Release' (server).
  --web-app-password      <no description>
  --web-app-user          <no description>
  --web-app-name          <no description>

  --continue              Indicates to continue a previously failed build attempt.
  --help                  Shows the help text for this build assembly.
  --host                  Host for execution. Default is 'automatic'.
  --no-logo               Disables displaying the NUKE logo.
  --plan                  Shows the execution plan (HTML).
  --profile               Defines the profiles to load.
  --root                  Root directory during build execution.
  --skip                  List of targets to be skipped. Empty list skips all
                          dependencies.
  --target                List of targets to be invoked. Default is 'Compile'.
  --verbosity             Logging verbosity during build execution. Default is
                          'Normal'.

Run the following command:

nuke Deploy --web-app-password <pasword> --web-app-name nuke-sandbox-app --web-app-user '$nuke-sandbox-app'

Go to your site to see the web app running. Finally, to see your build process in a nice dependency graph, run the following command:

nuke --plan

You can find the solution here. Thank you, and happy coding.

Running local images in Kubernetes (Docker Desktop)

Raul Naupari — Sun, 04 Aug 2024 13:24:53 +0000

Today, we want to share an error we encountered while deploying an application to Kubernetes (the standalone version included in Docker Desktop). This experience helped us understand how Kubernetes pulls images from a repository. Let's start by detailing the error itself. We created the image:

❯ docker images
REPOSITORY           TAG           IMAGE ID          CREATED          SIZE
registry/demoapi     latest        110fb82f1b68      23 hours ago     212MB

Using the following configuration, we created a deployment in Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demoapi-test-deployment
  labels:
    app: demoapi-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demoapi-test
  template:
    metadata:
      labels:
        app: demoapi-test
    spec:
      containers:
      - name: demoapi-test-container
        image: registry/demoapi:latest
        ports:
        - containerPort: 80

We encountered an error while trying to pull the image:

❯ kubectl get pods
NAME                                       READY   STATUS         RESTARTS   AGE
demoapi-test-deployment-7b8f5d4fc7-8fd7t   0/1     ErrImagePull   0          14s

Then a question came to us: why is Kubernetes trying to pull the image if it's already on our machine? Looking at the pod information, we found that Kubernetes set the image pull policy to Always:

❯ kubectl get pod demoapi-test-deployment-7b8f5d4fc7-8fd7t -o yaml
apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: "2022-04-17T15:51:47Z"
  generateName: demoapi-test-deployment-7b8f5d4fc7-
  labels:
    app: demoapi-test
    pod-template-hash: 7b8f5d4fc7
  name: demoapi-test-deployment-7b8f5d4fc7-8fd7t
  namespace: default
  ownerReferences:
  - apiVersion: apps/v1
    blockOwnerDeletion: true
    controller: true
    kind: ReplicaSet
    name: demoapi-test-deployment-7b8f5d4fc7
    uid: 7a4cdd35-8f56-4e5e-ab11-efc1e8994423
  resourceVersion: "70292"
  uid: 4c430c05-f007-4a81-ad6a-396231675567
spec:
  containers:
  - image: registry/demoapi:latest
    imagePullPolicy: Always
    name: demoapi-test-container
    ports:
    - containerPort: 80
      protocol: TCP

Checking the Kubernetes documentation, we found the logic used to assign the default image pull policy:

If you omit the imagePullPolicy field, and the tag for the container image is :latest, imagePullPolicy is automatically set to Always.

If you omit the imagePullPolicy field, and you don't specify the tag for the container image, imagePullPolicy is automatically set to Always.

If you omit the imagePullPolicy field, and you specify the tag for the container image that isn't :latest, the imagePullPolicy is automatically set to IfNotPresent.

After reading that, the fix was straightforward. We decided to specify an image pull policy:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demoapi-test-deployment
  labels:
    app: demoapi-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demoapi-test
  template:
    metadata:
      labels:
        app: demoapi-test
    spec:
      containers:
      - name: demoapi-test-container
        image: registry/demoapi:latest
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 80

And problem fixed:

❯ kubectl get deployments
NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
demoapi-test-deployment   1/1     1            1           2s

Thank you, and happy coding.

Getting Started with HTMX: A Beginner's Guide

Raul Naupari — Thu, 25 Jul 2024 23:47:17 +0000

HTMX is a JavaScript library that allows you to add AJAX capabilities directly to HTML using HTML attributes. The library is based on two fundamental ideas:

Allow any HTML element to make an HTTP request.
Use the response HTML to update the element.

A basic example might be:

<button hx-get="/data" hx-trigger="click" hx-swap="outerHTML">
    Get
</button>

This button will:

Make an HTTP GET request to /data when clicked.
Replace itself with the response HTML.

But why should one consider HTMX when several front-end frameworks are available today? Here are some key points to take into consideration:

Simplicity: HTMX allows developers to build interactive web apps using simple HTML attributes instead of JavaScript code.
Performance: Since HTMX relies mainly on HTML (and minimal JavaScript), pages often load faster and use less memory.
Learning Curve: Since HTMX works directly with HTML, it has a lower learning curve for developers who are more comfortable with HTML/CSS.
Server-Side Rendering: HTMX works with any server-side technology. It allows developers to work in their respective backend languages.

Hello World

Every new technology always starts with the classic "hello world" example. Run the following commands to set up the solution:

dotnet new web -o TodoApi
dotnet new sln -n Htmx
dotnet sln add --in-root TodoApi

In the TodoApi project, and add the HtmlResult.cs file with the following content:

using System.Net.Mime;
using System.Text;

namespace TodoApi;

public class HtmlResult : IResult
{
    private readonly string _html;

    public HtmlResult(string html)
    {
        _html = html;
    }

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.ContentType = MediaTypeNames.Text.Html;
        httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(_html);
        return httpContext.Response.WriteAsync(_html);
    }
}

This class will be used to return HTML from our Minimal API endpoints. Go to the Program.cs file and update the content as follows:

using Microsoft.AspNetCore.Html;
using TodoApi;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello-world", () => new HtmlResult(@"<!doctype html>
<html>
    <head>
        <meta charset=""UTF-8"">
        <meta name=""viewport"" content=""width=device-width, initial-scale=1.0"">
        <script src=""https://unpkg.com/htmx.org@1.9.6"" integrity=""sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"" crossorigin=""anonymous""></script>
    </head>
    <body>
        <button hx-post=""/hello-world"" hx-swap=""outerHTML"">Get time</button>
    </body>
</html>
"));
app.MapPost("/hello-world", () => new HtmlResult($@"<div>Hello World {DateTimeOffset.UtcNow}</div>"));
app.Run();

There are two endpoints in our API. The first one returns the initial HTML document, which includes a reference to the HTMX library via CDN. Within the body, there is a button with the HTMX attributes (to be explained later) that instructs the browser to make an HTTP POST request to /hello-world when the button is clicked and then replaces the button with the response. The second endpoint returns only a div tag containing the message. To see this in action, run the application and navigate to http://localhost:5179/hello-world.

Attributes

The primary attributes used in HTMX are designed for making AJAX requests:

hx-get: Issues a GET request to the given URL.
hx-post: Issues a POST request to the given URL.
hx-put: Issues a PUT request to the given URL.
hx-patch: Issues a PATCH request to the given URL.
hx-delete: Issues a DELETE request to the given URL.

The following attributes are most commonly used. For more information, please visit the official website here.

hx-trigger

The hx-trigger attribute enables us to define what initiates an AJAX request. By default, there is no need to specify the attribute when the following triggers are used:

input, textarea & select are triggered on the change event.
form is triggered on the submit event.
everything else is triggered by the click event.

A trigger value can be one of the following:

An event name.
A polling definition.
A comma-separated list of such events

hx-target

The hx-target attribute enables us to target a different element for swapping, rather than the one initiating the AJAX request. The value of this attribute can be:

A CSS query selector of the element to target.
this indicates that the element with the hx-target attribute is the target itself.
closest <CSS selector> finds the closest ancestor element or itself, that matches the given CSS selector.
find <CSS selector> finds the first child descendant element that matches the given CSS selector.
next <CSS selector> scans the DOM forward for the first element that matches the given CSS selector.
previous <CSS selector> scans the DOM backward for the first element that matches the given CSS selector.

hx-swap

The hx-swap attribute allows you to specify how the response will be swapped relative to the target of an AJAX request. The possible values of this attribute are:

innerHTML: Puts the content inside the target element. The default option.
outerHTML: Replace the entire target element with the response.
beforebegin: Insert the content before the target in the parent element.
afterbegin: Insert the response before the first child of the target element.
beforeend: Insert the response after the last child of the target element.
afterend: Insert the response after the target in the parent element.
delete: Deletes the target element regardless of the response.
none: Does not append content from the response.

Todo App

Let's build an application to see all these concepts in action. To build HTML in .NET we can use the HtmlContentBuilder class rather than using a simple string. This has several benefits:

Parameterizable: Since HtmlContentBuilder uses method calls, you can pass parameters to those methods to dynamically build up HTML.
Supports Encoding: HtmlContentBuilder will automatically HTML encode any unencoded strings you append.
Composable: We can compose multiple HtmlContentBuilder instances to build up more complex HTML.
Easier to Maintain: Building HTML as a single string can become difficult to maintain as the HTML grows more complex. HtmlContentBuilder allows you to build up the HTML incrementally using method calls.

Let's create a new IResult implementation based on the IHtmlContent interface:

using Microsoft.AspNetCore.Html;
using System.Net.Mime;
using System.Text.Encodings.Web;
using System.Text;
namespace TodoApi;
public class HtmlContentResult : IResult
{
    private readonly IHtmlContent _htmlContent;

    public HtmlContentResult(IHtmlContent htmlContent)
    {
        _htmlContent = htmlContent;
    }

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.ContentType = MediaTypeNames.Text.Html;
        using (var writer = new StringWriter())
        {
            _htmlContent.WriteTo(writer, HtmlEncoder.Default);
            var html = writer.ToString();
            httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(html);
            return httpContext.Response.WriteAsync(html);
        }
    }
}

Create a TodoItem.cs file to store our model:

namespace TodoApi;
public class TodoItem
{
    public Guid Id { get; set; }
    public bool IsCompleted { get; set; }
    public string? Name { get; set; }
};

Create a Components.cs class to contain all of our HTML builders:

using Microsoft.AspNetCore.Html;
namespace TodoApi;
public static class Components
{
    public static IHtmlContent Document(IHtmlContentContainer children)
    {
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<!doctype html>");
        builder.AppendHtml("<html>");
        builder.AppendHtml("<head>");
        builder.AppendHtml("<meta charset=\"UTF-8\">");
        builder.AppendHtml("<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">");
        builder.AppendHtml("<script src=\"https://unpkg.com/htmx.org@1.9.6\" integrity=\"sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni\" crossorigin=\"anonymous\"></script>");
        builder.AppendHtml("</head>");
        builder.AppendHtml(children);
        builder.AppendHtml("</html>");
        return builder;
    }

    public static IHtmlContent TodoList(IEnumerable<TodoItem> todoItems)
    {
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<div>");
        foreach (var todoItem in todoItems)
        {
            builder.AppendHtml(TodoItem(todoItem));
        }
        builder.AppendHtml("</div>");
        return builder;
    }

    public static IHtmlContent TodoItem(TodoItem todoItem)
    {
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<div>");
        builder.AppendHtml("<p>");
        builder.AppendFormat("{0}", todoItem.Name);
        builder.AppendHtml("</p>");
        builder.AppendHtml("</div>");
        return builder;
    }
}

Navigate to the Program.cs file and add the following code:

var db = new List<TodoItem>()
{
    new TodoItem() { Id = Guid.NewGuid(), Name = "abc", IsCompleted = true },
    new TodoItem() { Id = Guid.NewGuid(), Name = "123", IsCompleted = false },
};

app.MapGet("/", () =>
{
    var builder = new HtmlContentBuilder();
    builder.AppendHtml("<body hx-get=\"/todos\" hx-trigger=\"load\" hx-swap=\"innerHTML\">");
    builder.AppendHtml("</body>");
    return new HtmlContentResult(Components.Document(builder));
});

app.MapGet("/todos", () => new HtmlContentResult(Components.TodoList(db)));

The first endpoint renders the initial HTML document, while the second returns a list of items. During the body tag's load event (hx-trigger="load"), HTMX makes a request (hx-get="/todos") and inserts the response inside the element (hx-swap="innerHTML"). Let's add the features to toggle and delete items. Update the TodoItem component as follows:

    public static IHtmlContent TodoItem(TodoItem todoItem)
    {
        var isCompleted = string.Empty;
        if (todoItem.IsCompleted)
        {
            isCompleted = "checked";
        }
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<div>");
        builder.AppendHtml("<p>");
        builder.AppendFormat("{0}", todoItem.Name);
        builder.AppendHtml("</p>");
        builder.AppendHtml($"<input type=\"checkbox\" {isCompleted} hx-post=\"/todos/{todoItem.Id}/toggle\" hx-target=\"closest div\" hx-swap=\"outerHTML\"/>");
        builder.AppendHtml($"<button hx-delete=\"/todos/{todoItem.Id}\" hx-target=\"closest div\" hx-swap=\"outerHTML\">X</button>");
        builder.AppendHtml("</div>");
        return builder;
    }

During the change event of the checkbox input, HTMX initiates a request (hx-post="/todos/{todoItem.Id}/toggle") and replaces the element (hx-target="closest div") with the response (hx-swap="outerHTML"), updating the list. In the same line, the click event performs a similar action; however, since the response is empty, the item is removed from the list. In the Program.cs file, add these two endpoints:

app.MapPost("/todos/{id}/toggle", (string id) =>
{
    var todo = db.First(t => t.Id.ToString() == id);
    todo.IsCompleted = !todo.IsCompleted;
    return new HtmlContentResult(Components.TodoItem(todo));
});

app.MapDelete("/todos/{id}", (string id) =>
{
    var todo = db.First(t => t.Id.ToString() == id);
    db.Remove(todo);
});

The final feature will enable the addition of new items to the list. Navigate to the TodoItem.cs file and append the following code:

record AddTodoItem(string? Name);

Next, in the Program.cs file, add the following endpoint:

app.MapPost("/todos", (AddTodoItem command) =>
{
    var todo = new TodoItem {Id = Guid.NewGuid(),Name = command.Name, IsCompleted = false };
    db.Add(todo);
    return new HtmlContentResult(Components.TodoItem(todo));
});

Navigate to the Components.cs file and modify the Document component to install the json-enc extension to encode parameters in JSON format instead of URL format:

    public static IHtmlContent Document(IHtmlContentContainer children)
    {
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<!doctype html>");
        builder.AppendHtml("<html>");
        builder.AppendHtml("<head>");
        builder.AppendHtml("<meta charset=\"UTF-8\">");
        builder.AppendHtml("<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">");
        builder.AppendHtml("<script src=\"https://unpkg.com/htmx.org@1.9.6\" integrity=\"sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni\" crossorigin=\"anonymous\"></script>");
        builder.AppendHtml("<script src=\"https://unpkg.com/htmx.org/dist/ext/json-enc.js\"></script>");
        builder.AppendHtml("</head>");
        builder.AppendHtml(children);
        builder.AppendHtml("</html>");
        return builder;
    }

In the same file add a TodoForm component:

    public static IHtmlContent TodoForm()
    {
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<form hx-post=\"/todos\" hx-swap=\"beforebegin\" hx-ext=\"json-enc\">");
        builder.AppendHtml("<input type=\"text\" name=\"name\">");
        builder.AppendHtml("<button type=\"submit\">Add</button>");
        builder.AppendHtml("</form>");
        return builder;
    }

During the submit event, HTMX initiates a request (hx-post="/todos") in JSON format (hx-ext="json-enc") and appends the response in the parent element before the form (hx-swap="beforebegin"). Finally, modify the TodoList component to include the TodoForm component:

    public static IHtmlContent TodoList(IEnumerable<TodoItem> todoItems)
    {
        var builder = new HtmlContentBuilder();
        builder.AppendHtml("<div>");
        foreach (var todoItem in todoItems)
        {
            builder.AppendHtml(TodoItem(todoItem));
        }
        builder.AppendHtml(TodoForm());
        builder.AppendHtml("</div>");
        return builder;
    }

In conclusion, HTMX is a powerful and lightweight JavaScript library that simplifies the process of building interactive web applications. By utilizing HTML attributes to make AJAX requests, HTMX offers an easy learning curve, improved performance, and seamless integration with server-side technologies. This beginner's guide provides a solid foundation for getting started with HTMX, showcasing its capabilities through a simple Todo App example. All the code is available here. Thanks, and happy coding.

Getting Started with Azure Bicep

Raul Naupari — Sun, 14 Jul 2024 02:09:49 +0000

Azure Bicep is a domain-specific language (DSL) designed for deploying and managing Azure resources. It offers several advantages, including a more concise syntax compared to ARM templates, improved readability, enhanced maintainability, and a gentler learning curve.

How Does it Work?

A Bicep file is automatically converted into an ARM template (JSON) when a deployment is submitted to Azure.

Pre-requisites

Ensure you have an Azure Account
Install Azure CLI
Install Bicep CLI (az bicep install)
Check out our Getting Started with ARM Templates guide if you're unfamiliar with the basics of ARM templates.

Resources

The syntax for defining a resource is:

resource <symbolic-name> '<full-type-name>@<api-version>' = {
  <resource-properties>
}

To define a resource, use the resource keyword followed by:

<symbolic-name>: The symbolic name isn't the same as the resource name, and it is used to reference the resource in other sections of your Bicep file.
<full-type-name> and <api-version>: For the available resource types and versions, see Bicep resource reference.
<resource-properties>: name and location are properties that can be found in nearly every resource. After setting those values, we need to set the properties that are specific to the resource type we are using.

Create a main.bicep file with the following content:

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'myuniquestorage001'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_GRS'
  }
}

Execute the command az group create -l eastus -n MyResourceGroup to create the resource group where our resources will be stored. Afterward, run the following command:

az deployment group create --resource-group MyResourceGroup --template-file .\main.bicep

Parameters

The syntax for defining a parameter is:

@<decorator-name>
param <parameter-name> <parameter-data-type> = <default-value>

To define a parameter, use the param keyword followed by:

<parameter-name>: The name of the parameter. It cannot have the same name as a variable, resource, output, or another parameter in the same scope.
<parameter-type>: We can find the complete list of data types here.
<default-value>: The default value is used when a value is not supplied during deployment.
<decorator-name>: Parameters use decorators for constraints or metadata. The list of decorators can be found here.

Update the main.bicep file with the following content:

@description('storage account name')
param storageAccountName string = 'myuniquestorage001'

@description('storage account location')
param location string = resourceGroup().location

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountName
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_GRS'
  }
}

To pass inline parameters, you can execute a command like this:

az deployment group create --resource-group MyResourceGroup --template-file .\main.bicep --parameters storageAccountName='myuniquestorage002'

Variables

The syntax for defining a variable is:

var <variable-name> = <variable-value>

To define a variable, use the var keyword followed by:

<variable-name>: A variable cannot share the same name as a parameter, module, or resource.
<variable-value>: Note that we do not need to specify a data type for the variable. The type is inferred from the value provided.

Update the main.bicep file using the following content:

@description('storage account prefix')
param storageAccountPrefix string

@description('storage account location')
param location string = resourceGroup().location

var storageAccountName = '${toLower(storageAccountPrefix)}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountName
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_GRS'
  }
}

Execute the following command:

az deployment group create --resource-group MyResourceGroup --template-file .\main.bicep --parameters storageAccountPrefix='mystorage'

Outputs

The syntax for defining an output is:

output <output-name> <output-data-type> = <output-value>

To define a variable, use the output keyword followed by:

<output-name>: An output can have the same name as a parameter, variable, module, or resource.
<output-data-type>: Can use the same data types of the parameters.
<output-value>: The value we want to expose.

Update the main.bicep file with the content provided below:

@description('storage account prefix')
param storageAccountPrefix string

@description('storage account location')
param location string = resourceGroup().location

var storageAccountName = '${toLower(storageAccountPrefix)}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountName
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_GRS'
  }
}

output endpoints object = storageAccount.properties.primaryEndpoints

Execute the following command to deploy the resource and filter the output (How to query Azure CLI command output using a JMESPath query):

az deployment group create --resource-group MyResourceGroup --template-file .\main.bicep --parameters storageAccountPrefix='mystorage' --query "properties.outputs"

In conclusion, by understanding the core concepts of resources, parameters, variables, and outputs, you can effectively leverage Bicep to streamline your Azure deployments and make your infrastructure as code more accessible and maintainable. We encourage you to check the official documentation here to explore the full potential of this tool. Thanks, and happy coding.