C# Concurrentdictionary (How it Works for Developers)

When working with multi-threaded applications in C#, maintaining data integrity is crucial, especially when you're generating PDF documents on the fly using a library like IronPDF. The ConcurrentDictionary<tkey, tvalue> class provides a thread-safe collection to manage key and value pairs efficiently, even when multiple threads concurrently perform operations like insertions, updates, or lookups.

In this guide, we'll explore how ConcurrentDictionary works, how it can integrate with IronPDF for parallel PDF processing, and what every .NET developer needs to know about key type, thread safety, and common pitfalls like handling an existing key or ensuring data consistency.

What is a ConcurrentDictionary in C#?

The ConcurrentDictionary<tkey, tvalue> class, part of the System.Collections.Concurrent namespace, is a generic collection designed for high-performance, thread-safe operations. Unlike a regular dictionary, it allows multiple threads to safely access and modify the collection without locking the entire structure.

A new instance of ConcurrentDictionary<string, string> might look like this:

var dictionary = new ConcurrentDictionary<string, string>();

var dictionary = new ConcurrentDictionary<string, string>();

Dim dictionary = New ConcurrentDictionary(Of String, String)()

You can define your own TKey and TValue types based on your specific use case, such as caching rendered PDF file paths or tracking concurrent PDF generation tasks.

Why Use ConcurrentDictionary with IronPDF?

Imagine you're building a program that generates personalized invoices using IronPDF for thousands of users. If each thread needs to render a document and store its result, a regular dictionary would introduce race conditions or throw exceptions if a key already exists.

Using ConcurrentDictionary ensures:

• Data consistency across threads
• Efficient reads and writes
• Prevention of unknown code errors
• Zero locking overhead when multiple threads operate on different keys

Common Methods and Their Use with IronPDF

Let's break down key methods using IronPDF rendering scenarios.

GetOrAdd Method: Retrieve or Add a New Key

This method checks if a specified key exists. If it doesn't, it adds the new value.

var filePath = pdfCache.GetOrAdd(userId, id => GeneratePdfForUser(id));

var filePath = pdfCache.GetOrAdd(userId, id => GeneratePdfForUser(id));

Dim filePath = pdfCache.GetOrAdd(userId, Function(id) GeneratePdfForUser(id))

• Ensures thread safety
• Avoids duplicate rendering
• Returns associated value for the given key

AddOrUpdate Method: Handle an Existing Value Gracefully

This method allows you to update the value if the key exists, or add a new key value pair.

pdfCache.AddOrUpdate(userId,
    id => GeneratePdfForUser(id),
    (id, existingValue) => UpdatePdfForUser(id, existingValue));

pdfCache.AddOrUpdate(userId,
    id => GeneratePdfForUser(id),
    (id, existingValue) => UpdatePdfForUser(id, existingValue));

pdfCache.AddOrUpdate(userId, Function(id) GeneratePdfForUser(id), Function(id, existingValue) UpdatePdfForUser(id, existingValue))

• Manages logic for existing key
• Ensures members accessed are safe under concurrency

TryAdd Method: Add If Key Does Not Exist

This method tries to add a value and returns a Boolean value indicating success.

bool added = pdfCache.TryAdd(userId, pdfBytes);
if (!added)
{
    Console.WriteLine("PDF already cached.");
}

bool added = pdfCache.TryAdd(userId, pdfBytes);
if (!added)
{
    Console.WriteLine("PDF already cached.");
}

Dim added As Boolean = pdfCache.TryAdd(userId, pdfBytes)
If Not added Then
	Console.WriteLine("PDF already cached.")
End If

• Perfect for avoiding conflicts
• Method returns true if insert succeeds

Use Case Table: ConcurrentDictionary Methods

Optimizing for Performance

ConcurrentDictionary supports tuning via the constructor:

int concurrencyLevel = 4;
int initialCapacity = 100;
var dictionary = new ConcurrentDictionary<string, byte[]>(concurrencyLevel, initialCapacity);

