Create a helper script

The dotnet SDK comes with a built-in command to list the packages for a project/solution. Even if you execute the command for a .sln file, you get the outdated packages per project. The package version shown will always be the latest available. However, ever since central package management was introduced, most projects in a SLN would have the same version of a package. For this purpose we can create a very simple helper script using PowerShell.

1. List packages for solution in JSON format
2. Process every project with a valid TargetFramework (assumes single)
3. Capture outdated packages (unique by PackageId)
4. Print result

param (
    [Parameter(Mandatory=$true, HelpMessage = "The path to the project file")]
    [string] $ProjectPath
)

$OutdatedOutput = dotnet list $ProjectPath package --outdated --format json
$OutdatedOutputAsJson = $OutdatedOutput | ConvertFrom-json
$Projects = $OutdatedOutputAsJson.Projects

$Result = @{}
foreach ($Project in $Projects)
{
    $Frameworks = $Project.Frameworks
    if ($Frameworks -ne $null)
    {
        $Framework = $Frameworks[0]
        $TopLevelPackages = $Framework.TopLevelPackages
        foreach ($Package in $TopLevelPackages)
        {
            $PackageId = $Package.Id

            if ($Result.ContainsKey($PackageId))
            {
                Write-Verbose "Skipping '$PackageId' already processed"
                continue
            }

            $Result[$PackageId] = [pscustomobject]@{
                Id               = $PackageId
                From             = $Package.ResolvedVersion
                To               = $LatestVersion
            }
        }
    }
}

$Outdated = $Result.Values
if ($Outdated.Count -gt 0) {
    $sb = [System.Text.StringBuilder]::new()
    [void]$sb.AppendLine("The following dependencies have newer versions available:")
    foreach ($entry in $Outdated) {
        [void]$sb.AppendLine(" - $($entry.Id): $($entry.From) → $($entry.To)")
    }
    $sb | Write-Warning
}

Where example output looks like this

WARNING: The following dependencies have newer versions available:
 - FluentAssertions: 7.2.0 → 8.2.0

Lock versions

The script shared above has one big shortcoming, it does not handle pinned versions. Sometimes, for whatever reason, you want to prevent a package from being bumped. The example I prefer to give is locking a Microsoft.Extensions.* package to its corresponding .NET framework version. More recently, in the .NET open source community, there have been other cases: My first thought was Moq with SponsorLink (2023), then FluentAssertions with the new paid license model (January 2025). This week, AutoMapper, Mediator, and MassTransit joined the club. Nudging me to finally finish this article. Even though the announcement coincided with April Fool’s Day, it didn’t appear to be a joke. While I fully support and understand the need for these maintainers to earn money for their hard work, depending on how the update is handled it opens you up for liabilities.

Luckily we can pin a package version using version ranges. We can set an inclusive boundary by using [ or ] and an exclusive boundary by using ( or ). Following this logic

• Moq can be pinned with [4.18.2] or the equivalent [4.18.2, 4.18.2]
• FluentAssertions can receive update until the next major version with [7.0.0, 8.0.0)

We now need to update the script to parse these version ranges. If the latest version is higher than the resolved one but still within range, we should update. Also keep in mind that NuGet will always resolve the earliest possible resolution. In this case that means we get version 7.0.0.

The challenge is, that at the time of writing FluentAssertions has the following versions available (7.0.0, ..., 7.2.0, 8.0.0, ..., 8.2.0). This means NuGet resolves to 7.0.0, while dotnet list package reports 8.2.0 which violates the version range, and we don't know about 7.2.0 package that would be a valid upgrade.

We make the following changes to the script. Check via regex if we detect a version range (min, max package versions), and handle the following cases

1. Min == Max => no update, version pinned.
2. Latest < Max => update, latest version within range.
3. Latest > Max => check NuGet, there might be a version.

param (
    [Parameter(Mandatory=$true, HelpMessage = "The path to the project file")]
    [string] $ProjectPath
)

$OutdatedOutput = dotnet list $ProjectPath package --outdated --format json
$OutdatedOutputAsJson = $OutdatedOutput | ConvertFrom-json
$Projects = $OutdatedOutputAsJson.Projects

$Result = @{}
foreach ($Project in $Projects)
{
    $Frameworks = $Project.Frameworks
    if ($Frameworks -ne $null)
    {
        $Framework = $Frameworks[0]
        $TopLevelPackages = $Framework.TopLevelPackages
        foreach ($Package in $TopLevelPackages)
        {
            $PackageId = $Package.Id

            if ($Result.ContainsKey($PackageId))
            {
                continue
            }

            $ResolvedVersion = $Package.ResolvedVersion
            $LatestVersion = [version]$Package.LatestVersion
            $RequestedVersion = $Package.RequestedVersion
            $NewVersion = $null
            $Description = "N/A"

            $SpecialVersionRegexMatch = $RequestedVersion -match "^(?:(?<Open>[\[\(])(?<Min>[^,\)\]]*)?,?(?<Max>[^,\)\]]*)(?<Close>[\]\)])?)$"

            if (-not $SpecialVersionRegexMatch)
            {
                $NewVersion = $LatestVersion
                $Description = "Regular"
            }
            else
            {
                $min = $null
                $max = $null
                $minInclusive = $Matches.Open -eq "["
                $maxInclusive = $Matches.Close -eq "]"

                $minText = $Matches.Min
                $maxText = $Matches.Max

                if ($minText -match "-" -or $maxText -match "-")
                {
                    $NewVersion = $LatestVersion
                    $Description = "Preview version check manually"
                } 
                else 
                {
                    if ($minText) { 
                        $min = [version]$minText
                    } 
                    else {
                        # Fallback to ResolvedVersion 
                        $min = $ResolvedVersion 
                    }

                    if ($maxText) { 
                        $max = [version]$maxText 
                    }
                    elseif (-not $maxInclusive)
                    {
                        # No upper version, resolve to latest
                        $max = $LatestVersion
                    }
                    elseif ($min -ne $null -and $minInclusive -and $maxInclusive)
                    {
                        # Fixed version [1.0.0]
                        $max = $min
                    }
                    else
                    {
                        throw "Unreachable code: unexpected version constraint state for '$PackageId'"
                    }
                    
                    if ($min -eq $max) {
                        $NewVersion = $min
                        $Description = "Pinned"
                    }
                    elseif ($LatestVersion -le $max)
                    {
                        $NewVersion = $LatestVersion
                        $Description = "Below upper-constraint"
                    }
                    elseif ($LatestVersion -gt $max -and $ResolvedVersion -lt $max)
                    {
                        $url = "https://api.nuget.org/v3-flatcontainer/$packageId/index.json".ToLower()
                        
                        $response = Invoke-RestMethod -Uri $url -ErrorAction Stop
                        $allVersions = $response.versions | Where-Object { $_ -notmatch "-" } | ForEach-Object { [version]$_ }

                        if ($minInclusive) {
                            $allVersions = $allVersions | Where-Object { $_ -ge $min }
                        } else {
                            $allVersions = $allVersions | Where-Object { $_ -gt $min }
                        }

                        if ($maxInclusive) {
                            $allVersions = $allVersions | Where-Object { $_ -le $max }
                        } else {
                            $allVersions = $allVersions | Where-Object { $_ -lt $max }
                        }
                        
                        $NewVersion = $allVersions | Sort-Object -Descending | Select-Object -First 1
                        if ($ResolvedVersion -eq $NewVersion) {
                            $Description = "No new allowed version on NuGet"
                        } else {
                            $Description = "Found version in range on NuGet"
                        }
                    }
                }
            }

            $Result[$PackageId] = [pscustomobject]@{
                Id               = $PackageId
                From             = $ResolvedVersion
                To               = $NewVersion
                Description      = $Description
            }
        }
    }
}

$Outdated = $Result.Values
if ($Outdated.Count -gt 0) {
    $sb = [System.Text.StringBuilder]::new()
    [void]$sb.AppendLine("The following dependencies have newer versions available:")
    foreach ($entry in $Outdated) {
        [void]$sb.AppendLine(" - $($entry.Id): $($entry.From) → $($entry.To) ($($entry.Description))")
    }
    $sb | Write-Warning
}

If we have the version set to [7.0.0, 8.0.0) we get the following output:

WARNING: The following dependencies have newer versions available:
- FluentAssertions: 7.0.0 → 7.2.0 (Found version in range on NuGet)

After upgrading the range to [7.2.0, 8.0.0) we get the following output:

WARNING: The following dependencies have newer versions available:
 - FluentAssertions: 7.2.0 → 7.2.0 (No new allowed version on NuGet)

Next steps: ensure the script always runs

For my blog's repo I took it one step further. I included a Directory.Solution.props, which triggers a custom target post build. In my case I installed PowerShell as a dotnet tool.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="CheckDependencies" AfterTargets="Build">
    <PropertyGroup>
      <PowerShellCommand>dotnet pwsh</PowerShellCommand>
      <PowerShellExecutionPolicy>Bypass</PowerShellExecutionPolicy>
      <OutdatedScript>$(MSBuildProjectDirectory)/tools/Outdated.ps1</OutdatedScript>
      <TargetProject>$(MSBuildProjectDirectory)/SSG.sln</TargetProject>
    </PropertyGroup>
    <Exec Command="$(PowerShellCommand) -ExecutionPolicy $(PowerShellExecutionPolicy) -NoProfile -File $(OutdatedScript) -ProjectPath $(TargetProject)" />
  </Target>
</Project>

If you are on net9.0 you will probably not see any output. This is due to changes in MSBuild output, where the output from the script gets suppressed. Running dotnet build --verbosity detailed will provide the output.

My favorite editor for writing Markdown is VSCode. While this separation is useful for organization, it can be somewhat cumbersome when editing and previewing Markdown.

To illustrate this point, let’s look at an example. A typical directory structure looks like this:

# generated with the command tree -L 2
.
├── _posts
│   └── hello-world.md
├── assets
│   └── logo.svg
└── index.html

Using the Markdown preview feature of VSCode that would look like this:

The issue

If you’re like me, your project contains many more files than the few shown in the example. In such cases, I prefer working inside the _posts folder. Unfortunately, as the screenshot below shows, this breaks the image preview functionality.

Instead of displaying my logo, the preview now shows a broken image icon. Technically, this behavior is correct because, relative to our “hello-world.md” post, there is no “assets” directory. You might think that changing the path to “../assets/” would solve the issue, since that’s where the folder exists on disk. However, VSCode does not allow this due to security concerns. Even if it did work, it would create the issue that the preview would no longer function correctly when opened from the root directory.

The solution

To my knowledge, there is no built-in function in VSCode to address this issue. However, there is an operating system-level solution: using symbolic links.

We can create a symlink by running the following command inside the "_posts" directory

ln -s ../assets assets

From the filesystem perspective the "_posts" folder now has a subfolder called posts. If we now open it inside VSCode it renders the image correctly.

To consider

Personally, I believe its a nice workaround for an issue that irritated me. Before you leave I like to leave you with some final thoughts.

• This behavior is disabled by default, to prevent opening untrusted content. So don't blindly apply this solution everywhere
• If your blog is under source control via GIT you can include those symlinks in GIT so your teammates have the same benefits. If you are using Git for Windows you may need additional steps to support symlinks

For those who don't know, Specflow is (or I suppose was) the official Cucumber implementation for .NET, which has been open-source all the way since 2009. With Cucumber, you write tests using the Gherkin language. This allows for human readable tests and many more incredible advantages. One of the last things I did at my previous company was give a dev talk on all things Specflow and my experiences using it.

Somewhere in the past, Specflow was sold, and unfortunately, for the past two years, the project has seen no activity. Gáspár has made the decision to fork and revive it under the name of Reqnroll(pronounced as [reknroʊl]). He has done a lot of grunt work, and now it is up to him and the community to keep it alive.

A migration guide was published, and it is as simple as changing a package and changing a few namespaces. I think the migration took me about 15 minutes, and it was done. There is even a package published for backwards compatibility, so even fewer changes are required.

