C# NameValueCollection Usage

NameValueCollection allows many values for one key. It is found in System.Collections.Specialized. It does not provide excellent performance. Other collections are likely to be faster for your program.

This C# tutorial shows the NameValueCollection type. It provides benchmarks.

Example

First, we see how you can create a new NameValueCollection. The example then adds four key/value pairs to the collection. The keys can occur more than once, but map to the same array of values. This means you can have one key pointing to two values.

Program that uses NameValueCollection [C#]

using System;
using System.Collections.Specialized;

class Program
{
    static NameValueCollection GetCollection()
    {
	NameValueCollection collection = new NameValueCollection();
	collection.Add("Sam", "Dot Net Perls");
	collection.Add("Bill", "Microsoft");
	collection.Add("Bill", "White House");
	collection.Add("Sam", "IBM");
	return collection;
    }

    static void Main()
    {
	NameValueCollection collection = GetCollection();
	foreach (string key in collection.AllKeys) // <-- No duplicates returned.
	{
	    Console.WriteLine(key);
	}
    }
}

Output

Sam
Bill

Description. The GetCollection method defined here returns a new NameValueCollection. The collection maps two names (Sam, Bill) to four values. In other words, two keys are mapped to two string arrays. The NameValueCollection always acts on strings.

Using AllKeys property. The NameValueCollection defines an AllKeys property. We use it in a foreach loop to see all the keys in the collection. The loop prints two names.

Get value

Here we see how you can get a value in the collection using a string key. This is how you can use AppSettings in ASP.NET, or the QueryString collection. The collection returns null as a value if the key is not found. If more than one value is found, the string returned contains the values joined by commas.

Program that uses NameValueCollection indexer [C#]

using System;
using System.Collections.Specialized;

class Program
{
    static void Main()
    {
	NameValueCollection collection = GetCollection();
	Console.WriteLine(collection["Sam"]); // <-- Same as GetValues
	Console.WriteLine(collection["X"] == null); // <-- Not found
    }
}

Output

Dot Net Perls,IBM
True

Get methods

Here we see that the NameValueCollection also allows you to test whether there are keys, with HasKeys. It also lets you use GetKey with an index to get the key at that index. You can use Get to get the value at that index. My research has shown that the fastest way of accessing values in small NameValueCollections is with these methods.

Program that uses Get [C#]

using System;
using System.Collections.Specialized;

class Program
{
    static void Main()
    {
	NameValueCollection collection = GetCollection(); // <-- See first example

	// Write whether the collection has keys.
	Console.WriteLine(collection.HasKeys());

	// Write the first key.
	Console.WriteLine(collection.GetKey(0));

	// Get the first value.
	string value = collection.Get(0);
	Console.WriteLine(value);
    }
}

Output

True
Sam
Dot Net Perls,IBM

Remove value

You can also remove a key/value pair using the Remove method on NameValueCollection. This method requires that you pass it a string key for the pair. I found that you can remove a nonexistent value without throwing an exception. Also, if you remove a key, all its values are also removed.

Count pairs

You can count all the key/value pairs in the NameValueCollection. With the Count property, all the duplicate keys are considered separated. Each pair, even if it has the same key as another, is counted separately. To test this, add multiple identical keys, and then check the Count.

ASP.NET

The NameValueCollection is prevalent in ASP.NET, and it is used in appSettings, QueryString, and Headers collections. First, it is used in appSettings, which allows you to retrieve settings from your Web.config file.

QueryString usage. The NameValueCollection is also used in the query string collection in ASP.NET. You can access the query values very quickly simply by specifying the string key. Note that this may not be optimal.

Benchmark

Here we see sample code that was benchmarked. To reproduce the benchmark, you will need to paste the code blocks into a test harness and compile in Release mode outside of the debugger.

NameValueCollection tested

var collection = new NameValueCollection();
collection.Add("Sam", "Dot Net Perls");
collection.Add("Bill", "Microsoft");
collection.Add("Steve", "Apple");
collection.Add("Rupert", "News Corporation");

Dictionary tested

var dictionary = new Dictionary<string, string>();
dictionary.Add("Sam", "Dot Net Perls");
dictionary.Add("Bill", "Microsoft");
dictionary.Add("Steve", "Apple");
dictionary.Add("Rupert", "News Corporation");

NameValueCollection statement tested

string value = collection["Steve"];

Dictionary statement tested

string value = dictionary["Steve"];

Results (10 million iterations)

NameValueCollection lookup: 2768 ms
Dictionary lookup:           407 ms [faster]

Results. The NameValueCollection's lookup speed on even a small collection was very poor. This means that its performance is likely much worse in many situations. Therefore, the collection must be tested before being used in performance-critical code.

Summary

We saw ways you can use NameValueCollection in the C# language. The collection is located in System.Collections.Specialized, and allows you to associate one string key with multiple string values. The collection concatenates values with commas, and returns string[] arrays. It has serious performance drawbacks, and should be avoided unless it is tested thoroughly in your application.