int concurrencyLevel = 4;
int initialCapacity = 100;
var dictionary = new ConcurrentDictionary<string, byte[]>(concurrencyLevel, initialCapacity);

Dim concurrencyLevel As Integer = 4
Dim initialCapacity As Integer = 100
Dim dictionary = New ConcurrentDictionary(Of String, Byte())(concurrencyLevel, initialCapacity)

• concurrencyLevel: Expected number of threads (default = default concurrency level)
• initialCapacity: Expected number of elements (default initial capacity)

Properly setting these improves throughput and reduces contention across multiple threads.

Preventing Issues with Key Conflicts and Defaults

When a key does not exist, operations like TryGetValue can return the default value for the type:

if (!pdfCache.TryGetValue(userId, out var pdf))
{
    pdf = GeneratePdfForUser(userId); // Second call
}

if (!pdfCache.TryGetValue(userId, out var pdf))
{
    pdf = GeneratePdfForUser(userId); // Second call
}

Dim pdf As var
If Not pdfCache.TryGetValue(userId, pdf) Then
	pdf = GeneratePdfForUser(userId) ' Second call
End If

This safeguards your code against unknown code or null references. Always check for a specific value before assuming presence.

Practical Example: Thread-Safe IronPDF Report Generator

using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using IronPdf;
public class Program
{
    static ConcurrentDictionary<string, byte[]> pdfReports =
        new ConcurrentDictionary<string, byte[]>();
    static void Main(string[] args)
    {
        // Simulated user list with HTML content
        var users = new List<User>
        {
            new User { Id = "user1", HtmlContent = "<h1>Report for User 1</h1>" },
            new User { Id = "user2", HtmlContent = "<h1>Report for User 2</h1>" },
            new User { Id = "user3", HtmlContent = "<h1>Report for User 3</h1>" }
        };
        // Generate PDFs concurrently
        var renderer = new ChromePdfRenderer();
        Parallel.ForEach(users, user =>
        {
            var pdf = pdfReports.GetOrAdd(user.Id, id =>
            {
                var pdfDoc = renderer.RenderHtmlAsPdf(user.HtmlContent);
                return pdfDoc.BinaryData;
            });
            SaveToFile(pdf, $"{user.Id}.pdf");
        });
        Console.WriteLine("PDF generation complete.");
    }
    // Utility method to write PDF binary data to file
    static void SaveToFile(byte[] pdfBytes, string filePath)
    {
        File.WriteAllBytes(filePath, pdfBytes);
        Console.WriteLine($"Saved: {filePath}");
    }
}
// Simple user class with ID and HTML content
public class User
{
    public string Id { get; set; }
    public string HtmlContent { get; set; }
}

using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using IronPdf;
public class Program
{
    static ConcurrentDictionary<string, byte[]> pdfReports =
        new ConcurrentDictionary<string, byte[]>();
    static void Main(string[] args)
    {
        // Simulated user list with HTML content
        var users = new List<User>
        {
            new User { Id = "user1", HtmlContent = "<h1>Report for User 1</h1>" },
            new User { Id = "user2", HtmlContent = "<h1>Report for User 2</h1>" },
            new User { Id = "user3", HtmlContent = "<h1>Report for User 3</h1>" }
        };
        // Generate PDFs concurrently
        var renderer = new ChromePdfRenderer();
        Parallel.ForEach(users, user =>
        {
            var pdf = pdfReports.GetOrAdd(user.Id, id =>
            {
                var pdfDoc = renderer.RenderHtmlAsPdf(user.HtmlContent);
                return pdfDoc.BinaryData;
            });
            SaveToFile(pdf, $"{user.Id}.pdf");
        });
        Console.WriteLine("PDF generation complete.");
    }
    // Utility method to write PDF binary data to file
    static void SaveToFile(byte[] pdfBytes, string filePath)
    {
        File.WriteAllBytes(filePath, pdfBytes);
        Console.WriteLine($"Saved: {filePath}");
    }
}
// Simple user class with ID and HTML content
public class User
{
    public string Id { get; set; }
    public string HtmlContent { get; set; }
}