Most of the tests for the blog and static website generator you are reading this article on were written using Specflow (and now rewritten!). I was planning out a bunch of articles on this topic, but with a new job and everything, time got away from me. I'd like to personally thank Gáspár for the effort to first revive Specflow and now for the process of starting the fork and a brand new community. I hope the efforts will not be in vain and we can make the project successful. I will make it a priority that upcoming content will make use of Reqnroll! Not only because I love this way of writing tests but also to show that Gáspár has my full support moving forward!

Which Azure SDK should I use?

Since July 2019, Microsoft has made a design effort to unify the SDKs for the different services. There are shared concepts between the libraries like authentication and diagnostics. The libraries follow the pattern Azure.{service}.{library}. My contribution was to the ServiceBus SDK, so today's article focus is the service bus. Almost everything described is transferable to the other SDKs; only a few bits are ServiceBus specific. The NuGet package we need is the Azure.Messaging.Service package.

How to set up Azure Service Bus with Azure CLI?

I think the local development aspect of any service is as important as ease of use in production. Unfortunately, there is no way to emulate the service bus locally; Jimmy Bogard wrote about that in this article. Without emulating, we need to set up our resources in Azure, even for our development environment. There are a few possible options to create resources in Azure:

• Manually via the Azure Portal
• Infrastructure as Code (ARM, Bicep, etc.)
• Scripting (Azure CLI, Azure Powershell Module)

For prototypes such as this article, I prefer Azure CLI since the commands are repeatable and, more importantly, easy to understand.

NOTE:

When I work with the Azure CLI, I use the Azure CLI Tools extension for VS Code. It provides Intellisense and snippets to work with the CLI.

AzureSubscriptionId="<subscription-id>"
AzureTenantId="<tenant-id>"
AzureResourceGroup="demorg001"
AzureLocation="westeurope"

# Sign in to Azure using device code - After login session is scoped to Subscription in Tenant
az login --use-device-code --tenant $AzureTenantId
az account set --subscription $AzureSubscriptionId

# Set default values for location and resource group
az config set defaults.location=$AzureLocation defaults.group=$AzureResourceGroup

# Create resource group and capture resource group identifier
ResourceGroupId=$(az group create --name $AzureResourceGroup --query "id" --output tsv)

# Generate Unique ID based on ResourceGroupId
UniqueId=$(echo -n $ResourceGroupId | md5sum | cut -c-13)

# Create ServiceBus and Queue
ServiceBusNamespace="sbdemo0001$UniqueId"
QueueName="demoqueue"
echo "Going to create ServiceBus $ServiceBusNamespace and Queue $QueueName"
AzureServiceBusId=$(az servicebus namespace create --name $ServiceBusNamespace --sku Basic --query id -o tsv)
AzureServiceBusQueueId=$(az servicebus queue create --name $QueueName --namespace-name $ServiceBusNamespace --default-message-time-to-live P0Y0M0DT0H0M30S --query id -o tsv)

# Fetch ServiceBus Connectionstring
PrimaryConnectionString=$(az servicebus namespace authorization-rule keys list \
    --namespace-name $ServiceBusNamespace \
    --name "RootManageSharedAccessKey" \
    --query "primaryConnectionString" \
    --output tsv)

echo "$PrimaryConnectionString"

Note

The above snippet uses the default generated RootManageSharedAccessKey, which provides full access to your servicebus so use with caution!

How does the Azure Service Bus SDK work?

A message bus is dependent on both a sender and receiver for communication. There are many examples in the official GitHub repo, so I won't go into much more details regarding the bus itself.

This demo will focus on SDK features, so I created an Xunit project that runs multiple scenarios. Since all scenarios require some logic to communicate with the bus, I made the following extension method to avoid unnecessary boilerplate. In a real-world application sending and receiving messages using the ServiceBusClient would not be hidden behind a single extension method.

using System;
using System.Threading.Tasks;
using Azure.Messaging.ServiceBus;
using FluentAssertions;

namespace Test.Integration;

public static partial class ServiceBusClientTestExtensions
{
    public static async Task RunScenario(this ServiceBusClient client, string queueName, string scenarioName)
    {
        var sender = client.CreateSender(queueName);
        var receiver = client.CreateReceiver(queueName);

        var message = $"{scenarioName}-{DateTimeOffset.Now:s}";
        await sender.SendMessageAsync(new ServiceBusMessage(message));
        var receivedMessage = await receiver.ReceiveMessageAsync();

        receivedMessage.Body.ToString().Should().Be(message);
        await Task.Delay(TimeSpan.FromSeconds(35));
    }
}

The default method described by the docs is to pass the ServiceBusConnection string to the ServiceBusClient and create it as needed.

public class UnitTest1
{
    private const string ConnectionString = "<your-connectionstring>";
    private const string QueueName = "demoqueue";

    [Fact]
    public async Task Test_Scenario01_UsePrimaryConnectionString()
    {
        await using var client = new ServiceBusClient(ConnectionString);
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario01_UsePrimaryConnectionString));
        await scenario();
    }
}

Warning

Never store credentials in source control!

How to use Azure SDK without connection strings?

Working with secrets like our connection string provides extra overhead. Luckily this incarnation of the Azure SDK embraces token authentication via TokenCredential. For this, we need to install the package Azure.Identity. Using this method is the preferred method of authenticating the Azure SDK. The easiest way to use this SDK is by creating a DefaultAzureCredential, which attempts to authenticate with a couple of common authentication mechanisms in order.

1. Environment
2. Managed Identity
3. Visual Studio
4. Azure CLI
5. Azure Powershell

public class UnitTest1
{
    private const string FullyQualifiedNamespace = "<your-namespace>.servicebus.windows.net";
    private const string QueueName = "demoqueue";

    [Fact]
    public async Task Test_Scenario02_UseFullyQualifiedNamespace()
    {
        await using var client = new ServiceBusClient(FullyQualifiedNamespace, new DefaultAzureCredential());
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario02_UseFullyQualifiedNamespace));
        await scenario();
    }
}

Seeing the snippet, you might wonder how is providing your-namespace.servicebus.windows.net any better than a connection string? It's a good question; you still should not store something like that as plain text in source control. For one thing, it will probably be environment-specific. We still need it because we need an address so our application can communicate with Azure. The big difference here is that our address does not contain the key; the address alone is not enough to provide access to our resources.

Depending on how your organization handles roles and access management in Azure, you can now run this test and achieve the same result as before, without those pesky connection strings. For example, since I created a service bus, my user is the owner of that bus. Being the service bus instance owner is not enough to authenticate and successfully run our scenario. I require one of the service bus specific data roles. You can find a list of supported under Access Control (IAM) in the portal. I opted to use the "Azure Service Bus Data Owner" role for this tutorial. The tricky bit is that role management in Azure is very granular. When I assign a role, I need to select a scope:

• subscription
• resourceGroup
• resource (i.e. ServiceBusNamespace)
• child resource (i.e. queue)

Scopes are inherited, so if I assign my user a role on a resource group, all resources (if applicable) in that resource group will provide me with the same access.

We can update our Azure CLI script to provide the logged-in user access to the resource.

# Assign Role "Azure Service Bus Data Owner" for the current user
UserIdentity=$(az ad signed-in-user show --query objectId -o tsv)
az role assignment create --assignee $UserIdentity --role "Azure Service Bus Data Owner" --scope $AzureServiceBusId

Now you know why the previous script captured the AzureServiceBusId ;-)

One thing to note is that DefaultAzureCredential's intended use is to simplify getting started with development. In a real-world application, you would probably need a custom ChainedTokenCredential that uses ManagedIdentityCredential for production and AzureCliCredential for development.

How can I use the Azure SDK with Dependency Injection?

One thing that always bothered me with the code I have shown so far is creating clients on the fly. I prefer to receive my service bus client from the dependency injection container. Discovering that this was a viable solution caused me to submit that PR to the Azure SDK repo. The team had already provided the normal ServiceBusClient, so I recreated the extension method to make ServiceBusAdministrationClient available via DI. It's time to install our third NuGet package, Microsoft.Extensions.Azure which provides the necessary bits.

After installing the package, we get the AddAzureClients extension method on IServiceCollection. It provides access to the AzureClientFactoryBuilder on which we can register everything Azure SDK related. In the case of ServiceBus we get AddServiceBusClient and AddServiceBusClientWithNamespace. I like that these methods are much more explicit than the constructor.

public class UnitTest1
{
    private const string FullyQualifiedNamespace = "<your-namespace>.servicebus.windows.net";
    private const string ConnectionString = "<your-connectionstring>";
    private const string QueueName = "demoqueue";

    [Fact]
    public async Task Test_Scenario03_UseDependencyInjectionWithPrimaryConnectionString()
    {
        var services = new ServiceCollection();
        services.AddAzureClients(builder => {
            builder.AddServiceBusClient(ConnectionString);
        });
        var serviceProvider = services.BuildServiceProvider();
        var client = serviceProvider.GetRequiredService<ServiceBusClient>();
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario03_UseDependencyInjectionWithPrimaryConnectionString));
        await scenario();
    }

    [Fact]
    public async Task Test_Scenario04_UseDependencyInjectionWithFullyQualifiedNamespace()
    {
        var services = new ServiceCollection();
        services.AddAzureClients(builder => {
            builder.AddServiceBusClientWithNamespace(FullyQualifiedNamespace);
        });
        var serviceProvider = services.BuildServiceProvider();
        var client = serviceProvider.GetRequiredService<ServiceBusClient>();
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario04_UseDependencyInjectionWithFullyQualifiedNamespace));
        await scenario();
    }
}

You might wonder why the FullyQualifiedNamespace one does not need credentials this time around. That's because the Azure SDK can take care of this by default. As mentioned in the previous section, DefaultAzureCredential is the easiest way to hit the ground running. There are two ways we can customize this behaviour. We can either provide a default credential for all Azure Clients or on a per-client basis.

public class UnitTest1
{
    private const string FullyQualifiedNamespace = "<your-namespace>.servicebus.windows.net";
    private const string ConnectionString = "<your-connectionstring>";
    private const string QueueName = "demoqueue";

    [Fact]
    public async Task Test_Scenario05_DependencyInjectionChangeDefaultToken()
    {
        var services = new ServiceCollection();
        services.AddAzureClients(builder => {
            builder.AddServiceBusClientWithNamespace(FullyQualifiedNamespace);
            
            builder.UseCredential(new ManagedIdentityCredential());
        });
        var serviceProvider = services.BuildServiceProvider();
        var client = serviceProvider.GetRequiredService<ServiceBusClient>();
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario05_DependencyInjectionChangeDefaultToken));
        await scenario.Should().ThrowAsync<CredentialUnavailableException>();
    }

    [Fact]
    public async Task Test_Scenario06_DependencyInjectionChangeDefaultTokenOnClientLevel()
    {
        var services = new ServiceCollection();
        services.AddAzureClients(builder => {
            builder.AddServiceBusClientWithNamespace(FullyQualifiedNamespace)
                .WithCredential(new AzureCliCredential());
            
            builder.UseCredential(new ManagedIdentityCredential());
        });
        var serviceProvider = services.BuildServiceProvider();
        var client = serviceProvider.GetRequiredService<ServiceBusClient>();
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario06_DependencyInjectionChangeDefaultTokenOnClientLevel));
        await scenario();
    }
}

The first sample will not work since I have not set up ManagedIdentity in my environment. The second one also sets ManagedIdentityCredential as the default credential. However, since I set up AzureCliCredential on the client registration, it trumps the global one.

Can we have different client config when using the Azure SDK?

Here is where things get cool. When you register a client with the SDK, a client named Default gets registered. If, for example, you retrieve ServiceBusClient from the dependency injection, what happens is that the AzureClientFactoy creates this client for you.

