DEV Community: Xavier Abelaira Rueda

To comment, or not to comment

Xavier Abelaira Rueda — Thu, 02 Jan 2025 22:57:32 +0000

📃 Introduction

Yes, that's one of the less exciting but most over-discussed topic about code maintenance, I would like to say in every language and framework.

But I recently saw a post on Bluesky from Nick Cosentino asking about it and it reminded me that the topic was a good candidate to feed this series with another episode, where every developer has their own point of view and experience, whether being a Junior, or a Senior Software Developer Advocate in a big tech company.

So, let's try to gather some information about the topic and, as always, I'll try to give my point of view at the end with some reasons about why.

But bear in mind, as I always repeat, that in the end, it is just a matter of preference, and it never deserves long discussions. Hence, I encourage everybody reading it to be respectful and polite with other points of view or preferences.

🔍 The context

From very early on in the learning path of a developer, each of us has received recommendations about how to comment code, including our formative stage. Without going any further, during my time as a student, one of the evaluation criteria was having comments in code. I clearly remember discussing what was the standard when adding documentation to JavaScript files, because we were 'forced' to add documentation in code in different ways, depending on the teacher, and to a lesser extent, the technology or subject they taught. I even remember another requesting us to add a comment above each line explaining the intention of the line below.

More than a complaint, this is an example that this topic has lacked cohesion and even pragmatism since the very beginning in each of us as developers. These discrepancies have continued depending mainly on the developers' preferences in each project.

But I think that nothing has provided better alignment in our developer's path on this subject than Clean Code. Clean code, despite the years and even controversies around it, especially around Uncle Bob, has been part of our path and guided us through a more pragmatic orientation, and it is part of the usual bibliography of almost any developer.

Clean code makes some claims that are, to some extent, part of many of our code comment orientations.

Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information.

using System;

public class Calculator
{
    // This creates a new calculator instance
    public Calculator()
    {
        // Constructor does nothing
    }

    // This method adds two numbers
    public int Add(int a, int b)
    {
        // Adding a and b
        return a + b; // Return the sum
    }

    // This method subtracts two numbers
    public int Subtract(int a, int b)
    {
        // Subtracting b from a
        return a - b; // Return the difference
    }

    // This method multiplies two numbers
    public int Multiply(int a, int b)
    {
        // Multiplying a and b
        return a * b; // Return the product
    }

    // This method divides two numbers
    public int Divide(int a, int b)
    {
        // Dividing a by b
        return a / b; // Return the quotient
    }
}

public class Program
{
    // This is the main method
    public static void Main(string[] args)
    {
        // Creating an instance of Calculator
        Calculator calc = new Calculator();

        // Performing addition
        int sum = calc.Add(10, 5); // 10 + 5
        Console.WriteLine("Sum: " + sum); // Print the sum

        // Performing subtraction
        int difference = calc.Subtract(10, 5); // 10 - 5
        Console.WriteLine("Difference: " + difference); // Print the difference

        // Performing multiplication
        int product = calc.Multiply(10, 5); // 10 * 5
        Console.WriteLine("Product: " + product); // Print the product

        // Performing division
        int quotient = calc.Divide(10, 5); // 10 / 5
        Console.WriteLine("Quotient: " + quotient); // Print the quotient
    }
}

Staying within the context of Clean Code, another important sentence written in stone for most of us is the following:

The purpose of a comment is to explain code that does not explain itself. It is a pity when a comment needs its own explanation

This very important sentence states something obvious on paper, but that is not always applied perfectly.

public static class BubbleSortSample
{
    // This method sorts an array using bubble sort algorithm
    public static void SortArray(this int[] arr)
    {
        int n = arr.Length; // Get the length of the array
        for (int i = 0; i < n - 1; i++) // Loop through the array
        {
            for (int j = 0; j < n - i - 1; j++) // Loop through the array up to the unsorted part
            {
                if (arr[j] > arr[j + 1]) // Compare adjacent elements
                {
                    // Swap the elements if they are in the wrong order
                    int temp = arr[j]; // Store the value of arr[j] in a temporary variable
                    arr[j] = arr[j + 1]; // Assign the value of arr[j + 1] to arr[j]
                    arr[j + 1] = temp; // Assign the value of temp to arr[j + 1]
                }
            }
        }
    }
}

public class Program
{

    // This is the main method
    public static void Main(string[] args)
    {
        int[] myArray = { 54, 33, 25, 10, 105, 16, 22, 11, 93 }; // Initialize an array with unsorted elements
        myArray.SortArray(); // Call the bubble sort method to sort the array
        Console.WriteLine("Sorted array:"); // Print a message indicating the array is sorted
        foreach (int item in myArray) // Loop through the sorted array
        { 
            Console.Write(item + " "); // Print each element of the sorted array
        }
    }
}

At first sight, we might think that we have enough information to understand the intention of the code, nonetheless, there are a few questions, discrepancies or unnecessary elements.

So, the important question is: Do we understand this code more easily and quickly because of the comments that we see? Is there any other way to make it clearer and faster?

public static class BubbleSortSample
{
    public static void SortArray(this int[] numbers)
    {
        int length = numbers.Length;
        for (int pass = 0; pass < length - 1; pass++)
        {
            for (int index = 0; index < length - pass - 1; index++)
            {
                if (ShouldSwap(numbers, index))
                {
                    Swap(numbers, index);
                }
            }
        }
    }

    private static Boolean ShouldSwap(int[] numbers, int index)
    {
        return numbers[index] > numbers[index + 1];
    }

    private static void Swap(int[] array, int index)
    {
        int temp = array[index];
        array[index] = array[index + 1];
        array[index + 1] = temp;
    }
}

public class Program
{
    public static void Main(string[] args)
    {
        int[] numbers = { 54, 33, 25, 10, 105, 16, 22, 11, 93 };
        numbers.SortArray();

        Console.WriteLine("Sorted array:");
        foreach (int number in numbers)
        {
            Console.Write(number + " ");
        }
    }
}

I'm pretty sure that if look at the codebase of the projects that we work on, we will find tons of examples or scenarios where we can simply follow basic rules to improve readability, and most of the times, if not always, we will remove the need for comments explaining the intention.

In the example above, (and again, you might find much better examples), it's at least simple enough to understand than just by following basic techniques of refactoring, isolating certain actions in specific methods, and giving proper names to the variables that are used, we make the code clear and self-explanatory enough to avoid all the comments.

But comments in code don't lie just in a few explanatory lines. As .NET developers, we are familiar with the OpenAPI specification and generators such as Swashbuckle that are capable of reading some standard XML documentation from endpoints and models exposed externally and adding it to the OpenAPI definition of that REST API.

So, we can see that, even though we can refactor the code with the aim of having the most readable code with the fewest or no comment in code, there are a few scenarios that deserve their own specific chapter.

⭐ My preference

Having reached this point, my opinion on the matter is that I must agree with the general recommendations written in Clean Code, therefore I tend to name variables, properties, methods and classes as concretely as possible, easing the readability of the code and removing the need for unnecessary comments mixed with code making noise.

However, considering the entire context in mind, I would like to say that there are a few situations where some comments can be useful, if not almost mandatory.

XML Documentation for publicly exposed elements:

Whether you are developing a NuGet package or a REST API, these elements are useful for document generators and even for developers that consume that API if it's properly documented.

You can find a few samples of OpenAPI in .NET apps here

Sample method from an MVC controller with XML documentation:

 /// <summary>
 /// Authenticates the user and creates a new session.
 /// </summary>
 /// <param name="credentials">The user's credentials.</param>
 /// <returns>
 /// An <see cref="IActionResult"/> containing the session information if authentication is successful;
 /// otherwise, an <see cref="IActionResult"/> indicating the failure reason.
 /// </returns>
 /// <response code="200">Returns the session information if authentication is successful.</response>
 /// <response code="400">Returns the validation errors if the model state is invalid.</response>
 /// <response code="401">Returns if the authentication fails.</response>
 [AllowAnonymous]
 [HttpPost("login")]
 public async Task<IActionResult> LoginAsync([FromBody] Credentials credentials)
 {
     if (ModelState.IsValid)
     {
         var session = await _sessionService.AuthenticateAsync(credentials);

         if (session is not null)
             return Ok(session);
         else
             return Unauthorized();
     }
     else
     {
         return BadRequest(ModelState);
     }
 }

