How to use ValueTask in C#

If the method needs to return a value, it should return Task<T>. For event handlers, void is used. Prior to C# 7.0, asynchronous methods could return Task, Task<T>, or void.

Starting with C# 7.0, ValueTask (available through the System.Threading.Tasks.Extensions package) was introduced as a more efficient alternative to Task, helping avoid unnecessary memory allocations when returning task objects.

Benefits of Using ValueTask

A Task represents the state of an operation (e.g., whether it’s completed or canceled), but returning a Task from an asynchronous method requires allocating memory on the managed heap, which can be inefficient when the result is available immediately or completes synchronously.

In contrast, ValueTask offers two key benefits: improved performance by avoiding heap allocation and flexibility, as it’s a value type (struct) rather than a reference type. However, ValueTask can only be consumed once (either awaited or converted to a Task for blocking), and cannot be blocked directly. If blocking is needed, you should use the AsTask method.

Example of ValueTask in C#

Suppose you have an asynchronous method that checks whether a user exists in the system, and you initially return a Task:

public Task<bool> UserExistsAsync(int userId)
{
    return Task.FromResult(userId > 0);
}

While this works, it creates a Task object on the heap, which can be inefficient when the result is immediately available. Instead, you can use ValueTask to avoid the allocation:

public ValueTask<bool> UserExistsAsync(int userId)
{
    return new ValueTask<bool>(userId > 0);
}

Now, let's extend the example by creating an interface for a service that fetches user information:

public interface IUserService
{
    ValueTask<string> GetUserNameAsync(int userId);
}

Here's a concrete implementation of the IUserService interface:

public class UserService : IUserService
{
    public ValueTask<string> GetUserNameAsync(int userId)
    {
        // Simulate a delay for retrieving the user name.
        if (userId == 1)
        {
            return new ValueTask<string>("John Doe");
        }
        else
        {
            return new ValueTask<string>(string.Empty);
        }
    }
}

In the Main method, you can call the GetUserNameAsync method and handle the result:

static async Task Main(string[] args)
{
    IUserService userService = new UserService();
    
    var userNameResult = await userService.GetUserNameAsync(1);
    
    if (!string.IsNullOrEmpty(userNameResult))
    {
        Console.WriteLine($"User name: {userNameResult}");
    }
    else
    {
        Console.WriteLine("User not found.");
    }
    
    Console.ReadKey();
}

In this example, using ValueTask helps avoid unnecessary heap allocations when the result can be returned synchronously (like when the user ID is valid or invalid), optimizing performance for such common cases.

When to Use ValueTask in C#

While ValueTask offers performance benefits, especially by avoiding heap allocation, there are trade-offs to consider. ValueTask is a value type with two fields, which can increase the amount of data involved compared to the single field in a reference type like Task. This also makes the state machine for asynchronous methods larger when using ValueTask.

Additionally, if you use methods like Task.WhenAll or Task.WhenAny, converting ValueTask to Task (using AsTask) may incur unnecessary allocations. The general rule is to use Task for always-asynchronous operations and ValueTask for cases where the result is already available or cached. Always perform a performance analysis before choosing ValueTask.