In the case of servicebus, you might have multiple different namespaces registered. Every registration provides access to a method WithName. To use named clients in your code, replace ServiceBusClient with IAzureClientFactory<ServiceBusClient.

public class UnitTest1
{
    private const string FullyQualifiedNamespace = "<your-namespace>.servicebus.windows.net";
    private const string ConnectionString = "<your-connectionstring>";
    private const string QueueName = "demoqueue";

    [Fact]
    public async Task Test_Scenario07_MultipleClients()
    {
        var services = new ServiceCollection();
        services.AddAzureClients(builder =>
        {
            builder.AddServiceBusClient(ConnectionString);

            builder.AddServiceBusClientWithNamespace(FullyQualifiedNamespace)
                .WithName("OtherClient");
        });
        var serviceProvider = services.BuildServiceProvider();
        var clientFactory = serviceProvider.GetRequiredService<IAzureClientFactory<ServiceBusClient>>();
        
        var clientDefault = clientFactory.CreateClient("Default");
        var scenarioDefaultClient = async () => await clientDefault.RunScenario(QueueName, nameof(Test_Scenario07_MultipleClients) + "A");
        await scenarioDefaultClient();
        
        var otherClient = clientFactory.CreateClient("OtherClient");
        var scenarioOtherClient = async () => await otherClient.RunScenario(QueueName, nameof(Test_Scenario07_MultipleClients) + "B");
        await scenarioOtherClient();
    }
}

Can I use configuration to create Azure SDK clients?

If I had one criticism of the SDK, it would be that the extension methods require the address right there in the call to the method. To be fair, there is an overload that uses IConfiguration, but that leaves everything up to the SDK to validate.

In my previous article on validating IOptions, I wrote about a way to make sure all configuration for my app is valid.

That approach, of course, requires access to the dependency injection container. Luckily there is an additional method available.

public class UnitTest1
{
    private const string FullyQualifiedNamespace = "<your-namespace>.servicebus.windows.net";
    private const string QueueName = "demoqueue";

    [Fact]
    public async Task Test_Scenario08_StronglyTypedOptions()
    {
        var services = new ServiceCollection();
        services.Configure<DemoOptions>(options =>
        {
            options.ServiceBusNamespace = FullyQualifiedNamespace;
        });
        services.AddAzureClients(builder =>
        {
            builder.AddClient<ServiceBusClient, ServiceBusClientOptions>((options, credential, provider) =>
            {
                var demoOptions = provider.GetRequiredService<IOptions<DemoOptions>>();
                return new ServiceBusClient(demoOptions.Value.ServiceBusNamespace, credential, options);
            });
        });
        var serviceProvider = services.BuildServiceProvider();
        var client = serviceProvider.GetRequiredService<ServiceBusClient>();
        var scenario = async () => await client.RunScenario(QueueName, nameof(Test_Scenario08_StronglyTypedOptions));
        await scenario();
    }
}

Closing Thoughts

A single blog is too short for providing an overview of everything the Azure SDK offers. I like that authentication and interoperability with the dependency injection container are baked into the SDK. I have not even touched on diagnostics and testability, which are both great topics built into the entire SDK. Who knows, perhaps that is a topic for another time.

As always, if you have any questions, feel free to reach out. Do you have suggestions or alternatives? I would love to hear about them.

The corresponding source code for this article is on GitHub.

See you next time, stay healthy and happy coding to all 🧸!

Additional Resources

• Azure SDK for Dotnet on Microsoft Docs
• Azure.Messaging.ServiceBus on GitHub
• Azure.Core on GitHub
• Azure.Identity on GitHub
• Microsoft.Extensions.Azure on GitHub
• Service bus on Microsoft Docs
• Best practices Azure SDK
• Best practices Azure CLI

Thanks to the combination of .editorConfig and Roslyn Analyzers, managing this for your team is easier. Recently, however, I was required to create a custom check for my code. A quick google search pointed me to an article from Meziantou which mentioned the "Banned Symbol" Roslyn Analyzer.

Scenario

Before diving into this Analyzer, let's take a few steps back and do a quick scenario sketch. Imagine you work for a company that allows funds transfer between two parties. Since your company needs to make money, you charge a small fee.

public class FeeCalculator : IFeeCalculator
{
    private const decimal FeePercentage = 0.12M;
    private const decimal MinimumCharge = 0.50M;
    private const decimal PriorityFeePercentage = 0.25M;
    private const decimal PriorityMinimumCharge = 7.50M;

    public decimal Calculate(decimal baseAmount, bool isPriority = false)
    {
        if (isPriority)
        {
            return InternalCalculate(baseAmount, PriorityFeePercentage, PriorityMinimumCharge);
        }
        return InternalCalculate(baseAmount, FeePercentage, MinimumCharge);
    }

    private static decimal InternalCalculate(decimal amount, decimal percentage, decimal minimumFee)
    {
        var calculatedFee = amount * (percentage / 100);
        if (calculatedFee < minimumFee)
        {
            return minimumFee;
        }
        return calculatedFee;
    }
}

The company decided to offer "Monday Madness" at a heavily discounted fee as a special offer. The implementation would look similar to the snippet below.

public class DatedFeeCalculator : IFeeCalculator
{
    private const decimal DiscountedFeePercentage = 0.07M;
    private const decimal FeePercentage = 0.12M;
    private const decimal MinimumCharge = 0.50M;
    private const decimal PriorityFeePercentage = 0.25M;
    private const decimal PriorityMinimumCharge = 7.50M;

    public decimal Calculate(decimal baseAmount, bool isPriority = false)
    {
        if (isPriority)
        {
            return InternalCalculate(baseAmount, PriorityFeePercentage, PriorityMinimumCharge);
        }

        if (DateTime.Now.DayOfWeek == DayOfWeek.Monday)
        {
            return InternalCalculate(baseAmount, DiscountedFeePercentage, MinimumCharge);
        }
        return InternalCalculate(baseAmount, FeePercentage, MinimumCharge);
    }

    private static decimal InternalCalculate(decimal amount, decimal percentage, decimal minimumFee)
    {
        var calculatedFee = amount * (percentage / 100);
        if (calculatedFee < minimumFee)
        {
            return minimumFee;
        }
        return calculatedFee;
    }
}

Take notice of line 16 which now uses DateTime.Now; the problem that now arises is: how do we test this code?

Why testing DateTime is hard

The following test only results in a green build on a Monday, which is excellent if we release every week just before "Monday Madness" but not so great on every other day.

[Fact]
public void Test2_Discounted()
{
    IFeeCalculator calculator = new DatedFeeCalculator();
    var fee = calculator.Calculate(10_000M, false);
    fee.Should().Be(7.00M); // note only on Mondays it's 7.00; every other day its 12.00
}

We could mitigate by skipping the offending test every day that is not Monday like this; problem solved, right?

[SkippableFact]
public void Test2_Discounted_Alternative()
{
    Skip.If(DateTimeOffset.Now.DayOfWeek != DayOfWeek.Monday);
    IFeeCalculator calculator = new DatedFeeCalculator();
    var fee = calculator.Calculate(10_000M, false);
    fee.Should().Be(7.00M);
}

Well, no, not actually. What we want is to decouple our code from statics like DateTime.Now by putting them behind an interface. By providing an interface implementation, we can stub a static reference. In an ideal world, this interface would already exist, similar to ILogger in Microsoft.Extensions. For some background reading on why it does not yet exist, see this GitHub Issue.

Updated Scenario

In its most simple from the SystemClock can look like the snippet below.

public interface ISystemClock
{
    DateTimeOffset Now { get; }
}

public class SystemClock : ISystemClock
{
    public DateTimeOffset Now => DateTimeOffset.Now;
}

Our updated scenario looks like this:

public class SystemClockFeeCalculator : IFeeCalculator
{
    private const decimal DiscountedFeePercentage = 0.07M;
    private const decimal FeePercentage = 0.12M;
    private const decimal MinimumCharge = 0.50M;
    private const decimal PriorityFeePercentage = 0.25M;
    private const decimal PriorityMinimumCharge = 7.50M;

    private readonly ISystemClock systemClock;

    public SystemClockFeeCalculator(ISystemClock systemClock)
    {
        this.systemClock = systemClock;
    }


    public decimal Calculate(decimal baseAmount, bool isPriority = false)
    {
        if (isPriority)
        {
            return InternalCalculate(baseAmount, PriorityFeePercentage, PriorityMinimumCharge);
        }

        if (systemClock.Now.DayOfWeek == DayOfWeek.Monday)
        {
            return InternalCalculate(baseAmount, DiscountedFeePercentage, MinimumCharge);
        }
        return InternalCalculate(baseAmount, FeePercentage, MinimumCharge);
    }

    private static decimal InternalCalculate(decimal amount, decimal percentage, decimal minimumFee)
    {
        var calculatedFee = amount * (percentage / 100);
        if (calculatedFee < minimumFee)
        {
            return minimumFee;
        }
        return calculatedFee;
    }
}

With the use of a TestSystemClock or a Moq, we can test our behaviour every day of the week. See, we are improving quality already. In a previous article, "Adventures with Mock" you can read more about my preferred way of creating mocks.

public sealed class SystemClockMock : Mock<ISystemClock>
{
    public SystemClockMock SetupSystemTime(DateTimeOffset systemTime)
    {
        Setup(x => x.Now).Returns(systemTime);
        return this;
    }
}

Thanks to SystemClockMock I can now change the current date for the test.

[Fact]
public void Test3_FakeClock_Monday()
{
    var clock = new SystemClockMock()
        .SetupSystemTime(new DateTimeOffset(new DateTime(2022, 1, 31)));
    IFeeCalculator calculator = new SystemClockFeeCalculator(clock.Object);
    var fee = calculator.Calculate(10_000M, false);
    fee.Should().Be(7.00M);
}

[Fact]
public void Test3_FakeClock_Tuesday()
{
    var clock = new SystemClockMock()
        .SetupSystemTime(new DateTimeOffset(new DateTime(2022, 2, 1)));
    IFeeCalculator calculator = new SystemClockFeeCalculator(clock.Object);
    var fee = calculator.Calculate(10_000M, false);
    fee.Should().Be(12.00M);
}

Force Wrapper over Static Reference

Now that we have our SystemClock, how do we make sure every dev in our team uses it over just calling DateTimeOffset.Now?

Finally, our Roslyn Analyzer comes into play. We can use Microsoft.CodeAnalysis.BannedApiAnalyzers, which triggers the build warning RS0030. I prefer to enable these warnings on every project under src, so I use a Directory.Build.props file to install the analyzer via NuGet.

<Project>
  <Import Project="../Directory.Build.props" />
  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" Version="3.3.2">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
  <ItemGroup>
    <AdditionalFiles Include="$(MSBuildThisFileDirectory)/BannedSymbols.txt" />
  </ItemGroup>
</Project>

All that remains is to create a file called BannedSymbols.txt with the following content

note: I also blocked the use of DateTime in favour of DateTimeOffset.

T:System.DateTime;Always use System.DateTimeOffset over System.DateTime
P:System.DateTimeOffset.Now;Use ISystemClock.Now instead

From this point on every use of DateTimeOffset.Now results in the following error: error RS0030: The symbol 'DateTimeOffset.Now' is banned in this project: Use ISystemClock.Now instead. Which in my opinion is pretty cool :)

Closing Thoughts

Even if the system used in today's example is fictional, I think the BannedSymbolAnalyzers is a compelling package to include in your toolbelt. At the very least, I will use it to force DateTimeOffset over DateTime. Situation allowing I will also push my wrappers over static references to improve testability.

As always, if you have any questions, feel free to reach out. Do you have suggestions or alternatives? I would love to hear about them.

The corresponding source code for this article is on GitHub.

See you next time, stay healthy and happy coding to all 🧸!

Additional Resources