Sample of a Minimal API endpoint with OpenAPI documentation support through extension methods:

app.MapGet("/hello/{name}", 
        ([Description("The name of the person to greet.")] string name) => $"Hello, {name}!")
    .WithSummary("Get a personalized greeting")
    .WithDescription("This endpoint returns a personalized greeting.")
    .WithTags("GET");

Sample of an extension method registering services from a Nuget package:

 /// <summary>
 /// Configures library main functionalities
 /// </summary>
 /// <param name="services">Services container</param>
 /// <returns>ICustomConfigurationBuilder, allowing fluent syntax to its own builder</returns>
 public static ICustomConfigurationBuilder AddReleasy(this IServiceCollection services)
 {
     var configurationBuilder = new CustomConfigurationBuilder(services);

     configurationBuilder.Services.AddTransient<ICustomService, ImplementedService>();

     return configurationBuilder;
 }

Pending changes:
In this particular scenario, we can distinguish two different situations:
- A TO-DO: Sometimes, especially when the project is in an early stage of its conception, or during the development of new features that require a few iterations to be completed, we might have things pending to improve or change and are in a preliminary stage. To-Do comments play an important role here, helping to remind specific changes to apply in the near future.
- Temporary requests from business It might be possible that anyone from business requires a specific change, sometimes temporary, sometimes implying another change that requires more effort to have it properly implemented, but the urgency forces the team to deploy a quick change/fix as soon as possible. In such circumstances, it's really useful to remark the reason that forced it to be like this, and if possible, the planned action to revert this To-Do.

In both cases, a To-Do comment becomes really handy. Furthermore, IDEs such as Visual Studio, JetBrain IDEs among others have support for these comments in code, adding tasks to a task view that eases the life of every developer.

public record UserDto(int Id, string Email);

public class SampleService
{
    public Task<UserDto> GetAsync(int id)
    {
         //TODO: Infrastructure layer to be implemented in the incoming sprint.
         return Task.FromResult(
            new UserDto(1, "sample-user-1@email.com")
            );
    }
}

Visual Studio's Task List view

JetBrain's Rider TO DO view

I hope you liked this article, so please feel free to share your thoughts, opinions and/or experiences in the comments section below.

Happy coding! 💻

var or explicit type

Xavier Abelaira Rueda — Sun, 28 Jan 2024 08:20:15 +0000

📃 Introduction

Among the bunch of topics that I would like to cover in this post series, one emerged as an immediate candidate these past weeks after having a conversation with one colleague about it, and also after having seen a recent video from @elfocrash in his YouTube channel talking about it, so let's try to explain the context, my preference, and how to apply a rule about it.

At the same time, as always, I would like to encourage you to always keep a respectful point of view with other's coding styles, since they are just a matter of preference, and it never deserve long discussions that are a drop in the bucket.

🔍 The context

Since its introduction in c# 3.0 in 2007, the var keyword has created supporters and detractors indistinctly in its usage. The automatic type inferring was something interesting, using var then you didn't need to extend the variables declarations horizontally more than needed, avoiding in some cases to declare the type twice:

// Prior to c# 3.0
UserRepository userRepository = new UserRepository(connectionString);
User user = new User();

// Since c# 3.0
var userRepository = new UserRepository(connectionString);
var user = new User();

At the same time, the keyword was a requirement for the definition of anonymous types, a great added feature to the language:

var userDetails = new { FullName = "John Doe", Role = "Basic" };

This flexibility, and simplicity added to the way of coding since c# 3.0 created at the same time some detractors in its usage, arguing mainly the lack of explicitness at a first sight, and from a more purist point of view, considering the nature of c# as a strong typed language, the usage of var was seen as something allowing developers to code c# at a certain level, as if it was JavaScript.

⭐ My preference

I started as .NET developer after .NET 3.5 and C# was released in 2007, so I was born in a world where var was available and extensively used, and for someone who was coding mainly in Java during my learning period, the recurrent redundancy when typing types, variables names plus constructors or descriptive method names was something that once the var possibility in c# was known, made me see all of this as redundant and unnecessary.

It is true that the lack of explicitness forces the developer to deduct the type in some scenarios, specially when something is returned back from one method.

private SecurityTokenDescriptor GenerateTokenDescriptor(Claim[] claims)
{
  var signingKey = SecurityKeyHelper.GetSecurityKey(_authSettings.SecretKey);
  var expiringDate = DateTime.UtcNow.AddMinutes(_authSettings.MinutesToExpire);
  var signingCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256);

  return new SecurityTokenDescriptor
  {
      Issuer = _authSettings.SiteName,
      Audience = _authSettings.SiteName,
      Subject = new ClaimsIdentity(claims),
      Expires = expiringDate,
      SigningCredentials = signingCredentials
  };
}

For instance, even though the name of signingKey is descriptive enough, there's no concise way for knowing the specific type handled, and you are forced to point the cursor hover the variable to see the type.

So given that scenario, the option followed by the detractors of using var would be something like this:

private SecurityTokenDescriptor GenerateTokenDescriptor(Claim[] claims)
{
    SecurityKey signingKey = SecurityKeyHelper.GetSecurityKey(_authSettings.SecretKey);
    DateTime expiringDate = DateTime.UtcNow.AddMinutes(_authSettings.MinutesToExpire);
    SigningCredentials signingCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256);

    return new SecurityTokenDescriptor
    {
        Issuer = _authSettings.SiteName,
        Audience = _authSettings.SiteName,
        Subject = new ClaimsIdentity(claims),
        Expires = expiringDate,
        SigningCredentials = signingCredentials
    };
}

But, although we somehow achieve more explicitness with the second approach at a simple glance, I have never had this as a problem, since the solution is as simple as hovering over the variable, helped by the IDE.

Otherwise, just because of the need to see it without moving the cursor or deducing, something that seems really unnecessary to me, we introduce redundancy, inconsistency, or let me add, something less orderly.

Why? Because using var helps pulling off the unnecessary visual noise, the developer has to think less when declaring variables (always var), and less characters (just three) to achieving more consistent code. Last but not least, its flexibility even allows you to change return types in functions without having to change the declaration: simply var takes care of it for you.

It is in no way the definitive argument, nor one by which to throw the rest to the ground, but in my humble opinion, the consistency and readiness, as well as during writing, is something with much greater weight than the rest of arguments that I have seen against its usage.

I might finish this section now, but there is another actor that alters my view on the overall equation: the new target-typed new expressions introduced in C#9. This avoids the need of typing the specific types in constructors when the type is already known. So, in that case we are shortening the declaration, but in the initialization instead of the declaration.

//Traditional way
User user = new User();

//var approach
var user = new User();

//new() approach
User user = new();

If we think only in the horizontal length, the new approach is shorter, but it still can create some visual inconsistency when declaring variables. In any case the new Target-typed new expressions feature is something that I found really interesting, and I am not against its usage.

📏 How to apply

I would like to start this last section of the post with a big disclaimer: This is just a matter of preference. The key aspect over this is to agree within the team the standard that makes everybody feel comfortable with, following and stick to it.

csharp_style_var_elsewhere = true
csharp_style_var_for_built_in_types = true
csharp_style_var_when_type_is_apparent = true

The example above demonstrates how to suggest var over specific types within your .editorConfig file, including primitives. However, you can customize these three values according to your team preferences. Also you can specify the level of severity just by adding :suggestion or :error or :warning at the end of any of them, allowing the IDE to suggest accordingly to the different rules applied.

I hope you liked this post, so please feel free to share your thoughts, opinions and/or experiences as well on the comments section below.

Happy coding! 💻

Private fields with or without underscore

Xavier Abelaira Rueda — Sat, 18 Nov 2023 22:00:06 +0000

📃 Introduction

We start our series with one of the most classic discussions about code styling in .NET: The usage of underscore prefix in private fields.

🔍 The context

In c# classses, we have multiple type of memebers to define within a class: fields, properties, methods, constants...