Imports System
Imports System.Collections.Concurrent
Imports System.Collections.Generic
Imports System.IO
Imports System.Threading.Tasks
Imports IronPdf
Public Class Program
	Private Shared pdfReports As New ConcurrentDictionary(Of String, Byte())()
	Shared Sub Main(ByVal args() As String)
		' Simulated user list with HTML content
		Dim users = New List(Of User) From {
			New User With {
				.Id = "user1",
				.HtmlContent = "<h1>Report for User 1</h1>"
			},
			New User With {
				.Id = "user2",
				.HtmlContent = "<h1>Report for User 2</h1>"
			},
			New User With {
				.Id = "user3",
				.HtmlContent = "<h1>Report for User 3</h1>"
			}
		}
		' Generate PDFs concurrently
		Dim renderer = New ChromePdfRenderer()
		Parallel.ForEach(users, Sub(user)
			Dim pdf = pdfReports.GetOrAdd(user.Id, Function(id)
				Dim pdfDoc = renderer.RenderHtmlAsPdf(user.HtmlContent)
				Return pdfDoc.BinaryData
			End Function)
			SaveToFile(pdf, $"{user.Id}.pdf")
		End Sub)
		Console.WriteLine("PDF generation complete.")
	End Sub
	' Utility method to write PDF binary data to file
	Private Shared Sub SaveToFile(ByVal pdfBytes() As Byte, ByVal filePath As String)
		File.WriteAllBytes(filePath, pdfBytes)
		Console.WriteLine($"Saved: {filePath}")
	End Sub
End Class
' Simple user class with ID and HTML content
Public Class User
	Public Property Id() As String
	Public Property HtmlContent() As String
End Class

Saved Files

Example Output

Code Breakdown

This example demonstrates how to combine ConcurrentDictionary<TKey, TValue> with IronPDF to generate PDFs in a thread-safe way. It’s perfect for apps where multiple threads are processing and caching PDF files simultaneously.

Why ConcurrentDictionary?

• Ensures thread-safe access to key-value pairs.
• GetOrAdd() avoids duplicate PDF generation.

• No manual locks needed—perfect for high concurrency. How It Works

• A list of users each has an ID and HTML.
• Parallel.ForEach spawns threads to generate PDFs.
• Each thread uses GetOrAdd() to either fetch or create the PDF.
• The PDF is saved using the user’s ID as the filename. Summary

This pattern is ideal when:

• You're generating PDFs for many users at once.
• You need performance and thread safety.
• You want clean, reliable concurrency in C#.

Extension Methods and Access Patterns

While ConcurrentDictionary doesn't expose all LINQ features, you can still use extension methods to query values:

var completedKeys = pdfReports.Keys.Where(k => k.StartsWith("done-")).ToList();

var completedKeys = pdfReports.Keys.Where(k => k.StartsWith("done-")).ToList();

Dim completedKeys = pdfReports.Keys.Where(Function(k) k.StartsWith("done-")).ToList()

However, avoid relying on elements copied during iteration as the dictionary may change. Use .ToList() or .ToArray() to work with a snapshot if needed.

Conclusion: Thread Safety Meets PDF Automation

The ConcurrentDictionary<TKey, TValue> is ideal for scenarios where multiple threads need to read/write key value pairs simultaneously—making it a perfect companion for IronPDF in multi-threaded applications.

Whether you’re caching rendered PDFs, tracking job status, or preventing redundant operations, using this thread safe collection ensures your logic scales with performance and reliability.

Try IronPDF Today

Ready to build high-performance PDF applications with full thread safety? Download a free trial of IronPDF and experience seamless PDF generation combined with the power of C#'s ConcurrentDictionary.