• [https://github.com/dotnet/roslyn-analyzers](Roslyn Analyzers)
• [https://docs.microsoft.com/en-us/visualstudio/code-quality/roslyn-analyzers-overview](Visual Studio Code Quality)

As I understand it, the configuration concept in .NET is the combination of different configuration sources, called configuration providers, resulting in a single combined configuration. In contrast, the options concept provides access to configuration from our application code. I've attempted to illustrate it with the image below.

Configuration in .NET

Technically the image above is an over-simplification. In reality, you use an IConfigurationBuilder where different providers are provided, and the configuration block in the middle is the merged build-result of the configuration builder. In fact, you get a preconfigured configuration builder every time you use the ASP.NET Web templates. You get a default HostBuilder that setups an IHost. This default builder also takes care of the default configuration.

The default configuration adds in order

• appsettings.json
• appsettings.Environment.json
• user secrets (if the environment is development)
• environment variables
• command-line arguments

The priority of settings is in the reverse order of adding them to the builder. Passing a setting via the command line will always win from a setting in the appsettings.json file. Fun fact, there are two configurations in ASP.NET. You have the AppConfiguration we just discussed, and you have the HostConfiguration. The HostConfiguration is used to set variables like the DOTNET_ENVIRONMENT, which is used to load the proper appsettings.json and user secrets. Via means of ChainedConfiguration the entire HostConfiguration is also available as part of AppConfiguration.

Let's look at an example. Take the following JSON configuration:

{
    "MySample": {
        "MyText": "Hello World!",
        "MyCollection": [
            {
                "MyOtherText": "Goodbye Cruel World!"
            }
        ]
    }
}

That would result in the following two settings being present in our IConfiguration.

• MySample:MyText
• MySample:MyCollection:0:MyOtherText

With this bit of knowledge, you can override any setting in any provider you can imagine. Visually it would look something like the image below. You can provide sensible defaults in appsettings.json and overwrite values as needed.

As pointed out by the "The Twelve-Factor App" article linked previously, adding configuration files per environment does not scale. I typically end up with one appsettings.json for the defaults and an appsettings.Production.json that gets transformed in my CICD pipeline.

You can read about changes to IConfiguration in .NET6 in a post from Andrew Lock. It also contains a different visual representation of configuration, which neatly displays the merging of the different levels.

Options in .NET

According to the Microsoft Docs the options pattern is the preferred way to read related configuration values. The options pattern comes in three different flavours, IOptions<>, IOptionsSnapshot<> and IOptionsMonitor<>. Probably the most used one is the default IOptions one, with the drawback that you cannot read configuration after your app starts. Others have taken the task upon themself to explain the differences between the interfaces, for example Andrew Lock and Khalid Abuhakmeh. For this post, I will keep it simple with the regular IOptions.

A typical registration of configuration would look like this:

public static partial class ServiceCollectionExtensions
{
    public static IServiceCollection AddDemo(this IServiceCollection services, IConfiguration configuration)
    {
        services.Configure<DemoOptions>(configuration.GetSection(DemoOptions.DefaultConfigurationSectionName));
        return services;
    }
}

This snippet requires the Microsoft Extensions Options ConfigurationExtensions package to work

Looking at our dependency injection container right after this registration, we see more than just IOptions. We have a total of seven registrations at this point.

ServiceType = 'Microsoft.Extensions.Options.IOptions`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.UnnamedOptionsManager`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsSnapshot`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsManager`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsMonitor`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsMonitor`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsFactory`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsFactory`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsMonitorCache`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsCache`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsChangeTokenSource`1[Test.Unit.DemoOptions]' ImplementationType = ''
ServiceType = 'Microsoft.Extensions.Options.IConfigureOptions`1[Test.Unit.DemoOptions]' ImplementationType = ''

The problem with the above approach is that it assumes the configuration exists at a predefined section, which is not very flexible. An alternative approach to register IOptions is the use of an Action<>.

public static partial class ServiceCollectionExtensions
{
    public static IServiceCollection AddExample(this IServiceCollection services, Action<ExampleOptions> configureDelegate)
    {
        services.Configure(configureDelegate);
        return services;
    }
}

With this approach, we get a total of six DI registrations.

ServiceType = 'Microsoft.Extensions.Options.IOptions`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.UnnamedOptionsManager`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsSnapshot`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsManager`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsMonitor`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsMonitor`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsFactory`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsFactory`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IOptionsMonitorCache`1[TOptions]' ImplementationType = 'Microsoft.Extensions.Options.OptionsCache`1[TOptions]'
ServiceType = 'Microsoft.Extensions.Options.IConfigureOptions`1[Test.Unit.ExampleOptions]' ImplementationType = ''

The only difference is that we do not get the IOptionsChangeTokenSource. To be most flexible, you can combine both techniques like this.

public static partial class ServiceCollectionExtensions
{
    public static IServiceCollection AddExample(this IServiceCollection services, IConfiguration config)
    {
        services.AddExample(options => config.GetSection(ExampleOptions.DefaultConfigurationSectionName).Bind(options));
        return services;
    }

    public static IServiceCollection AddExample(this IServiceCollection services, Action<ExampleOptions> configureDelegate)
    {
        services.Configure(configureDelegate);
        return services;
    }
}

Validated Options

Now that we covered the basics, I can move on to the focal point of this blog post. As you can imagine overlaying the different configuration sources does not guarantee a valid result from the point of view of your application. Worse, since the number of configuration sources can differ between environments, you can potentially have configuration issues very late in your CICD pipeline. For example, if you use Azure Key Vault as a configuration provider, settings might be changed by anyone with access to the vault.

In my article Generate C# client for OpenAPI, I used HttpClient to call a generated OpenAPI service. HTTP is the perfect example for validating configuration. In our API example, we will likely have different base URLs per environment. If we represent an URL as a string in configuration, it is feasible to enter "not-an-url" as its value, which causes your application to crash and burn.

As I see it, there are two distinct ways configuration can fail.

Missing Configuration Sections

The first variant is binding configuration at a section that does not exist. That is because configuration.GetSection does not throw but returns null for a section that does not exist. Oddly enough, when configuration fails to bind, you still get an IOptions<TOptions> but with null values.

When specifying a section by name, I expect that section to exist. Therefore I want my application to not boot with missing configuration sections. The following extension method takes care of that.

public static IConfigurationSection GetExistingSectionOrThrow(this IConfiguration configuration, string key)
{
    var configurationSection = configuration.GetSection(key);

    if (!configurationSection.Exists())
    {
        throw configuration switch
        {
            IConfigurationRoot configurationIsRoot => new ArgumentException($"Section with key '{key}' does not exist. Existing values are: {configurationIsRoot.GetDebugView()}", nameof(key)),
            IConfigurationSection configurationIsSection => new ArgumentException($"Section with key '{key}' does not exist at '{configurationIsSection.Path}'. Expected configuration path is '{configurationSection.Path}'", nameof(key)),
            _ => new ArgumentException($"Failed to find configuration at '{configurationSection.Path}'", nameof(key))
        };
    }

    return configurationSection;
}

caution: configurationIsRoot.GetDebugView() prints all configuration settings and their value, if you have secrets you should add log masking to prevent them from being logged.

DataAnnotations Validation

The second variant is the most likely to occur. That is, settings are present but not valid in the context of the application. I recently browsed the Microsoft Docs after (again) losing time chasing configuration issues when I came across IValidateOptions. I also rediscovered ValidateDataAnnotations on the IOptionsBuilder, which I previously dismissed since it was a different API (AddOptions<>) than the Configure<> APIs. With Resharper by my side, I checked the implementation and discovered that it uses DataAnnotationValidateOptions a class that is a IValidateOptions.

When consuming an IOptions, there are three hooks we can use. We have IConfigureOptions, IPostConfigureOptions and IValidateOptions. If you head back up to where I printed the dependency injection container, you see that every time you use Configure<>, you get an IConfigureOptions. I illustrated this process below, IOptions makes use of an OptionsFactory. This factory goes through all registered "option services".

You can add any number of implementations of these three interfaces. Implementations of the same interface execute in the order in which you define them. If you register an IPostConfigureOptions or IValidateOptions before the normal IConfigureOptions, it won't run before it. The factory runs through 0 or more IConfigureOptions, 0 or more IPostConfigureOptions and finally 0 or more IValidateOptions and always in that order.

To demonstrate how this works, consider the following example:

public class ConfigureLibraryExampleServiceOptions : IConfigureOptions<LibraryExampleServiceOptions>, IPostConfigureOptions<LibraryExampleServiceOptions>, IValidateOptions<LibraryExampleServiceOptions>
{
    private readonly ILogger _logger;

    public ConfigureLibraryExampleServiceOptions(ILogger<ConfigureLibraryExampleServiceOptions> logger)
    {
        _logger = logger;
    }
    
    public void Configure(LibraryExampleServiceOptions options)
    {
        _logger.LogInformation("ConfigureExampleServiceOptions Configure");
    }

    public void PostConfigure(string name, LibraryExampleServiceOptions options)
    {
        _logger.LogInformation("ConfigureExampleServiceOptions PostConfigure");
    }

    public ValidateOptionsResult Validate(string name, LibraryExampleServiceOptions options)
    {
        _logger.LogInformation("ConfigureExampleServiceOptions ValidateOptionsResult");
        return ValidateOptionsResult.Skip;
    }
}

You might assume that this validation triggers the moment we resolve an IOptions from the DI container. Unfortunately, this is not the case; it only triggers when using the .Value property.

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string>() {
        [string.Join(":", LibraryExampleServiceOptions.DefaultConfigurationSectionName, nameof(LibraryExampleServiceOptions.BaseUrl))] = "http://example.com"
    })
    .Build();
var serviceProvider = new ServiceCollection()
    .AddLogging(builder => builder.AddConsole())
    .AddExampleLibrary(configuration)
    .BuildServiceProvider();

var logger = serviceProvider.GetRequiredService<ILogger<Program>>();
logger.LogInformation("Before retrieving IOptions");
var options = serviceProvider.GetRequiredService<IOptions<LibraryExampleServiceOptions>>();
logger.LogInformation("After retrieving IOptions; before IOptions.Value");
var optionsValue = options.Value;
logger.LogInformation("After IOptions.Value");

Console.ReadLine();

Which outputs:

info: Program[0]
      Before retrieving IOptions
info: Program[0]
      After retrieving IOptions; before IOptions.Value
info: Kaylumah.ValidatedStronglyTypedIOptions.Library.ConfigureLibraryExampleServiceOptions[0]
      ConfigureExampleServiceOptions Configure
info: Kaylumah.ValidatedStronglyTypedIOptions.Library.ConfigureLibraryExampleServiceOptions[0]
      ConfigureExampleServiceOptions PostConfigure
info: Kaylumah.ValidatedStronglyTypedIOptions.Library.ConfigureLibraryExampleServiceOptions[0]
      ConfigureExampleServiceOptions ValidateOptionsResult
info: Program[0]
      After IOptions.Value

Circling back to validation, I've created an extension method that registers DataAnnotationValidateOptions for us. One thing to note is that IValidateOptions is a named option, whereas the normal IOptions is an unnamed option. Microsoft solved this by providing a "DefaultName" for an options object which is an empty string.

public static partial class ServiceCollectionExtensions
{
    public static IServiceCollection ConfigureWithValidation<TOptions>(this IServiceCollection services, IConfiguration config) where TOptions : class
        => services.ConfigureWithValidation<TOptions>(Options.Options.DefaultName, config);
    
    public static IServiceCollection ConfigureWithValidation<TOptions>(this IServiceCollection services, string name, IConfiguration config) where TOptions : class
    {
        _ = config ?? throw new ArgumentNullException(nameof(config));
        services.Configure<TOptions>(name, config);
        services.AddDataAnnotationValidatedOptions<TOptions>(name);
        return services;
    }

    public static IServiceCollection ConfigureWithValidation<TOptions>(this IServiceCollection services, Action<TOptions> configureOptions) where TOptions : class
        => services.ConfigureWithValidation<TOptions>(Options.Options.DefaultName, configureOptions);

    public static IServiceCollection ConfigureWithValidation<TOptions>(this IServiceCollection services, string name, Action<TOptions> configureOptions) where TOptions : class
    {
        services.Configure(name, configureOptions);
        services.AddDataAnnotationValidatedOptions<TOptions>(name);
        return services;
    }

    private static IServiceCollection AddDataAnnotationValidatedOptions<TOptions>(this IServiceCollection services, string name) where TOptions : class
    {
        services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<TOptions>>(new DataAnnotationValidateOptions<TOptions>(name)));
        return services;
    }
}