The general rule has been always fo use camelCase for fields and variables names, and PascalCase for classes, methods and properties. However, in the case of private fields in a class scope, the usage of an underscore as a prefix has been followed since the beginning.

Among the years, the standards defined for this have been varying, both by the community and opinions in general, and by Microsoft in particular. Today, we can find it in Microsoft's general code style guides on naming identifiers, exposing the following:

Private instance fields start with an underscore (_).

However, at some point this was not the case, and the community has also sometimes followed its own guidelines and/or principles, as is natural in any healthy development environment/language/framework.

The arguments against of its usage argue the no real need to use them, as well as the use of this to differentiate the one defined in the global scope from that of the method scope, especially in their assignment in constructors, having then an unnecessary extra character at the beginning.

⭐ My preference

I consider myself a developer with some traditions strongly stablished on me, even being a huge fan of all the new features and techniques coming with the c# language and the .NET framework, however, some of the rules that I have been following since the beginning of my career are still there, but there's only one rule: the tradition must have a reason to be.

Having said that, at this point you might have guessed that my preference is to use the underscore prefix in private fields, but why?

It highly important to remark, that at the end, following this rule or the other one will not make your code more robust, or more maintainable. So it's just a matter of preference thinking on how you organize your code and the way you interact with it and with the IDE for being more productive and automatic.

So, let's have a look on what do we have in case of having a class, in our example a Controller that is injecting a service on it. The code will be grossly simplified to focus on our aim:

public interface IUserService
{
    //Contract methods
}

public class UserController
{

    private readonly IUserService _userService;


    public UserController(IUserService userService)
    {
        _userService = userService;
    }


    public void Create(UserCreationParams userCreationParams)
    {
        //Implementation goes here
    }

}

In this case, using the underscore, I always expect to have the class scope services starting with an underscore. So given that, no matters the size of the class (In our example the UserController), If just start typing a _ I'll quickly have access to the class scope services, defined as private readonly fields.

This also avoids the usage of this in the assignment during the initialization at the constructor.

So we have two advantages:

Quick and concrete access to our private fields.
Less characters typed to access: this are 4 characters while the underscore is simply one.

But perhaps you might thing, hey, you have to type an additional character out of the constructor since you don't need to differenciate it from the injected variable with the same name, and it's true, however in this case we can have less help distinguishing the services in our class from the method scope variables that starts with the same letter. In that case we will remove the underscore from the service, and then we will have this when IntelliSense prompts:

You are forced then to navigate through IntelliSense's suggestions to select the service.

But using this, does not completely help us to go directly to the service:

At this moment, we can also have some voices saying that, you can opt using private property, but let's check what the compiler generates:

Original code:

    public class UserController
    {

        private IUserService UserService { get; init; }


        public UserController(IUserService userService)
        {
            UserService = userService;
        }


        public void Create(UserCreationParams userCreationParams)
        {
            //Implementation goes here
        }

    }

The compiler transform the above code as you see below:

[System.Runtime.CompilerServices.NullableContext(1)]
[System.Runtime.CompilerServices.Nullable(0)]
public class UserController
{
    [CompilerGenerated]
    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    private readonly IUserService <UserService>k__BackingField;

    private IUserService UserService
    {
        [CompilerGenerated]
        get
        {
            return <UserService>k__BackingField;
        }
        [CompilerGenerated]
        init
        {
            <UserService>k__BackingField = value;
        }
    }

    public UserController(IUserService userService)
    {
        UserService = userService;
    }

    public void Create(UserCreationParams userCreationParams)
    {
    }
}

As we can see, the compiler generates extra code completely unnecessary for our need.

Once using again IntelliSense, it is even worse: it does not help us distinguish between our service easily since in this case it is not able to distinguish if we want a variable or a type:

Finally, in this case are not able to distinguish between properties that manage the state of the class, and our services:

📏 How to apply

I would like to start this last section of the post with a big disclaimer: This is just a matter of preference. The key aspect over this is to agree within the team the standard that makes everybody feel comfortable with, following and stick to it.

Having said that, I would like to share with you the way I apply this in my projects, using an .editorConfig file:

[*.cs]

dotnet_naming_rule.private_members_with_underscore.symbols  = private_fields
dotnet_naming_rule.private_members_with_underscore.style    = prefix_underscore
dotnet_naming_rule.private_members_with_underscore.severity = suggestion

dotnet_naming_symbols.private_fields.applicable_kinds           = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

dotnet_naming_style.prefix_underscore.capitalization = camel_case
dotnet_naming_style.prefix_underscore.required_prefix = _

I hope you liked this post, so please feel free to share your thoughts, opinions and/or experiences as well on the comments section below.

Happy coding! 💻

The silly nonsense Software Development discussions in .NET context

Xavier Abelaira Rueda — Sat, 18 Nov 2023 21:50:50 +0000

📃 Introduction

Have you not had the situation where you spent hours with someone in your team discussing about these silly manias that we all have when refer to coding standards, rules, styles, techniques, whatever... in discussions that took much more than your plannings or feature analysis discussions? Even without reaching an agreement at the end?

Don't? If not, maybe it is because you have not played in the game of software development for quite long. This kind of discussion happens very often, in so many teams, by so many developers, especially when more experience rely on their shoulders, and having so nitpicky members within the team it's hard to force twisting other's arm. And in the case you might have thought about it: Yes, I have been also part of this kind of heated discussions in the past. 😅

Unfortunately, these discussions do not bring any added value to the project or the team since are just different ways of doing the same thing, normally with benefits and drawbacks in every option, and it is, at the end of the day, just a matter of personal preferences.

In any case, the problem arises when developers with strong and opposite preferences have to code in the same project, so in such situations somehow, we have to align ourselves to develop the project with the less possible frictions.

✔️ Objective

The objective of this series of posts will be to visualize first that these kinds of discussions, as commented at the introduction, provides no added value to the project, but of course are always interesting to be shared between the team, being polite and reaching an agreement, and I will also try to share my personal preferences, but never against others.

At the same time, I will try to give some advice / tips to help in reaching an agreement and how to put it into practice in your projects in an effective way.

Having so many examples to touch, I already have some topics to talk about, but in case you have faced some situation in this sense, or you have an idea about it, you can talk about it in the comments down below, I will be happy to receive suggestions, ideas or comments about this series.

So, let's start with this series. I hope you enjoy it. 😊

Keyed Services in .NET8's Dependency Injection

Xavier Abelaira Rueda — Tue, 01 Aug 2023 21:29:31 +0000

📃 Introduction

Since the beginning, AspNetCore provided a simple but effective dependency injection container by default, without the need of configuring it manually.

This amazing built-in implementation has worked like a charm in most of the common scenarios. However, not everything was covered as easy as pie by default.

As a counterexample, if we needed to deal with more than one implementation pointing to the same interface, we needed some kind of workaround to overcome this challenge.

⏪ Previous context

Having said that, we would be able to use a Factory method; or a custom implementation resolver among others (or directly using a different DI container provider like Autofac), but the one that I used the most until now was using a custom delegate and a simple enum with the different implementations.

With this aim in mind, this is how it looked an implementation having this kind of Service Resolver:

1. Services definition

Let's imagine that we have a couple of implementations fulfilling the same contract definition:

public interface IService 
{
    public Task<string> DoSomethingAsync();
}


public class ServiceImplementationA : IService
{
    public Task<string> DoSomethingAsync() 
        => Task.FromResult("Hello there from Service A");
}

public class ServiceImplementationB : IService
{
    public Task<string> DoSomethingAsync() 
        => Task.FromResult("Hello there from Service B");
}

2. Custom delegate and Enum

With this scenario, we will need something in charge of resolving this within the needed part of the project (Controller, Service...) and this will have the shape of a custom delegate, considering the members of an enum that has the different implementations defined in the project:

public enum ServiceImplementation
{
    A,
    B
}

public delegate IService ServiceResolver(ServiceImplementation implementationType);

3. DI Container configuration

Once we have this delegate defining what we need for resolving our different implementations, let's see how to properly set up everything within the DI container:

builder.Services.AddTransient<ServiceImplementationA>();
builder.Services.AddTransient<ServiceImplementationB>();

