How to use ValueTuples in C#

A Tuple is a data structure that comprises an ordered, finite sequence of immutable, heterogeneous elements of fixed sizes. When we say the elements in a Tuple are immutable, we mean that they pertain to a specific type that cannot be changed.

A ValueTuple is a structure introduced in C# 7.0. A ValueTuple overcomes two major limitations of tuples—namely, that they are inefficient and that they must be referenced as Item1, Item2, etc. That is, ValueTuples are both performant and referenceable by names the programmer chooses. This article discusses what ValueTuples are and how we can use them in C#.

To work with the code examples provided in this article, you should have Visual Studio 2019 installed in your system. If you don’t already have a copy, you can download Visual Studio 2019 here. 

Create a console application project in Visual Studio

First off, let’s create a .NET Core Console Application project in Visual Studio. Assuming Visual Studio 2019 is installed in your system, follow the steps outlined below to create a new .NET Core Console Application project in Visual Studio 2019.

1. Launch the Visual Studio IDE.
2. Click on “Create new project.”
3. In the “Create new project” window, select “Console App (.NET Core)” from the list of templates displayed.
4. Click Next. 
5. In the “Configure your new project” window shown next, specify the name and location for the new project.
6. Click Create.

This will create a new .NET Core console application project in Visual Studio 2019. We’ll use this project to work with ValueTuples in the subsequent sections of this article.

ValueTuple vs. Tuple in C#

ValueTuple provides a lightweight type that can be used to return multiple values from a method. Unlike a Tuple, which is a reference type, a ValueTuple is a value type with optimized syntax and strong naming conventions. Also unlike a Tuple, the fields in a ValueTuple are mutable. As a result, the performance of a ValueTuple is far better than that of a Tuple.

And while the properties in a Tuple are read-only — i.e., their values cannot be altered once they have been created — the properties in a ValueTuple can be changed after creation.

Install the System.ValueTuple NuGet package

After you have created a console application in Visual Studio, the next thing you should do is install the necessary NuGet package. You can also install the System.ValueTuple package from the NuGet package manager inside the Visual Studio 2019 IDE, or you can enter the following command to install this package via the .NET CLI.

dotnet add package System.ValueTuple

Note that ValueTuple is available as part of .NET Framework 4.7.

Create a ValueTuple in C#

There are several ways in which you can create a ValueTuple. These include the following:

• Using a constructor
• Using the Create method
• Using parentheses, ()

The following code snippet illustrates how you can create a ValueTuple using its constructor.

ValueTuple<int, string, string> valueTuple =
new ValueTuple<int, string, string>(1, "Joydip", "Kanjilal");

You can also create a ValueTuple using the Create method. The following code snippet illustrates how this can be achieved.

var valueTuple = ValueTuple.Create(1, "Joydip", "Kanjilal");

You can assign member names and corresponding values to a ValueTuple at the right side as shown below.

var author = (Id: 1, FirstName: "Joydip", LastName: "Kanjilal");

Lastly, you can create and initialize a ValueTuple using parentheses as well. The following code snippet leverages parentheses to create and initialize a ValueTuple.

(int Id, string FirstName, string LastName) author = (1, "Joydip", "Kanjilal");

Use named properties in a ValueTuple in C#

ValueTuple also supports named properties. That is, instead of the default property names Item1, Item2, Item3, etc., you can assign meaningful names to the properties of a ValueTuple. The following code snippet illustrates how you can assign names to the properties of a ValueTuple.

(int Id, string FirstName, string LastName) author = (1, "Joydip", "Kanjilal");

Return a ValueType from a method in C#

As with a Tuple, you can take advantage of a ValueTuple to return multiple values from a method. The following code snippet illustrates how you can return a ValueTuple from a method.

static (int, string, string) GetAuthor()
{
    return (Id: 1, FirstName: "Joydip", LastName: "Kanjilal");
}

Retrieve individual members from a ValueTuple using deconstruction in C#

You can take advantage of deconstruction to retrieve individual members from a ValueTuple. The following code snippet shows how this can be done.

(int Id, string FirstName, string LastName) = GetAuthor();

Note that the GetAuthor method is given in the preceding section.

I’ll wrap up by pointing out that you can use the extension methods in System.Tuple and System.ValueTuple to convert a Tuple to a ValueTuple and vice versa. The following code snippet shows how you can convert a ValueTuple to a Tuple.

var valueTuple = ValueTuple.Create(1, "Joydip", "Kanjilal");
var tuple = valueTuple.ToTuple();

ValueTuples offer a simpler syntax and better performance than Tuples, plus the advantages of being able to change their data members and assign them meaningful names. In short, there are many good reasons for using ValueTuples instead of Tuples.