If we put it to the test, our settings object could look like this. In this case, we use the Required and Url attributes. You can use any of the attributes provided by default, or create your custom attributes.

public class LibraryExampleServiceOptions
{
    public const string DefaultConfigurationSectionName = nameof(LibraryExampleServiceOptions);

    [Required, Url]
    public string? BaseUrl { get;set; }
}

Consider nullability and default values of properties when defining them. In the spirit of the example, you might have a retry-count if it has the value 0; is that because you specified it or forgot to define it? That's why I always define properties as [Required] and Nullable.

info: Program[0]
      Before retrieving IOptions
info: Program[0]
      After retrieving IOptions; before IOptions.Value
info: Kaylumah.ValidatedStronglyTypedIOptions.Library.ConfigureLibraryExampleServiceOptions[0]
      ConfigureExampleServiceOptions Configure
info: Kaylumah.ValidatedStronglyTypedIOptions.Library.ConfigureLibraryExampleServiceOptions[0]
      ConfigureExampleServiceOptions PostConfigure
info: Kaylumah.ValidatedStronglyTypedIOptions.Library.ConfigureLibraryExampleServiceOptions[0]
      ConfigureExampleServiceOptions ValidateOptionsResult
Unhandled exception. Microsoft.Extensions.Options.OptionsValidationException: DataAnnotation validation failed for 'LibraryExampleServiceOptions' members: 'BaseUrl' with the error: 'The BaseUrl field is not a valid fully-qualified http, https, or ftp URL.'.
   at Microsoft.Extensions.Options.OptionsFactory`1.Create(String name)
   at Microsoft.Extensions.Options.UnnamedOptionsManager`1.get_Value()
   at Program.<Main>$(String[] args) 

I think that is pretty neat. But I am not a big fan of the formatting. I remember the last time I used the Web API template, which resulted in a nicely formatted error. I had to dig in the ASPNET code, and it's the ModelStateInvalidFilter that transforms ModelStateDictionary.cs into a ValidationProblemDetails. I've added an example of this to the source repo, with the output shown below.

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-50f5816f844377e66f37688f297dfd29-ab771434a82ee290-00",
    "errors": {
        "Name": ["The Name field is required."],
        "EmailAddresses[0].Label": ["The Label field is required."],
        "EmailAddresses[0].Address": ["The Address field is required."]
    }
}

In the example above, I added validation on both the parent and the child DTO. It appears, however, that doing the same with DataAnnotations does not work. To enable the same behaviour for DataAnnotations, we can create custom ValidationAttributes. We begin with defining a special ValidationResult that is a composite of multiple ValidationResults.

public class CompositeValidationResult : System.ComponentModel.DataAnnotations.ValidationResult
{
    private readonly List<System.ComponentModel.DataAnnotations.ValidationResult> results = new();

    public IEnumerable<System.ComponentModel.DataAnnotations.ValidationResult> Results => results;

    public CompositeValidationResult(string? errorMessage) : base(errorMessage)
    {
    }

    public CompositeValidationResult(string errorMessage, IEnumerable<string>? memberNames) : base(errorMessage, memberNames)
    {
    }

    protected CompositeValidationResult(System.ComponentModel.DataAnnotations.ValidationResult validationResult) : base(validationResult)
    {
    }

    public void AddResult(System.ComponentModel.DataAnnotations.ValidationResult validationResult)
    {
        results.Add(validationResult);
    }
}

Next we create a custom ValidationAttribute for objects.

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class ValidateObjectAttribute : ValidationAttribute
{
    protected override System.ComponentModel.DataAnnotations.ValidationResult IsValid(object? value, ValidationContext validationContext)
    {
        if (value != null && validationContext != null)
        {
            var results = new List<System.ComponentModel.DataAnnotations.ValidationResult>();
            var context = new ValidationContext(value, null, null);

            System.ComponentModel.DataAnnotations.Validator.TryValidateObject(value, context, results, true);

            if (results.Count != 0)
            {
                var compositeValidationResult = new CompositeValidationResult($"Validation for {validationContext.DisplayName} failed.", new[] { validationContext.MemberName });
                results.ForEach(compositeValidationResult.AddResult);

                return compositeValidationResult;
            }
        }

        return System.ComponentModel.DataAnnotations.ValidationResult.Success;
    }
}

And finally, we need a ValidationAttribute for collections.

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Parameter)]
public sealed class ValidateCollectionAttribute : ValidationAttribute
{
    protected override System.ComponentModel.DataAnnotations.ValidationResult IsValid(object? value, ValidationContext validationContext)
    {
        CompositeValidationResult? collectionCompositeValidationResult = null;

        if (value is IEnumerable collection && validationContext != null)
        {
            var index = 0;
            foreach (var obj in collection)
            {
                var results = new List<System.ComponentModel.DataAnnotations.ValidationResult>();
                var context = new ValidationContext(obj, null, null);

                System.ComponentModel.DataAnnotations.Validator.TryValidateObject(obj, context, results, true);

                if (results.Count != 0)
                {
                    var compositeValidationResult = new CompositeValidationResult($"Validation for {validationContext.MemberName}[{index}] failed.", new[] { $"{validationContext.MemberName}[{index}]" });
                    results.ForEach(compositeValidationResult.AddResult);

                    if (collectionCompositeValidationResult == null)
                    {
                        collectionCompositeValidationResult = new CompositeValidationResult($"Validation for {validationContext.MemberName} failed.", new[] { validationContext.MemberName });
                    }

                    collectionCompositeValidationResult.AddResult(compositeValidationResult);
                }

                index++;
            }

            if (collectionCompositeValidationResult != null)
            {
                return collectionCompositeValidationResult;
            }
        }

        return System.ComponentModel.DataAnnotations.ValidationResult.Success;
    }
}

Our validation would already trigger with just these attributes. But we are also interested in handling our CompositeValidationResult and pretty-printing it.

public static class Validator
{
    public static ValidationResult[] ValidateReturnValue(object objectToValidate)
    {
        var validationResults = new List<System.ComponentModel.DataAnnotations.ValidationResult>();

        if (objectToValidate == null)
        {
            validationResults.Add(new System.ComponentModel.DataAnnotations.ValidationResult("Return value is required."));
        }
        else
        {
            var validationContext = new ValidationContext(objectToValidate);

            System.ComponentModel.DataAnnotations.Validator.TryValidateObject(objectToValidate, validationContext, validationResults, true);

            if (validationResults.Count != 0)
            {
                var compositeValidationResult = new CompositeValidationResult($"Validation for {validationContext.DisplayName} failed.", new[] { validationContext.MemberName });
                validationResults.ForEach(compositeValidationResult.AddResult);
            }
        }

        var structuredValidationResults = StructureValidationResults(validationResults);
        return structuredValidationResults;
    }

    private static ValidationResult[] StructureValidationResults(IEnumerable<System.ComponentModel.DataAnnotations.ValidationResult> validationResults)
    {
        var structuredValidationResults = new List<ValidationResult>();
        foreach (var validationResult in validationResults)
        {
            var structuredValidationResult = new ValidationResult
            {
                ErrorMessage = validationResult.ErrorMessage,
                MemberNames = validationResult.MemberNames.ToArray()
            };

            if (validationResult is CompositeValidationResult compositeValidationResult)
            {
                structuredValidationResult.ValidationResults = StructureValidationResults(compositeValidationResult.Results);
            }

            structuredValidationResults.Add(structuredValidationResult);
        }

        return structuredValidationResults.ToArray();
    }
}

You can then use it in an IValidateOptions like this

internal class CustomValidate : IValidateOptions<NestedParent>
{
    public ValidateOptionsResult Validate(string name, NestedParent options)
    {
        var validationResults = Kaylumah.ValidatedStronglyTypedIOptions.Utilities.Validation.Validator.ValidateReturnValue(options);
        if (validationResults.Any())
        {
            var builder = new StringBuilder();
            foreach (var result in validationResults)
            {
                var pretty = PrettyPrint(result, string.Empty, true);
                builder.Append(pretty);
            }
            return ValidateOptionsResult.Fail(builder.ToString());
        }

        return ValidateOptionsResult.Success;
    }

    private string PrettyPrint(Kaylumah.ValidatedStronglyTypedIOptions.Utilities.Validation.ValidationResult root, string indent, bool last)
    {
        // Based on https://stackoverflow.com/a/1649223
        var sb = new StringBuilder();
        sb.Append(indent);
        if (last)
        {
            sb.Append("|-");
            indent += "  ";
        }
        else
        {
            sb.Append("|-");
            indent += "| ";
        }

        sb.AppendLine(root.ToString());

        if (root.ValidationResults != null)
        {
            for (var i = 0; i < root.ValidationResults.Length; i++)
            {
                var child = root.ValidationResults[i];
                var pretty = PrettyPrint(child, indent, i == root.ValidationResults.Length - 1);
                sb.Append(pretty);
            }
        }

        return sb.ToString();
    }
}

Which prints

Microsoft.Extensions.Options.OptionsValidationException : |-Children => Validation for Children failed.
  |-Children[0] => Validation for Children[0] failed.
    |-Name => The Name field is required.

    Stack Trace:
       at Microsoft.Extensions.Options.OptionsFactory`1.Create(String name)
   at Microsoft.Extensions.Options.UnnamedOptionsManager`1.get_Value()

That looks more like it. One thing this approach, unfortunately, cannot solve is that errors occur at runtime. Wherewith IConfiguration, we could get the error at startup; we don't have the same luxury with IOptions since, as demonstrated, Value triggers at runtime. It is, however, a step in the right direction.

Note: since IOptions<> is an unbound generic you cannot retrieve all instances of it from the DI container to trigger this behaviour at startup

Bonus: Strongly typed options

I never liked using IOptions<> all over the place. I've found it especially bothersome in unit tests. I would either need Options.Create or create an IOptions Moq. If you don't rely on reloading configuration (remember IOptions is a Singleton), you can register a typed instance, which I find pretty neat.

var serviceProvider = new ServiceCollection()
            .Configure<StronglyTypedOptions>(builder => {
                builder.Name = "TestStronglyTypedOptions";
            })
            .AddSingleton(sp => sp.GetRequiredService<IOptions<StronglyTypedOptions>>().Value)
            .BuildServiceProvider();
var options = serviceProvider.GetRequiredService<IOptions<StronglyTypedOptions>>().Value;
var typedOptions = serviceProvider.GetRequiredService<StronglyTypedOptions>();
typedOptions.Name.Should().Be(options.Name);

Closing Thoughts

Using the options and configuration patterns described in this article makes it a lot less likely to run into configuration errors, or at the very least, it makes it easier to troubleshoot configuration mistakes.

As always, if you have any questions, feel free to reach out. Do you have suggestions or alternatives? I would love to hear about them.

The corresponding source code for this article is on GitHub.

See you next time, stay healthy and happy coding to all 🧸!

Resources

• Configuration in .NET
• Configuration in ASP.NET Core
• Options pattern in .NET
• Options pattern in ASP.NET Core

The next version of Visual Studio will come with a lot of promised performance improvements. VisualStudio 2022 is the first version that takes advantage of the 64-bit processor architecture. I have not yet tested it, but I am hopeful for a more performant experience developing when it ships.

While I think the 1600+ projects in a solution demo are cool, I would not see myself using the single solution model at that scale.