builder.Services.AddTransient<ServiceResolver>(serviceProvider => implType =>
{
    return implType switch
    {
        ServiceImplementation.A => serviceProvider.GetService<ServiceImplementationA>()!,
        ServiceImplementation.B => serviceProvider.GetService<ServiceImplementationB>()!,
        _ => throw new ArgumentException("Invalid service type")
    };
});

⚠️ Note that we are using a pattern matching implementation for resolving the different types, however this could also be done with a traditional switch case:

builder.Services.AddTransient<ServiceResolver>(serviceProvider => implType =>
{
    switch (implType)
    {
        case ServiceImplementation.A:
            return serviceProvider.GetService<ServiceImplementationA>()!;
        case ServiceImplementation.B:
            return serviceProvider.GetService<ServiceImplementationB>()!;

        default:
            throw new ArgumentException("Invalid service type");
    }
});

4. Resolving it

Having this, in a minimal API as a quick example, this would look like the example below once we needed to resolve our different services:

app.MapGet("/test-a", async (ServiceResolver serviceResolver) =>
{
    var service = serviceResolver(ServiceImplementation.A);
    var data = await service.DoSomethingAsync();

    return Results.Ok(data);
})
.WithName("TestEndpoint-A")
.WithOpenApi();

app.MapGet("/test-b", async (ServiceResolver serviceResolver) =>
{
    var service = serviceResolver(ServiceImplementation.B);
    var data = await service.DoSomethingAsync();

    return Results.Ok(data);
})
.WithName("TestEndpoint-B")
.WithOpenApi();

⚠️ Note that we directly inject the ServiceResolver delegate, and we request the concrete service through our initially defined enum type.

5. Running it

With the API running, once we try to execute it, this is what we have back in both endpoints:

💡 The invocation shown in the screenshot above was using HttpRepl dotnet tool, more info here.

⏩ What's new in .NET8?

Accordingly to one of the latest tweets from David Fowler, .NET 8 will introduce a new feature called Keyed Services that will allow to define keyed elements within the DI Container. This feature will be available to any kind of AspNetCore application, and the key can be anything.

This feature isn't delivered yet in any of the current .NET 8 preview releases, so it may vary on final release.

So, the example shown above, would look like this:

1. DI Container configuration

Configuring it is quite straightforward, it's required to use the concrete extension method according to the life scope that we want to specify for the given implementation, so here we have some of the "equivalent" methods to the one that we already know.

Regular	Keyed
`AddTransient<TService, TImplementation>()`	`AddKeyedTransient<TService, TImplementation>(object key)`
`AddScoped<TService, TImplementation>()`	`AddKeyedScoped<TService, TImplementation>(object key)`
`AddSingleton<TService, TImplementation>()`	`AddKeyedSingleton<TService, TImplementation>(object key)`

Following the previous example, equally registering ours as Transient ones:

builder.Services.AddKeyedTransient<IService, ServiceImplementationA>(ServiceImplementation.A);
builder.Services.AddKeyedTransient<IService, ServiceImplementationB>(ServiceImplementation.B);

2. Resolving it

Here we have a couple of simple mechanisms for helping us to inject the concrete type. One is using the decorator [FromKeyedServices]: very useful especially in Minimal API's. The other one is using a concrete new service provider type called IKeyedServiceProvider:

Using [FromKeyedServices]:

app.MapGet("/test-a", async ([FromKeyedServices(ServiceImplementation.A)] IService serviceImplA) =>
{
    var data = await serviceImplA.DoSomethingAsync();

    return Results.Ok(data);
})
.WithName("TestEndpoint-A")
.WithOpenApi();

app.MapGet("/test-b", async ([FromKeyedServices(ServiceImplementation.B)] IService serviceImplB) =>
{
    var data = await serviceImplB.DoSomethingAsync();

    return Results.Ok(data);
})
.WithName("TestEndpoint-B")
.WithOpenApi();

Using IKeyedServiceProvider:

public class AnotherServiceConsumingA
{
    private readonly IService _service;

    public AnotherServiceConsumingA(IKeyedServiceProvider keyedServiceProvider)
    {
        _service = keyedServiceProvider.GetRequiredKeyedService<IService>(ServiceImplementation.A);
    }
}

📒 Conclusion

This new feature is a simple but effective built-in way for resolving these particular situations in our code base easily without the need of using external libraries or workarounds, and the two flavours provided for resolving it in the consumer classes provides all that we need, so looking forward to the final implementation delivered in the upcoming .NET8 previews.

⚠️ As commented, this is based on a preliminar information still not available on current .NET8 previews, so the final approach could vary significantly from this post.

If you liked it, please give me a ⭐ and follow me 😉.

🔗 Resources

You can check it out the current approach code here

Useful links

Mechanisms and Performance when querying data to SQLServer from C#

Xavier Abelaira Rueda — Sat, 29 Jul 2023 09:48:50 +0000

📃 Introduction

SQL database management systems are widely used and, when interacting with the data from our applications, we know that performance is a critical element to take into consideration.

How to interact with them, knowing the different alternatives and best practices to apply in these scenarios are key elements to have performant applications, avoiding bottlenecks in our interactions with the database.

✅ Goal

We are going to benchmark different ways of retrieving data in common query scenarios, comparing the performance in each of them.

For this purpose we are going to use our beloved BenchmarkDotNet tool.

In addition, since we don't need long run benchmarks, and we want to avoid Identity resolution from EFCore, specially for a proper comparision between tracked and non tracked queries, we will use [ShortRunJob] option for these executions, also considering all the details that can affect the different scenarios in a real project / environment.

🔍 Scenario

Description

For each of the benchmark's scenario, we will test with the following preloaded data:

100_000 total persons
100_000 persons x 10 addresses = 1_000_000 total addresses
100_000 persons x 100 posts = 10_000_000 total posts

Data model

Querying from a single table

In our first scenario, we are going to check the simplest situation where we need to retrieve paginated data from a single table.

We will have two scenarios:

Retrieving 100 rows
Retrieving 1000 rows

Retrieving paginaged rows tracking entities with EFCore.

This is the most common scenario to see using EFCore and not worrying about the change tracker. Despite the fact that over the paper there will always be a decrease in performance compared to using it without tracking (AsNoTracking()), it should be mentioned that in certain scenarios, EFCore's Identity Resolution manages to match the performance of both, although they are not usually common scenarios, especially in the REST API development since it's not common to retrieve the same data over and over again within the same request scope.



var data = _dbContext.Persons
    .Take(PageSize)
    .ToList();

This is translated from EFCore like this:



SELECT TOP(@__p_0) 
    p.Id, p.Bio, p.BirthDate, p.Email, p.Name, p.OriginId, p.PhoneNumber, p.Surname
FROM Persons_Guid AS p

Rows	Mean	Allocated
100	17.627 ms	753.35 KB
1000	177.532 ms	6492.23 KB

Retrieving paginated rows using `AsNoTracking()` with EFCore.

Similar to the one above, but in this case we specify to EFCore that we don't want to track the entities retrived. This is specially useful when we need this information back for readonly purposes. In this case, without the overhead from EFCore tracking them, the performance boost is high.



var data = _dbContext.Persons
    .AsNoTracking()
    .Take(PageSize)
    .ToList();

Purely from SQL perspective, EFCore translates it identically to the previous example:



SELECT TOP(@__p_0) 
    p.Id, p.Bio, p.BirthDate, p.Email, p.Name, p.OriginId, p.PhoneNumber, p.Surname
FROM Persons_Guid AS p

Rows	Mean	Allocated
100	3.375 ms	324.26 KB
1000	9.093 ms	2196.32 KB

Retrieving paginated rows using a DTO projection with EFCore.

In this case we are going to use a projection through a LINQ Select statement. This scenario, since is not returning any Entity, tracking of course is disabled, and avoiding client-side evaluation we have very good performance specially for DTOs direct transformation. In our scenario we are mapping a DTO with the same number of properties that the original Entity has.
This could not be the best scenario, since it's specially useful when creating plain DTO's from more than one Entity, however it will be enough to get the idea.



