C# on Allen's Dev Journal

Why Doesn't IEnumerable Have a ForEach Method?

Fri, 20 Jun 2025 00:00:00 +0000

Have a ForEach Method?" />

In C#, types like List<T> (and others such as ImmutableList<T>) include a convenient ForEach method. It can be seen as a more functional-style alternative to the traditional foreach loop. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var list = new List<int> { 1, 2, 3, 4, 5 };

// Traditional foreach loop
foreach (var n in list)
{
 Console.WriteLine(n);
}

// The ForEach method achieves the same result
list.ForEach(n => Console.WriteLine(n));

Additionally, the Array class provides a static ForEach method that serves a similar purpose. However, you’ll quickly notice that this handy method is not available on the IEnumerable<T> interface. Why is that?

Note: Let’s address a common but misguided workaround: converting an IEnumerable<T> to a List<T> just to use ForEach() is generally a bad idea. This can trigger the premature execution of a LINQ query, involve unnecessary object creation, and incur the cost of populating a new collection.

There are good reasons for this design choice. I’ve summarized a few of them below.

The Consequences of Adding `ForEach`

Compromising Interface Purity

To put it more formally, adding a ForEach method would violate the Single Responsibility Principle (SRP) and the Interface Segregation Principle (ISP) from the SOLID principles.

Let’s examine the definition of the IEnumerable<T> interface:

1
2
3
4
5
6
7


namespace System.Collections.Generic
{
 public interface IEnumerable<out T> : IEnumerable
 {
 new IEnumerator<T> GetEnumerator();
 }
}

It’s incredibly clean. Its name and definition clearly indicate its single purpose: to signify that an object is “enumerable.” The ForEach method, however, is designed to execute logic and perform actions, which contradicts the interface’s core responsibility of simple iteration.

Unlike LINQ methods such as Select, Where, and OrderBy, which are used for data projection, filtering, and sorting, ForEach is inherently about side effects. LINQ methods are designed to be pure transformations of data sequences. Imagine if LINQ queries included time-consuming logical operations (like complex CPU calculations or I/O). The reliability and predictability of LINQ would be severely compromised.

If a ForEach method contained such intensive operations, the better approach would be to use asynchronous programming (e.g., creating tasks and awaiting them with Task.WhenAll), the Parallel class, or PLINQ. This keeps the IEnumerable<T> as a pure data sequence, free from uncontrollable operational logic.

Here is a simple example using async tasks:

1
2
3
4


IEnumerable<int> items = ...;
var tasks = items.Select(x => CalculateValueAsync(x));
await Task.WhenAll(tasks);
var results = tasks.Select(t => t.Result).ToList();

Introducing Side Effects

Of course, we could write our own extension method to enable ForEach on IEnumerable<T>:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


static class EnumerableExtensions
{
 public static void ForEach<T>(this IEnumerable<T> items, Action<T> action)
 {
 foreach (var item in items)
 {
 action.Invoke(item);
 }
 }
}

However, this can “pollute” the established functional paradigm of LINQ. Why?

Think about the primary purpose of LINQ methods. They are for querying—projecting, filtering, and ordering data. These methods are generally understood to be “pure”; they don’t modify the source data. While they accept a delegate, it’s almost always a Func<T, TResult> that returns a new value or a basis for comparison, not an Action<T> that returns nothing.

The ForEach method is different because it accepts an Action<T>, implying that no value is returned. In this scenario, the operation is very likely to cause side effects by modifying the original data. For instance:

1
2
3
4
5
6


List<Employee> employees = ...;

employees.ForEach(e => {
 if (e.IsPromoted) // If the employee is promoted, give them a raise
 e.Salary += 1000;
});

This shows that ForEach is often used with the intent to mutate the elements of the collection.

While this is a general tendency and not an absolute rule—one could misuse Select to modify data as well—the design of ForEach leans much more heavily toward encouraging side effects compared to standard LINQ methods.

Performance and Resource Considerations

Another critical point is that collections with a built-in ForEach method, like List<T> and Array, have a known, finite size. This is crucial because an IEnumerable<T> can represent a sequence that is deferred or even infinite.

1
2
3
4
5
6
7


IEnumerable<int> GenerateInfiniteNumbers()
{
 while (true)
 {
 yield return 0;
 }
}

Given this, applying a ForEach operation to a sequence of unknown size is inherently risky. Furthermore, unlike a foreach statement, the ForEach method doesn’t allow the use of break, continue, or return to exit the loop early. Once it starts, it is committed to iterating over every single element in the sequence.

From this perspective, omitting a ForEach extension method for IEnumerable<T> seems like a very sensible decision. You might argue that LINQ methods also face issues with infinite sequences, which is true. However, LINQ is fundamentally designed to work with IEnumerable<T>, so this is an unavoidable characteristic that developers must be mindful of.

The benchmarks show that its performance is significantly worse than traditional for and foreach loops:

Method	Mean	Allocation
`for`	424.9 us	-
`foreach`	426.4 us	-
`ForEach`	1,785.0 us	88 B

Notes on the benchmark results:

The table above is simplified and omits some columns for clarity.

The test was run on a preview version of .NET 9, where foreach and for have nearly identical performance with zero memory allocations.

The ForEach method was approximately 4 times slower and incurred memory allocation due to the delegate and its associated closure.

This provides further evidence that ForEach is not a high-performance option. For iterating over a collection where performance matters, traditional for or foreach loops remain the superior choice.

Summary

In conclusion, while adding a ForEach method to IEnumerable<T> is technically feasible, the .NET framework designers chose not to include it due to design philosophy, code clarity, performance considerations, and the potential for unintended side effects.

However, if you find you need this functionality, you are free to implement your own extension method. Just be sure you understand the potential consequences of doing so.

A Tour of Hash Functions: From MD5 to Argon2 and Beyond

Mon, 16 Jun 2025 00:00:00 +0000

In a previous article, we explored the topic of salted password hashing. This time, we’ll expand on that by taking a broader look at the world of hash functions.

Hash functions are crucial tools in computer science and cryptography, essential for tasks like data integrity verification, digital signatures, and secure password storage. There is a wide variety of hash functions, some common and others less so. This article will introduce several of them, highlighting their characteristics and primary use cases.

Early Hash Functions

When we talk about early hash functions, MD5 and SHA-1 are the most widely known. (Of course, even earlier ones like MD4 and SHA-0 exist, but they have long fallen out of use). MD5 and SHA-1 were extremely popular in the 1990s and early 2000s, widely used for file integrity checks, digital signatures, and more.

Although they were once ubiquitous, they are no longer recommended for security-sensitive applications due to known vulnerabilities. Despite this, they remain popular. For instance, many software download sites still provide MD5 or SHA-1 checksums for users to verify that their downloaded files are complete and untampered with. This highlights a common phenomenon: even when a technology has known flaws—or even severe vulnerabilities—its popularity can ensure its continued use. It’s similar to the JPG image format, which, despite its shortcomings (no transparency, lossy compression, prone to artifacts), remains one of the most used image formats today.

So, what are their security issues? In short, both MD5 and SHA-1 are vulnerable to collision attacks. A collision occurs when two different inputs produce the same hash value. This means an attacker could potentially create a malicious file with the same hash as a legitimate one, thereby bypassing integrity checks.

Consider the file download verification scenario mentioned earlier. A website tells you a file’s hash is d41d (using just the first four characters for simplicity). You download the file, compute its hash, and it matches. Normally, you would feel confident that the file is authentic. However, an attacker could craft a malicious file that also produces the hash d41d and trick you into downloading it instead. After verifying the hash, you would mistakenly trust the file and run a virus. This could also be used to forge certificate files, leading to severe consequences.

Even so, executing a collision attack is still computationally expensive. This, combined with MD5’s widespread adoption and fast computation speed, means it is still used in many non-security-critical scenarios to quickly verify file integrity.

The SHA-2 Family

Due to the security flaws in MD5 and SHA-1, the SHA-2 family (including SHA-256, SHA-384, SHA-512, etc.) emerged as the new standard. SHA-2 functions are more complex in design and offer a much higher level of security. They are widely used in digital signatures, certificate authorities (CAs), and other security-critical areas.

When using SHA-2 to store user passwords in a database, it is standard practice to add a random salt. This prevents rainbow table attacks, where an attacker pre-computes the hashes of common passwords and stores them in a lookup table. By adding a unique salt to each password before hashing, the resulting hashes will be different even if two users have the same password, making such attacks infeasible.

Here is a C# example of hashing a password with SHA-256 and a salt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


using System;
using System.Text;
using System.Security.Cryptography;

static byte[] GenerateSalt()
{
 // The method below will show an obsoletion warning in modern .NET
 using (var rng = new RNGCryptoServiceProvider())
 {
 byte[] salt = new byte[16];
 rng.GetBytes(salt);
 return salt;
 }

 // You should use the following instead:
 // return RandomNumberGenerator.GetBytes(16);
}

static byte[] HashPassword(string password, byte[] salt)
{
 using (var sha256 = SHA256.Create())
 {
 byte[] passwordBytes = Encoding.UTF8.GetBytes(password);
 byte[] saltedPassword = new byte[passwordBytes.Length + salt.Length];
 Buffer.BlockCopy(passwordBytes, 0, saltedPassword, 0, passwordBytes.Length);
 Buffer.BlockCopy(salt, 0, saltedPassword, passwordBytes.Length, salt.Length);
 return sha256.ComputeHash(saltedPassword);
 }

 // Newer .NET versions also provide more convenient static methods, like SHA256.HashData().
}

You would then store both the salted hash and the salt in the database. To verify a password, retrieve the salt from the database, apply it to the user’s input, hash it using the same function, and compare it to the stored hash.

Don’t worry about the salt being exposed. Its purpose is not to be secret but to ensure the uniqueness of each hash, rendering pre-computed tables useless.

The SHA-3 Family

While SHA-2 resolved the security issues of its predecessors, it is still based on the same Merkle-Damgård construction. Concerned that cryptanalytic techniques could eventually be extended to break the SHA-2 family and with the rise of quantum computing, the U.S. National Institute of Standards and Technology (NIST) released the SHA-3 standard in 2015.

SHA-3 is based on a completely different design philosophy, the Keccak algorithm. It not only provides higher security but also offers flexible output lengths (e.g., SHA3-224, SHA3-256, SHA3-384, SHA3-512).

However, SHA-3 is not yet widely adopted. It currently serves more as a backup for SHA-2, ready to be deployed if a critical vulnerability is ever found in SHA-2. Furthermore, while it offers excellent security and flexibility, other specialized algorithms are often preferred for specific use cases like password hashing.

PBKDF2

To further increase the difficulty of cracking passwords beyond just adding a salt, we can introduce iterations. PBKDF2 (Password-Based Key Derivation Function 2) is a popular function that does exactly this. It increases the computational work required for a brute-force attack by repeatedly applying a hash function.

PBKDF2 takes a password and a salt and runs them through a hash function thousands of times. The more iterations, the more difficult it is to crack. It is commonly used for password storage and key derivation.

In C#, you can use the Rfc2898DeriveBytes class to implement it:

1
2
3
4
5
6
7
8
9


using System;
using System.Security.Cryptography;
using System.Text;

static byte[] HashPasswordWithPBKDF2(string password, byte[] salt, int iterations = 10000)
{
 using var pbkdf2 = new Rfc2898DeriveBytes(password, salt, iterations, HashAlgorithmName.SHA256);
 return pbkdf2.GetBytes(32); // Generate a 32-byte hash
}

bcrypt and Argon2

Unfortunately, even PBKDF2 can be vulnerable to attacks using modern hardware, especially the massive parallel processing power of GPUs. To address this, more advanced password hashing functions like bcrypt and Argon2 were developed.

bcrypt is a password hashing function based on the Blowfish cipher. It is designed to be slow and computationally intensive. A key feature of bcrypt is its adjustable cost factor, which controls the hashing time. Unlike simple iterations, the cost factor is exponential—incrementing it by one doubles the computation time. In C#, you can use libraries like BCrypt.Net-Next to implement bcrypt.

Argon2 was the winner of the Password Hashing Competition in 2015 and is considered one of the most secure password hashing functions available today. It is highly configurable, allowing you to tune its memory usage, iteration count, and degree of parallelism to provide robust security. Argon2 comes in three variants: Argon2d, Argon2i, and Argon2id, each designed to protect against different types of attacks. In C#, you can use libraries like Konscious.Security.Cryptography.Argon2.

BLAKE2

BLAKE2 is a relatively new hash function (published in 2013) that strikes an excellent balance between speed and security. It was designed to be faster than MD5 and SHA-1 while providing higher security than SHA-2. It is well-suited for file integrity verification and even password hashing.

Its high performance comes from leveraging modern CPU SIMD instruction sets (like SSE2/AVX), making it especially efficient on multi-core processors. It comes in two main versions: BLAKE2b (for 64-bit platforms, with a variable output up to 64 bytes) and BLAKE2s (for 8- to 32-bit platforms, with a variable output up to 32 bytes). It also includes features like a built-in keying mechanism, optional salt, and personalization strings, making it very versatile.

In C#, you can use libraries like BouncyCastle to implement BLAKE2:

1
2
3
4
5
6
7


using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Digests;

var digest = new Blake2bDigest(512); // Output is 512 bits by default
digest.BlockUpdate(data, 0, data.Length);
var hash = new byte[digest.GetDigestSize()];
digest.DoFinal(hash, 0);

SM3

Finally, let’s introduce a Chinese national standard hash function: SM3. Released by the China State Cryptography Administration in 2010, SM3 is an independently designed hash algorithm that does not rely on foreign standards, which is significant for national and information security.

The SM3 algorithm produces a 256-bit hash value and is comparable to SHA-256 in terms of security and efficiency. It is designed to be resistant to collision and preimage attacks and is seeing increasing adoption in China, especially in the finance, government, and defense sectors.

Summary

The world of hash functions is diverse, with each function having its own strengths. From the early MD5 and SHA-1 to the modern SHA-2, SHA-3, PBKDF2, bcrypt, Argon2, BLAKE2, and SM3, every algorithm was designed with a specific purpose in mind.

Here’s a quick guide for common needs:

Data Integrity Verification: MD5, SHA-1 (for non-critical uses), SHA-2, BLAKE2
Password Storage: PBKDF2, bcrypt, Argon2
Digital Signatures: SHA-2, SHA-3

Why You Must Salt and Hash Passwords: A Journey to Secure Storage

Thu, 05 Jun 2025 00:00:00 +0000

The topic of salting and hashing passwords is a fundamental concept in security, but why is it so crucial? This article will guide you through the evolution of password storage, from insecure to secure, to demonstrate the necessity of salted hashing and how to implement it.

We’ve all heard that passwords should never be stored in plaintext. Instead, they should be hashed, and more specifically, salted and hashed. What is the purpose and necessity of this process? And how can we achieve it in C#? Let’s explore these questions by progressing from the least secure to the most secure methods.

1. Plaintext Storage

Let’s start with the most insecure approach imaginable: storing the password as is.

1
2
3
4
5
6


class User
{
 public int Id { get; set; } // Auto-incrementing primary key
 public string Username { get; set; }
 public string Password { get; set; } // Plaintext password
}

When we create a new user, the database stores the literal password.

1
2
3
4
5


var user = new User
{
 Username = "admin",
 Password = "123456"
};

This is incredibly dangerous for several reasons:

If the database is local (e.g., SQLite), anyone who gains access to the database file or decompiles the application to find the connection string can see every user’s password.
If the database is remote, attackers have numerous ways to access the data, including SQL injection, leaked SSH keys, exposed database backups, or other server vulnerabilities.

A plaintext password leak is catastrophic. It not only exposes private user information but also enables attackers to perform credential stuffing (using the leaked credentials to try and log into other websites). Therefore, storing passwords in plaintext must be avoided under all circumstances.

2. Simple Hashing (MD5 / SHA1)

Let’s upgrade our code to store a hash of the password using an algorithm like MD5 or SHA1.

1
2
3
4
5
6


class User
{
 public int Id { get; set; }
 public string Username { get; set; }
 public string PasswordHash { get; set; } // The password hash
}

We can create a helper class to handle hashing and verification:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


class PasswordHelper
{
 public static string HashPassword(string password)
 {
 using var md5 = MD5.Create();
 var hash = md5.ComputeHash(Encoding.UTF8.GetBytes(password));
 return Convert.ToBase64String(hash);
 }

