C# Discriminated Unions (How it Works for Developers)

What Are Discriminated Unions in C#?

Discriminated unions, also known as tagged unions or union types, allow a variable to hold one value from a limited set of possible options, where each option is associated with a unique case identifier.

In other languages like F#, you might define them using the union keyword. C# doesn’t provide this feature natively, but developers can use clever combinations of records, classes, and switch expressions to mimic them.

For example:

public abstract record PdfAction;
public record GenerateReport(string ReportName) : PdfAction;
public record LogError(string Message) : PdfAction;
public record ExportToExcel(string FilePath) : PdfAction;

public abstract record PdfAction;
public record GenerateReport(string ReportName) : PdfAction;
public record LogError(string Message) : PdfAction;
public record ExportToExcel(string FilePath) : PdfAction;

Each record above represents a single case of the union. The base PdfAction type is the discriminant.

Why Discriminated Unions Matter in IronPDF Workflows

Imagine you're building a PDF report generator using IronPDF, and you need to perform different actions based on a user’s input—maybe generating a PDF, logging an error, or exporting data.

Using discriminated unions in C# lets you represent these option types cleanly, leading to compile time safety, fewer bugs, and clearer logic.

Here’s how you might use it with IronPDF:

void HandlePdfAction(PdfAction action)
{
    switch (action)
    {
        case GenerateReport r:
            var pdf = new IronPdf.HtmlToPdf().RenderHtmlAsPdf("<h1>" + r.ReportName + "</h1>");
            pdf.SaveAs(r.ReportName + ".pdf");
            break;
        case LogError e:
            Console.WriteLine("Logging Error: " + e.Message);
            break;
        case ExportToExcel x:
            Console.WriteLine("Exporting to Excel at " + x.FilePath);
            break;
        default:
            throw new NotSupportedException("Unknown action");
    }
}

void HandlePdfAction(PdfAction action)
{
    switch (action)
    {
        case GenerateReport r:
            var pdf = new IronPdf.HtmlToPdf().RenderHtmlAsPdf("<h1>" + r.ReportName + "</h1>");
            pdf.SaveAs(r.ReportName + ".pdf");
            break;
        case LogError e:
            Console.WriteLine("Logging Error: " + e.Message);
            break;
        case ExportToExcel x:
            Console.WriteLine("Exporting to Excel at " + x.FilePath);
            break;
        default:
            throw new NotSupportedException("Unknown action");
    }
}

This approach keeps your code organized and robust, and makes it easier for developers to understand all possible options in a single location.

Simulating Discriminated Unions in C# – Struct vs. Record vs. Class

Although C# lacks the union keyword, you can simulate discriminated unions using:

• Records: Ideal for immutable data, and supports pattern matching cleanly.
• Classes: More flexible with inheritance and reference semantics.
• Structs: Useful for value types, but less flexible when dealing with reference types or inheritance.

If performance and memory layout are important—for example, in high-throughput PDF logging—you might consider using struct discriminated unions carefully:

public interface IAction { }
public readonly struct SaveAction : IAction
{
    public string FileName { get; }
    public SaveAction(string fileName) => FileName = fileName;
}

public interface IAction { }
public readonly struct SaveAction : IAction
{
    public string FileName { get; }
    public SaveAction(string fileName) => FileName = fileName;
}

Note: You’ll lose some pattern matching benefits with structs, especially when relying on switch expressions.

Benefits of Using Discriminated Unions in C#

There are several key advantages to adopting this software engineering pattern:

• Compile-time safety: You’ll catch missing cases in a switch expression before runtime.
• Clearer logic: It’s easier to write, comment, and reason about actions with named cases.
• Separation of concerns: You decouple behaviors based on data rather than type hierarchies.
• Refactoring ease: Adding or removing cases becomes more straightforward.

When paired with IronPDF, this makes it easier to manage user input, rendering logic, or create dynamic templates with different value pipelines.

When to Use Discriminated Unions with IronPDF

Here are some practical scenarios where this pattern excels:

• PDF Generation Workflows: Different steps in a document lifecycle (generate, save, email).
• Permission Models: Represent different user access levels.
• Logging Systems: Use discriminated union types for log levels (info, error, debug).
• Unit Tests: Define test actions as union types for maintainable logic trees.
• Export Options: Represent output targets like PDF, Excel, Word as union instances.

Example – Handling PDF Actions from UI Events

Let’s say you're capturing UI events and want to route them to IronPDF tasks using discriminated unions:

public abstract record UserAction;
public record GeneratePdf(string HtmlContent, string FileName) : UserAction;
public record ShowMessage(string Text) : UserAction;
public record ExitApplication() : UserAction;
void OnUserEvent(UserAction action)
{
    switch (action)
    {
        case GeneratePdf pdf:
            var renderer = new IronPdf.HtmlToPdf();
            var document = renderer.RenderHtmlAsPdf(pdf.HtmlContent);
            document.SaveAs(pdf.FileName);
            break;
        case ShowMessage msg:
            MessageBox.Show(msg.Text);
            break;
        case ExitApplication:
            Application.Exit();
            break;
    }
}

public abstract record UserAction;
public record GeneratePdf(string HtmlContent, string FileName) : UserAction;
public record ShowMessage(string Text) : UserAction;
public record ExitApplication() : UserAction;
void OnUserEvent(UserAction action)
{
    switch (action)
    {
        case GeneratePdf pdf:
            var renderer = new IronPdf.HtmlToPdf();
            var document = renderer.RenderHtmlAsPdf(pdf.HtmlContent);
            document.SaveAs(pdf.FileName);
            break;
        case ShowMessage msg:
            MessageBox.Show(msg.Text);
            break;
        case ExitApplication:
            Application.Exit();
            break;
    }
}

This lets you represent events with clear logic and reduces reliance on public object types or overly dynamic handling.

Future Outlook – Will C# Ever Support Native Discriminated Unions?

There’s already been a proposal to add native support for discriminated unions in C#, especially with growing demand for more expressive type systems. While the language hasn’t yet introduced a true union keyword, C# continues to evolve—bringing features like records, pattern matching, and switch expressions closer to full discriminated union functionality.

.NET developers interested in modern, functional-friendly language constructs will want to watch this space closely.

Final Thoughts

Using discriminated unions in C#, even without native support, can significantly improve how you structure and represent logic in IronPDF applications. By leveraging records, switch expressions, and base classes, you’ll make your codebase more readable, maintainable, and resilient to errors—while also unlocking a more declarative and expressive way to handle PDF-related tasks.

If you're a software engineer building modern, flexible .NET applications, this pattern is a must-have in your toolkit.