var data = _dbContext.Persons
    .Select(x => new PersonDto
    {
        Id = x.Id,
        OriginId = x.OriginId,
        Name = x.Name,
        Surname = x.Surname,
        Email = x.Email,
        PhoneNumber = x.PhoneNumber,
        BirthDate = x.BirthDate,
        Bio = x.Bio
    })
    .Take(PageSize)
    .ToList();

Again, from SQL perspective, this is translated from EF Core similarly than the previous examples (with the difference of the columns ordering):



SELECT TOP(@__p_0)
    p.Id, p.OriginId, p.Name, p.Surname, p.Email, p.PhoneNumber, p.BirthDate, p.Bio
FROM Persons_Guid AS p

Rows	Mean	Allocated
100	3.422 ms	324.26 KB
1000	8.966 ms	2162.07 KB

Retrieving paginated rows using a FromSql / FromSqlInterpolated from EFCore.

Given that EFCore also allow us to send RAW SQL queries, also parametrized, we can then try how it performs, and the important thing here is that since what is returned back is an Entity, is also being tracked by default by EFCore Change Tracker.



var data = _dbContext.Persons
     .FromSqlInterpolated
     (
         $"SELECT TOP ({PageSize}) [Id],[OriginId],[Name],[Surname],[BirthDate],[Bio],[Email],[PhoneNumber] FROM [dbo].[Persons_Guid]"
     )
     .ToList();

No need to specify a translation from EFCore in this case, so, using the default (tracked) mechanism:

Rows	Mean	Allocated
100	17.498 ms	755.45 KB
1000	153.713 ms	6490.82 KB

Same rule applies when adding AsNoTracking() for performance improvement. It's then visible than the performance is equally as the one using a classic LINQ Select statement.

Retrieving paginated rows using a view mapped from EFCore as non-indexed entity.

Perhaps it is the least useful case but we would also want to measure how EFCore performs when it has to retrieve simple data from a table through a View, so in case you need it or have it in your project this is the result:

Having this View:



CREATE VIEW PersonsSimpleView
AS
SELECT 
    [Id], [OriginId], [Name], [Surname], [BirthDate], [Bio], [Email], [PhoneNumber]
FROM [dbo].[Persons_Guid]

Invoked like:



//PersonSimpleQuery is the name given to this View mapping
var data = _dbContext.PersonSimpleQuery
    .Take(PageSize)
    .ToList();

This is translated from EFCore like this:



SELECT TOP(@__p_0) 
    [p].[Id], [p].[Bio], [p].[BirthDate], [p].[Email], [p].[Name], [p].[OriginId], [p].[PhoneNumber], [p].[Surname]
FROM [PersonsSimpleView] AS [p]

Rows	Mean	Allocated
100	17.456 ms	760.53 KB
1000	152.410 ms	6551.15 KB

Retrieving paginated rows using a Stored Procedure invoked from EFCore.

Another option is to have a predefined Stored Procedure to retrieve the data. It is not recommended to do, but in case you need it or have it, the performance is very similar to the one with Views.

Having this Store Procedure:



CREATE OR ALTER PROC GetPersons(@rows INT) 
AS 
SELECT 
    [Id], [OriginId], [Name], [Surname], [BirthDate], [Bio], [Email], [PhoneNumber]
FROM [dbo].[Persons_Guid] WITH(NOLOCK)
ORDER BY [Id]
OFFSET 0 ROWS
FETCH NEXT @rows ROWS ONLY

Invoked like:



var data = _dbContext.PersonSimpleQuery
    .FromSqlInterpolated
    (
        $"[dbo].[GetPersons] {PageSize}"
    )
    .ToList();

This is translated from EFCore like this:



[dbo].[GetPersons] @p0

Rows	Mean	Allocated
100	19.39 ms	753.39 KB
1000	167.47 ms	6492.67 KB

Retrieving paginated rows using a SQL query executed with Dapper.

And now is when we reach the most performant option, in this case using Dapper. With Dapper we can send directly the SQL query parametrized or not having amazing performance, at the expense of losing the type safety benefits that EFCore provides as an ORM.

In readonly scenarios where performance and responsiviness is key, this option is the preferable one making it up to 3x faster to retrieve the same data compared with the fastest EFCore option. It's also worth mentioning the memory allocation is also quite awesome being much less than EFCore in similar operations.

SQL invokation through Dapper:



var sql = $@"
    SELECT top ({PageSize})
        [Id], [OriginId], [Name], [Surname], [BirthDate], [Bio], [Email], [PhoneNumber]
    FROM [dbo].[Persons_Guid]
    ";

using var connection = new SqlConnection(_connectionString);

var persons = connection.Query<PersonDto>(sql).ToList();

Rows	Mean	Allocated
100	1.281 ms	195.89 KB
1000	5.655 ms	1947.13 KB

Querying having nested data

In our second scenario, we are going to check another common situation where we need to retrieve paginated data for an specific Entity with the nested data.

We will have again two scenarios:

Retrieving 100 rows
Retrieving 1000 rows

In both sceanarios, each Entity will have 10 elements for each nested collection (Addesses and Posts)

In this case we will then discard Views, SQL queries from EFCore and Store procedures since we checked in the previous example how to work with them and the performance that these solutions may have.

Retrieving paginated rows joining tables using EFCore with LINQ.

In this common scenario, we request 100 elements by playing in turn with all the possibilities that EFCore allows with or without AsNoTracking() and AsSplitQuery(). Two nested collections are retrieved at the same time.

Scenario using both of them at the same time



var data = SqlServerDbTestDataContextHelper.New.DbContext.Persons
    .Include(x => x.Addresses)
    .Include(x => x.Posts)
    .AsNoTracking()
    .AsSplitQuery()
    .Take(PageSize)
    .ToList();

When translated without splitting queries



SELECT 
    [t].[Id], [t].[Bio], [t].[BirthDate], [t].[Email], [t].[Name], [t].[OriginId], [t].[PhoneNumber], [t].[Surname], [a].[Id], [a].[CityId], [a].[Line], [a].[PersonId], [a].[Sequence], [p0].[Id], [p0].[AuthorId], [p0].[Text], [p0].[Title]
FROM (
    SELECT TOP(@__p_0) [p].[Id], [p].[Bio], [p].[BirthDate], [p].[Email], [p].[Name], [p].[OriginId], [p].[PhoneNumber], [p].[Surname]
        FROM [Persons_Guid] AS [p]
        ) 
AS [t]
    LEFT JOIN [Addresses_Guid] AS [a] ON [t].[Id] = [a].[PersonId]
    LEFT JOIN [Posts_Guid] AS [p0] ON [t].[Id] = [p0].[AuthorId]
ORDER BY [t].[Id], [a].[Id]

And using AsSplitQuery()



SELECT TOP(@__p_0) [p].[Id], [p].[Bio], [p].[BirthDate], [p].[Email], [p].[Name], [p].[OriginId], [p].[PhoneNumber], [p].[Surname]
FROM [Persons_Guid] AS [p]
ORDER BY [p].[Id]


SELECT [a].[Id], [a].[CityId], [a].[Line], [a].[PersonId], [a].[Sequence], [t].[Id]
FROM (
    SELECT TOP(@__p_0) [p].[Id]
    FROM [Persons_Guid] AS [p]
     ) 
AS [t]
    INNER JOIN [Addresses_Guid] AS [a] ON [t].[Id] = [a].[PersonId]
ORDER BY [t].[Id]


SELECT [p0].[Id], [p0].[AuthorId], [p0].[Text], [p0].[Title], [t].[Id]
FROM (
    SELECT TOP(@__p_0) [p].[Id]
    FROM [Persons_Guid] AS [p]
      ) 
AS [t]
    INNER JOIN [Posts_Guid] AS [p0] ON [t].[Id] = [p0].[AuthorId]
ORDER BY [t].[Id]

AsNoTracking()	AsSplitQuery()	Rows	Mean	Allocated
✖️	✖️	100	3,219.56 ms	255.52 MB
✔️	✖️	100	1,300.48 ms	213.31 MB
✖️	✔️	100	1,811.96 ms	59.98 MB
✔️	✔️	100	81.09 ms	18.21 MB