 public static bool VerifyPassword(string password, string passwordHash)
 {
 return HashPassword(password) == passwordHash;
 }
}

In this method, we hash the password with MD5 and store it as a Base64 string. To verify, we simply hash the user’s input and compare it to the stored hash.

Info: Why Base64? Storing the hash as a Base64 string makes it human-readable in the database, unlike a binary BLOB. String-based columns are also often easier and more efficient to index. Many modern hashing algorithms produce string-based outputs by default.

A stored password hash might look like this: ISMvKXpXpadDiUoOSoAfww==

This looks much safer than plaintext. Unfortunately, to an attacker, it’s only marginally better. This is because of rainbow table attacks. A rainbow table is a massive precomputed lookup table containing the hashes of common passwords. An attacker can compare the hashes in your database against their rainbow table to quickly find the original password.

For instance, the hash above corresponds to the plaintext “admin”. An attacker with a rainbow table could crack this password instantly. Don’t underestimate these tables; they can contain billions of entries. Unless your password is very complex, it’s likely vulnerable.

Furthermore, algorithms like MD5 and SHA1 are broken. They are susceptible to collisions, where two different inputs produce the same hash value. An attacker might not find your original password, but if they find another string (e.g., “qwerty”) that produces the same hash, they can use that to log in, as the server only compares the hash values.

3. Hashing with a Salt (SHA256)

To counter these attacks, we need to upgrade our algorithm and introduce a salt. We’ll use SHA256 (part of the secure SHA-2 family) and a unique, random salt for each user.

1
2
3
4
5
6
7


class User
{
 public int Id { get; set; }
 public string Username { get; set; }
 public string PasswordHash { get; set; }
 public string Salt { get; set; } // The salt
}

Now, we update our PasswordHelper:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


class PasswordHelper
{
 public static string HashPassword(string password, byte[] salt)
 {
 var passwordBytes = Encoding.UTF8.GetBytes(password);
 // Combine password and salt
 var combinedBytes = new byte[passwordBytes.Length + salt.Length];
 Buffer.BlockCopy(passwordBytes, 0, combinedBytes, 0, passwordBytes.Length);
 Buffer.BlockCopy(salt, 0, combinedBytes, passwordBytes.Length, salt.Length);

 var hash = SHA256.HashData(combinedBytes);
 return Convert.ToBase64String(hash);
 }

 public static bool VerifyPassword(string password, string passwordHash, byte[] salt)
 {
 return HashPassword(password, salt) == passwordHash;
 }

 public static byte[] GenerateSalt()
 {
 // A 16-byte (128-bit) salt is generally sufficient
 return RandomNumberGenerator.GetBytes(16);
 }
}

Tip: Modern versions of .NET provide convenient static methods like SHA256.HashData and RandomNumberGenerator.GetBytes, removing the need to create instances. In the past, you might have seen RNGCryptoServiceProvider, which is now considered obsolete.

By combining the password with a unique salt before hashing, every resulting hash is unique, even if two users have the same password. This renders rainbow tables useless.

The salt must be stored in the database alongside the hash. During verification, you retrieve the user’s salt and hash, apply the same salt to the entered password, and compare the results. Now, even if an attacker gets your database, they can’t use precomputed tables to crack passwords.

4. Using a Key Derivation Function (PBKDF2)

Salting with SHA256 is quite secure, but we can do better. An attacker who has your database can still attempt a brute-force attack against each individual password. They can’t use a rainbow table, but they can take one user’s hash and salt and rapidly try millions of password combinations.

To combat this, our next step is to make the hashing process intentionally slow. We can achieve this with a Password-Based Key Derivation Function (PBKDF2). C# provides an implementation in the Rfc2898DeriveBytes class.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


class PasswordHelper
{
 public static string HashPassword(string password, byte[] salt)
 {
 // PBKDF2 with 10,000 iterations and SHA256
 using var pbkdf2 = new Rfc2898DeriveBytes(password, salt, 10000, HashAlgorithmName.SHA256);
 // Get a 32-byte (256-bit) hash
 return Convert.ToBase64String(pbkdf2.GetBytes(32));
 }

 // Other methods remain the same
}

Info: Rfc2898 is the standard that specifies PBKDF2. You must specify a hash algorithm in the constructor, as the overload without it is now obsolete.

PBKDF2 introduces an iteration count. This forces the algorithm to repeat the hashing process thousands of times. The higher the count, the slower the computation, and the more difficult it is for an attacker to brute-force the password. A count of 10,000 is a reasonable starting point today, but this number should increase over time as computing power grows. This drastically increases the cost for an attacker to crack even a single password.

5. The Gold Standard: BCrypt and Argon2

Unfortunately, the arms race continues. Attackers can use specialized hardware like GPUs or FPGAs to accelerate the calculations for algorithms like PBKDF2. This brings us to our heavy hitters: BCrypt and Argon2. These algorithms are designed to be “memory-hard,” making them resistant to GPU-based attacks.

Let’s look at BCrypt. Since it’s not in the .NET standard library, we can use a popular third-party library like BCrypt.Net-Next.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


class PasswordHelper
{
 public static string HashPassword(string password)
 {
 // The work factor (12) controls the complexity
 return BCrypt.Net.BCrypt.HashPassword(password, 12);
 }

 public static bool VerifyPassword(string password, string passwordHash)
 {
 return BCrypt.Net.BCrypt.Verify(password, passwordHash);
 }
}

Notice that our User class no longer needs a Salt property. BCrypt generates a salt internally and includes it in the final hash string.

A BCrypt hash looks like this: $2a$12$lraBT1/lH3RiFXjQbywREutDElnBFaolPOEsDAvo1sjK2iRjwCAUi

This string contains everything needed for verification: the algorithm identifier ( $2a$ ), the work factor (12), the salt, and the hash. You only need to store this single string in your database.

Info: The work factor is a power of 2 that controls the computational cost (e.g., a work factor of 12 means 2¹² = 4096 rounds). The higher the factor, the slower the hashing. A value between 10 and 12 is common today.

But what if an attacker is still determined to use their powerful hardware? This is where we bring out our ultimate weapon: Argon2.

Like BCrypt, Argon2 requires a third-party library, such as Konscious.Security.Cryptography. The implementation details are similar to BCrypt—it also produces a self-contained hash string. However, Argon2 is considered even more secure. It was the winner of the Password Hashing Competition (2013-2015) and is designed to be highly resistant to brute-force attacks by being tunable across three dimensions:

Time cost: How many iterations to run (CPU-intensive).
Memory cost: How much memory to use (memory-hard).
Parallelism: How many threads to use.

Argon2 comes in three variants:

Argon2d: Maximizes resistance to GPU cracking attacks.
Argon2i: Optimized to resist side-channel attacks.
Argon2id: A hybrid version that provides resistance to both side-channel and GPU attacks. It is the recommended choice for general-purpose password hashing.

With a robust algorithm like Argon2, you can be confident that passwords are protected against even the most determined attackers using current technology.

Conclusion

In this article, we journeyed from the dangerously insecure practice of storing plaintext passwords to the modern, robust standards of password hashing. We saw how simple hashing is vulnerable to rainbow tables, how old algorithms are broken by collisions, and how salting defeats precomputation attacks. We then explored how key derivation functions like PBKDF2 and memory-hard functions like BCrypt and Argon2 raise the cost of brute-force attacks.

In practice, your choice of algorithm depends on your security requirements.

For a small, low-risk project, SHA256 with a strong, unique salt is a decent baseline that is easy to implement.
For any application where security is a priority, BCrypt or, even better, Argon2 should be your go-to choice. They represent the current best practice for securing user passwords.

Advanced XML Parsing: A Performance Duel Between LINQ, XPath, and Regex

Mon, 26 May 2025 00:00:00 +0000

Continuing our exploration from last time, let’s dive deeper into the surprising performance differences in XML parsing. Our sample XML remains the same, provided by W3Schools:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<?xml version="1.0" encoding="UTF-8"?>
<breakfast_menu>
 <food>
 <name>Belgian Waffles</name>
 <price>$5.95</price>
 <description>Two of our famous Belgian Waffles with plenty of real maple syrup</description>
 <calories>650</calories>
 </food>
 <!-- Three other <food> elements omitted for brevity -->
 <food>
 <name>Homestyle Breakfast</name>
 <price>$6.95</price>
 <description>Two eggs, bacon or sausage, toast, and our ever-popular hash browns</description>
 <calories>950</calories>
 </food>
</breakfast_menu>

This time, our task is more specific: get the value of the <calories> element from the last <food> node (which should be 950).

Our contestants are: LINQ to XML, XPath (running on XDocument), and Regular Expressions.

LINQ to XML

First, let’s see how to accomplish this using the System.Xml.Linq namespace.

1
2
3
4
5
6


public int GetWithElements()
{
 var foods = doc.Root.Elements("food");
 var lastFood = foods.Last();
 return (int)lastFood.Element("calories");
}

Since we know the structure of the XML document, we can simplify this for a slight performance gain by not checking element names at every step:

1
2


public int GetWithElementsOptimized()
 => (int)doc.Root.Elements().Last().Elements().Last();

We can also use the Descendants() method to reduce the number of Elements() calls. In this specific case, because the element we want happens to be the very last element in the entire document, we can take an extreme shortcut:

1
2


public int GetWithDescendants()
 => (int)doc.Root.Descendants().Last();

XPath

Next, let’s try using an XPath expression. We can use the System.Xml.XPath namespace extension methods on our XDocument object.

1
2


public int GetWithXPath()
 => (int)doc.XPathSelectElement("//food[last()]/calories");

Here, we use XPath’s last() function to directly select the <calories> child of the last <food> element. We could have also hardcoded [5] instead of [last()] since we know there are five <food> elements. While this might provide a minuscule performance boost, it’s not robust and feels a bit like cheating, so we’ll stick with last().

However, the expression above is not the most efficient. The //food syntax triggers a search for <food> elements across the entire XML document. We can significantly improve performance by writing a more precise path:

1
2


public int GetWithXPathOptimized()
 => (int)doc.XPathSelectElement("/breakfast_menu/food[last()]/calories");

By specifying the full path, we instruct the engine to only look for <food> nodes that are direct children of the <breakfast_menu> root. This seemingly small change yields a significant performance boost (around 4-5 times faster!).

Regular Expressions

Finally, let’s look at the simple and direct approach with Regex. We just need to match all <calories> nodes and grab the value from the last match.

1
2
3
4
5
6
7


private readonly Regex regex = new Regex(@"<calories>(\d+)</calories>");

public int GetWithRegex()
{
 var matches = regex.Matches(xml);
 return int.Parse(matches[^1].Groups[1].Value);
}

But there’s a huge opportunity for optimization here. Since we only need the last match, we don’t need to find all of them. We can achieve this by using the RegexOptions.RightToLeft option, which tells the engine to start its search from the end of the string.

1
2
3
4
5
6
7


private readonly Regex regexOptimized = new Regex(@"<calories>(\d+)</calories>", RegexOptions.RightToLeft);

public int GetWithRegexOptimized()
{
 var match = regexOptimized.Match(xml);
 return int.Parse(match.Groups[1].Value);
}

With this simple change, we again achieve a performance improvement of about 4-5 times.

Performance Comparison

Now, let’s look at the results of our race. Here’s a summary of the benchmark findings, from fastest to slowest:

Elements() (LINQ to XML): ~101 ns
RegexOptimized() (RightToLeft): ~128 ns
Descendants() (LINQ to XML): ~243 ns
Regex() (Standard): ~605 ns
XPathOptimized() (Full Path): ~1,297 ns
XPath() (Global Search): ~5,099 ns

Are these results what you expected? It’s surprising to see that the humble LINQ to XML methods easily outperformed even the optimized Regex and XPath versions. Most notably, XPath was shockingly slow, with its execution time measured in microseconds, not nanoseconds.

Meanwhile, regular expressions—the winner in our previous contest—couldn’t keep up with LINQ to XML this time. And without the RightToLeft optimization, the Regex performance was significantly worse.

This benchmark proves once again that for querying XML documents, LINQ to XML is often the best choice, offering a fantastic combination of ease-of-use and high performance.

One More Thing…

No performance showdown would be complete without an entry from Span<T>.

1
2
3
4
5
6
7
8


public int GetWithSpan()
{
 var xmlSpan = testXml.AsSpan();
 int endTagIndex = xmlSpan.LastIndexOf("</calories>");
 var trimmedSpan = xmlSpan.Slice(0, endTagIndex);
 int startTagIndex = trimmedSpan.LastIndexOf("<calories>") + 10;
 return int.Parse(xmlSpan.Slice(startTagIndex, endTagIndex - startTagIndex));
}

And the result?

GetWithSpan() Mean Execution Time: ~22.3 ns

As expected, Span<T> operates on another level entirely, leaving all other methods in the dust and showcasing its power for raw, low-level text processing.

Fields vs. Properties: Why Not Just Use Public Fields in C#?

Mon, 12 May 2025 00:00:00 +0000

When writing C# code, we frequently define auto-properties like this:

1
2
3
4


public class Person
{
 public int Age { get; set; }
}

This often raises a question, especially for developers new to the language: Why go through the trouble of writing an auto-property? Why not just declare a simple public field? Like this:

1
2
3
4


public class Person
{
 public int Age;
}

It’s a valid question, and there are several important reasons behind this convention. Let’s explore them.

A Fundamental Difference in Perspective

First and foremost, the way we perceive properties and fields—and the roles they play—is fundamentally different.

When we see a property, we generally expect it to represent a piece of the class’s public contract. We anticipate that it has public read access, while its write access might be more restricted. When we expose a property, we are making a deliberate decision to share a member with the outside world, having fully considered the implications (for example, we can add logic to the setter or make it read-only).

In short, we typically expect a property to be:

A deliberate part of the public API: It’s a member that the developer has intentionally exposed because it has meaning and value to the consumers of the class.
Controlled: Its initialization and modification can be controlled with logic. We can define when it can be set, if it’s required, and whether it can be changed after initialization.
Potentially computed: It isn’t necessarily backed by a simple field. Its value might be derived from other data.

Examples of Computed Properties:

List<T>.Count is derived from the state of the internal array.

AsyncRelayCommand.IsRunning is determined by the status of an underlying Task.

ObservableValidator.HasErrors depends on the contents of an internal list of validation errors.

In UI frameworks, a CheckBox.IsChecked property is often connected to a more complex dependency property system.

Now, how do we typically think about fields? Consider this simple code snippet:

1
2
3
4
5
6
7


class Manager
{
 private readonly int _uniqueId; // A unique ID with a special purpose.
 private readonly IConfiguration _config; // An interface object initialized via dependency injection.
 private bool _isDataProcessed = false; // A flag for internal state tracking.
 private readonly object _syncRoot = new(); // A lock object for internal thread safety.
}

Does this align with your general impression of fields? If so, then the following code would probably feel a bit jarring and confusing:

1
2
3
4
5
6


class Manager
{
 protected readonly int UniqueId;
 public bool Flag = false;
 public string ErrorMessage = "Oops!";
}

The reason for this discomfort should be becoming clear. Our conventional understanding of a field’s role is:

It’s primarily for internal use, serving as a helper for properties or methods (e.g., lock objects, flags, injected dependencies).
It’s a simple storage location without much associated logic, lacking the sophisticated initialization options of properties.
It’s generally considered “unsafe” for public exposure, as developers consuming the class wouldn’t know if they can safely modify it without breaking internal invariants.

Based on these different perspectives, it’s easier to understand why we generally avoid public fields.

Of course, there are always exceptions. For example, in simple Unity game development, you might write code like this:

1
2
3
4
5
6
7


public class Player : MonoBehaviour
{
 [SerializeField]
 private int health; // Unity's official convention is lowercase for serialized fields
 public int attack;
 public int defense;
}

Or when interacting with C/C++ DLLs (P/Invoke), you’ll often define structs with public fields to match the memory layout:

1
2
3
4
5
6
7


[StructLayout(LayoutKind.Sequential)]
public struct MyData
{
 public ushort Index;
 public uint Value;
 public byte[] Data;
}

In these specific contexts, public fields are not just acceptable but are often the standard practice.

Long-Standing Conventions in the Ecosystem

These differing perspectives have led to a set of strong conventions that are reinforced by the .NET standard libraries and third-party packages.