That brings me to the topic of today's post. I recently discovered a VS2019 feature I did not know that can bring some improvement to my experience. VS2019 introduced a new feature called solution filters. I googled a bit against it and did not find a lot about it, except for the Microsoft Docs itself. So I wrote this post to help raise awareness for something I found very useful.

Project Setup

I think over my past couple of posts, it's become clear that I am a fan of the Microsoft.Extensions repository. While Microsoft uses multiple solution files throughout the repository, I would opt for the single solution model.

Many of the projects in the repo follow this pattern:

• Concept.Abstractions provides interfaces
• .Concept provides default implementation for Concept.Abstractions
• Concept.Concrete technology specific implementation for Concept.Abstractions

dotnet new sln --name "SlnFilter"

dotnet new classlib --framework netstandard2.1 --name Kaylumah.SlnFilter.Extensions.Concept.Abstractions --output src/Kaylumah.SlnFilter.Extensions.Concept.Abstractions
dotnet new classlib --framework netstandard2.1 --name Kaylumah.SlnFilter.Extensions.Concept --output src/Kaylumah.SlnFilter.Extensions.Concept
dotnet new classlib --framework netstandard2.1 --name Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha --output src/Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha
dotnet new classlib --framework netstandard2.1 --name Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo --output src/Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo

dotnet new xunit --framework netcoreapp3.1 --name Kaylumah.SlnFilter.Extensions.Concept.Tests --output test/Kaylumah.SlnFilter.Extensions.Concept.Tests
dotnet new xunit --framework netcoreapp3.1 --name Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.Tests --output test/Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.Tests
dotnet new xunit --framework netcoreapp3.1 --name Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo.Tests --output test/Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo.Tests

dotnet sln add src/Kaylumah.SlnFilter.Extensions.Concept.Abstractions/Kaylumah.SlnFilter.Extensions.Concept.Abstractions.csproj
dotnet sln add src/Kaylumah.SlnFilter.Extensions.Concept/Kaylumah.SlnFilter.Extensions.Concept.csproj
dotnet sln add src/Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha/Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.csproj
dotnet sln add src/Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo/Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo.csproj
dotnet sln add test/Kaylumah.SlnFilter.Extensions.Concept.Tests/Kaylumah.SlnFilter.Extensions.Concept.Tests.csproj
dotnet sln add test/Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.Tests/Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.Tests.csproj
dotnet sln add test/Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo.Tests/Kaylumah.SlnFilter.Extensions.Concept.ConcreteBravo.Tests.csproj

dotnet new classlib --framework netstandard2.1 --name Kaylumah.SlnFilter.Test.Utilities --output test/Kaylumah.SlnFilter.Test.Utilities

Note Kaylumah.SlnFilter.Test.Utilities should not yet be added to the solution.

Setting up our filters

After following these steps, our project should look like the picture below in Visual Studio.

We can select one or more projects at a time and unload them from the solution.

Up until now, this is how I would have done things. Just unload projects I won't need and don't worry about them anymore. What I did not know is that we save the current state of the solution.

Unloading projects manually to create filters can be error-prone. Since a solution filter only builds the projects selected by the filter missing a project causes the build to fail.

An alternative can be to unload all projects, select the project you want, and use the "reload with dependencies" option.

Like before, we can save the solution filter with the Save As Solution Filter option. The only difference is that we now get 4/7 projects as opposed to 5/7 projects. That's because we loaded the ConcreteBravo.Tests projects and it's dependencies. Even though that loads Extensions.Concept it does not load Extensions.Concept.Tests since it is not a dependency of ConcreteBravo.Tests.

While researching something unrelated to this post, I noticed that the EF Core team used this feature I did not know existed. The cool thing was that they also had a filter for all projects. So I had to try that out, and as it turns out, you can create a filter without unloading projects.

The image below shows the difference between the three filters we created. It looks exactly like a traditional Solution Explorer with the addition that the name of the filter applied is displayed.

For example, the SlnFilter.Alpha.slnf I created for Concept.ConcreteAlpha implementation looks like this:

{
  "solution": {
    "path": "SlnFilter.sln",
    "projects": [
      "src\\Kaylumah.SlnFilter.Extensions.Concept.Abstractions\\Kaylumah.SlnFilter.Extensions.Concept.Abstractions.csproj",
      "src\\Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha\\Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.csproj",
      "src\\Kaylumah.SlnFilter.Extensions.Concept\\Kaylumah.SlnFilter.Extensions.Concept.csproj",
      "test\\Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.Tests\\Kaylumah.SlnFilter.Extensions.Concept.ConcreteAlpha.Tests.csproj",
      "test\\Kaylumah.SlnFilter.Extensions.Concept.Tests\\Kaylumah.SlnFilter.Extensions.Concept.Tests.csproj"
    ]
  }
}

It contains a reference to the sln-file and relative paths to all my *.csprojs I included in the .slnf-file.

Manage solution changes

You might be wondering what happens when I need to add new projects to my solution?

To demonstrate, let us assume our test projects have a shared helper project. At this time, I want to update our "Concept.Bravo" solution filter. This time I don't want to use dotnet CLI but use Add existing project.

You cannot use dotnet sln add on slnf files, but you can use them with dotnet build

As soon as you did this, you get this pop-up stating a mismatch between the loaded projects and the project specified in the filter.

If you followed the steps in a GIT environment, you would see that even before pressing Update Solution Filter the underlying solution is already updated.

The missing bit

I discussed this feature at work as a potential workaround for an issue we had in structuring our projects. One of my colleagues remembered looking at it about a year ago and finding it lacking. A few minutes later, he found a post on the developer community for Visual Studio. Funnily enough, it's a small world; the user-post links to a GitHub issue he created in this matter.

The problem is the management of multiple solutions filters because the filters are inclusive with relative paths following the sln-filter location. A proposed improvement would be to use glob patterns to include/exclude projects. That would make it easier when following naming conventions to have always up-to-date filters.

At a customer I work for, they use PowerShell as their script platform of choice, so I needed a deeper understanding of PowerShell. With PowerShell, it's reasonably easy to work with the file system and convert from and to JSON. So I thought, how hard can it be to script this.

The following script loads the paths of all *.csproj present in the solution directory and filters them out by RegEx. It then writes it to disk in the .slnf-format.

$inputSln = "SlnFilter.sln"
$outputSlnFilter = "SlnFilter.Generated.slnf"

$projectFiles = Get-ChildItem -Recurse -Filter "*.csproj" -Name
# $excludeFilters = @()
$excludeFilters = @('.ConcreteBravo')


$targetProjects = New-Object Collections.Generic.List[String]

foreach ($project in $projectFiles)
{
    $shouldInclude = $true

    foreach ($filter in $excludeFilters)
    {
        $shouldInclude = $project -notmatch $filter
        if (!$shouldInclude)
        {
            break
        }
    }

    if ($shouldInclude)
    {
        $targetProjects.Add($project)
    }
}

$sln = New-Object -TypeName psobject
$sln | Add-Member -MemberType NoteProperty -Name "path" -Value $inputSln
$sln | Add-Member -MemberType NoteProperty -Name "projects" -value $targetProjects

$root = New-Object -TypeName psobject
$root | Add-Member -MemberType NoteProperty -Name "solution" -value $sln

$root | ConvertTo-Json | Out-File $outputSlnFilter

Closing Thoughts

I like this new feature as a way to manage my larger solutions. Of course, it's not practical to maintain my (very basic) script for this. It will be a huge help if you think this is a valuable feature to upvote the Visual Studio Community forum issue.

As always, if you have any questions, feel free to reach out. Do you have suggestions or alternatives? I would love to hear about them.

The corresponding source code for this article is on GitHub.

See you next time, stay healthy and happy coding to all 🧸!

Sources

• slnf in VisualStudio
• slnf in MSBuild

For simplification purposes, my sample project will consist of only a single class library project. I like you to keep in mind that this would scale to many projects as Microsoft did with the "Microsoft.Extensions packages". The sky is the limit.

Setup

There are bits of this demo that work cross-platform and bits that require you to run on Windows. For example, I like the control the .NET CLI gives me when creating a new project. If you prefer to use Visual Studio, the result will remain the same.

$ dotnet new sln

The template "Solution File" was created successfully.

$ dotnet new classlib --framework netstandard2.0 --output src/Kaylumah.Logging.Extensions.Abstractions

The template "Class library" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on src/Kaylumah.Logging.Extensions.Abstractions\Kaylumah.Logging.Extensions.Abstractions.csproj...
  Determining projects to restore...
  Restored C:\Projects\NugetMetadata\src\Kaylumah.Logging.Extensions.Abstractions\Kaylumah.Logging.Extensions.Abstractions.csproj (in 84 ms).
Restore succeeded.

$ dotnet sln add src/Kaylumah.Logging.Extensions.Abstractions/Kaylumah.Logging.Extensions.Abstractions.csproj

Project `src\Kaylumah.Logging.Extensions.Abstractions\Kaylumah.Logging.Extensions.Abstractions.csproj` added to the solution.

I chose "Kaylumah.Logging.Extensions.Abstractions" to keep inline and in style with the extension packages Microsoft provides. By default, the namespace of the assembly sets the unique package identifier. Of course, this only matters when publishing the package to a NuGet source like https://nuget.org. That is not this article's scope, as publishing the default template with only the empty Class1.cs file would not benefit anyone by sharing it.

Why do we even need metadata in our packages?

Before showing you how I set metadata, I like to show you what happens without specifying any metadata. You can run the command dotnet pack for a single project or an entire solution. If you do it for the solution, only projects that are <IsPackable>true</IsPackable> generate a package. The class library we created uses the Microsoft.NET.Sdk and is packable by default.

$ dotnet pack

Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
Copyright (C) Microsoft Corporation. All rights reserved.

  Determining projects to restore...
  All projects are up-to-date for restore.
  Kaylumah.Logging.Extensions.Abstractions -> C:\Projects\NugetMetadata\src\Kaylumah.Logging.Extensions.Abstractions\bin\Debug\netstandard2.0\Kaylumah.Logging.Extensions.Abstractions.dll
  Successfully created package 'C:\Projects\NugetMetadata\src\Kaylumah.Logging.Extensions.Abstractions\bin\Debug\Kaylumah.Logging.Extensions.Abstractions.1.0.0.nupkg'.

This command generated the package in my bin folder. Since I did not specify a configuration, it chose the default configuration, which is Debug. So how do we inspect "Kaylumah Logging Extensions Abstractions 1.0.0 nupkg"? My prefered way is the NuGet Package Explorer, which is unfortunately only available on Windows.

There seems to be no metadata set by default. Let's, for a quick moment, compare it to what Microsoft adds to its packages. We can do this by downloading the package from nuget.org and view it like we just did for "Kaylumah.Logging.*.nupkg". Alternatively, the NuGet Package Explorer also supports viewing metadata from remote sources such as nuget.org.

Now that is what I call metadata. Remember that .nupkg files are archives; this means we can easily verify what the explorer was telling us about our package. You can do this by changing the extension from .nupkg to .zip and then extracting it. It contains the "Kaylumah Logging .nuspec", which is the manifest I was talking about in the introduction. At the moment, it looks like this:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <id>Kaylumah.Logging.Extensions.Abstractions</id>
    <version>1.0.0</version>
    <authors>Kaylumah.Logging.Extensions.Abstractions</authors>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package Description</description>
    <dependencies>
      <group targetFramework=".NETStandard2.0" />
    </dependencies>
  </metadata>
</package>

So as expected, it matches what NuGet Package Explorer shows us. The default for both id and authors is the assembly namespace, whereas description defaults to "Package Description", which tells our users nothing about what the package does.

How do we set metadata?

Now that we have covered our basis, we can finally explain how we can set metadata via MSBuild.

Set metadata from csproj

Since we are working on a single project, the logical place to set metadata is by editing our .csproj file. I will not cover every property today, so I refer you to pack target docs link. I will, however, cover properties I often use in my projects.