ℹ️ Note that the performance it's radically better using both methods, and especially the absence of tracking from EFCore is what has the most positive impact on performance

Retrieving paginated rows joining tables using a DTO projection with EFCore.

In this case, we will be retrieving information from several tables projected into a DTO before client's side evaluation, so EFCore smartly translates the statement to a single SQL having a very good performance, especially considering that we only retrieve the necessary data, we avoid mapping / iterating a second time between domain models and DTOs, and collaterally, since the models projected are not entities, EFCore does not perform any type of tracking on them.

It is therefore the best option for read-only models in our project if we don't want to deal with Dapper.

Projection code using EFCore:



var data = SqlServerDbTestDataContextHelper.New.DbContext.Persons
    .Select(x => new PersonDto
    {
        Id = x.Id,
        OriginId = x.OriginId,
        Name = x.Name,
        Surname = x.Surname,
        Email = x.Email,
        PhoneNumber = x.PhoneNumber,
        BirthDate = x.BirthDate,
        Bio = x.Bio,
        Addresses = x.Addresses.Select(y => new AddressDto { Id = y.Id, CityId = y.CityId, Line = y.Line, Sequence = y.Sequence }),
        Posts = x.Posts.Select(y => new PostDto { Id = y.Id, Text = y.Text, Title = y.Title })
    })
    .Take(PageSize)
    .ToList();

This is translated to SQL from EFCore to something like this:



SELECT [t].[Id], [t].[OriginId], [t].[Name], [t].[Surname], [t].[Email], [t].[PhoneNumber], [t].[BirthDate], [t].[Bio], [a].[Id], [a].[CityId], [a].[Line], [a].[Sequence], [p0].[Id], [p0].[Text], [p0].[Title]
FROM (
    SELECT TOP(@__p_0) [p].[Id], [p].[OriginId], [p].[Name], [p].[Surname], [p].[Email], [p].[PhoneNumber], [p].[BirthDate], [p].[Bio]
    FROM [Persons_Guid] AS [p]
    ) 
AS [t]
    LEFT JOIN [Addresses_Guid] AS [a] ON [t].[Id] = [a].[PersonId]
    LEFT JOIN [Posts_Guid] AS [p0] ON [t].[Id] = [p0].[AuthorId]
ORDER BY [t].[Id], [a].[Id]

Rows	Mean	Allocated
100	1,226.3537 ms	1218030776 B
1000	96,768.088 ms	2217682664 B

Retrieving paginated rows joining tables using raw SQL query with Dapper

Before finishing with the paginated queries, of course, we have to evaluate the performance of Dapper with a query that retrieves the same data from the previous scenario.

In this case we see that the performance is much higher again, mainly by avoiding the translation to SQL.

SQL statement invokation from C# with Dapper:



var sql = $@"
    SELECT top ({PageSize})
        persons.[Id] as [PersonId], persons.[OriginId], persons.[Name], persons.[Surname], persons.[BirthDate], persons.[Bio], persons.[Email], persons.[PhoneNumber],
        addresses.[Id] as [AddressId], addresses.[CityId], addresses.[Line], addresses.[Sequence],
        posts.[Id] as [PostId], posts.[Text], posts.[Title]
    FROM [dbo].[Persons_Guid] persons
        join [dbo].[Addresses_Guid] addresses on persons.Id = addresses.PersonId
        join [dbo].[Posts_Guid] posts on persons.Id = posts.AuthorId
    ";

using (var connection = new SqlConnection(SqlServerDbTestDataContextHelper.TestDbConnectionString))
{
    var persons = connection.Query<PersonFullView>(sql).ToList();
}

Rows	Mean	Allocated
100	1.6398 ms	384083 B
1000	11.6887 ms	3815858 B

Retrieving single entity with joining tables using LINQ FirstAsync with EFCore

Again, in this case we start with the more common case where we need to return a single filtered entity, with all its associated data in two of its collections.

We also compare the performance with AsNoTracking() and AsSplitQuery() separately and together. We will also check the performance using Explicit loading, that in any case have a similar behaviour in this case than AsSplitQuery() when being tracked.

Since the arrival of AsSplitQuery(), explicit loading has been in the background, being less comprehensible in code and being limited to loading on a single row. However, the idea of both is the same: to avoid the cartesian explosion by separating the queries of the parent element from those of the nested data.

Code example combining both:



var data = await SqlServerDbTestDataContextHelper.New.DbContext.Persons
    .Include(x => x.Addresses)
    .Include(x => x.Posts)
    .AsNoTracking()
    .AsSplitQuery()
    .FirstAsync();

In the case of a single query, this is the translation done by EFCore (Not using AsSplitQuery() or explicit loading)



SELECT [t].[Id], [t].[Bio], [t].[BirthDate], [t].[Email], [t].[Name], [t].[OriginId], [t].[PhoneNumber], [t].[Surname], [a].[Id], [a].[CityId], [a].[Line], [a].[PersonId], [a].[Sequence], [p0].[Id], [p0].[AuthorId], [p0].[Text], [p0].[Title]
FROM (
    SELECT TOP(1) [p].[Id], [p].[Bio], [p].[BirthDate], [p].[Email], [p].[Name], [p].[OriginId], [p].[PhoneNumber], [p].[Surname]
    FROM [Persons_Guid] AS [p]
    )
AS [t]
    LEFT JOIN [Addresses_Guid] AS [a] ON [t].[Id] = [a].[PersonId]
    LEFT JOIN [Posts_Guid] AS [p0] ON [t].[Id] = [p0].[AuthorId]
ORDER BY [t].[Id], [a].[Id]

and in the case of using AsSplitQuery() or explicit loading:



SELECT TOP(1) [p].[Id], [p].[Bio], [p].[BirthDate], [p].[Email], [p].[Name], [p].[OriginId], [p].[PhoneNumber], [p].[Surname]
FROM [Persons_Guid] AS [p]

SELECT a.Id, a.CityId, a.Line, a.PersonId, a.Sequence
FROM Addresses_Guid AS a
WHERE a.PersonId == @__get_Item_0)

SELECT p.Id, p.AuthorId, p.Text, p.Title
FROM Posts_Guid AS p
WHERE p.AuthorId == @__get_Item_0)

AsNoTracking()	AsSplitQuery()	Explicit loading	Mean	Allocated
✖️	✖️	✖️	34.2348 ms	5962998 B
✔️	✖️	✖️	17.8125 ms	5530597 B
✖️	✔️	✖️	22.6501 ms	829366 B
✔️	✔️	✖️	6.0082 ms	401577 B
✖️	✖️	✔️	25.4532 ms	806981 B

ℹ️ Note that the performance it's radically better using both methods, and especially the absence of tracking from EFCore is what has the most positive impact on performance

Explicit loading has a bit of overhead comparing to AsSplitQuery() both very similar in terms of performance, just as expected initially

Retrieving single element with joining tables using a projection with EFCore

Again a mandatory test would be to evaluate the performance of EFCore translating our LINQ query to SQL for a single element with its nested data.

Again, a very good option for managing read-only queries transformed directly to their corresponding DTO's without the need of dealing with Dapper.

Projection code using EFCore:



var data = SqlServerDbTestDataContextHelper.Instance.DbContext.Persons
     .Select(x => new PersonDto
     {
         Id = x.Id,
         OriginId = x.OriginId,
         Name = x.Name,
         Surname = x.Surname,
         Email = x.Email,
         PhoneNumber = x.PhoneNumber,
         BirthDate = x.BirthDate,
         Bio = x.Bio,
         Addresses = x.Addresses.Select(y => new AddressDto { Id = y.Id, CityId = y.CityId, Line = y.Line, Sequence = y.Sequence }),
         Posts = x.Posts.Select(y => new PostDto { Id = y.Id, Text = y.Text, Title = y.Title })
    })
    .First(x => x.Id == id);

This is translated to SQL from EFCore to something like this:



SELECT [t].[Id], [t].[OriginId], [t].[Name], [t].[Surname], [t].[Email], [t].[PhoneNumber], [t].[BirthDate], [t].[Bio], [a].[Id], [a].[CityId], [a].[Line], [a].[Sequence], [p0].[Id], [p0].[Text], [p0].[Title]
FROM (
    SELECT TOP(1) [p].[Id], [p].[OriginId], [p].[Name], [p].[Surname], [p].[Email], [p].[PhoneNumber], [p].[BirthDate], [p].[Bio]
    FROM [Persons_Guid] AS [p]
    WHERE [p].[Id] = @__id_0
    ) 
AS [t]
    LEFT JOIN [Addresses_Guid] AS [a] ON [t].[Id] = [a].[PersonId]
    LEFT JOIN [Posts_Guid] AS [p0] ON [t].[Id] = [p0].[AuthorId]
ORDER BY [t].[Id], [a].[Id]

Mean	Allocated
18.6125 ms	4617402 B

Retrieving single element with joining tables using raw SQL multi-query with Dapper

Finally, our latest test puts one of Dapper's most interesting features under the microscope: its ability to launch multiple queries at once and be mapped.

This is useful to compare the performance when loading the same data from the previous scenario, although dumped in a DTO model.

Again, the peformance demonstrated with this approach is simply astonishing.

SQL queries invocation through Dapper:



var sql = $@"
    SELECT [Id], [OriginId], [Name], [Surname], [BirthDate], [Bio], [Email], [PhoneNumber] FROM [dbo].[Persons_Guid] WHERE Id = @PersonId;

    SELECT [Id], [CityId], [Line], [Sequence] FROM [dbo].[Addresses_Guid] WHERE [PersonId] = @PersonId;

    SELECT [Id], [Title], [Text] FROM [dbo].[Posts_Guid] WHERE [AuthorId] = @PersonId
    ";

using (var connection = new SqlConnection(SqlServerDbTestDataContextHelper.TestDbConnectionString))
{
    using (var multiQuery = await connection.QueryMultipleAsync(sql, new { PersonId = id }))
    {
         var person = (await multiQuery.ReadAsync<PersonDto>()).First();
         var addresses = (await multiQuery.ReadAsync<AddressDto>()).ToList();
         var posts = (await multiQuery.ReadAsync<PostDto>()).ToList();

        person.Posts = posts;
        person.Addresses = addresses;
    }
}

Mean	Allocated
0.7817 ms	111833 B

📒 Conclusion

On the one hand, during this extensive post we have been able to see different ways of querying data with both EFCore and Dapper, as well as deep diving on the details of the fuctionality and performance offered by each of these solutions.

Applying one option, another or both will depend, as always, on the needs of each project, however as a general rule of thumb, with EFCore we can fully manage the needs of a project, also taking advantage of the additional collateral advantages that it allows us such as migrations management and safe typing in entity-table mappings. However, it will require making good use of the different features that it provides at the query level such as AsNoTracking() or AsSplitQuery(), or making explicit loading according to the needs of each situation.

On the other hand, however, in higher systems, with large volumes of data, especially those where performance is critical, Dapper offers unmatched performance and low memory load, however it will require extra control at testing level with integration and/or end-to-end tests so that model changes do not impact previously defined queries.

I hope I have been able to provide ideas, tips and useful information in this post about how to take advantage of both tools in this context.

If you liked it, please give me a ⭐ and follow me 😉.

📉 All results

To carry out this comparison, innumerable executions were released, many of them required specific specifications either due to problems with Windows Defender or due to the execution time, so I took the opportunity to leave all the important ones reported. Depending on the type of execution, the results may vary, however they are all really valid to establish some metrics and compare performance.

🔗 Resources

The entire code can be found here; and the corresponding report here

Useful links

Managing AspNetCore appSettings from local to release

Xavier Abelaira Rueda — Thu, 11 May 2023 22:39:20 +0000

Introduction

When working with any .NET application, we normally require to set up some settings that will be different depending on the environment running.

The default, recommended and broadly used mechanism in this case is under appSetting.json files in the root of the starting project.

Having said that, there are multiple ways to properly manage, and even though it may seem like an easy scenario to manage, without proper care and organization it is easy to end up turning the settings files into a little mess drawer of configurations.

I will try to explain though, the one that I have been using the most, considering the following bullet points:

Use the most simple mechanism possible
Avoid settings keys redundancy as much as possible
Secure management

With this aim, we are going to focus on the following scenario:

AspNetCore WebAPI project >= 6.0
Visual Studio 2022
dotnet secrets
Azure AppService
Azure Key Vault

appSettings files

Well, imagine our project having a couple of environments in the cloud: one for test, and the Production one. With the aim of having specific configurations for local Development and both cloud environments, we would have something like this:

appSettings.json
appSettings.Development.json
appSettings.Test.json
appSettings.Production.json

But, then how can easily differenciate where to add the settings in every scenario? For example: What if I have a setting that should be the same for all environments except Production?

Given this, my current approach is the following:

appSettings.json: General setttings, can apply to every environment.
appSettings.Development.json: Specific configurations only used in local development. Overrides in case of conflict our appSettings.json.
appSettings.Test.json && appSettings.Production.json Specific configurations for our cloud environments, overrides in case of conflict our appSettings.json.

Microsoft.Extensions.Configuration and WebApplicationBuilder

The default AspNetCore template installs all the required NuGet packages for a typical WebAPI throught the metapackage Microsoft.AspNetCore.App.

In our case, the WebApplicationBuilder will use these packages to build our configuration based on what we have configured between the appSettings files and the local user-secrets.

1. What to configure in global appSettings.json

The global appSettings.json is the first file that the WebApplicationBuilder will take into account. These are therefore those configurations that apply globally to the project, and you will see many approaches on how to manage it.
There are developers who prefer that this file be self-sufficient, containing a complete development environment configuration, but I prefer to write all configuration keys and to only provide a non-empty value when the same value is shared between all environments. With this strategy I try to achieve the following:

Clarity on whether the setting is global or environment specific.
Prevent accidental misconfiguration: I prefer that the construction of the settings be forced between both files (global + env) so that the environment only works if it really has its settings configured, and if it doesn't throw an exception. Imagine forgetting to put the proper connection string in prod, but having the environment working correctly pointing to test DB because the global file allows it.

In any case, what is never recommended is to use any PROD setting in the global file, since this could have dire consequences during the development and testing process. Therefore, the PROD settings can only be in their corresponding file.

So, given that, for instance let's add the connectionString to our database, and the settings for connecting through an external API protected by an API token.



