C# Reference ยท Collections
ReadOnlyCollection and AsReadOnly
Reference for C# ReadOnlyCollection<T>, List<T>.AsReadOnly(), ReadOnlyDictionary and IReadOnlyList: how read-only views work and why they are not snapshots.
A read-only collection wrapper lets a class expose its internal list without letting callers change it. ReadOnlyCollection<T> (namespace System.Collections.ObjectModel) wraps an IList<T>; ReadOnlyDictionary<TKey,TValue> wraps an IDictionary<TKey,TValue>. You create the wrapper with its constructor or, for lists, with list.AsReadOnly().
The wrapper is a live view, not a copy. If the owner later adds an item to the underlying list, readers holding the view see it. That is often what you want for a property, but it is not the same as immutability.
var items = new List<string> { "a", "b" }; ReadOnlyCollection<string> view = items.AsReadOnly(); // view.Add("c"); // does not compile: there is no Add
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public class ReadOnlyCollection<T> : IList<T>, IReadOnlyList<T> { public ReadOnlyCollection(IList<T> list); public int Count { get; } public T this[int index] { get; } public bool Contains(T value); public int IndexOf(T value); public void CopyTo(T[] array, int index); } // On List<T>, Array and others public ReadOnlyCollection<T> AsReadOnly(); // List<T> public static ReadOnlyCollection<T> Array.AsReadOnly<T>(T[] array); public class ReadOnlyDictionary<TKey, TValue> { public ReadOnlyDictionary(IDictionary<TKey, TValue> dictionary); }
| Name | Description |
|---|---|
list / dictionary |
The collection to wrap. It is not copied. |
index |
Zero-based position for the indexer, which has no setter. |
Returns: AsReadOnly() returns a ReadOnlyCollection<T> over the same list. The wrapper has Count, an indexer, Contains, IndexOf and an enumerator, but no Add or Remove methods of its own.
Errors: ArgumentNullException for a null list. Modifying through the explicit IList<T> or ICollection<T> interface throws NotSupportedException.
Usage notes
- View, not snapshot. Changes to the source list show up in the view. Return
list.ToArray()orlist.ToImmutableArray()when callers must see a frozen copy. - Wrapping is O(1) and does not allocate a copy of the elements, so returning a view from a property is cheap (the wrapper object itself is a small allocation each call; cache it in a field if the property is hot).
- Casting can break the guard. A caller who cast the exposed
IReadOnlyList<T>back toList<T>can modify it when you returned the list itself. AReadOnlyCollection<T>wrapper prevents that cast. - Prefer interfaces in signatures.
IReadOnlyList<T>,IReadOnlyCollection<T>andIReadOnlyDictionary<TKey,TValue>state intent without a wrapper type, but remember they do not stop casts. - Items stay mutable. The collection is read-only, not its elements.
- Dictionaries:
ReadOnlyDictionary<TKey,TValue>follows the same live-view rule. In .NET 8+FrozenDictionaryandImmutableDictionarygive true immutability. - Thread safety: the wrapper adds none. If the owner changes the list while another thread enumerates the view, enumeration can throw.