This raises a classic “chicken or the egg” question: did the libraries adopt these conventions because it was already a best practice, or did it become a best practice because the libraries were designed that way? Regardless, the convention is firmly established.

Here are just a few examples:

WPF/UI Frameworks: To bind a variable in XAML to a Model or ViewModel, that variable must be a property. Key features like Dependency Properties are also intrinsically linked to properties.
Serialization: Libraries like Json.NET and System.Text.Json will, by default, only serialize public properties. Fields are ignored.
Data-Binding Controls: UI controls like DataGrid or PropertyGrid that automatically generate their interface based on a data type do so by reflecting over its properties, not its fields.
Entity Framework Core: In a Code-First approach, your entity’s mapped members must be properties. When using a Database-First approach, the scaffolding tools generate classes with properties.
Interfaces: C# interfaces can declare properties, but they cannot declare fields.
Records: C#’s record types use properties under the hood to achieve their immutability and value-based equality features.

You’ll find similar behavior in other tools, such as object-mappers (e.g., AutoMapper, Mapster), where properties are treated as the primary members for mapping.

Given how deeply ingrained this convention is, why choose to be the outlier?

Flexibility and Encapsulation

Properties offer unparalleled flexibility. You can embed arbitrary logic within their get and set accessors. A classic example is data validation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public class Person
{
 private int _age;

 public int Age
 {
 get => _age;
 set
 {
 if (value < 0)
 {
 throw new ArgumentOutOfRangeException(nameof(value), "Age must be greater than 0.");
 }

 _age = value;
 }
 }
}

Another common use case is implementing change notification:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


class ViewModel : INotifyPropertyChanged
{
 private string _name;

 public string Name
 {
 get => _name;
 set
 {
 if (_name != value)
 {
 _name = value;
 OnPropertyChanged(nameof(Name)); // Implementation of event and method omitted
 }
 }
 }
 // ... INotifyPropertyChanged implementation
}

Even more important is the fine-grained encapsulation they provide. Consider the common variations for a setter:

public set;: Anyone can modify the property.
protected set;: Only the class and its subclasses can modify it.
private set;: Only methods within the class itself can modify it.
internal set;: Only code within the same assembly can modify it.
init;: The property can only be set during object initialization.
**(no setter)`: A read-only property, settable only in the constructor.

Furthermore, these can be combined with keywords like required and virtual to achieve even greater flexibility and control. Fields simply cannot compete with this level of sophistication (while some keywords can be applied to fields, their effect is usually all-or-nothing, restricting both read and write access).

Performance Considerations

At this point, some might argue: “I know that an auto-property is just syntactic sugar. The compiler turns it into a private backing field and a pair of get/set methods. Doesn’t a method call have more overhead than directly accessing a field? If so, isn’t a public field more performant?”

This is an excellent question. Let’s look at the compiled code. Consider this class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var p = new Person();

p.Age1 = 10;
p.Age2 = 20;

public class Person
{
 public int Age1 { get; set; }
 public int Age2;
}

If we inspect the Intermediate Language (IL), we see a difference:

1
2
3
4
5
6
7


IL_0000: newobj instance void Person::.ctor()
IL_0005: dup
IL_0006: ldc.i4.s 10
IL_0008: callvirt instance void Person::set_Age1(int32) // Method call for property
IL_000d: ldc.i4.s 20
IL_000f: stfld int32 Person::Age2 // Direct field store
IL_0014: ret

It certainly seems that Age1 uses a method call (callvirt) while Age2 uses a direct field store instruction (stfld). So, is the property slower? Before you jump to conclusions, let’s look at the final machine code generated by the Just-In-Time (JIT) compiler:

1
2
3
4
5
6


; Program.<Main>$(System.String[])
 L0000: mov ecx, 0x33a4ca1c
 L0005: call 0x066f300c ; new Person()
 L000a: mov dword ptr [eax+4], 0xa ; p.Age1 = 10
 L0011: mov dword ptr [eax+8], 0x14 ; p.Age2 = 20
 L0018: ret

As you can see, the JIT compiler is smart enough to inline the simple auto-property setter, converting it into a direct memory write operation. The resulting machine code for setting the property is identical to that of setting the field. This means that at runtime, the performance of an auto-property is the same as a public field. You can safely dismiss this concern.

The Future is Properties: C# 13 and the `field` Keyword

If you’re still on the fence, there’s more good news on the horizon. .NET 9 (with C# 13) is expected to finally introduce the field keyword. This feature makes it much easier to add logic to properties without manually declaring a backing field.

Previously, to write a “full property,” you had to do this:

1
2
3
4
5
6
7


private int _age;

public int Age
{
 get => _age / 2;
 set => _age = value * 2;
}

With the new field keyword, you can write it like this:

1
2
3
4
5


public int Age
{
 get => field / 2;
 set => field = value * 2;
}

Here, field acts as an implicit, compiler-generated backing field. This further streamlines the process of creating properties with custom logic, reinforcing their central role in the language.

Summary

Through this discussion, you should now have a deeper understanding of why C# development strongly favors properties over public fields. This doesn’t mean public fields are forbidden—they have their place in specific scenarios like P/Invoke or certain game development frameworks. However, for general application and library development, properties are the superior choice.

The continued evolution of C#—from init setters in C# 9, to records, to primary constructors in C# 12, and now the upcoming field keyword—is consistently aimed at improving the experience of working with properties.

This should give you the confidence to embrace properties in your C# code without hesitation.

Efficient XML Parsing in C#: A Performance Comparison

Sun, 04 May 2025 00:00:00 +0000

I recently encountered a task at work involving reading and writing XML, which led me to explore the performance implications of different approaches. I’d like to share my findings with you.

For our demonstration, we’ll use a sample XML text from W3Schools:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<?xml version="1.0" encoding="UTF-8"?>
<breakfast_menu>
 <food>
 <name>Belgian Waffles</name>
 <price>$5.95</price>
 <description>Two of our famous Belgian Waffles with plenty of real maple syrup</description>
 <calories>650</calories>
 </food>
 <!-- ... three <food> elements omitted for brevity ... -->
 <food>
 <name>Homestyle Breakfast</name>
 <price>$6.95</price>
 <description>Two eggs, bacon or sausage, toast, and our ever-popular hash browns</description>
 <calories>950</calories>
 </food>
</breakfast_menu>

Our goal is to read the values of all <name> elements and store them in a List<string>. Let’s implement this using several different methods.

Using `XmlDocument`

XmlDocument represents the traditional, DOM-based approach. It can be used in a couple of ways: one is by using methods like GetElementsByTagName to traverse the document tree, and the other is by using XPath expressions to select nodes directly. Let’s look at the first method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public List<string> XmlDocument()
{
 var doc = new XmlDocument();
 doc.LoadXml(testXml);
 return doc
 .GetElementsByTagName("food")
 .OfType<XmlNode>()
 .Select(node => node["name"]!.InnerText)
 .ToList();
}

Now, let’s try it with an XPath expression:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public List<string> XmlDocumentXPath()
{
 var doc = new XmlDocument();
 doc.LoadXml(testXml);
 return doc
 .SelectNodes("//food/name")
 .OfType<XmlNode>()
 .Select(node => node.InnerText)
 .ToList();
}

Using `System.Xml.Linq`

System.Xml.Linq (XDocument) offers a more modern and developer-friendly API. Here’s how to implement our task with it:

1
2
3
4
5
6
7
8
9


public List<string> XDocument()
{
 var doc = XDocument.Parse(testXml);
 return doc
 .Root
 .Elements("food")
 .Select(node => node.Element("name")!.Value)
 .ToList();
}

While XDocument also supports XPath, its fluent API is already so concise that using XPath often isn’t necessary for simpler queries.

Using `XmlReader`

XmlReader is a forward-only, stream-based parser. While its API is more complex to use, it is extremely efficient in terms of speed and memory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public List<string> XmlReader()
{
 using var stringReader = new StringReader(testXml);
 using var xmlReader = System.Xml.XmlReader.Create(stringReader);
 var res = new List<string>(8);
 while (xmlReader.Read())
 {
 if (xmlReader.IsStartElement() && xmlReader.Name == "name")
 {
 res.Add(xmlReader.ReadElementContentAsString());
 }
 }
 return res;
}

Using Regular Expressions (Regex)

Since our task is relatively simple and the XML structure is predictable, we can also use regular expressions.

1
2
3
4
5


public List<string> Regex()
{
 var matches = System.Text.RegularExpressions.Regex.Matches(testXml, @"<name>(.*?)</name>");
 return matches.Select(match => match.Groups[1].Value).ToList();
}

Using Traditional String Methods

Finally, we can fall back on basic string manipulation methods.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


public List<string> StringOps()
{
 var res = new List<string>(8);
 int cur = 0;
 while (true)
 {
 // Find the next <name> tag
 int idx = testXml.IndexOf("<name>", cur);
 // If not found, we're done
 if (idx < 0)
 break;
 // Find the corresponding </name> tag
 int end = testXml.IndexOf("</name>", idx + 6);
 res.Add(testXml.Substring(idx + 6, end - idx - 6));
 // Continue searching from the end of the current tag
 cur = end + 7;
 }
 return res;
}

Spoiler alert: this method is surprisingly inefficient, much slower than the other approaches. This leads us to our secret weapon: Span<T>.

Using `Span<T>`

Span<T>, introduced in C# 7.2, allows for highly efficient, allocation-free memory manipulation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


public List<string> SpanOps()
{
 var res = new List<string>(8);
 var span = testXml.AsSpan();
 while (true)
 {
 int idx = span.IndexOf("<name>");
 if (idx < 0)
 break;
 // Slice from after "<name>" and find the closing tag
 var contentSlice = span.Slice(idx + 6);
 int end = contentSlice.IndexOf("</name>");
 // Add the content to the list
 res.Add(contentSlice.Slice(0, end).ToString());
 // Move the span past the content we just processed
 span = contentSlice.Slice(end + 7);
 }
 return res;
}

Performance Test

We used BenchmarkDotNet to test the performance of these methods. Here are the results:

Case	Mean	Min	Max	Allocated Bytes
`XmlDocument`	10.65 µs	10.40 µs	10.79 µs	17,608
`XPath`	5.74 µs	5.72 µs	5.76 µs	18,912
`LINQ`	3.95 µs	3.94 µs	3.97 µs	15,054
`XmlReader`	3.04 µs	3.02 µs	3.06 µs	11,776
`Regex`	2.13 µs	2.11 µs	2.14 µs	2,632
`StringOps`	37.16 µs	37.08 µs	37.32 µs	448
`SpanOps`	134.48 ns	133.89 ns	135.11 ns	448

So, were you impressed by the power of Span<T>? It’s in a league of its own, reaching nanosecond-level performance. From these results, we can draw a few conclusions:

If the content we need to extract isn’t complex and the structure is consistent, we can use Regex for a very fast and low-allocation solution.
When the task requires robust XML parsing, we should rely on dedicated XML APIs. Their performance ranking is: XmlReader > XDocument (LINQ) > XmlDocument.
From a practical standpoint, XDocument is often the best choice. It’s significantly faster than the traditional XmlDocument and not much slower than XmlReader, but with a much more pleasant and productive API, making it the optimal choice for most scenarios.
Using Span<T> can lead to massive performance gains, especially when your logic involves frequent string operations like IndexOf and slicing (Substring). It’s the clear winner for performance-critical scenarios that can be solved with string manipulation.

Why ValueTask? A Guide to C#'s Performance-Oriented Task Alternative

Wed, 23 Apr 2025 00:00:00 +0000

Since C# 5.0 introduced the async and await keywords, asynchronous programming has become remarkably simple. The Task type has played a crucial role in this paradigm, becoming a ubiquitous part of modern .NET development. However, with the release of .NET Core 2.0, Microsoft introduced a new type: ValueTask. What is this type, why do we need it, and in what situations should we use it? Let’s explore these questions today.

A Quick Recap of the `Task` Type

In asynchronous programming, we use the Task type to represent an asynchronous operation. Compared to other mainstream programming languages, C#’s tasks are incredibly lightweight. For instance, C# experts have noted that a Task object typically consumes only 64-136 bytes of memory, whereas a goroutine in Go starts at a minimum of 2 KB.

Furthermore, Task comes with numerous optimization techniques:

Task.FromResult: To return a completed task with a specific result.
Task.CompletedTask: To return a singleton, already-completed task.
Task.FromCanceled: To return a task in a canceled state.
Task.FromException: To return a task in a faulted state.

For a long time, from C# 5.0 (.NET Framework 4 era) until .NET Core 2.0, Task served its purpose exceptionally well.

The Problem with the Traditional `Task` Type

As .NET evolved into a cross-platform framework, its use cases expanded dramatically. Microsoft’s ambitions grew, leading to a relentless focus on performance optimization from every angle. This effort brought us innovations like Span<T>, Memory<T>, and ref struct, and it also led to the creation of ValueTask. So, what was the problem with the traditional Task type?

First, we need to understand that Task exists in both generic (Task<TResult>) and non-generic versions, representing async operations with and without a return value, respectively. When ValueTask was first introduced, it only had a generic version. This tells us that its initial design was focused exclusively on asynchronous methods that return a value.

Let’s consider a classic example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


private readonly ConcurrentDictionary<int, string> _cache = new ();

public async Task<string> GetMessageAsync(int id)
{
 if (_cache.TryGetValue(id, out var message))
 {
 return message;
 }

 message = await GetMessageFromDatabaseAsync(id);
 _cache.TryAdd(id, message);

 return message;
}

In the GetMessageAsync method above, we first try to retrieve a message from a cache. If it’s not found, we fetch it from the database. The problem lies in the cache-hit scenario. Although it seems like we are returning a value directly, the method’s signature is async Task<string>. This means that even when the result is available synchronously, the C# compiler still allocates a new Task<string> object on the heap to wrap that result. This leads to unnecessary memory allocation.

This scenario, where an async method can return a result without ever hitting an await keyword, is known as “synchronous completion.” The operation begins and ends on the same thread.

Introducing `ValueTask`

ValueTask was created to solve this very problem. It was officially introduced in .NET Core 2.0 and enhanced in .NET Core 2.1 (with the addition of the IValueTaskSource<T> interface, enabling properties like IsCompleted). A non-generic ValueTask was also added later.

Instead of thinking of ValueTask as just a value type, it’s more helpful to understand it as a type that can represent either a Value or a Task. This makes it perfectly suited for the caching scenario described above. We can modify the code to use ValueTask:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public async ValueTask<string> GetMessageAsync(int id)
{
 if (_cache.TryGetValue(id, out var message))
 {
 return new ValueTask<string>(message); // In C# 7.2+, you can just `return message;`
 }

 message = await GetMessageFromDatabaseAsync(id);
 _cache.TryAdd(id, message);

 return message;
}

Now, if the data is found in the cache, the method can return a ValueTask<T> that wraps the result directly, avoiding any heap allocation for a Task<T> object. If the data is not in the cache (the “cold path”), the method proceeds to await the database call. In this case, ValueTask<T> will wrap an underlying Task<T>, and its performance will be roughly equivalent to (or very slightly slower than) using Task<T> directly, due to the overhead of the wrapper struct.

The non-generic ValueTask is used even more rarely. It’s only beneficial in scenarios where an operation can complete asynchronously without requiring any memory allocation. Stephen Toub, a key architect behind this feature, advises against using the non-generic ValueTask unless profiling has proven that the tiny allocation of a standard Task is a critical performance bottleneck.

At this point, you might be thinking: ValueTask is a struct, so it’s allocated on the stack, which is much cheaper than heap allocation. Like ValueTuple versus Tuple or Span<T> versus an array slice, it seems like a clear performance win.

But is ValueTask really that perfect? Can it completely replace Task? The answer is not so simple.

Important `ValueTask` Caveats

Now it’s time to discuss the important rules and limitations you must respect when using ValueTask.

A `ValueTask` Cannot Be Awaited More Than Once

A ValueTask may wrap a reusable underlying object (an IValueTaskSource<T>). Once you await it and the operation completes, that underlying object may be recycled and used for another operation. Awaiting it a second time could lead to reading incorrect state or other unpredictable behavior. In contrast, a Task represents a final state and can be awaited any number of times.

Do Not Block on a `ValueTask`

The underlying IValueTaskSource<T> that a ValueTask may wrap is not required to support blocking until completion. This means you must not call methods like .Wait() or access the .Result property on a ValueTask that has not yet completed. Doing so is likely to cause a deadlock or throw an exception.

However, if you can confirm that a ValueTask is already complete (by checking its IsCompleted property), it is safe to access its .Result property to get the value.

Microsoft has added a specific Roslyn analyzer warning for this misuse: CA2012: Use ValueTask correctly.

Do Not `await` a `ValueTask` Concurrently

ValueTask was designed as a performance optimization, not a full-featured Task replacement. The underlying object is intended to be awaited by a single “consumer” at a time and is not thread-safe. Attempting to await the same ValueTask from multiple threads concurrently can easily introduce race conditions and subtle bugs. A Task, on the other hand, is thread-safe and supports any number of concurrent awaiters.

How to Work Around `ValueTask`’s Limitations

In practice, you might encounter situations where you need to overcome these limitations. Here are the recommended approaches:

To get the result synchronously: If you need to block to get a ValueTask<T>’s result, you must first check properties like IsCompleted or IsCompletedSuccessfully. Only after confirming it’s complete should you access the .Result property.
To await multiple times or from multiple threads: Use the .AsTask() method. This will convert the ValueTask<T> into a standard Task<T>. If the ValueTask<T> already wraps a Task<T>, it returns that same instance. If it wraps a result, it will return a new, completed Task<T>. Once you have a Task<T>, you can use it with all the flexibility you’re used to.

Based on its design and limitations, a widely accepted best practice has emerged:

Best Practice: In the vast majority of cases, you should await a ValueTask<T> immediately to consume its result. Avoid assigning the returned ValueTask<T> to a local variable for later use. If you need to store it, pass it around, or await it multiple times, convert it to a Task first using .AsTask().

Conclusion

In summary, ValueTask is a powerful feature for performance-critical code, offering a way to eliminate heap allocations in “hot path” scenarios where an async method often completes synchronously. However, this performance gain comes with strict usage rules, such as the single-await limitation. Using it can feel like walking a tightrope; a misstep can lead to subtle bugs.

Fortunately, the primary use case is simple and safe: await the ValueTask<T> immediately. As long as you remember that it is a specialized tool and not a general-purpose replacement for Task, you can leverage its benefits effectively.

Hopefully, this article helps you use ValueTask correctly and confidently in your projects.

References

Improving Thread Communication in .NET: Moving Beyond Flags and Polling

Sun, 06 Apr 2025 00:00:00 +0000

In multi-threaded development, we often use flags and polling to control execution logic within threads. However, this approach reduces code readability and maintainability while lacking elegance. This article explores how to use semaphores and other mechanisms to replace polling and flags, thereby improving inter-thread communication and control.

Traditional Approach

First, let’s examine the traditional approach using flags and polling with a simple example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


class MyService
{
 private volatile bool _shouldStop;
 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 private void Worker()
 {
 while (_shouldStop)
 {
 // Do some work
 Thread.Sleep(50); // Simulate work
 }
 }
}

This is a typical example. Here, _shouldStop is a flag indicating whether the thread should stop. We set and read this flag in the Start and Stop methods, and poll it in the Worker method to determine whether the thread should continue executing.

Info: The _shouldStop flag is marked as volatile, ensuring the compiler doesn’t optimize it and guaranteeing each read gets the most recent value. In practice, if our polling includes operations like Thread.Sleep, we would still get the latest value even without the volatile keyword.

Warning: Note that we’re using simple code to introduce concepts, not providing a robust implementation. The example doesn’t handle multiple calls to Start or thread exceptions.

If we want to add pause and resume functionality, we need additional flags and polling logic:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


class MyService
{
 private volatile bool _shouldStop;
 private volatile bool _isRunning;
 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _isRunning = true;
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 public void Pause()
 {
 _isRunning = false;
 }

 public void Resume()
 {
 _isRunning = true;
 }

 private void Worker()
 {
 while (_shouldStop)
 {
 if (_isRunning)
 {
 // Do some work
 }

 Thread.Sleep(50); // Sleep even when paused to avoid high CPU usage
 }
 }
}

Classic Two-Flag Pattern

Now let’s explore how to replace flags with semaphores.

Using ManualResetEvent for Thread Pause and Resume

Let’s consider what _isRunning accomplishes. We use its value to control thread execution but can’t be notified immediately when it changes, so we must poll periodically. What if we could block at a specific point when it’s false and continue when it becomes true, without polling?

For this requirement, we can use two WaitHandle subclasses: ManualResetEvent and AutoResetEvent. ManualResetEvent is a manually resettable semaphore that remains in a signaled state until reset. In contrast, AutoResetEvent automatically resets after each signal. Here, ManualResetEvent fits our needs better because we want continuous execution after signaling rather than requiring a set for each execution.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


class MyService
{
 private volatile bool _shouldStop;
 private ManualResetEvent _isRunningEvent = new ManualResetEvent(false); // Initially closed

 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _isRunningEvent.Set(); // Signal when the thread starts
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 public void Pause()
 {
 _isRunningEvent.Reset(); // Close the semaphore
 }

 public void Resume()
 {
 _isRunningEvent.Set(); // Signal the semaphore
 }

 private void Worker()
 {
 while (_shouldStop)
 {
 _isRunningEvent.WaitOne(); // Wait for the semaphore to signal

 // Do some work

 Thread.Sleep(50); // Sleep to avoid high CPU usage
 }
 }
}

Using CancellationToken to Stop Tasks

We can further optimize by using CancellationToken to stop tasks. CancellationToken is a .NET mechanism for canceling operations that can pass a cancellation request to a task and be checked within that task. It works for both asynchronous and multi-threaded programming. Here, we use it to replace the _shouldStop flag:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


class MyService
{
 private ManualResetEvent _isRunningEvent = new ManualResetEvent(false); // Initially closed
 private Thread? _workerThread;
 private CancellationTokenSource _cancellationTokenSource = new CancellationTokenSource();

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _isRunningEvent.Set(); // Signal when the thread starts
 _workerThread.Start();
 }

 public void Stop()
 {
 _cancellationTokenSource.Cancel(); // Cancel the operation
 _workerThread?.Join();
 }

 public void Pause()
 {
 _isRunningEvent.Reset(); // Close the semaphore
 }

 public void Resume()
 {
 _isRunningEvent.Set(); // Signal the semaphore
 }

 private void Worker()
 {
 while (!_cancellationTokenSource.Token.IsCancellationRequested)
 {
 _isRunningEvent.WaitOne(); // Wait for the semaphore to signal

 // Do some work

 Thread.Sleep(50); // Sleep to avoid high CPU usage
 }
 }
}

The advantages of CancellationToken aren’t fully demonstrated in this simple example. In practice, many methods accept a CancellationToken parameter, allowing us to cancel long-running tasks called within the Worker method rather than waiting for them to finish after cancellation.

Optimizing the Producer-Consumer Pattern

We often need to implement a producer-consumer pattern using a queue:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


class MyService
{
 private readonly Queue<int> _queue = new Queue<int>();
 private readonly object _lock = new object();

 private volatile bool _shouldStop;
 private volatile bool _isRunning;

 private Thread? _workerThread;

 public void Start()
 {
 _workerThread = new Thread(Worker);
 _shouldStop = false;
 _isRunning = true;
 _workerThread.Start();
 }

 public void Stop()
 {
 _shouldStop = true;
 _workerThread?.Join();
 }

 // Pause and Resume methods omitted

 public void Enqueue(int item)
 {
 lock (_lock)
 {
 _queue.Enqueue(item);
 }
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 lock (_lock)
 {
 if (_queue.Count > 0 && _isRunning) // Could also use TryDequeue
 {
 var item = _queue.Dequeue();
 // Process item
 }
 }

 Thread.Sleep(50); // Sleep even when paused to avoid high CPU usage
 }
 }
}

In this example, we:

UseQueue with thread locks to ensure thread safety
Use_shouldStop and_isRunning to control thread execution
Uselock in theWorker method to access the queue safely
Expose anEnqueue method for producers to add tasks

How can we optimize this approach?

Using Thread-Safe Collections

.NET provides thread-safe collection types like ConcurrentQueue<T> that can be safely used in multi-threaded environments without manual locking:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


class MyService
{
 private readonly ConcurrentQueue<int> _queue = new ConcurrentQueue<int>();

 public void Enqueue(int item)
 {
 _queue.Enqueue(item);
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 if (_isRunning && _queue.TryDequeue(out var item))
 {
 // Process item
 }

 Thread.Sleep(50); // Sleep even when paused to avoid high CPU usage
 }
 }
}

This eliminates the need for manual locking as ConcurrentQueue<T> automatically handles thread safety.

Using Semaphores Instead of Flags

We’re still polling in the code above, essentially waiting for data in the queue. We could use a semaphore that signals only when new data arrives—an AutoResetEvent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


class MyService
{
 private readonly ConcurrentQueue<int> _queue = new ConcurrentQueue<int>();
 private readonly AutoResetEvent _queueEvent = new AutoResetEvent(false); // Initially closed

 public void Enqueue(int item)
 {
 _queue.Enqueue(item);
 _queueEvent.Set(); // Signal the semaphore
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 _queueEvent.WaitOne(); // Wait for the semaphore to signal

 if (_isRunning && _queue.TryDequeue(out var item))
 {
 // Process item
 }
 }
 }
}

However, this approach isn’t ideal. If multiple data items arrive simultaneously, we call Set multiple times, but the semaphore only signals once, potentially delaying data processing. A better approach would be using Semaphore, which is like a gate with variable width—each signal makes the gate wider, unlike AutoResetEvent’s binary states. But we have an even better solution.

Using BlockingCollection for the Producer-Consumer Pattern

.NET provides BlockingCollection<T>, a purpose-built class for the producer-consumer pattern with thread safety and blocking functionality:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


class MyService
{
 private readonly BlockingCollection<int> _queue = new BlockingCollection<int>();

 public void Enqueue(int item)
 {
 _queue.Add(item); // Add data to the queue
 }

 public void Worker()
 {
 while (!_shouldStop)
 {
 if (_isRunning && _queue.TryTake(out var item, Timeout.Infinite)) // Wait for data
 {
 // Process item
 }
 }
 }
}

With this approach, if the queue is empty, TryTake blocks the current thread until data is available. When Add is called, BlockingCollection<T> automatically signals waiting threads, eliminating the need to manually handle semaphores.

Info: Looking at BlockingCollection<T>’s source code reveals it uses ConcurrentQueue<T> and SemaphoreSlim internally. The underlying collection is configurable (e.g., ConcurrentStack<T>, ConcurrentBag<T>), allowing different behaviors by passing different collection types.

Conclusion

In this article, we explored how to use semaphores and other mechanisms to replace polling and flags for thread communication and control. Classes like ManualResetEvent, AutoResetEvent, CancellationToken, and BlockingCollection<T> enable more elegant multi-threaded programming, avoiding the problems associated with polling and flags.

In real-world development, always consider these built-in classes and tools rather than reinventing the wheel.

.NET 8 Dependency Injection

Mon, 10 Mar 2025 00:00:00 +0000

Dependency Injection (DI) is a design pattern used to decouple dependencies between components (services). It achieves this by delegating the creation and management of dependencies to an external container, rather than having components create their dependent objects directly.

In .NET, this is primarily implemented using IServiceCollection and IServiceProvider, which are now integral parts of the runtime libraries, making them universally available across the .NET platform!

1 ServiceCollection

IServiceCollection is essentially a list of ServiceDescriptor objects. A ServiceDescriptor describes a service’s type, its implementation, and its lifetime.

1
2
3
4
5


public interface IServiceCollection :
 IList<ServiceDescriptor>,
 ICollection<ServiceDescriptor>,
 IEnumerable<ServiceDescriptor>,
 IEnumerable;

The framework provides a set of extension methods (primarily in ServiceCollectionServiceExtensions) to help us add service descriptions to the service container.

1
2
3
4
5
6
7
8


// Example: Registering services with different lifetimes
builder.Services.AddTransient<StudentService>();
// Registering keyed services (new in .NET 8)
builder.Services.AddKeyedTransient<IStudentRepository, StudentRepository>("a");
builder.Services.AddKeyedTransient<IStudentRepository, StudentRepository2>("b");
builder.Services.AddTransient<TransientService>();
builder.Services.AddScoped<ScopeService>();
builder.Services.AddSingleton<SingletonService>();

2 ServiceProvider

IServiceProvider defines a method, GetService, which allows us to retrieve an instance of a service given its type.

1
2
3
4


public interface IServiceProvider
{
 object? GetService(Type serviceType);
}

Here’s a look at the default implementation of GetService (it defaults to the root scope if no engine scope is provided):

1
2
3


// Simplified view
public object? GetService(Type serviceType) =>
 GetService(ServiceIdentifier.FromServiceType(serviceType), Root);

The more detailed internal implementation looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


internal object? GetService(ServiceIdentifier serviceIdentifier, ServiceProviderEngineScope serviceProviderEngineScope)
{
 if (_disposed)
 {
 ThrowHelper.ThrowObjectDisposedException();
 }

 // Get the accessor for the requested service identifier
 ServiceAccessor serviceAccessor = _serviceAccessors.GetOrAdd(serviceIdentifier, _createServiceAccessor);

 // Execute resolution hook
 OnResolve(serviceAccessor.CallSite, serviceProviderEngineScope);
 DependencyInjectionEventSource.Log.ServiceResolved(this, serviceIdentifier.ServiceType);

 // Get the service instance using the accessor's realization function
 object? result = serviceAccessor.RealizedService?.Invoke(serviceProviderEngineScope);
 System.Diagnostics.Debug.Assert(result is null || CallSiteFactory.IsService(serviceIdentifier));
 return result;
}

The ServiceIdentifier struct essentially wraps the service type and an optional service key (introduced for .NET 8’s keyed services):

1
2
3
4
5


internal readonly struct ServiceIdentifier : IEquatable<ServiceIdentifier>
{
 public object? ServiceKey { get; }
 public Type ServiceType { get; }
}

Clearly, service resolution is handled by serviceAccessor.RealizedService. The creation of the ServiceAccessor itself happens in CreateServiceAccessor:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


private ServiceAccessor CreateServiceAccessor(ServiceIdentifier serviceIdentifier)
{
 // Get the CallSite for the service using CallSiteFactory. 
 // The CallSite represents the plan for resolving the service.
 ServiceCallSite? callSite = CallSiteFactory.GetCallSite(serviceIdentifier, new CallSiteChain());

 if (callSite != null)
 {
 DependencyInjectionEventSource.Log.CallSiteBuilt(this, serviceIdentifier.ServiceType, callSite);

 // Trigger event related to CallSite creation.
 OnCreate(callSite);

 // If the cache location is Root, it indicates a singleton service.
 if (callSite.Cache.Location == CallSiteResultCacheLocation.Root)
 {
 // Resolve the value directly from the cache.
 object? value = CallSiteRuntimeResolver.Instance.Resolve(callSite, Root);
 // Return an accessor that always returns the cached value.
 return new ServiceAccessor { CallSite = callSite, RealizedService = scope => value };
 }

 // Use the engine to create the realization function.
 Func<ServiceProviderEngineScope, object?> realizedService = _engine.RealizeService(callSite);
 return new ServiceAccessor { CallSite = callSite, RealizedService = realizedService };
 }

 // If no CallSite could be created, return an accessor that always returns null.
 return new ServiceAccessor { CallSite = callSite, RealizedService = _ => null };
}

2.1 ServiceProviderEngine

The ServiceProviderEngine is the execution engine responsible for resolving services within the provider. It’s established when the provider is initialized. There are two main types of engines: Dynamic and Runtime. By default, the Dynamic engine is used on .NET Framework and .NET Standard 2.0.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


private ServiceProviderEngine GetEngine()
{
 ServiceProviderEngine engine;

#if NETFRAMEWORK || NETSTANDARD2_0
 engine = CreateDynamicEngine();
#else
 // Use dynamic engine if dynamic code compilation is supported and not disabled
 if (RuntimeFeature.IsDynamicCodeCompiled && !DisableDynamicEngine)
 {
 engine = CreateDynamicEngine();
 }
 else
 {
 // Fallback to Runtime engine (e.g., for AOT scenarios)
 engine = RuntimeServiceProviderEngine.Instance;
 }
#endif
 return engine;

 [UnconditionalSuppressMessage("AotAnalysis", "IL3050:RequiresDynamicCode",
 Justification = "CreateDynamicEngine won't be called when using NativeAOT.")]
 ServiceProviderEngine CreateDynamicEngine() => new DynamicServiceProviderEngine(this);
}

Due to conflicts between .NET AOT (Ahead-of-Time compilation) and dynamic code generation techniques (like System.Reflection.Emit), the Runtime engine must be used in AOT scenarios. However, the Dynamic engine remains the default in most other cases.

The Dynamic engine utilizes Emit technology (a dynamic compilation technique). In contrast, AOT requires all code to be compiled before deployment, preventing new code generation at runtime. The Runtime engine primarily uses reflection, aiming to provide a viable solution in AOT environments without sacrificing too much performance.

Let’s examine how the Dynamic engine resolves services:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


// Inside DynamicServiceProviderEngine
public override Func<ServiceProviderEngineScope, object?> RealizeService(ServiceCallSite callSite)
{
 // Track the number of times the delegate is invoked
 int callCount = 0;
 return scope =>
 {
 // First time: Resolve the service using the simpler runtime resolver.
 // This ensures the service can be resolved quickly without waiting for compilation.
 var result = CallSiteRuntimeResolver.Instance.Resolve(callSite, scope);

 // Second time: Initiate background compilation optimization.
 if (Interlocked.Increment(ref callCount) == 2)
 {
 // Queue work to the thread pool without capturing the execution context.
 _ = ThreadPool.UnsafeQueueUserWorkItem(_ =>
 {
 try
 {
 // Replace the current service accessor with one using the 
 // compiled/optimized delegate (using Emit/Expression trees).
 _serviceProvider.ReplaceServiceAccessor(callSite, base.RealizeService(callSite));
 }
 catch (Exception ex)
 {
 DependencyInjectionEventSource.Log.ServiceRealizationFailed(ex, _serviceProvider.GetHashCode());
 Debug.Fail($"We should never get exceptions from the background compilation.{Environment.NewLine}{ex}");
 }
 },
 null);
 }
 return result;
 };
}

The key idea here is “resolve-then-optimize”. The first resolution uses a simple runtime resolver for quick service instance return. When the service is requested again, a background compilation process starts, generating a more efficient resolution delegate. Once compilation completes, this optimized delegate replaces the original, speeding up subsequent resolutions. This approach gradually optimizes performance without impacting application startup time.

2.2 ServiceProviderEngineScope

Enter ServiceProviderEngineScope! This class acts as the representative or instance of a service scope. Its definition shows it exposes the capabilities of a service provider and scope management:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


internal sealed class ServiceProviderEngineScope :
 IServiceScope, // Can manage its own lifetime
 IServiceProvider, // Can resolve services
 IKeyedServiceProvider, // Can resolve keyed services
 IAsyncDisposable, // Can be disposed asynchronously
 IServiceScopeFactory // Can create nested scopes
{
 // List of services within this scope that implement IDisposable or IAsyncDisposable
 private List<object>? _disposables;

 // Cache for resolved services within this scope (primarily for Scoped lifetime services)
 // Singleton services are typically cached directly on the CallSite's root cache.
 internal Dictionary<ServiceCacheKey, object?> ResolvedServices { get; }

 // Confirms its role as the service provider for this scope
 public IServiceProvider ServiceProvider => this;

 // Allows creating nested scopes, which are independent of this one
 // Note: Creates scopes from the RootProvider
 public IServiceScope CreateScope() => RootProvider.CreateScope();

 // Other members: IsRootScope, RootProvider, Sync object, _disposed flag...
}

Observing its GetService logic reveals its straightforward nature: it uses the root ServiceProvider (RootProvider) to resolve services, passing this (the current scope) as the engineScope. This subtly hints that the engineScope exists primarily to manage the Scoped lifetime. The ResolvedServices dictionary holds the instances of Scoped services resolved within this specific scope, ensuring they are unique within this scope instance.

1
2
3
4
5
6
7
8
9


public object? GetService(Type serviceType)
{
 if (_disposed)
 {
 ThrowHelper.ThrowObjectDisposedException();
 }
 // Delegates resolution to the RootProvider, passing itself as the scope context.
 return RootProvider.GetService(ServiceIdentifier.FromServiceType(serviceType), this);
}

Another crucial method is CaptureDisposable. Services implementing disposable interfaces are added to the _disposables list.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


internal object? CaptureDisposable(object? service)
{
 // If the service is the scope itself or doesn't implement IDisposable/IAsyncDisposable, ignore.
 if (ReferenceEquals(this, service) || !(service is IDisposable || service is IAsyncDisposable))
 {
 return service;
 }

 bool disposed = false;
 lock (Sync) // Synchronization lock for thread safety
 {
 if (_disposed) // If the scope is already disposed, mark for immediate disposal.
 {
 disposed = true;
 }
 else
 {
 // Initialize the list if needed and add the service.
 _disposables ??= new List<object>();
 _disposables.Add(service);
 }
 }

 // Don't run potentially long-running customer disposal code under the lock.
 if (disposed) // If the scope was already disposed when trying to capture.
 {
 // Dispose the service immediately.
 if (service is IDisposable disposable)
 {
 disposable.Dispose();
 }
 else
 {
 // Handle IAsyncDisposable synchronously if needed (rare case).
 object? localService = service;
 Task.Run(() => ((IAsyncDisposable)localService).DisposeAsync().AsTask()).GetAwaiter().GetResult();
 }
 // Throw exception because the scope is already disposed.
 ThrowHelper.ThrowObjectDisposedException();
 }

 return service; // Return the original service instance.
}

When an ServiceProviderEngineScope is disposed (via DisposeAsync), all the captured disposable services within its scope (i.e., those in _disposables) are also disposed, typically in reverse order of resolution.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


public async ValueTask DisposeAsync()
{
 List<object>? toDispose = BeginDispose(); // Retrieves _disposables and marks the scope as disposed
 if (toDispose != null)
 {
 // Dispose services in reverse order...
 for (int i = toDispose.Count - 1; i >= 0; i--)
 {
 object disposable = toDispose[i];
 if (disposable is IAsyncDisposable asyncDisposable)
 {
 await asyncDisposable.DisposeAsync().ConfigureAwait(false);
 }
 else
 {
 ((IDisposable)disposable).Dispose();
 }
 }
 }
}

private List<object>? BeginDispose()
{
 lock (Sync)
 {
 if (_disposed) return null;
 _disposed = true;
 // If this is the root scope and the root provider hasn't been disposed yet,
 // trigger the root provider's disposal (which handles singletons).
 if (IsRootScope && !RootProvider.IsDisposed()) RootProvider.Dispose();
 }
 return _disposables;
}

A common question arises: Since singleton instances aren’t stored in the scope’s ResolvedServices but cached on the CallSite, how are they disposed? Will they leak?

No need to worry. While singleton instances are cached on the call site, disposable singletons are still captured by the scope that first resolves them (which is typically the root scope). As seen in BeginDispose, when the root scope is disposed, it explicitly triggers the disposal of the RootProvider, which in turn handles the disposal of any captured singleton instances.

3 ServiceCallSite

The primary responsibility of a ServiceCallSite is to encapsulate the logic required to resolve a service. It can represent various resolution strategies like a constructor call, property injection (less common in MS.DI), a factory method invocation, etc. The DI system uses this abstraction to represent how a service instance should be obtained.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


internal abstract class ServiceCallSite
{
 protected ServiceCallSite(ResultCache cache)
 {
 Cache = cache;
 }

 public abstract Type ServiceType { get; } // The type of service being requested
 public abstract Type? ImplementationType { get; } // The concrete implementation type (if applicable)
 public abstract CallSiteKind Kind { get; } // The kind of call site (Constructor, Factory, etc.)
 public ResultCache Cache { get; } // Caching information for the resolved instance
 public object? Value { get; set; } // Cached value (used primarily for singletons)
 public object? Key { get; set; } // Service key (for keyed services)

 // Determines if the resolved instance should be captured for disposal
 public bool CaptureDisposable => ImplementationType == null ||
 typeof(IDisposable).IsAssignableFrom(ImplementationType) ||
 typeof(IAsyncDisposable).IsAssignableFrom(ImplementationType);
}

3.1 ResultCache

The ResultCache within a ServiceCallSite defines how the resolved result should be cached.

1
2
3
4
5


public struct ResultCache
{
 public CallSiteResultCacheLocation Location { get; set; } // Where to cache (Root, Scope, etc.)
 public ServiceCacheKey Key { get; set; } // Cache key (relevant for Scoped services)
}

CallSiteResultCacheLocation is an enum defining cache behaviors:

Root: The service instance should be cached in the root IServiceProvider. This typically means the service is a Singleton, created once per application lifetime and shared across all requests/scopes.
Scope: The service instance should be cached within the current scope (ServiceProviderEngineScope). For Scoped services, an instance is created once per scope and shared within that scope.
Dispose: Despite the name, in the context of ResultCache, this indicates the service is Transient (a new instance is created every time it’s requested). The name relates to the fact that these instances still need to be tracked for disposal if they implement IDisposable/IAsyncDisposable.
None: No caching is performed for the service instance (e.g., for constant values).

The ServiceCacheKey struct combines the ServiceIdentifier and a Slot index, used internally to differentiate multiple implementations resolved within a scope.

1
2
3
4
5


internal readonly struct ServiceCacheKey : IEquatable<ServiceCacheKey>
{
 public ServiceIdentifier ServiceIdentifier { get; }
 public int Slot { get; } // Slot index (e.g., last implementation might be slot 0)
}

3.2 CallSiteFactory.GetCallSite

Let’s look at how call sites are created. We saw this method called earlier in CreateServiceAccessor:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


// Inside CallSiteFactory
private ServiceCallSite? CreateCallSite(ServiceIdentifier serviceIdentifier, CallSiteChain callSiteChain)
{
 // Prevent stack overflow during deep recursive resolutions
 if (!_stackGuard.TryEnterOnCurrentStack())
 {
 return _stackGuard.RunOnEmptyStack(CreateCallSite, serviceIdentifier, callSiteChain);
 }

 // Use a lock specific to the service identifier to ensure thread-safe call site creation.
 // This guarantees that even with concurrent requests, the call site for a given service 
 // is created only once. Example:
 // Thread 1: C -> D -> A
 // Thread 2: E -> D -> A (Both threads need the call site for D and A)
 var callsiteLock = _callSiteLocks.GetOrAdd(serviceIdentifier, static _ => new object());
 lock (callsiteLock)
 {
 // Check for circular dependencies in the resolution chain.
 callSiteChain.CheckCircularDependency(serviceIdentifier);

 // Attempt to create the call site using different strategies:
 // 1. Exact match for the service descriptor.
 // 2. Match an open generic definition.
 // 3. Handle IEnumerable<T> requests.
 ServiceCallSite? callSite = TryCreateExact(serviceIdentifier, callSiteChain) ??
 TryCreateOpenGeneric(serviceIdentifier, callSiteChain) ??
 TryCreateEnumerable(serviceIdentifier, callSiteChain);
 return callSite;
 }
}

Here’s a simplified overview of the call site creation process:

Check Cache: Look for an existing call site in the factory’s cache. If found, return it immediately.
Get ServiceDescriptor: Retrieve the corresponding ServiceDescriptor based on the ServiceIdentifier (for keyed services without a key, it might default to the last registered one).
Create ServiceCallSite (Order Matters):
- TryCreateExact:
  - Calculate ResultCache based on the descriptor’s lifetime.
  - If an instance is already provided (ImplementationInstance), return a ConstantCallSite.
  - If a factory delegate is provided (ImplementationFactory), return a FactoryCallSite.
  - If an implementation type is provided (ImplementationType), return a ConstructorCallSite.
- TryCreateOpenGeneric:
  - Find a ServiceDescriptor for the open generic definition.
  - Calculate ResultCache.
  - Construct the closed generic implementation type using the specific generic arguments from the ServiceIdentifier.
  - Perform AOT compatibility checks (e.g., ensure code for value type generics exists).
  - If successful, return a ConstructorCallSite.
- TryCreateEnumerable:
  - Verify the requested type is IEnumerable<T>.
  - Perform AOT compatibility checks (e.g., ensure code for T[] exists).
  - Find all matching ServiceDescriptors for T.
  - Create call sites for each match (usually involves looping through TryCreateExact and TryCreateOpenGeneric for each descriptor).
  - Return an IEnumerableCallSite that aggregates the results.

4 CallSiteVisitor

With the above understanding, we can now explore the internals of service resolution. Resolution essentially involves the engine “visiting” the call site structure using a CallSiteVisitor. Resolving a service means visiting its corresponding call site.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


// Base class for resolvers (like CallSiteRuntimeResolver)
protected virtual TResult VisitCallSite(ServiceCallSite callSite, TArgument argument)
{
 // Stack guard checks...
 if (!_stackGuard.TryEnterOnCurrentStack())
 {
 return _stackGuard.RunOnEmptyStack(VisitCallSite, callSite, argument);
 }

 // Branch resolution based on the call site's cache location (lifetime)
 switch (callSite.Cache.Location)
 {
 case CallSiteResultCacheLocation.Root: // Singleton
 return VisitRootCache(callSite, argument);
 case CallSiteResultCacheLocation.Scope: // Scoped
 return VisitScopeCache(callSite, argument);
 case CallSiteResultCacheLocation.Dispose: // Transient
 return VisitDisposeCache(callSite, argument);
 case CallSiteResultCacheLocation.None: // Constant / No Cache
 return VisitNoCache(callSite, argument);
 default:
 throw new ArgumentOutOfRangeException(nameof(callSite.Cache.Location));
 }
}

For clarity, we’ll focus on the Runtime resolver’s logic, which uses reflection and is easier to follow than the Emit/Expression-based logic of the Dynamic engine.

4.1 VisitRootCache (Singleton)

Let’s see how singleton instances are accessed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// Inside CallSiteRuntimeResolver
protected override object? VisitRootCache(ServiceCallSite callSite, RuntimeResolverContext context)
{
 // Check if the value is already cached directly on the call site.
 if (callSite.Value is object value)
 {
 // Value already calculated, return it directly.
 return value;
 }

 var lockType = RuntimeResolverLock.Root;
 // Singletons are associated with the root scope.
 ServiceProviderEngineScope serviceProviderEngine = context.Scope.RootProvider.Root;

 // Use a lock on the call site object itself for thread safety.
 lock (callSite)
 {
 // Double-checked locking: Re-check if another thread cached the value while waiting for the lock.
 if (callSite.Value is object callSiteValue)
 {
 return callSiteValue;
 }

 // If still null, proceed to resolve the value using the main visitor logic.
 // Pass the root scope as the context.
 object? resolved = VisitCallSiteMain(callSite, new RuntimeResolverContext
 {
 Scope = serviceProviderEngine,
 AcquiredLocks = context.AcquiredLocks | lockType // Track acquired locks
 });

 // Capture the resolved service if it's disposable (tracked by the root scope).
 serviceProviderEngine.CaptureDisposable(resolved);

 // Cache the resolved instance directly on the call site's Value property.
 callSite.Value = resolved;
 return resolved;
 }
}

The core resolution logic happens in VisitCallSiteMain. The CallSiteKind was determined during call site creation, so we just need to handle each kind:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// Inside CallSiteRuntimeResolver (base visitor logic)
protected virtual TResult VisitCallSiteMain(ServiceCallSite callSite, TArgument argument)
{
 switch (callSite.Kind)
 {
 case CallSiteKind.Factory:
 return VisitFactory((FactoryCallSite)callSite, argument);
 case CallSiteKind.IEnumerable:
 return VisitIEnumerable((IEnumerableCallSite)callSite, argument);
 case CallSiteKind.Constructor:
 return VisitConstructor((ConstructorCallSite)callSite, argument);
 case CallSiteKind.Constant:
 return VisitConstant((ConstantCallSite)callSite, argument);
 case CallSiteKind.ServiceProvider:
 return VisitServiceProvider((ServiceProviderCallSite)callSite, argument);
 // Other kinds might exist (e.g., KeyedService)
 default:
 throw new NotSupportedException($"Call site type {callSite.GetType()} is not supported.");
 }
}

Let’s examine the most common case: ConstructorCallSite. It simply involves creating an instance via its constructor. If the constructor has dependencies, those are resolved recursively first. Easy! (Other kinds like ConstantCallSite or FactoryCallSite are generally simpler).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


// Inside CallSiteRuntimeResolver
protected override object VisitConstructor(ConstructorCallSite constructorCallSite, RuntimeResolverContext context)
{
 object?[] parameterValues;
 if (constructorCallSite.ParameterCallSites.Length == 0)
 {
 parameterValues = Array.Empty<object>();
 }
 else
 {
 parameterValues = new object?[constructorCallSite.ParameterCallSites.Length];
 // Recursively resolve each constructor parameter dependency.
 for (int index = 0; index < parameterValues.Length; index++)
 {
 parameterValues[index] = VisitCallSite(constructorCallSite.ParameterCallSites[index], context);
 }
 }

 try
 {
 // Invoke the constructor using reflection.
 return constructorCallSite.ConstructorInfo.Invoke(BindingFlags.DoNotWrapExceptions, binder: null, parameters: parameterValues, culture: null);
 }
 catch (Exception ex) when (ex.InnerException != null)
 {
 // Unwrap exceptions for better debugging experience
 ExceptionDispatchInfo.Capture(ex.InnerException).Throw();
 // The above line will always throw, this is just to satisfy the compiler.
 throw;
 }
}

4.2 VisitScopeCache (Scoped)

Visiting the singleton cache involved a simple double-checked lock on the call site. Let’s see if the scoped cache differs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// Inside CallSiteRuntimeResolver
protected override object? VisitScopeCache(ServiceCallSite callSite, RuntimeResolverContext context)
{
 // Check for the rare scenario where a scoped service resolution is happening 
 // directly within the root scope (e.g., IServiceProvider injected into singleton).
 // In this case, treat it like a singleton for locking purposes.
 return context.Scope.IsRootScope ?
 VisitRootCache(callSite, context) :
 VisitCache(callSite, context, context.Scope, RuntimeResolverLock.Scope); // Standard scoped resolution
}

Indeed, it’s different! It first checks if we are unexpectedly in the root scope (context.Scope.IsRootScope). This can happen if, for instance, IServiceProvider is injected directly into a singleton service, and that provider is later used to resolve a scoped service. In such rare cases, it falls back to VisitRootCache’s locking behavior.

Most of the time, it calls VisitCache. The synchronization model in VisitCache is quite clever, using a combination of scope-level locks and tracking flags (AcquiredLocks) to prevent deadlocks during recursive resolutions involving mixed lifetimes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


// Inside CallSiteRuntimeResolver
private object? VisitCache(ServiceCallSite callSite, RuntimeResolverContext context,
 ServiceProviderEngineScope serviceProviderEngineScope, RuntimeResolverLock lockType)
{
 bool lockTaken = false;
 // Use the scope's internal sync object for locking.
 object sync = serviceProviderEngineScope.Sync;
 // Get the cache dictionary specific to this scope instance.
 Dictionary<ServiceCacheKey, object?> resolvedServices = serviceProviderEngineScope.ResolvedServices;

 // Only acquire the scope lock if it hasn't already been acquired further up the resolution chain for this scope.
 if ((context.AcquiredLocks & lockType) == 0)
 {
 Monitor.Enter(sync, ref lockTaken);
 }

 try
 {
 // Check the scope's cache first (inside the lock).
 if (resolvedServices.TryGetValue(callSite.Cache.Key, out object? resolved))
 {
 return resolved;
 }

 // If not found in the cache, resolve using the main visitor logic.
 // Pass the current scope and update the acquired locks flag.
 resolved = VisitCallSiteMain(callSite, new RuntimeResolverContext
 {
 Scope = serviceProviderEngineScope,
 AcquiredLocks = context.AcquiredLocks | lockType
 });

 // Capture for disposal if necessary (tracked by this specific scope).
 serviceProviderEngineScope.CaptureDisposable(resolved);

 // Add the resolved service to this scope's cache.
 resolvedServices.Add(callSite.Cache.Key, resolved);
 return resolved;
 }
 finally
 {
 // Release the lock only if it was acquired in this specific call frame.
 if (lockTaken)
 {
 Monitor.Exit(sync);
 }
 }
}

The elegance here lies in the scope isolation. For non-root scopes (Scoped lifetime), locking is confined within that specific scope instance (serviceProviderEngineScope.Sync and resolvedServices). There’s no need for global locks across different scopes as required for Singletons (VisitRootCache locking on callSite itself).

4.3 VisitDisposeCache (Transient)

Finally, let’s look at the Transient case:

1
2
3
4
5
6
7
8


// Inside CallSiteRuntimeResolver
protected override object? VisitDisposeCache(ServiceCallSite transientCallSite, RuntimeResolverContext context)
{
 // Resolve the service using the main visitor logic...
 // ...and immediately capture it for disposal within the current scope if needed.
 // No caching occurs.
 return context.Scope.CaptureDisposable(VisitCallSiteMain(transientCallSite, context));
}

It’s exceptionally simple. It follows the scoped resolution path (VisitCallSiteMain) but performs no caching. Every request for a transient service results in a new call to VisitCallSiteMain, and the resulting instance is captured by the current scope for potential disposal.

Common Image Data Type Conversions in .NET Development

Thu, 20 Feb 2025 00:00:00 +0000

When developing with .NET, especially WPF applications, handling various image data types is a frequent requirement. The “type” mentioned here refers to how image data is represented in memory rather than the image file formats (e.g., JPG, PNG, BMP). Converting between these types can sometimes be confusing. This document summarizes common conversion methods to clarify these processes.

Common Image Data Types

byte[]: Byte arrays, either:
- Raw data read from image files (including headers).
- Pixel data such as RGB values.
Stream: Data streams like MemoryStream or FileStream, easily convertible to and from byte arrays.
Bitmap: Used in WinForms (based on GDI+), located in System.Drawing namespace.
BitmapImage: Used in WPF (System.Windows.Media.Imaging), commonly set as the Source for Image controls.
BitmapSource: Base class for BitmapImage, used in WPF (System.Windows.Media).
Other image types from third-party libraries.

Conversion Examples

Convert Image Path to BitmapImage

If you have an image path (local or URL) and wish to display it in an Image control:

1
2


var image = new Image();
image.Source = new BitmapImage(new Uri(@"path\to\image.jpg", UriKind.RelativeOrAbsolute));

This method automatically handles common formats (JPG, PNG, BMP, GIF, TIFF, WebP, HEIC, AVIF). Uncommon formats may require third-party libraries.

Convert Bitmap to BitmapImage

Converting from WinForms (Bitmap) to WPF (BitmapImage):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


using System.Drawing;
using System.Windows.Media.Imaging;

static BitmapImage ConvertBitmapToBitmapImage(Bitmap bitmap)
{
 using var stream = new MemoryStream();
 bitmap.Save(stream, ImageFormat.Png);
 stream.Position = 0;

 var bitmapImage = new BitmapImage();
 bitmapImage.BeginInit();
 bitmapImage.CacheOption = BitmapCacheOption.OnLoad;
 bitmapImage.StreamSource = stream;
 bitmapImage.EndInit();
 bitmapImage.Freeze(); // Optional: enhances performance and thread safety
 return bitmapImage;
}

Convert Byte Array to ImageSource

From file data (e.g., JPG, PNG, BMP):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


using System.IO;
using System.Windows.Media.Imaging;

static ImageSource ConvertByteArrayToImageSource(byte[] bytes)
{
 using var stream = new MemoryStream(bytes);
 var bitmapImage = new BitmapImage();
 bitmapImage.BeginInit();
 bitmapImage.CacheOption = BitmapCacheOption.OnLoad;
 bitmapImage.StreamSource = stream;
 bitmapImage.EndInit();
 bitmapImage.Freeze();
 return bitmapImage;
}

Alternatively, using BitmapDecoder:

1
2
3
4
5
6
7
8
9


using System.Windows.Media.Imaging;

static ImageSource ConvertByteArrayToImageSource(byte[] bytes)
{
 using var stream = new MemoryStream(bytes);
 return BitmapDecoder
 .Create(stream, BitmapCreateOptions.PreservePixelFormat, BitmapCacheOption.OnLoad)
 .Frames[0];
}

From pixel data (e.g., RGB data):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


using System.Windows.Media;
using System.Windows.Media.Imaging;

static ImageSource BgrByteArrayToImageSource(byte[] array, int width, int height, int channel = 3, int? stride = null)
{
 var bmp = new WriteableBitmap(width, height, 96, 96, PixelFormats.Bgr24, null);
 stride ??= ((width * channel + 3) / 4) * 4;
 bmp.WritePixels(new Int32Rect(0, 0, width, height), array, stride.Value, 0);
 bmp.Freeze();
 return bmp;
}

Convert BitmapSource to BitmapImage

Typically, converting from clipboard data (BitmapSource) to BitmapImage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


using System.Windows.Media.Imaging;

static BitmapImage ConvertBitmapSourceToBitmapImage(BitmapSource bitmapSource)
{
 var bitmapImage = new BitmapImage();
 using var stream = new MemoryStream();
 BitmapEncoder encoder = new BmpBitmapEncoder(); // Clipboard images are typically BMP
 encoder.Frames.Add(BitmapFrame.Create(bitmapSource));
 encoder.Save(stream);
 stream.Position = 0;
 bitmapImage.BeginInit();
 bitmapImage.CacheOption = BitmapCacheOption.OnLoad;
 bitmapImage.StreamSource = stream;
 bitmapImage.EndInit();
 bitmapImage.Freeze();
 return bitmapImage;
}

Convert Emgu.CV.Image to BitmapImage

For uncommon formats (e.g., JP2), use the Emgu.CV library:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


var filename = @"path\to\image.jp2";
var mat = new Image<Bgr, Byte>(filename);
var bytes = mat.ToJpegData();

using var stream = new MemoryStream(bytes);
var bitmap = new BitmapImage();
bitmap.BeginInit();
bitmap.CacheOption = BitmapCacheOption.OnLoad;
bitmap.StreamSource = stream;
bitmap.EndInit();
bitmap.Freeze();

var control = new Image();
control.Source = bitmap;

Summary

Most conversions involve converting data to a common Stream format first, creating a BitmapImage, and then assigning it to an Image control. Following this pattern ensures consistent and effective image handling across various scenarios.

Implement Batch Dependency Injection in .NET 6 WebAPI

Mon, 17 Feb 2025 00:00:00 +0000

Preface

In .NET WebAPI development, when dealing with numerous business modules and classes that require dependency injection, manually registering each service becomes tedious and harms code readability. This article demonstrates an elegant batch injection solution using custom attributes.

Implementation

1. Create Custom Attribute

Create an AppServiceAttribute.cs file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class AppServiceAttribute : Attribute
{
 public ServiceLifeType ServiceLifeType { get; set; } = ServiceLifeType.Singleton;
 public Type ServiceType { get; set; }
}

public enum ServiceLifeType
{
 Transient,
 Scoped,
 Singleton
}

2. Batch Registration Extension

Create AppServiceExtensions.cs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


public static class AppServiceExtensions
{
 public static void AddAppServices(this IServiceCollection services, params string[] assemblyNames)
 {
 foreach (var name in assemblyNames)
 {
 var assembly = Assembly.Load(name);
 foreach (var type in assembly.GetTypes())
 {
 var attribute = type.GetCustomAttribute<AppServiceAttribute>();
 if (attribute != null)
 {
 RegisterService(services, type, attribute);
 }
 }
 }
 }

 private static void RegisterService(IServiceCollection services, Type implementationType, AppServiceAttribute attribute)
 {
 var serviceType = attribute.ServiceType ?? implementationType;

 switch (attribute.ServiceLifeType)
 {
 case ServiceLifeType.Singleton:
 services.AddSingleton(serviceType, implementationType);
 break;
 case ServiceLifeType.Scoped:
 services.AddScoped(serviceType, implementationType);
 break;
 case ServiceLifeType.Transient:
 services.AddTransient(serviceType, implementationType);
 break;
 default:
 services.AddTransient(serviceType, implementationType);
 break;
 }
 }
}

3. Service Implementation

ISystemService.cs:

1
2
3
4


public interface ISystemService
{
 int Add(int a, int b);
}

SystemService.cs:

1
2
3
4
5


[AppService(ServiceType = typeof(ISystemService), ServiceLifeType = ServiceLifeType.Scoped)]
public class SystemService : ISystemService
{
 public int Add(int a, int b) => a + b;
}

4. Registration in Program.cs

1
2


var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAppServices("Your.Service.Assembly");

Key Features

Flexible Lifetime Management: Easily configure service lifetime via attribute
Interface-Implementation Decoupling: Explicitly specify service contracts
Batch Processing: Automatically discover and register all decorated classes
Code Generation Friendly: Perfect match with T4 templates or Roslyn-based generators

Recommended Improvements

Add null validation for ServiceType
Support automatic interface discovery (e.g., IService -> Service)
Add duplicate registration detection
Implement assembly scanning with IAssemblyProvider

Why Not Just Use Manual Registration?
While this approach still requires attributes, it becomes extremely powerful when combined with code generators - most boilerplate code can be automatically generated during build process.

1
2
3
4
5
6



This implementation provides:
✅ Clean architecture separation
✅ Centralized dependency management
✅ Improved code maintainability
✅ Reduced human error in registration

Configuration Management in .NET Core with appsettings.json

Mon, 03 Feb 2025 00:00:00 +0000

A comprehensive guide to leveraging appsettings.json for flexible configuration management in .NET Core applications.

Quick Start

1. Create appsettings.json

1
2
3
4
5
6
7
8


{
 "AppSettings": {
 "LogLevel": "Warning",
 "ConnectionStrings": {
 "Default": "Server=localhost;Database=mydb;"
 }
 }
}

2. Basic Configuration Loading

1
2
3
4
5
6
7
8


using Microsoft.Extensions.Configuration;

var config = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
 .Build();

string logLevel = config["AppSettings:LogLevel"];
string connectionString = config["AppSettings:ConnectionStrings:Default"];

Core Features

1. Value Retrieval Methods

1
2
3
4
5
6
7
8


// Traditional string access
var logLevel = config["AppSettings:LogLevel"];

// Type-safe retrieval
int timeout = config.GetValue<int>("Network:Timeout", 30); // Default value

// Connection string shortcut
var dbConn = config.GetConnectionString("Default");

2. Multi-Environment Configuration

appsettings.Development.json

1
2
3
4
5
6


{
 "AppSettings": {
 "LogLevel": "Debug",
 "DebugMode": true
 }
}

Configuration Builder

1
2
3
4


var config = new ConfigurationBuilder()
 .AddJsonFile("appsettings.json") // Base configuration
 .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
 .Build();

Configuration Priority:

Command-line arguments
Environment variables
Environment-specific JSON
Base appsettings.json

Advanced Techniques

1. Strongly-Typed Configuration

Configuration Class

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class AppSettings
{
 public string LogLevel { get; set; }
 public DatabaseConfig Database { get; set; }

 public class DatabaseConfig
 {
 public string Host { get; set; }
 public int Port { get; set; }
 }
}

Binding Configuration

1
2


var appConfig = config.GetSection("AppSettings").Get<AppSettings>();
Console.WriteLine($"DB Port: {appConfig.Database.Port}");

2. Dynamic Reloading

1
2
3
4
5
6


var reloadToken = config.GetReloadToken();
reloadToken.RegisterChangeCallback(_ =>
{
 Console.WriteLine("Configuration changed!");
 // Refresh configuration-sensitive components
}, null);

Runtime Configuration Sources

1. Environment Variables

1
2
3
4
5


# Linux/macOS
export AppSettings__LogLevel=Verbose

# Windows
set AppSettings__LogLevel=Verbose

2. Command-Line Arguments

1
2
3


var config = new ConfigurationBuilder()
 .AddCommandLine(args)
 .Build();

Execution Example

1

dotnet run --AppSettings:LogLevel=Critical

Best Practices

Security Considerations

1
2


// Never store secrets in appsettings.json
var secret = config["Azure:KeyVaultSecret"];

Validation Pattern

1
2


services.Configure<AppSettings>(config.GetSection("AppSettings"))
 .ValidateDataAnnotations();

Custom Configuration Providers

1
2
3
4
5
6
7
8


public class DatabaseConfigurationProvider : ConfigurationProvider
{
 public override void Load()
 {
 // Load config from database
 Data = GetConfigFromDB();
 }
}

Key Limitations

No Native Write Support: Configuration system is read-only
Type Conversion Requirements: Manual handling for complex types
Environment-Specific Complexity: Requires careful management of multiple files

Recommended NuGet Packages

Microsoft.Extensions.Configuration.Json
Microsoft.Extensions.Configuration.EnvironmentVariables
Microsoft.Extensions.Configuration.CommandLine
Microsoft.Extensions.Options.ConfigurationExtensions

Official Configuration Documentation Configuration Best Practices

Next Steps: Explore integration with HostBuilder and dependency injection for enterprise-level configuration management.

Task in C#

Fri, 31 Jan 2025 00:00:00 +0000

The Task class in C# is a powerful tool for multithreaded programming, enabling asynchronous operations, parallel processing, and task cancellation. This guide demonstrates common patterns and best practices for leveraging Task effectively.

1. Executing Asynchronous Operations

Use Task.Run to offload work to the thread pool and await to handle completion.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


static async Task<int> LongRunningOperationAsync()
{
 await Task.Delay(1000); // Simulates async work (e.g., I/O)
 return 1;
}

static async Task MyMethodAsync()
{
 int result = await Task.Run(() => LongRunningOperationAsync());
 Console.WriteLine(result); // Output: 1
}

Key Points: • Task.Run queues work to the thread pool. • await asynchronously waits for completion without blocking the thread.

2. Parallel Task Processing

Use Task.WhenAll to await multiple tasks concurrently.

1
2
3
4
5
6


Task<int> task1 = Task.Run(() => LongRunningOperationAsync());
Task<int> task2 = Task.Run(() => LongRunningOperationAsync());
Task<int> task3 = Task.Run(() => LongRunningOperationAsync());

int[] results = await Task.WhenAll(task1, task2, task3);
Console.WriteLine($"Sum: {results.Sum()}"); // Output: Sum: 3

Advantages: • Runs tasks in parallel for better CPU utilization. • Aggregates results when all tasks complete.

3. Canceling Async Operations

Use CancellationTokenSource to gracefully terminate tasks.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


static async Task<int> LongRunningOperationAsync(CancellationToken cancellationToken)
{
 await Task.Delay(1000, cancellationToken); // Honors cancellation
 return 1;
}

static async Task MyMethodAsync(CancellationToken cancellationToken)
{
 using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
 cts.CancelAfter(500); // Auto-cancel after 500ms

 try
 {
 int result = await Task.Run(() => LongRunningOperationAsync(cts.Token));
 Console.WriteLine(result);
 }
 catch (TaskCanceledException)
 {
 Console.WriteLine("Operation canceled.");
 }
}

Mechanism: • CancellationToken propagates cancellation requests. • CancelAfter() triggers cancellation after a timeout.

Best Practices and Pitfalls

✅ Do:

• Use ConfigureAwait(false) in library code to avoid deadlocks. • Prefer async/await over .Result or .Wait() to prevent blocking. • Handle exceptions with try/catch around awaited tasks.

❌ Avoid:

• Mixing synchronous and async code without proper context management. • Ignoring OperationCanceledException when using cancellation tokens. • Overusing Task.Run for CPU-bound work; consider Parallel.For instead.

Summary

The Task API enables: • Asynchronous Programming: Non-blocking execution for I/O-bound work. • Parallelism: Efficient utilization of multi-core CPUs. • Cancellation: Graceful termination of long-running operations.

By following these patterns, you’ll write responsive, scalable, and maintainable C# applications. For advanced scenarios, explore ValueTask, TaskCompletionSource, and the TPL Dataflow library.

graph TD
A[Start Task] --> B{Is Async?}
B -->|Yes| C[Use async/await]
B -->|No| D[Use Task.Run]
C --> E[Handle Completion/Errors]
D --> E
E --> F[Process Results]

BSON vs MessagePack: Differences and How to Choose

Fri, 03 Jan 2025 00:00:00 +0000

Basic Information

BSON (Binary JSON) is a binary-encoded JSON format developed by MongoDB, primarily used for data storage and transmission in MongoDB databases. It extends the JSON format by adding support for additional data types such as dates, timestamps, and binary data.

MessagePack is an efficient binary serialization format designed to achieve the smallest possible size and fastest possible processing speed. It supports multiple programming languages and is commonly used for network communication and data storage.

Similarities

BSON and MessagePack share several similarities. First, both encode data in binary form, which can reduce data volume and improve transmission efficiency compared to text-based JSON. While JSON has the advantage of readability, its text nature can lead to slower parsing and greater storage space when handling large amounts of data. Binary formats avoid these issues by storing data in a way that computers can process more easily, thereby improving efficiency.

Second, they both support various data types, including basic types (such as integers, floating-point numbers, strings, boolean values) and complex types (such as arrays, binary data, dates). This allows them to flexibly handle various data structures and meet the needs of different application scenarios.

Furthermore, both provide implementations in multiple programming languages, enabling data exchange between different systems and platforms. Whether using Python, Java, C#, Go, or other programming languages, we can find corresponding libraries to use them. Finally, they both offer efficient serialization and deserialization mechanisms, making it convenient for developers to perform data-related operations.

So, being both binary data formats, do they both have similarly high space efficiency and performance?

Differences

However, there are some key design differences between BSON and MessagePack. These differences lead to variations in their space efficiency and specialized functionalities.

BSON’s design goal is primarily for MongoDB’s data storage and transmission, rather than providing a superior alternative to JSON. This difference in design philosophy directly affects their performance in terms of space efficiency and performance. Since BSON includes some additional metadata (such as field lengths), its space efficiency is relatively lower; MessagePack uses compact representation methods to encode data, such as using fewer bytes to represent smaller integers, resulting in very high space efficiency. MessagePack’s design philosophy is “as small as possible,” making it an ideal choice in scenarios with strict data size requirements.

In terms of performance, BSON’s serialization and deserialization speed is relatively slower, while MessagePack’s is very fast. This is because MessagePack’s encoding method is simpler and more efficient, reducing the computational load required for processing data. However, although BSON is relatively less efficient, it has many optimizations in MongoDB. For example, in terms of indexing, BSON’s structure allows MongoDB to efficiently traverse and query data, which compensates for some of its shortcomings in general performance. Specifically, MongoDB can utilize information such as field lengths stored in BSON to quickly locate needed data, without needing to scan character by character as when parsing JSON.

Code Comparison

Here, we use a simple example in C# to compare BSON and MessagePack. We use the Newtonsoft.Json.Bson and MessagePack libraries for implementation.

First, we design a class with some properties and populate it with data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


public class MyModel
{
 public int Id { get; set; }
 public string Name { get; set; }
 public DateTime CreatedAt { get; set; }
 public bool IsActive { get; set; }
 public decimal Price { get; set; }
 public double Rating { get; set; }
 public Guid UniqueId { get; set; }
 public byte[] Data { get; set; }
 public List<string> Tags { get; set; }
 public Dictionary<string, int> Counts { get; set; }
 public long BigNumber { get; set; }
 public short SmallNumber { get; set; }
 public char Initial { get; set; }
 public TimeSpan Duration { get; set; }
 public Uri Website { get; set; }
 public Version Version { get; set; }
 public object DynamicValue { get; set; }
 public Status Status { get; set; }
}

public enum Status
{
 Pending,
 InProgress,
 Completed
}

var model = new MyModel
{
 Id = 123,
 Name = "My Model",
 CreatedAt = DateTime.UtcNow,
 IsActive = true,
 Price = 99.99m,
 Rating = 4.5,
 UniqueId = Guid.NewGuid(),
 Data = new byte[] { 1, 2, 3 },
 Tags = new List<string> { "tag1", "tag2" },
 Counts = new Dictionary<string, int> { { "a", 1 }, { "b", 2 } },
 BigNumber = 123456789012345,
 SmallNumber = 123,
 Initial = 'A',
 Duration = TimeSpan.FromMinutes(15),
 Website = new Uri("https://www.example.com"),
 Version = new Version(1, 0, 0),
 DynamicValue = new { Value = "dynamic" },
 Status = Status.InProgress
};

Then, we use two methods to serialize this object. First with BSON:

1
2
3
4
5
6
7
8
9


using Newtonsoft.Json;
using Newtonsoft.Json.Bson;

using (var fs = File.OpenWrite(@"bson.dat"))
using (var writer = new BsonWriter(fs))
{
 var serializer = new JsonSerializer();
 serializer.Serialize(writer, model);
}

Then with MessagePack. To serialize the above model, we need to add some attributes to the model class, including:

Add [MessagePackObject] to the class
Add [Key(0)], [Key(1)], [Key(2)], etc. to each property in sequence

Otherwise, the serialization code will throw an error. Here’s the modified model class (partial) and serialization code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


[MessagePackObject]
public class MyModel
{
 [Key(0)]
 public int Id { get; set; }
 [Key(1)]
 public string Name { get; set; }
 [Key(2)]
 public DateTime CreatedAt { get; set; }
 [Key(3)]
 public bool IsActive { get; set; }
 // ...
}

using (var fs = File.OpenWrite(@"msgpack.dat"))
{
 var data = MessagePackSerializer.Serialize(model);
 fs.Write(data);
}

Then, we observe the file sizes:

BSON: 381 bytes
MessagePack: 166 bytes

It’s clear that BSON has no advantage in terms of space efficiency.

Note

In fact, even when compared to JSON, BSON may not necessarily have significant advantages in space efficiency. BSON’s advantages mainly come from its handling of dates, binary data, numbers, etc., while JSON can only store everything as strings. For a large number like 100,000,000, JSON needs 9 characters, while BSON only needs 4 bytes; but for a small decimal like 1.0, JSON needs 3 characters, while BSON needs 8 bytes. Moreover, BSON also includes additional metadata, such as field names and field lengths, which also means that BSON’s space efficiency does not show much improvement compared to JSON.

Summary

In conclusion, both BSON and MessagePack are excellent and modern binary serialization formats. BSON’s advantages lie in its compatibility with JSON and support for rich data types, making it excel in database applications like MongoDB; MessagePack’s advantages lie in its high performance and high space efficiency, making it more advantageous in scenarios such as network communication and big data processing that require fast transmission and processing of large amounts of data. In practical applications, we should choose the appropriate format based on specific requirements.

String-Manipulation: Practical Tips & Common Mistakes for Beginners in C#

Fri, 27 Dec 2024 00:00:00 +0000

C# String Manipulation: Practical Tips & Common Mistakes for Beginners

Date: Jul 27, 2024
Reading Time: ~7 minutes
Video Tutorial Available on Bilibili

Most developers interact with strings every single day. But do you really understand how strings work, and can you pick the most efficient way to solve real-world problems? In this article, we’ll go over some useful tips and common mistakes when working with C# strings.

C# offers a variety of classes for string operations:

string
StringBuilder
Encoding
Regex

They are very powerful, but this can also lead to misunderstandings about their usage. You might be unaware of certain method overloads or performance issues, which can result in inefficient code (often without you even noticing). This post highlights practical tips and pitfalls in C# string manipulation to help you write more efficient and maintainable code.

When You Can Use a `char`, Don’t Use a `string`

In C#, there’s a typical distinction in syntax between a char (single quotes) and a string (double quotes). Beyond syntax, they are fundamentally different. A string is a reference type, allocated on the heap, whereas a char is a value type stored on the stack. Because of this, a char is generally more performant than a string.

It’s important not to think of a char simply as a string of length 1. In many C# string methods, there are overloads that accept a char instead of a string. For example:

1
2
3
4
5
6
7


string str = "Hello, World!";

str.StartsWith('H');
str.EndsWith('!');
str.Contains('o');
str.IndexOf('o');
str.Split(',');

These methods accept char parameters, which can help improve performance. Think about how Contains might be implemented under the hood: if you pass a string, even if it’s length 1, the method still treats it as a substring. That involves additional checks and possible overhead for matching a multi-character sequence. Passing a single char avoids that overhead.

Use Overloaded Methods to Reduce Unnecessary Calls

Many string operations have multiple overloads. Using them appropriately can help you reduce extra calls and resource waste. Consider the following examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


string str = " Hello, World,, Good, Morning ";

// We want to split on commas and remove empty entries:
var slices = str.Split(',', StringSplitOptions.RemoveEmptyEntries);

// If you're not aware of this overload, you might do:
var slicesLegacy = str.Split(',')
 .Where(s => !string.IsNullOrEmpty(s))
 .ToArray();

// Similarly, if we want to trim each split segment:
var slicesTrimmed = str.Split(',', StringSplitOptions.TrimEntries);

// Without this overload, you might write:
var slicesTrimmedLegacy = str.Split(',')
 .Select(s => s.Trim())
 .ToArray();

Each extra call (Where, Select, etc.) can introduce additional overhead.

Another common example: comparing two strings in a case-insensitive manner. A naive approach might be:

1
2
3
4


if (s1.ToLower() == s2.ToLower())
{
 // ...
}

A better way is to use the Equals overload:

1
2
3
4


if (s1.Equals(s2, StringComparison.OrdinalIgnoreCase))
{
 // ...
}

This avoids creating new lowercase strings and does a more efficient comparison.

String Constructors

Most developers create strings by assigning a literal or calling various instance methods, for example:

1
2
3
4
5




string str = "Hello, World!";
string str2 = str.Substring(0, 5);
string str3 = str.Replace(",", " ");

But string also has several constructors that can come in handy. For instance, if you’ve used Python, you might be familiar with ‘=’ * 20 to quickly create a string of repeated characters. In C#, the equivalent is:

1
2


string sep = new string('=', 20);
Console.WriteLine(sep);

You can also create a string from a char array:

1
2
3


char[] chars = str.ToCharArray();
Array.Reverse(chars);
string reversed = new string(chars);

This is often the most efficient way to reverse a string without using Span or unsafe code. Less efficient approaches might look like:

1

string reversed = string.Join("", str.Reverse());

OS-Specific Methods & Considerations

Due to differences between Windows and Unix systems, there are two major pain points: line endings and path separators. 1. Line Endings: • Windows: \r\n (CRLF) • Unix: \n (LF) 2. Path Separators: • Windows:
• Unix: /

Use Path.Combine for Directory Paths

When building file paths, use the Path class. It automatically handles path separators based on the current OS:

1
2
3
4
5


var folder = "MyFolder";
var subfolder = "MySubFolder/";
var filename = "MyFile.txt";

var path = Path.Combine(folder, subfolder, filename);

Path.Combine also takes care of normalizing paths (e.g., removing redundant / or \ characters).

Use Environment.NewLine for Line Endings

To handle line endings, you can use Environment.NewLine, which returns the newline sequence for the current OS. For instance:

1
2
3
4
5
6
7


var lines = new string[]
{
 "Hello, World!",
 "Good, Morning!"
};

var text = string.Join(Environment.NewLine, lines);

Tip: You can also rely on built-in .NET methods that handle line endings automatically, such as File.ReadAllLines(), File.WriteAllLines(), Console.WriteLine(), etc.

.NET 6 ReplaceLineEndings

.NET 6 introduced ReplaceLineEndings, which converts all line endings in a string to a specified string (defaulting to the current OS’s newline):

1
2
3
4
5
6
7
8


var text = "Hello, World!\r\nGood morning!\nGood night!";

// Use the OS default line ending
var normalized = text.ReplaceLineEndings();

// Or specify a custom replacement
var unixNormalized = text.ReplaceLineEndings("\n");
var tabNormalized = text.ReplaceLineEndings("\t");

A Few StringBuilder Tricks

StringBuilder is a well-known class for efficient concatenation of large or frequently modified strings, but you may not be aware of all its features. Below are a few highlights:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16



var sb = new StringBuilder();

// Add strings
sb.Append("Hello, World!");
sb.AppendLine("Hello, World!");
sb.AppendFormat("Hello, {0}!", "World");
sb.Append('H', 5); // Append 5 'H' characters

sb.Insert(0, "Hello, "); // Insert at index 0
sb.Replace("Hello", "Good"); // Replace text
sb.Remove(0, 5); // Remove text starting at index 0
sb.Clear(); // Clear the StringBuilder

sb.ToString(); // Convert to a regular string
sb.ToString(0, 5); // Convert a substring to a regular string

Note that ToString(int startIndex, int length) can reduce extra allocations if you only need part of the content.

Embrace Syntax Sugar with String Interpolation

C# 6 introduced string interpolation, a convenient syntax for string concatenation, allowing you to embed expressions directly into string literals:

1
2
3
4
5
6
7


var name = "World";
var age = 18;

var str = $"Hello, {name}! You are {age} years old.";

// Before string interpolation, you might write:
var strOld = string.Format("Hello, {0}! You are {1} years old.", name, age);

String interpolation is also faster than string.Format. Even with StringBuilder, interpolation can be more readable than AppendFormat, but note that calling Append repeatedly might still yield the best performance in tight loops:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


var id = 123;
var name2 = "World";
var age2 = 18;

var sb = new StringBuilder();

// Using AppendFormat
sb.AppendFormat("ID: {0}, Name: {1}, Age: {2}", id, name2, age2);

// Using string interpolation
sb.Append($"ID: {id}, Name: {name2}, Age: {age2}");

// Using consecutive Append calls
sb.Append("ID: ")
.Append(id)
.Append(", Name: ")
.Append(name2)
.Append(", Age: ")
.Append(age2);

conclusion

We’ve covered several practical tips for C# string operations: • Prefer char over string where applicable. • Use method overloads that reduce unnecessary calls (e.g., Split with StringSplitOptions, Equals with StringComparison, etc.). • Take advantage of string constructors, especially for repeating characters or creating strings from character arrays. • Use platform-aware approaches like Path.Combine and Environment.NewLine. • Leverage StringBuilder efficiently, knowing its handy features. • Embrace string interpolation for more readable and often faster string assembly.

There are many other string-related features in C#, such as raw string literals, StringPool and string.Intern, Span, and various encoding classes. But hopefully, this article has given you insight into some of the most common pitfalls and best practices, helping you write more efficient and readable code when working with strings.

Deep Dive into .NET 8 WebApplication: Architecture and Components

Wed, 19 Apr 2023 00:00:00 +0000

WebApplication is used to configure the HTTP pipeline and routes in web applications. In this article, I’ll break down its components and structure.

1
2
3
4
5
6


/// <summary>
/// The web application used to configure the HTTP pipeline, and routes.
/// </summary>
[DebuggerDisplay("{DebuggerToString(),nq}")]
[DebuggerTypeProxy(typeof(WebApplication.WebApplicationDebugView))]
public sealed class WebApplication : IHost, IDisposable, IApplicationBuilder, IEndpointRouteBuilder, IAsyncDisposable

IHost

First and foremost, a web application is a program, and IHost is the abstraction of that program.

1
2
3
4
5
6


public interface IHost : IDisposable
{
 IServiceProvider Services { get; }
 Task StartAsync(CancellationToken cancellationToken = default(CancellationToken));
 Task StopAsync(CancellationToken cancellationToken = default(CancellationToken));
}

It makes sense that a program has start and stop lifecycle methods. I want to highlight IServiceProvider, which is crucial and will be explained in detail in the dependency injection chapter. For now, just know that it’s a service provider that allows you to access services, provided they’re registered in the IoC container.

The code flow for Host.StartAsync is as follows:

1
2
3
4
5
6


await host._hostLifetime.WaitForStartAsync(token1).ConfigureAwait(false); // Register start program
host.Services.GetService<IStartupValidator>()?.Validate(); // Validate
IHostedLifecycleService.StartingAsync
IHostedService.StartAsync
IHostedLifecycleService.StartedAsync
host._applicationLifetime.NotifyStarted();

Similarly, StopAsync follows this flow:

1
2
3
4


IHostedLifecycleService.StoppingAsync
IHostedService.StopAsync
IHostedLifecycleService.StoppedAsync
this._logger.StoppedWithException((Exception) ex);

It’s worth noting that IStartupValidator, IHostedService, and IHostedLifecycleService provide different hooks for us to inject our custom business logic by registering them with the container.

IApplicationBuilder

WebApplication implements IApplicationBuilder, which provides the pipeline mechanism.

1
2


IApplicationBuilder Use(Func<RequestDelegate, RequestDelegate> middleware);
RequestDelegate Build();

Let me explain the pipeline concept: pipelines are a widespread concept in .NET, with aspect-oriented programming at their core. We’ll cover this in a dedicated chapter later. For now, just know that it follows an onion model.

Additionally, as the name suggests, IApplicationBuilder implements the builder pattern, so WebApplication provides a Build method:

1
2
3
4
5
6
7


public WebApplication Build()
{
 this._hostApplicationBuilder.Services.Add(this._genericWebHostServiceDescriptor);
 this.Host.ApplyServiceProviderFactory(this._hostApplicationBuilder);
 this._builtApplication = new WebApplication(this._hostApplicationBuilder.Build());
 return this._builtApplication;
}

Due to space constraints, I won’t delve into all the details, but four hooks are executed in the Build method:

1
2
3
4


public IHostBuilder ConfigureHostConfiguration(Action<IConfigurationBuilder> configureDelegate)
public IHostBuilder ConfigureAppConfiguration(Action<HostBuilderContext, IConfigurationBuilder> configureDelegate)
public IHostBuilder ConfigureServices(Action<HostBuilderContext, IServiceCollection> configureDelegate)
public IHostBuilder ConfigureContainer<TContainerBuilder>(Action<HostBuilderContext, TContainerBuilder> configureDelegate)

Ultimately, the service container is marked as read-only.

IEndpointRouteBuilder

IEndpointRouteBuilder defines the convention for building routes in the application.

1

ICollection<EndpointDataSource> DataSources { get; }

Here’s the implementation in WebApplication, showing how EndpointDataSource implementations are composed together:

1
2
3
4
5
6
7
8


public IReadOnlyList<Endpoint> Endpoints
{
 get
 {
 EndpointDataSource requiredService = this._webApplication.Services.GetRequiredService<EndpointDataSource>();
 return requiredService is CompositeEndpointDataSource endpointDataSource && endpointDataSource.DataSources.Intersect<EndpointDataSource>((IEnumerable<EndpointDataSource>) this._webApplication.DataSources).Count<EndpointDataSource>() != this._webApplication.DataSources.Count ? new CompositeEndpointDataSource((IEnumerable<EndpointDataSource>) this._webApplication.DataSources).Endpoints : requiredService.Endpoints;
 }
}

An EndpointDataSource is essentially a collection of Endpoints, and Endpoint is an extremely important concept in AspNetCore that we’ll explore later. For now, understand that it represents a terminal point for handling HTTP requests, containing both the logic to process requests and associated metadata.

IAsyncDisposable

IAsyncDisposable is an interface introduced in .NET Core 2.0 for asynchronously releasing resources. It’s the asynchronous version of the IDisposable interface. Releasing certain resources may involve asynchronous operations, and using the synchronous release pattern of the IDisposable interface could block threads, affecting application performance and responsiveness.

1
2
3
4


public interface IAsyncDisposable
{
 ValueTask DisposeAsync();
}

After using the object, you can use the await using syntactic sugar or directly call the DisposeAsync() method to release resources.

Run

The Run function is WebApplication’s start button. You can pass a URL to add it to the listening list:

1
2
3
4
5
6


public void Run([StringSyntax("Uri")] string? url = null)
{
 this.Listen(url);
 // public static void Run(this IHost host) => host.RunAsync().GetAwaiter().GetResult();
 HostingAbstractionsHostExtensions.Run(this);
}

The source code for HostingAbstractionsHostExtensions.Run is relatively simple. The host’s StartAsync and WaitForShutdownAsync were discussed above, and WebApplication’s DisposeAsync is triggered in the finally block:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public static async Task RunAsync(this IHost host, CancellationToken token = default(CancellationToken))
{
 try
 {
 ConfiguredTaskAwaitable configuredTaskAwaitable = host.StartAsync(token).ConfigureAwait(false);
 await configuredTaskAwaitable;
 configuredTaskAwaitable = host.WaitForShutdownAsync(token).ConfigureAwait(false);
 await configuredTaskAwaitable;
 }
 finally
 {
 if (host is IAsyncDisposable asyncDisposable)
 await asyncDisposable.DisposeAsync().ConfigureAwait(false);
 else
 host.Dispose();
 }
}

An interesting point here is: why trigger in the finally block? This is because the Host’s lifecycle functions all use a combined cancellation token. This is a safe cancellation cooperation pattern - after the token is canceled, an OperationCanceledException exception is triggered, allowing normal disposal work to continue even in this situation. This is an excellent programming practice.

File Transfer in C#

Wed, 01 Mar 2023 00:00:00 +0000

This guide demonstrates a reliable file transfer solution using C#’s native networking classes, with enhancements for error handling, asynchronous operations, and large file support.

Enhanced Client Implementation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


using System.IO;
using System.Net.Sockets;
using System.Threading.Tasks;

public class FileSender
{
 public async Task SendFileAsync(string filePath, string host, int port)
 {
 using var client = new TcpClient();
 await client.ConnectAsync(host, port);

 using var networkStream = client.GetStream();
 using var fileStream = File.OpenRead(filePath);

 // Send file metadata first (file name and size)
 var fileName = Path.GetFileName(filePath);
 var fileNameData = System.Text.Encoding.UTF8.GetBytes(fileName);
 await networkStream.WriteAsync(BitConverter.GetBytes(fileNameData.Length), 0, 4);
 await networkStream.WriteAsync(fileNameData, 0, fileNameData.Length);
 await networkStream.WriteAsync(BitConverter.GetBytes(fileStream.Length), 0, 8);

 // Buffer-based transfer for large files
 var buffer = new byte[81920];
 int bytesRead;
 while ((bytesRead = await fileStream.ReadAsync(buffer, 0, buffer.Length)) > 0)
 {
 await networkStream.WriteAsync(buffer, 0, bytesRead);
 }
 }
}

Enhanced Server Implementation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


using System.Net.Sockets;
using System.Threading.Tasks;

public class FileReceiver
{
 public async Task StartListeningAsync(int port, string saveDirectory)
 {
 var listener = new TcpListener(System.Net.IPAddress.Any, port);
 listener.Start();

 try
 {
 while (true)
 {
 var client = await listener.AcceptTcpClientAsync();
 _ = Task.Run(() => HandleClientAsync(client, saveDirectory));
 }
 }
 finally
 {
 listener.Stop();
 }
 }

 private async Task HandleClientAsync(TcpClient client, string saveDirectory)
 {
 using (client)
 using (var stream = client.GetStream())
 {
 // Read metadata
 var fileNameSizeBuffer = new byte[4];
 await stream.ReadAsync(fileNameSizeBuffer, 0, 4);
 int fileNameSize = BitConverter.ToInt32(fileNameSizeBuffer);

 var fileNameBuffer = new byte[fileNameSize];
 await stream.ReadAsync(fileNameBuffer, 0, fileNameSize);
 string fileName = System.Text.Encoding.UTF8.GetString(fileNameBuffer);

 var fileSizeBuffer = new byte[8];
 await stream.ReadAsync(fileSizeBuffer, 0, 8);
 long fileSize = BitConverter.ToInt64(fileSizeBuffer);

 // Prepare file storage
 var savePath = Path.Combine(saveDirectory, fileName);
 using var fileStream = File.Create(savePath);

 // Buffer-based reception
 var buffer = new byte[81920];
 long totalBytesRead = 0;
 int bytesRead;

 while (totalBytesRead < fileSize &&
 (bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length)) > 0)
 {
 await fileStream.WriteAsync(buffer, 0, bytesRead);
 totalBytesRead += bytesRead;
 }
 }
 }
}

Key Enhancements

Asynchronous Operations • Uses async/await for non-blocking I/O • Handles multiple concurrent connections • Implements proper resource cleanup with using statements
Large File Support • Chunked transfer using 80KB buffers (adjustable) • Memory-efficient streaming instead of full-file buffering • Progress tracking capability
Metadata Handling • Transmits filename and size before file content • UTF-8 encoding for cross-platform compatibility • Prevents path injection attacks
Error Handling • Automatic client disconnection cleanup • Network timeout handling (recommended to add) • File size validation during transfer

Usage Example

Sender:

1
2


var sender = new FileSender();
await sender.SendFileAsync("largefile.zip", "192.168.1.100", 5000);

Receiver:

1
2


var receiver = new FileReceiver();
await receiver.StartListeningAsync(5000, @"C:\ReceivedFiles");

Recommended Improvements

Security Enhancements • Add SSL/TLS encryption • Implement file checksum verification • Add authentication mechanism
Performance Optimization • Implement compression during transfer • Adjust buffer size based on network conditions • Add parallel chunk transfer support
Diagnostics • Add transfer progress reporting • Implement cancellation support • Add logging for error tracking

Comparison Table: Native vs Enhanced Implementation

Feature	Basic Implementation	Enhanced Version
Large File Support	❌	✅
Async Operations	❌	✅
Metadata Handling	❌	✅
Memory Efficiency	❌	✅
Concurrent Connections	❌	✅
Error Handling	❌	Partial

This implementation provides a foundation for reliable file transfers while maintaining flexibility for customization. For production use, consider implementing additional security measures and error recovery mechanisms.

C# on Allen's Dev Journal

Why Doesn't IEnumerable Have a ForEach Method?

The Consequences of Adding ForEach

Compromising Interface Purity

Introducing Side Effects

Performance and Resource Considerations

Summary

A Tour of Hash Functions: From MD5 to Argon2 and Beyond

Early Hash Functions

The SHA-2 Family

The SHA-3 Family

PBKDF2

bcrypt and Argon2

BLAKE2

SM3

Summary

Why You Must Salt and Hash Passwords: A Journey to Secure Storage

1. Plaintext Storage

2. Simple Hashing (MD5 / SHA1)

3. Hashing with a Salt (SHA256)

4. Using a Key Derivation Function (PBKDF2)

5. The Gold Standard: BCrypt and Argon2

Conclusion

Advanced XML Parsing: A Performance Duel Between LINQ, XPath, and Regex

LINQ to XML

XPath

Regular Expressions

Performance Comparison

One More Thing…

Fields vs. Properties: Why Not Just Use Public Fields in C#?

A Fundamental Difference in Perspective

Long-Standing Conventions in the Ecosystem

Flexibility and Encapsulation

Performance Considerations

The Future is Properties: C# 13 and the field Keyword

Summary

Efficient XML Parsing in C#: A Performance Comparison

Using XmlDocument

Using System.Xml.Linq

Using XmlReader

Using Regular Expressions (Regex)

Using Traditional String Methods

Using Span<T>

Performance Test

Why ValueTask? A Guide to C#'s Performance-Oriented Task Alternative

A Quick Recap of the Task Type

The Problem with the Traditional Task Type

Introducing ValueTask

Important ValueTask Caveats

A ValueTask Cannot Be Awaited More Than Once

Do Not Block on a ValueTask

Do Not await a ValueTask Concurrently

How to Work Around ValueTask’s Limitations

Conclusion

References

Improving Thread Communication in .NET: Moving Beyond Flags and Polling

Traditional Approach

Classic Two-Flag Pattern

Using ManualResetEvent for Thread Pause and Resume

Using CancellationToken to Stop Tasks

Optimizing the Producer-Consumer Pattern

Using Thread-Safe Collections

Using Semaphores Instead of Flags

Using BlockingCollection for the Producer-Consumer Pattern

Conclusion

.NET 8 Dependency Injection

1 ServiceCollection

2 ServiceProvider

2.1 ServiceProviderEngine

2.2 ServiceProviderEngineScope

3 ServiceCallSite

3.1 ResultCache

3.2 CallSiteFactory.GetCallSite

4 CallSiteVisitor

4.1 VisitRootCache (Singleton)

4.2 VisitScopeCache (Scoped)

4.3 VisitDisposeCache (Transient)

Common Image Data Type Conversions in .NET Development

Common Image Data Types

Conversion Examples

The Consequences of Adding `ForEach`

The Future is Properties: C# 13 and the `field` Keyword

Using `XmlDocument`

Using `System.Xml.Linq`

Using `XmlReader`

Using `Span<T>`

A Quick Recap of the `Task` Type

The Problem with the Traditional `Task` Type

Introducing `ValueTask`

Important `ValueTask` Caveats

A `ValueTask` Cannot Be Awaited More Than Once

Do Not Block on a `ValueTask`

Do Not `await` a `ValueTask` Concurrently

How to Work Around `ValueTask`’s Limitations

When You Can Use a `char`, Don’t Use a `string`