{
  "ConnectionStrings": {
    "SqlServerConnection": ""
  },
  "ExternalServices": {
    "ExternalApiSettings": {
      "EndpointUrl": "",
      "Token": ""
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

We could even not create the sections and just define it in each environment appSettings, but personally I like to be able to peek in the global file for all the necessary project's settings, knowing that those empty ones will be overwritten by the environment in question, or by the secrets manager.

2. What to configure in appSettings.{env}.json (test, production)

Now we know that after having loaded the global file, AspNetCore will load the appSettings values of the running environment. This is done through the environment variable ASPNETCORE_ENVIRONMENT.

Since the value of it is "Development" in local, it will be in charge of loading the appSettings.Development.json values, even overwriting the global ones, just as we want.

So given that, we can have multiple options. For instance, since we are locally running an SqlServer instance for our local development using Integrated Security, and this connection string is not exposing any kind of sensitive data, we can do the following for our scenario:

appSettings.Development.json



{
  "ConnectionStrings": {
    "SqlServerConnection": "Data Source=localhost;Initial Catalog=TestDatabase;Integrated Security=True;TrustServerCertificate=True"
  },
  "ExternalServices": {
    "ExternalApiSettings": {
      "EndpointUrl": "https://www.apisandbox.com/api"
    }
  }  
}

In our example, we are not configuring anything particular in local environment for logging, so given this, we can just remove the entire section.

Additionally, we only specify the URL for the testing sandbox provided for our external API service, so now we only have to configure the Token so that our local environment will be fully functional.

appSettings.Test.json



{ 
  "ExternalServices": {
    "ExternalApiSettings": {
      "EndpointUrl": "https://www.apisandbox.com/api"
    }
  }  
}

appSettings.Production.json



{ 
  "ExternalServices": {
    "ExternalApiSettings": {
      "EndpointUrl": "https://www.apiprod.com/api"
    }
  }  
}

However, in our Azure environment files (Test, Production) we want to securely control our database connection, so we can avoid overwrite this value at this stage, and as on Development, only the External Service url can be placed here since it's not exposing any sensitive information and should not be part of the Azure Vault configuration later on.

3. Configure dotnet secrets

.NET by default provides us with a secure credential store outside the git repository, for this we have two very simple ways to configure it.

Option A: By using Visual Studio integrated view.

The simplest will just require us to right click on the startup project and then on "Manage user secrets".

Option B: By using dotnet cli

It's no more difficult to do from the dotnet cli, just running the following command in the root of the startup project will do exactly the same:

dotnet user-secrets init

I both cases, what we will be able to see is a new tag in our csproj file like this:



<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <!-- [...] -->

        <!-- Our autogenerated unique ID for storing sensitive configurations -->
        <UserSecretsId>69f106e3-5df1-4e94-8ef6-3f964a3fdb98</UserSecretsId> 
    </PropertyGroup>

<!-- [...] -->

</Project>

Then we can again configure our settings both from the built-in tool in Visual Studio, or from the dotnet cli

Using Visual Studio

If done the previous step, just right clicking on the startup project and then on "Manage user secrets" it will show us a json editor where we can add the same configuration that we can see in the json later.

Using dotnet cli

Simply running the following command from the console will have the same effect:

dotnet user-secrets set "ExternalServices:ExternalApiSettings:Token" "OurSecretToken"

Note that we are specifying three levels of nesting.

This will generate the following JSON file stored in the following user's path:

%APPDATA%\Microsoft\UserSecrets\69f106e3-5df1-4e94-8ef6-3f964a3fdb98\secrets.json



{
  "ExternalServices:ExternalApiSettings:Token": "OurSecretToken"
}

Note that the UserSecretsId is the one specified in the path, this will ensure that all developers pulling the code will have the same ID in their local secrets manager, easing the configuration to each team member.

As you also may have noticed, the dotnet secrets manager collapses the configurations, so that we can have an easy to manage key-value equivalent, however if we prefer a prettier JSON formed in the same way, we can manipulate it and it will equally work.



{
  "ExternalServices": {
    "ExternalApiSettings": {
      "Token": "OurSecretToken"
    }
  }
}

Time to run the project again, and we can observe, regardless of the path followed and indicated above, that the settings are correctly merged between files and loaded, in a well, clean and secure way:

Road to Azure

Although in this article I am not going to explain how to create an Azure Vault or an AppService, we will go into the details that are required to properly link one to the other, and make sure that our settings are properly configured in each of the environments.

Since the official Microsoft documentation has good resources explaining these parts better than me, I leave here the links for those who require some information on how to perform these steps:

1. App Service

The first thing we will need is to provide our AppService with a managed identity in order to guarantee controlled access to our Azure Vault.

For this, Azure provides a very simple configuration tab where a unique identifier will be assigned for it.

By default, this option is inactive in an AppService, so it will be required to activate it,

Once configured, we can copy it for properly finding in the next step.

2. Azure Vaults

Already configured the managed Id for our AppService, we only have to give it permissions so that it can read the secrets configured inside.

It is important to remember that each instance must have its own associated Vault, otherwise we could not properly configure the access control either by application or by users who are in charge of maintaining such environment.

Giving permissions to our AppService

So, in our created Azure Vault:

Then we have to click on (+) to create.
For our current needs, we can configure it like this:

Once selected, we will be able to filter having the unique Id copied from the AppService Identity menu.

Note: It's important to remind that these configurations can also be done from Azure cli. More information here

Creating secrets in Vaults

Clicking on (+) Generate/Import we will be able to create the secrets that will be overwriting the ones configured in appSetting.json.

Please put special attention at how the configuration is boiled down using double hyphen notation to separate configuration section names.

Having done that, we have finished our Azure configuration between our AppService and Azure Vault for being able to properly replace our sensitive data in runtime once deployed on our Azure AppServices.

3. Azure Vault code integration

Back to our project again, the last step is to make sure that any values specified in a Vault can overwrite existing configuration specified in the appsettings files.

Required NuGets

Azure.Extensions.AspNetCore.Configuration.Secrets

dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets

Azure.Identity

dotnet add package Azure.Identity

Code configuration

AppSettings

In the environment's appSettings.{env}.json (Test, Production)

For each environment, we have to add a new property in the json file:



 [...]
 "AzureKeyVaultUrl": "https://ourtestkeyvault.vault.azure.net/"
 [...]

The Vault url can be obtained on the main screen of each Vault.

Program.cs

Through the WebApplicationBuilder, add the following code protected by a precompilation directive based on Debug mode:



#if !DEBUG
var keyVaulUrl = builder.Configuration["AzureKeyVaultUrl"];
if(keyVaulUrl == null)
    throw new ArgumentNullException("AzureKeyVaultUrl must be configured for the given environment");

builder.Configuration.AddAzureKeyVault(new Uri(keyVaulUrl), new DefaultAzureCredential());
#endif

This protection will allow us to only use the dotnet-secrets in a local environment, and in any other scenario it will be doing it through the Vaults.

Conclussion

Proper management of settings will allow for an isolated development environment for each developer, as well as well-separated management in the different environments with control over them managed segregated by teams, individuals, roles... etc.

And most important of all, the process allows us to manage our configurations in a completely secure way, both locally and in Azure.

Resources

The entire code can be found here

Useful links

If you liked it, please give me a ⭐ and follow me 😉

DEV Community: Xavier Abelaira Rueda

To comment, or not to comment

📃 Introduction

🔍 The context

⭐ My preference

var or explicit type

📃 Introduction

🔍 The context

⭐ My preference

📏 How to apply

Private fields with or without underscore

📃 Introduction

🔍 The context

⭐ My preference

📏 How to apply

The silly nonsense Software Development discussions in .NET context

📃 Introduction

✔️ Objective

Keyed Services in .NET8's Dependency Injection

📃 Introduction

⏪ Previous context

1. Services definition

2. Custom delegate and Enum

3. DI Container configuration

4. Resolving it

5. Running it

⏩ What's new in .NET8?

1. DI Container configuration

2. Resolving it

📒 Conclusion

🔗 Resources

Useful links

Mechanisms and Performance when querying data to SQLServer from C#

📃 Introduction

✅ Goal

🔍 Scenario

Description

Data model

Querying from a single table

Retrieving paginaged rows tracking entities with EFCore.

Retrieving paginated rows using AsNoTracking() with EFCore.

Retrieving paginated rows using a DTO projection with EFCore.

Retrieving paginated rows using a FromSql / FromSqlInterpolated from EFCore.

Retrieving paginated rows using a view mapped from EFCore as non-indexed entity.

Retrieving paginated rows using a Stored Procedure invoked from EFCore.

Retrieving paginated rows using a SQL query executed with Dapper.

Querying having nested data

Retrieving paginated rows joining tables using EFCore with LINQ.

Retrieving paginated rows joining tables using a DTO projection with EFCore.

Retrieving paginated rows joining tables using raw SQL query with Dapper

Retrieving single entity with joining tables using LINQ FirstAsync with EFCore

Retrieving single element with joining tables using a projection with EFCore

Retrieving single element with joining tables using raw SQL multi-query with Dapper

📒 Conclusion

📉 All results

🔗 Resources

Useful links

Managing AspNetCore appSettings from local to release

Introduction

appSettings files

Microsoft.Extensions.Configuration and WebApplicationBuilder

1. What to configure in global appSettings.json

2. What to configure in appSettings.{env}.json (test, production)

appSettings.Development.json

appSettings.Test.json

appSettings.Production.json

3. Configure dotnet secrets

Option A: By using Visual Studio integrated view.

Option B: By using dotnet cli

Using Visual Studio

Using dotnet cli

Road to Azure

1. App Service

2. Azure Vaults

Giving permissions to our AppService

Creating secrets in Vaults

3. Azure Vault code integration

Required NuGets

Code configuration

AppSettings

Retrieving paginated rows using `AsNoTracking()` with EFCore.