last modified May 13, 2025
The KeyValuePair struct in C# is a fundamental data structure that represents a key-value pair. It's commonly used with dictionaries and other collection types to store paired elements. This tutorial explores KeyValuePair in depth.
KeyValuePair is a generic struct defined in the
System.Collections.Generic namespace. It encapsulates two related elements: a
key and a value.
This structure is primarily used when working with dictionaries, but can also be employed in other scenarios where you need to associate two values together. It's a lightweight, immutable structure that provides efficient storage.
KeyValuePair is particularly useful when you need to enumerate
through dictionary entries or when you need to return a single key-value pair
from a method.
This example demonstrates the most basic usage of KeyValuePair, creating instances and accessing their properties.
KeyValuePair<string, int> product1 = new ("Apples", 50);
var product2 = new KeyValuePair<string, int>("Oranges", 30);
Console.WriteLine($"Product: {product1.Key}, Quantity: {product1.Value}");
Console.WriteLine($"Product: {product2.Key}, Quantity: {product2.Value}");
DisplayKeyValuePair(product1);
void DisplayKeyValuePair(KeyValuePair<string, int> pair)
{
Console.WriteLine($"In method - Key: {pair.Key}, Value: {pair.Value}");
}
This code shows how to create KeyValuePair instances and access
their Key and Value properties. It also demonstrates passing KeyValuePair to
methods.
KeyValuePair<string, int> product1 = new ("Apples", 50);
Creates a KeyValuePair with string key "Apples" and integer value
50. The generic parameters specify the types of the key and value.
var product2 = new KeyValuePair<string, int>("Oranges", 30);
Uses var keyword for implicit typing. The compiler infers the type from the right-hand side of the assignment.
Console.WriteLine($"Product: {product1.Key}, Quantity: {product1.Value}");
Accesses the Key and Value properties of the KeyValuePair instance. These properties are read-only.
KeyValuePair is most commonly encountered when working with dictionaries. This example shows how to use it when iterating through dictionary entries.
Dictionary<string, int> inventory = new()
{
{"Apples", 50},
{"Oranges", 30},
{"Bananas", 45},
{"Grapes", 25}
};
Console.WriteLine("Inventory Contents:");
foreach (KeyValuePair<string, int> item in inventory)
{
Console.WriteLine($"{item.Key}: {item.Value} units");
}
KeyValuePair<string, int> bananaItem = inventory.FirstOrDefault(
x => x.Key == "Bananas");
if (bananaItem.Key != null)
{
Console.WriteLine($"\nFound: {bananaItem.Key} - {bananaItem.Value}");
}
This example demonstrates using KeyValuePair with dictionaries, including iteration and searching operations.
foreach (KeyValuePair<string, int> item in inventory)
When enumerating a dictionary, each element is a KeyValuePair containing the key and value for that entry. This is the primary use case for KeyValuePair.
KeyValuePair<string, int> bananaItem = inventory.FirstOrDefault( x => x.Key == "Bananas");
Uses LINQ's FirstOrDefault to find a specific
KeyValuePair in the dictionary. Note that we check if the Key is
null to determine if the item was found.
KeyValuePair can be useful as a return type when you need to return two related values from a method. This example shows this pattern.
int[] numbers = { 12, 45, 7, 32, 19, 3, 56 };
var minMax = FindMinMax(numbers);
Console.WriteLine($"Minimum: {minMax.Key}, Maximum: {minMax.Value}");
var result = TryParseNumber("42");
if (result.Key)
{
Console.WriteLine($"Parsed successfully: {result.Value}");
}
KeyValuePair<int, int> FindMinMax(int[] numbers)
{
if (numbers == null || numbers.Length == 0)
{
throw new ArgumentException("Array cannot be empty");
}
int min = numbers[0];
int max = numbers[0];
foreach (int num in numbers)
{
if (num < min) min = num;
if (num > max) max = num;
}
return new KeyValuePair<int, int>(min, max);
}
KeyValuePair<bool, int> TryParseNumber(string input)
{
bool success = int.TryParse(input, out int result);
return new KeyValuePair<bool, int>(success, result);
}
This code demonstrates two common patterns for using KeyValuePair
as a return type: returning related values (min/max) and implementing a TryParse
pattern.
KeyValuePair<int, int> FindMinMax(int[] numbers)
Method returns two related integers (min and max) bundled in a KeyValuePair. This is cleaner than using out parameters in some cases.
KeyValuePair<bool, int> TryParseNumber(string input)
Implements a TryParse pattern using KeyValuePair, returning both a success flag and the parsed value. Similar to how int.TryParse works with out params.
This example shows more advanced scenarios including deconstruction, LINQ operations, and custom comparisons with KeyValuePair.
Dictionary<string, decimal> productPrices = new()
{
{"Laptop", 999.99m},
{"Phone", 699.99m},
{"Tablet", 349.99m},
{"Monitor", 249.99m}
};
foreach (var (product, price) in productPrices)
{
Console.WriteLine($"{product} costs {price:C}");
}
var expensiveItems = productPrices
.Where(kvp => kvp.Value > 500m)
.OrderByDescending(kvp => kvp.Value);
Console.WriteLine("\nExpensive Items:");
foreach (var item in expensiveItems)
{
Console.WriteLine($"{item.Key}: {item.Value:C}");
}
KeyValuePair<string, decimal> mostExpensive = productPrices
.OrderByDescending(kvp => kvp.Value)
.First();
Console.WriteLine($"\nMost expensive: {mostExpensive.Key} at {mostExpensive.Value:C}");
This example demonstrates modern C# features like deconstruction, LINQ operations, and custom sorting with KeyValuePair.
foreach (var (product, price) in productPrices)
Uses deconstruction syntax to break the KeyValuePair into separate variables. This is available in C# 7.0 and later for cleaner code.
.Where(kvp => kvp.Value > 500m) .OrderByDescending(kvp => kvp.Value);
Shows LINQ operations filtering and sorting based on the Value property of the KeyValuePairs in the dictionary.
KeyValuePair<string, decimal> mostExpensive = productPrices .OrderByDescending(kvp => kvp.Value) .First();
Finds the most expensive item by sorting by value and taking the first item. Demonstrates how KeyValuePair can be used in custom comparison operations.
Microsoft KeyValuePair Documentation
KeyValuePair is a versatile structure that provides a clean way to work with paired data in C#. It's particularly useful with dictionaries but has broader applications as shown in these examples.
My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.
List all C# tutorials.