So behind the scenes, what happens is that specific MSBuild properties map to properties in the .nuspec file. We have to either edit the existing PropertyGroup in our file or add one to set properties. In my opinion, every package should contain branding (like authors, company and copyright information), a helpful description and categorized by a series of tags. So in the example below, I have set these values.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <Authors>Max Hamulyák</Authors>
    <!-- Note: Company does not get added to the .nuspec but it is part of the Assembly...Attribute so I often set them all -->
    <Company>Kaylumah</Company>
    <Description>Logging abstractions for Kaylumah.</Description>
    <PackageTags>logging;abstractions</PackageTags>
    <Copyright>Copyright (c) 2021 Kaylumah</Copyright> 
  </PropertyGroup>
</Project>

If we run dotnet pack now, we can immediately see that our package no longer has empty metadata.

You can also verify this in Visual Studio by checking your projects properties and clicking on the Package tab.

In the introduction, I talked about what exactly is a NuGet package. We are now at the part regarding other files. Since we already took care of branding, let us also add an icon. Our code is under license; how do we include it in the package?

Add files named Logo.png and LICENSE to the folder containing our project. We can then use the tags PackageIcon and PackageLicenseFile respectfully. We also need to tell MSBuild that these files should be part of the package. The updated project file looks like this:

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

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <Authors>Max Hamulyák</Authors>
    <Company>Kaylumah</Company>
    <Description>Logging abstractions for Kaylumah.</Description>
    <PackageTags>logging;abstractions</PackageTags>
    <Copyright>Copyright (c) 2021 Kaylumah</Copyright>
    <PackageIcon>Logo.png</PackageIcon>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="Logo.png" Pack="true" PackagePath="" />
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>

</Project>

Regarding these files, I like to say a couple of things before moving on to more advanced use cases. There is more than one way to set both the Icon and the License files for starters, which the Microsoft Docs describe. Both used to have a Url variant that would link to the Icon or License in question. Both of those options are now deprecated, and in the case of PackageLicenseFile, the alternative is PackageLicenseExpression, which uses SDPX license identifiers.

note: For backwards compatibility, PackageLicenseUrl gets populated with https://docs.microsoft.com/en-us/nuget/consume-packages/finding-and-choosing-packages#license-url-deprecation if you choose to use PackageLicenseFile and with https://licenses.nuget.org/MIT for example, if your SPDX would be MIT.

The second point I like to raise is regarding the file names. In my example, the value for PackageIcon and the name of my icon file match precisely; this is not necessary. What does matter is the name we specify in the package path. Failing to do so would, for example, trigger "NU5046: The icon file 'NotAnIcon.png' does not exist in the package. See a couple of samples below:

<!-- Visible 'False' hides the file in the Visual Studio explorer but still packages it under Logo.png -->
<None Include="Logo.png" Pack="true" PackagePath="" Visible="false" />

<!-- Link changes the name Visual Studio displays in the explorer but still packages it under Logo.png -->
<None Include="Logo.png" Pack="true" PackagePath="" Link="NotAnIcon.png" />

<!-- PackagePath rewrites the filename to Icon.png so PackageIcon remains unchanged -->
<None Include="KaylumahLogo.png" Pack="true" PackagePath="Icon.png" />

<!-- PackagePath rewrites the filename to KaylumahLogo.png so set PackageIcon to "KaylumahLogo" -->
<None Include="Icon.png" Pack="true" PackagePath="KaylumahLogo.png" />

Rewriting via package path only works for files with an extension. For historical purposes, both NuGet and MSBuild treat these files as directories. If we had used LICENSE.txt over LICENSE, we would have been able to modify the name in the package. However, our LICENSE file can apply both the Visible and the Link example. For more information regarding Package Icons, see package-icon. For packing licenses without an extension see package-license-1, and licenses with an extension see package-license-2

Keep in mind that by adding both Icon and License files to the package, the overall package size slightly increases; this can cause slower restore times on initial package downloads. This performance penalty is a trade-off you have to decide for your self. Given today's network speeds, I think the impact isn't noticeable.

Set metadata for multiple projects

So lets for a moment, assume our project is a huge success. We are creating more and more extension libraries. Think about the vast number of packages in dotnet/runtime. Even if we would only include an implementation for .Abstractions package, it would be very time consuming to do this for every project. It would also violate the DRY principle.

To get started, create a file called Directory.Build.props at the root of your solution. The way Microsoft handles this file, and in precisely that casing, is starting from your project folder; it goes up till it finds a match or it reaches the root of your drive. This Directory.Build.props file follows the same syntax we use in our .csproj files. To demonstrate, remove only the Copyright tag from the project and recreate it in the Directory.Build.props file. Now is the perfect moment to also demonstrate something I have not yet told you. We are using MSBuild to populate our metadata, and thus we can use the full force of MSBuild. For example, we can reference other variables and even use built-in functions. So the thing about our current Copyright implementation is that if after 31/12/2021 I want to release the next version, I have to remember to update my copyright notice. We can achieve this by setting the copyright tag like below.

<?xml version="1.0" encoding="utf-8"?>
<Project>
    <PropertyGroup>
        <Copyright>Copyright © $(Company) $([System.DateTime]::Now.Year)</Copyright>
    </PropertyGroup>
</Project>

What happened? Something is wrong; why do I see the copyright year 2021, but not my company name? Before explaining it, let me prove it by adding a company tag to the Directory.Build.props with a different value. For example:

<?xml version="1.0" encoding="utf-8"?>
<Project>
    <PropertyGroup>
        <Company>NotKaylumah</Company>
        <Copyright>Copyright © $(Company) $([System.DateTime]::Now.Year)</Copyright>
    </PropertyGroup>
</Project>

Unlike the Copyright tag do not remove the Company tag from the .csproj file. The result, this time, is a little different.

It appears that I have two different values for Company; this happens because Directory.Build.props gets imported before your project, and Directory.Build.targets gets imported after. The latest registration wins. That is why if we would read the System.Reflection AssemblyCopyrightAttribute the value for Company is "Kaylumah", but when we set Copyright, it is still "NotKaylumah". You can verify this behaviour by running the preprocess command (dotnet build -pp:fullproject.xml). See msbuild comand line reference for an explanation.

Word of caution, you should not set every property this way. You should only set the values that are shared cross-project. For example, Company and Copyright are likely to be the same for every project. The Authors and PackageTags could be project-specific; heck, even Description could be reused if so desired. One thing for sure is that Id can not be recycled since every package requires a unique Id.

<?xml version="1.0" encoding="utf-8"?>
<Project>
    <PropertyGroup>
        <Authors>Max Hamulyák</Authors>
        <Company>Kaylumah</Company>
        <Description>Logging abstractions for Kaylumah.</Description>
        <Copyright>Copyright © $(Company) $([System.DateTime]::Now.Year)</Copyright>
        <PackageTags>logging;abstractions</PackageTags>
        <PackageIcon>Logo.png</PackageIcon>
        <PackageLicenseFile>LICENSE</PackageLicenseFile>
    </PropertyGroup>

    <ItemGroup>
        <None Include="$(MSBuildThisFileDirectory)Logo.png" Pack="true" PackagePath="" />
        <None Include="$(MSBuildThisFileDirectory)LICENSE" Pack="true" PackagePath="" />
    </ItemGroup>

</Project>

In case you are wondering where did $(MSBuildThisFileDirectory) come from, it is one of the predefined MSBuild variables you can use. It allows us to set the path without thinking about relative file paths; for other variables, see the Microsoft Docs on the topic.

Bonus Chapter

I have referred to the list of properties before. There are a couple of handy ones we have not yet discussed. I am talking about the repository fields, making sure that an artefact can always trace back to a specific revision of your source code (Under repository in the nuspec).

Before I explain this, I am getting a bit tired of running dotnet pack every time. Lucky for me, there is a way to generate a package on build. Update the .csproj file to look like this:

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

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>

</Project>

So back to repository info. MSBuild itself is not aware of things like source control. Fortunately, we can pass parameters from the outside to use inside MSBuild. For this, we have the -p or -property switch. The following script retrieves the URL, branch name and SHA1 hash from the current commit.

#!/bin/sh -x

REPO_URL=$(git config --get remote.origin.url)
REPO_BRANCH=$(git branch --show-current)
REPO_COMMIT=$(git rev-parse HEAD)
dotnet build -p:RepositoryUrl="$REPO_URL" -p:RepositoryBranch="$REPO_BRANCH" -p:RepositoryCommit="$REPO_COMMIT" -p:RepositoryType="git"

Remember, we now generate a package on build. Let us verify we see repo info by opening the created package in NuGet Package Explorer.

Even though it is OK to add repo metadata this way, there is a better alternative. This alternative does more than add metadata; it also enables source code debugging from NuGet packages. How cool is that? This technology is called Source Link.

Like before with the properties, I have no wish to add source link to every package separately. For this, create Directory.Build.targets, which looks like this:

<?xml version="1.0" encoding="utf-8"?>
 <Project>
     <ItemGroup>
         <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="all" IsImplicitlyDefined="true" />
     </ItemGroup>
 </Project>

To configure source link, we need to update Directory.Build.props as well.

<?xml version="1.0" encoding="utf-8"?>
<Project>
    <PropertyGroup>
        <Authors>Max Hamulyák</Authors>
        <Company>Kaylumah</Company>
        <Description>Logging abstractions for Kaylumah.</Description>
        <Copyright>Copyright © $(Company) $([System.DateTime]::Now.Year)</Copyright>
        <PackageTags>logging;abstractions</PackageTags>
        <PackageIcon>Logo.png</PackageIcon>
        <PackageLicenseFile>LICENSE</PackageLicenseFile>
    </PropertyGroup>

    <ItemGroup>
        <None Include="$(MSBuildThisFileDirectory)Logo.png" Pack="true" PackagePath="" />
        <None Include="$(MSBuildThisFileDirectory)LICENSE" Pack="true" PackagePath="" />
    </ItemGroup>

    <PropertyGroup>
        <PublishRepositoryUrl>true</PublishRepositoryUrl>
        <EmbedUntrackedSources>true</EmbedUntrackedSources>
        <IncludeSymbols>true</IncludeSymbols>
        <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    </PropertyGroup>

</Project>

To prove that it is still working, here is the entire .nuspec file after adding Source Link

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <id>Kaylumah.Logging.Extensions.Abstractions</id>
    <version>1.0.0</version>
    <authors>Max Hamulyák</authors>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <license type="file">LICENSE</license>
    <licenseUrl>https://aka.ms/deprecateLicenseUrl</licenseUrl>
    <icon>Logo.png</icon>
    <description>Logging abstractions for Kaylumah.</description>
    <copyright>Copyright © Kaylumah 2021</copyright>
    <tags>logging abstractions</tags>
    <repository type="git" url="https://github.com/Kaylumah/NugetMetadataDemo.git" commit="3378cf33e0061b234c1f58e060489efd81e08586" />
    <dependencies>
      <group targetFramework=".NETStandard2.0" />
    </dependencies>
  </metadata>
</package>

Closing Thoughts

We looked at setting metadata via MSBuild and sharing metadata between projects. You can take this even further by using MSBuild tasks to verify that packages must have a description like shown here. It is also possible to create an entire SDK as Microsoft did with Arcade. Of course, Arcade goes much further than just specifying some metadata. You can read about how / why Microsoft did that on the devblogs. I experimented with a custom SDK heavily inspired by Arcade, but that is a blog post for another day.

For now, I hope I was able to teach you something about the power of MSBuild and how we can use it to manipulate our NuGet packages. If you have any questions, feel free to reach out.

The corresponding source code for this article is on GitHub, there you can see all the changes I addressed in sequence.

See you next time, stay healthy and happy coding to all 🧸!

Sources

This blog was written based on personal experience when creating packages. If not already explicitly linked in the text, here are some of the primary sources used in the article.

• Customize your build
• MSBuild targets
• Create a package dotnet cli
• Create and publish a package using dotnet cli
• MSBuild reserved and well-known properties
• Setting assembly and nuget package metadata in .NET Core

We, as developers, love platforms like GitHub, GitLab, Atlassian, Azure DevOps etc., as our managed git system and collaboration platform. We also love clean code and keep inventing new linters and rules to enforce it. In my opinion, every commit should allow the codebase to deploy to production. There is nothing worse than commits like “fixed style errors” or “fixed build”. These are often small mistakes you want to know as early as possible in your development cycle. You don’t want to break the build for the next developer because he pulled your ‘mistake’ or waste precious build minutes of your CI server. Say you have asked your teammate to review your code; in the meantime, the build server rejects your code. That means you have to go back and fix this, and your teammate has to come back and possibly review again after the changes (i.e., approvals reset on new commit). Doing so would waste a lot of time and effort.

note: I favour server-side hooks, but when using a SaaS solution, this is not always a possibility. I know I would not want someone to run arbitrary code on my servers. Unfortunately, a developer can bypass the client-side hooks. Until we can run, possibly sandboxed, server-side hooks on our prefered platform, we have to make the best of it by using client-side hooks.

Githooks are scripts that can execute on certain parts of the git lifecycle. Hooks must be executable, but other than that, hooks' power is only limited to the developer's imagination. I have seen many samples of hooks written in JavaScript (node) using tools like husky and commitlint to enforce a certain way of working. When I was browsing the changes in the upcoming .NET Core 3.0 release, the concept of local-tools got me thinking. I knew of the existence of dotnet-script, would that make it possible to C# in my GitHooks?

note: in the past I have used a set-up with node since I occasionally work with front-end frameworks like Angular. Since I had node installed I could use it even in my pure backend projects to enforce commit messages and such. For me it felt dirty, since that would require team members to have node installed. Using the dotnet cli feels less as a forced decision since members are likely to have it installed already.

Let’s get started!

When creating a git repository there is a folder called hooks where all the git hooks are placed. For every event there is a sample post-fixed with .sample that shows the possibility of each hook. This directory is not under source control and we are going to create our own directory to be able to share the hooks with the team.

mkdir git-hooks-example  
cd git-hooks-example  
git init  
dotnet new gitignore  
dotnet new tool-manifest  
dotnet tool install dotnet-script  
dotnet tool install dotnet-format  
mkdir .githooks

Pre-Commit Hook

To demonstrate we are going to create a plain hook. To check if it is working git commit -m “” (using empty commit message will abort the commit). You should see the line pre-commit hook printed.

#!/usr/bin/env dotnet dotnet-script
Console.WriteLine("pre-commit hook");

To make it executable run:

find .git/hooks -type f -exec rm {} \;
find .githooks -type f -exec chmod +x {} \;
find .githooks -type f -exec ln -sf ../../{} .git/hooks/ \;

Since we can reference other files (and even load nuget packages) in our csx we will first create a couple of files so we can have code-reuse between the hooks.

Create a file called logger.csx

public class Logger
{
    public static void LogInfo(string message)
    {
        Console.ForegroundColor = ConsoleColor.White;
        Console.Error.WriteLine(message);
    }
    public static void LogError(string message)
    {
        Console.ForegroundColor = ConsoleColor.Red;
        Console.Error.WriteLine(message);
    }
}

Create a file called command-line.csx

#load "logger.csx"
public class CommandLine
{
    public static string Execute(string command)
    {
        // according to: https://stackoverflow.com/a/15262019/637142
        // thans to this we will pass everything as one command
        command = command.Replace("\"", "\"\"");
        var proc = new Process
        {
            StartInfo = new ProcessStartInfo
            {
                FileName = "/bin/bash",
                Arguments = "-c \"" + command + "\"",
                UseShellExecute = false,
                RedirectStandardOutput = true,
                CreateNoWindow = true
            }
        };
        proc.Start();
        proc.WaitForExit();
        if (proc.ExitCode != 0)
        {
            Logger.LogError(proc.StandardOutput.ReadToEnd());
            return proc.ExitCode.ToString();
        }
        return proc.StandardOutput.ReadToEnd();
    }
}

Create a file called dotnet-commands.csx

#load "logger.csx"
#load "command-line.csx"
public class DotnetCommands
{
    public static int FormatCode() => ExecuteCommand("dotnet format");
    public static int BuildCode() => ExecuteCommand("dotnet build");

    public static int TestCode() => ExecuteCommand("dotnet test");

    private static int ExecuteCommand(string command)
    {
        string response = CommandLine.Execute(command);
        Int32.TryParse(response, out int exitCode);
        return exitCode;
    }

}

Create a file called git-commands.csx

#load "logger.csx"
#load "command-line.csx"
public class GitCommands
{
    public static void StashChanges()
    {
        CommandLine.Execute("git stash -q --keep-index");
    }
    public static void UnstashChanges()
    {
        CommandLine.Execute("git stash pop -q");
    }
}

We now have a utility in place for Logging and running GIT and dotnet commands. Next we are going to start with out pre-commit hook. Create a file called pre-commit The difference between this file and the others we just made is that we don’t specify the extension, and that using Shebang we explicitly load dotnet-script. For an explanation of each hook see the article posted below.

Git Hooks | Atlassian Git Tutorial

#!/usr/bin/env dotnet dotnet-script
#load "logger.csx"
#load "git-commands.csx"
#load "dotnet-commands.csx"

// We'll only runchecks on changes that are a part of this commit so let's stash others
GitCommands.StashChanges();

int buildCode = DotnetCommands.BuildCode();

// We're done with checks, we can unstash changes
GitCommands.UnstashChanges();
if (buildCode != 0) {
    Logger.LogError("Failed to pass the checks");
    Environment.Exit(-1);
}
// All checks have passed

If we run git commit -m “” again this time we get an error saying Failed to pass the checks, which makes sense since we don’t have a project yet. We are going to create a simple sln consisting of a classlibary and a test libary.

dotnet new sln  
dotnet new classlib --framework netstandard2.1 --langVersion 8 --name SomeLib --output src/SomeLib  
dotnet new xunit --output tests/SomeLibTests  
dotnet sln add **/*.csproj 
cd tests/SomeLibTests/  
dotnet add reference ../../src/SomeLib/SomeLib.csproj  
cd ../../  
dotnet build

If we use git commit -m “” one more time, we get the message about aborting the commit again. We now know that every commit will at least compile :-) If for example we remove the namespace ending curly brace from Class1 we get the error Class1.cs(7,6): error CS1513: }. If we extend our pre-commit hook even further we can have dotnet-format and dotnet-test running on every commit. If we purposely write a failing test (1 equals 0 or something like that) the build won’t pass.

#!/usr/bin/env dotnet dotnet-script
#load "logger.csx"
#load "git-commands.csx"
#load "dotnet-commands.csx"

Logger.LogInfo("pre-commit hook");

// We'll only runchecks on changes that are a part of this commit so let's stash others
GitCommands.StashChanges();

int formatCode = DotnetCommands.FormatCode();
int buildCode = DotnetCommands.BuildCode();
int testCode = DotnetCommands.TestCode();

// We're done with checks, we can unstash changes
GitCommands.UnstashChanges();
int exitCode = formatCode + buildCode + testCode;
if (exitCode != 0) {
    Logger.LogError("Failed to pass the checks");
    Environment.Exit(-1);
}
// All checks have passed

Prepare-commit-message hook

Thus far, we have not really used anything we need C# for; Admittedly we are using C# to execute shell commands. For our next hook we are going to use System.IO. Imagine as a team you have a commit-message convention. Let's say you want each commit message to include a reference to your issue tracker.

type(scope?): subject  #scope is optional

Create a file prepare-commit-msg in this hook we can provide a convenient commit message place holder if the user did not supply a message. To actual enforce the message, you need the commit-msg hook. In this example, we only create a message for feature branches.

#!/usr/bin/env dotnet dotnet-script
#load "logger.csx"
#load "util.csx"
#load "git-commands.csx"

Logger.LogInfo("prepare-commit-msg hook");

string commitMessageFilePath = Util.CommandLineArgument(Args, 0);
string commitType = Util.CommandLineArgument(Args, 1);
string commitHash = Util.CommandLineArgument(Args, 2);

if (commitType.Equals("message")) {
    // user supplied a commit message, no need to prefill.
    Logger.LogInfo("commitType message");
    Environment.Exit(0);
}

string[] files = GitCommands.ChangedFiles();
for(int i = 0; i < files.Length; i++) {
    // perhaps determine scope based on what was changed.
    Logger.LogInfo(files[i]);
}

string branch = GitCommands.CurrentBranch();
if (branch.StartsWith("feature")) {
    string messageToBe = "feat: ISS-XXX";
    PrepareCommitMessage(commitMessageFilePath, messageToBe);
}

public static void PrepareCommitMessage(string messageFile, string message)
{
     string tempfile = Path.GetTempFileName();
    using (var writer = new StreamWriter(tempfile))
    using (var reader = new StreamReader(messageFile))
    {
        writer.WriteLine(message);
        while (!reader.EndOfStream)
            writer.WriteLine(reader.ReadLine());
    }
    File.Copy(tempfile, messageFile, true);
}

Create a new helper called util.csx

public class Util
{
    public static string CommandLineArgument(IList<string> Args, int position)
    {
        if (Args.Count() >= position + 1)
        {
            return Args[position];
        }
        return string.Empty;
    }

}

Commit-msg Hook

The final local git hook I took for a spin is the commit-msg hook. It uses a regex to make sure the commit message is according the specified format.

#!/usr/bin/env dotnet dotnet-script
#load "logger.csx"
#load "util.csx"
#load "git-commands.csx"
using System.Text.RegularExpressions;

Logger.LogInfo("commit-msg hook");

string commitMessageFilePath = Util.CommandLineArgument(Args, 0);
string branch = GitCommands.CurrentBranch();
Logger.LogInfo(commitMessageFilePath);
Logger.LogInfo(branch);
string message = GetCommitedMessage(commitMessageFilePath);
Logger.LogInfo(message);

const string regex = @"\b(feat|bug)\b(\({1}\b(core)\b\){1})?(:){1}(\s){1}(ISS-[0-9]{0,3}){1}";
var match = Regex.Match(message, regex);

if (!match.Success) {
    Logger.LogError("Message does not match commit format");
    Environment.Exit(1);
}

public static string GetCommitedMessage(string filePath) {
    return File.ReadAllLines(filePath)[0];
}

pre push Hook

It is even possible to use NuGet packages in our hooks. Let say we want to prevent pushes to master (perhaps not even commits?). We can read a config file using Newtonsoft.Json and look for a protected branch and abort.

#!/usr/bin/env dotnet dotnet-script
#r "nuget: Newtonsoft.Json, 12.0.2"
#load "logger.csx"
#load "config.csx"
#load "git-commands.csx"
using Newtonsoft.Json;

string currentBranch = GitCommands.CurrentBranch().Trim();
Config currentConfig = GetConfig();
bool lockedBranch = currentConfig.ProtectedBranches.Contains(currentBranch);

if (lockedBranch) {
    Logger.LogError($"Trying to commit on protected branch '{currentBranch}'");
    Environment.Exit(1);
}

public static Config GetConfig()
{
    return JsonConvert.DeserializeObject<Config>(File.ReadAllText(".githooks/config.json"));
}

Conclusion

My current hooks are far from the best, and perhaps C# is not the fastest language to use in git hook. I do, however consider the experiment a success. I much rather code in C# than in shell script. Ideas for further improvement include

• based on the list of changes, determine the scope of the change (i.e. only one directory changed we might know the scope)
• configure the regex, allowed scopes, allowed types
• improve pre-commit-msg for more scenarios
• enforce users to use the hooks
• managing versions of the hooks, on checkout old / different version of pull (with an update of the hooks) sync the directory. (perhaps githook location)

Let me know what you think :-)

maxhamulyak/git-hooks-example

Happy Coding 🍻