What is NBuilder in .NET used for?

NBuilder is a .NET library that simplifies test data generation, allowing developers to create complex object graphs effortlessly with its fluent interface.

How does NBuilder help in testing in .NET applications?

NBuilder is useful for unit testing, functional testing, and integration testing as it quickly generates objects with default or custom inputs, making it easier to test .NET applications.

Can NBuilder integrate with other .NET libraries?

Yes, NBuilder can seamlessly integrate with popular testing frameworks and libraries, enhancing its capabilities and flexibility in .NET test environments.

How can I install NBuilder in my .NET project?

To install NBuilder, you can use the command `Install-Package NBuilder` in the NuGet Package Manager Console.

Is NBuilder compatible with IronPDF for document generation?

Yes, NBuilder can be used in conjunction with IronPDF to generate PDF documents from HTML content that includes test data objects created by NBuilder.

What is the benefit of using NBuilder's fluent interface?

NBuilder's fluent interface allows developers to effortlessly create and configure object instances, providing a straightforward and readable way to generate test data.

Can NBuilder be used to create lists of objects with default values?

Yes, NBuilder allows for the easy creation of lists of objects with default values, helping populate large datasets for testing purposes quickly.

How does NBuilder facilitate customization of generated objects?

NBuilder allows for customization of generated objects by overriding default properties using methods like `With()`, enabling detailed configuration of object properties.

What kind of data can be generated with NBuilder and the Faker library?

By using NBuilder with the Faker library, you can generate objects with realistic and random data, enhancing the realism of test scenarios.

How does NBuilder enhance testing with Xunit?

NBuilder aids in testing with Xunit by providing easy object creation and initialization, allowing developers to generate test data that can be used in unit tests to verify application functionality.

The C# PDF Library

Explore IronPDF Start Free Trial

HTML to PDF

Online Demo See All Code Examples

using IronPdf;

// Disable local disk access or cross-origin requests
Installation.EnableWebSecurity = true;

// Instantiate Renderer
var renderer = new ChromePdfRenderer();

// Create a PDF from a HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

// Advanced Example with HTML Assets
// Load external html assets: Images, CSS and JavaScript.
// An optional BasePath 'C:\site\assets\' is set as the file location to load assets from
var myAdvancedPdf = renderer.RenderHtmlAsPdf("<img src='icons/iron.png'>", @"C:\site\assets\");
myAdvancedPdf.SaveAs("html-with-assets.pdf");

using IronPdf;

// Disable local disk access or cross-origin requests
Installation.EnableWebSecurity = true;

// Instantiate Renderer
var renderer = new ChromePdfRenderer();

// Create a PDF from a HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

// Advanced Example with HTML Assets
// Load external html assets: Images, CSS and JavaScript.
// An optional BasePath 'C:\site\assets\' is set as the file location to load assets from
var myAdvancedPdf = renderer.RenderHtmlAsPdf("<img src='icons/iron.png'>", @"C:\site\assets\");
myAdvancedPdf.SaveAs("html-with-assets.pdf");

PM >Install-Package IronPdf

Install-Package IronPdf

.NET HELP

NBuilder .NET (How It Works For Developers)

Jacob Mellor

Updated: August 1, 2026

NBuilder is a .NET library simplifying test data generation. Developers can create complex object graphs effortlessly with its fluent interface. It offers flexibility, efficiency, and seamless integration with popular testing frameworks. In this article, we will explore the features of NBuilder, how to install it, and demonstrate its capabilities with practical code examples.

NBuilder .NET (How It Works For Developers): Figure 1 - NBuilder

Features of NBuilder

NBuilder is a C# open source .NET library designed to simplify the creation of objects for testing and mocking purposes. It allows developers to quickly generate objects with default or custom-specified inputs based on different data types.
It is especially useful for unit testing, functional testing, and integration testing.
It is one of the essential packages for testing built-in .NET data types and complex objects.
It is used for random data generation. You can contribute to this open-source project.
With NBuilder, you can effortlessly override default properties and write custom configurations.

Installing NBuilder

To install NBuilder in the NuGet Package Manager Console, use the following command.

PM > Install-Package NBuilder

Install-Package NBuilder

The above command will install NBuilder with all its dependencies.

NBuilder .NET (How It Works For Developers): Figure 2 - Install NBuilder

Usage of NBuilder

NBuilder provides a fluent way for creating objects on the fly. Let's start with a simple example of creating an object.

Here is the Person Model Class source code.

class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public bool IsMarried { get; set; }
}

class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public bool IsMarried { get; set; }
}

Friend Class Person
	Public Property Id() As Integer
	Public Property Name() As String
	Public Property Email() As String
	Public Property IsMarried() As Boolean
End Class

Friend Class Person
	Public Property Id() As Integer
	Public Property Name() As String
	Public Property Email() As String
	Public Property IsMarried() As Boolean
End Class

Example 1: Creating a Person Object with Default Values

// Create a new person object with default values using NBuilder
var person = Builder<Person>
                .CreateNew()
                .Build();
// By default, NBuilder can provide values like 
// Id = 1, Name = Name1, Email = Email1, IsMarried = false

// Create a new person object with default values using NBuilder
var person = Builder<Person>
                .CreateNew()
                .Build();
// By default, NBuilder can provide values like 
// Id = 1, Name = Name1, Email = Email1, IsMarried = false

' Create a new person object with default values using NBuilder
Dim person = Builder(Of Person) .CreateNew().Build()
' By default, NBuilder can provide values like 
' Id = 1, Name = Name1, Email = Email1, IsMarried = false

' Create a new person object with default values using NBuilder
Dim person = Builder(Of Person) .CreateNew().Build()
' By default, NBuilder can provide values like 
' Id = 1, Name = Name1, Email = Email1, IsMarried = false

Sample Image

NBuilder .NET (How It Works For Developers): Figure 3 - Person object with values

Example 2: Creating Objects with a Custom Builder

Here is an example of how to use NBuilder to create and configure a Person object with custom properties:

// Initialize a custom builder for the Person object with specific values
var customPersonBuilder = Builder<Person>.CreateNew()
                .With(p => p.Name = "Tom")
                .With(p => p.Email = "Tom@email.com");
// Build the custom person object with the specified properties
var objTom = customPersonBuilder.Build();

// Initialize a custom builder for the Person object with specific values
var customPersonBuilder = Builder<Person>.CreateNew()
                .With(p => p.Name = "Tom")
                .With(p => p.Email = "Tom@email.com");
// Build the custom person object with the specified properties
var objTom = customPersonBuilder.Build();

' Initialize a custom builder for the Person object with specific values
Dim customPersonBuilder = Builder(Of Person).CreateNew().With(Sub(p) p.Name = "Tom").With(Sub(p) p.Email = "Tom@email.com")
' Build the custom person object with the specified properties
Dim objTom = customPersonBuilder.Build()

' Initialize a custom builder for the Person object with specific values
Dim customPersonBuilder = Builder(Of Person).CreateNew().With(Sub(p) p.Name = "Tom").With(Sub(p) p.Email = "Tom@email.com")
' Build the custom person object with the specified properties
Dim objTom = customPersonBuilder.Build()

The above code creates a new Person object with custom properties. It initializes a customPersonBuilder for a Person object, setting the Name to "Tom" and the Email to "Tom@email.com". Finally, it builds the object and assigns it to objTom.

Example 3: Creating a Person Object List with Default Value

// Create a list of 10 Person objects with default values using NBuilder
var personList = Builder<Person>
                                     .CreateListOfSize(10)
                                     .Build();

// Create a list of 10 Person objects with default values using NBuilder
var personList = Builder<Person>
                                     .CreateListOfSize(10)
                                     .Build();

' Create a list of 10 Person objects with default values using NBuilder
Dim personList = Builder(Of Person) .CreateListOfSize(10).Build()

' Create a list of 10 Person objects with default values using NBuilder
Dim personList = Builder(Of Person) .CreateListOfSize(10).Build()

Sample Image

NBuilder .NET (How It Works For Developers): Figure 4 - Person object list

Here personList has 10 objects with their default values and prints them.

// Creating a list of 10 Person objects with default values
var personList = Builder<Person>
                                            .CreateListOfSize(10)
                                            .Build();

// Print details of each Person object in the list
foreach (var person in personList)
{
    Console.WriteLine($"{person.Id}, {person.Name}, {person.Email}, {person.IsMarried}");
}

// Creating a list of 10 Person objects with default values
var personList = Builder<Person>
                                            .CreateListOfSize(10)
                                            .Build();

// Print details of each Person object in the list
foreach (var person in personList)
{
    Console.WriteLine($"{person.Id}, {person.Name}, {person.Email}, {person.IsMarried}");
}

' Creating a list of 10 Person objects with default values
Dim personList = Builder(Of Person) .CreateListOfSize(10).Build()

' Print details of each Person object in the list
For Each person In personList
	Console.WriteLine($"{person.Id}, {person.Name}, {person.Email}, {person.IsMarried}")
Next person

' Creating a list of 10 Person objects with default values
Dim personList = Builder(Of Person) .CreateListOfSize(10).Build()

' Print details of each Person object in the list
For Each person In personList
	Console.WriteLine($"{person.Id}, {person.Name}, {person.Email}, {person.IsMarried}")
Next person

NBuilder .NET (How It Works For Developers): Figure 5 - Automatically assigning values

Example 4: Customizing Generated Objects

Sometimes you may need to customize objects being created. You can also customize the value of an object by using the With() method.

// Customize properties for all Person objects in the list
var personList = Builder<Person>
                .CreateListOfSize(10)
                .All()
                .With(p => p.Name = "Kim")
                .With(p => p.Email = "abc@email.com")
                .With(p => p.IsMarried = false)
                .Build();

// Customize properties for all Person objects in the list
var personList = Builder<Person>
                .CreateListOfSize(10)
                .All()
                .With(p => p.Name = "Kim")
                .With(p => p.Email = "abc@email.com")
                .With(p => p.IsMarried = false)
                .Build();

' Customize properties for all Person objects in the list
Dim personList = Builder(Of Person) .CreateListOfSize(10).All().With(Sub(p) p.Name = "Kim").With(Sub(p) p.Email = "abc@email.com").With(Sub(p) p.IsMarried = False).Build()

' Customize properties for all Person objects in the list
Dim personList = Builder(Of Person) .CreateListOfSize(10).All().With(Sub(p) p.Name = "Kim").With(Sub(p) p.Email = "abc@email.com").With(Sub(p) p.IsMarried = False).Build()

This creates a personList with each object having its default value overridden to Name = "Kim", Email = "abc@email.com", and IsMarried = false.

Example 5: Creating a Person Object List with Realistic Random Data

In order to get realistic data values in the Person List, you can use the Faker Library .NET to generate realistic data.

// Creating a list of Person objects with random yet realistic values using Faker
var personList = Builder<Person>
                .CreateListOfSize(10)
                .All()
                .With(p => p.Name = Faker.Name.FullName())
                .With(p => p.Id = Faker.RandomNumber.Next(20, 60))
                .Build();

// Creating a list of Person objects with random yet realistic values using Faker
var personList = Builder<Person>
                .CreateListOfSize(10)
                .All()
                .With(p => p.Name = Faker.Name.FullName())
                .With(p => p.Id = Faker.RandomNumber.Next(20, 60))
                .Build();

' Creating a list of Person objects with random yet realistic values using Faker
Dim personList = Builder(Of Person) .CreateListOfSize(10).All().With(Sub(p) p.Name = Faker.Name.FullName()).With(Sub(p) p.Id = Faker.RandomNumber.Next(20, 60)).Build()

' Creating a list of Person objects with random yet realistic values using Faker
Dim personList = Builder(Of Person) .CreateListOfSize(10).All().With(Sub(p) p.Name = Faker.Name.FullName()).With(Sub(p) p.Id = Faker.RandomNumber.Next(20, 60)).Build()

Example 6: Creating a Person Object List with Sequential Data

There are times when you might need to generate objects with sequential data. NBuilder .NET facilitates this using the Do method.

// Creating a list of 10 sequential Person objects using NBuilder
var personList = Builder<Person>.CreateListOfSize(10)
                .All()
                .Do((p, i) => p.Id = 501 + i)
                .Do((p, i) => p.Name = $"Person {i + 1}")
                .Build();

// Creating a list of 10 sequential Person objects using NBuilder
var personList = Builder<Person>.CreateListOfSize(10)
                .All()
                .Do((p, i) => p.Id = 501 + i)
                .Do((p, i) => p.Name = $"Person {i + 1}")
                .Build();

' Creating a list of 10 sequential Person objects using NBuilder
Dim personList = Builder(Of Person).CreateListOfSize(10).All().Do(Sub(p, i) p.Id = 501 + i).Do(Sub(p, i) p.Name = $"Person {i + 1}").Build()

' Creating a list of 10 sequential Person objects using NBuilder
Dim personList = Builder(Of Person).CreateListOfSize(10).All().Do(Sub(p, i) p.Id = 501 + i).Do(Sub(p, i) p.Name = $"Person {i + 1}").Build()

Here, the All() method ensures the subsequent operations apply to all 10 person objects created in memory. The Do() method executes the Action delegate on each Person object. This setup assigns the Id property sequentially starting from 501, and similarly, names each person sequentially as "Person 1" to "Person 10".

NBuilder .NET (How It Works For Developers): Figure 6 - Sequential Data

Example 7: NBuilder with Unit Testing using Xunit

NBuilder in .NET is significantly used in testing environments, where developers need to generate a realistic and diverse set of data for testing. It makes testing easy and maintainable with complex objects that allow developers to define custom initialization logic using lambda expressions and delegate functions catering to those interested in efficient and flexible test data generation.

Model Class and Service for Unit Testing

class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public bool IsMarried { get; set; }
}

class PersonService
{
    public string GetPersonEmail(Person person)
    {
        return person.Email;
    }
}

class Person
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public bool IsMarried { get; set; }
}

class PersonService
{
    public string GetPersonEmail(Person person)
    {
        return person.Email;
    }
}

Friend Class Person
	Public Property Id() As Integer
	Public Property Name() As String
	Public Property Email() As String
	Public Property IsMarried() As Boolean
End Class

Friend Class PersonService
	Public Function GetPersonEmail(ByVal person As Person) As String
		Return person.Email
	End Function
End Class

Friend Class Person
	Public Property Id() As Integer
	Public Property Name() As String
	Public Property Email() As String
	Public Property IsMarried() As Boolean
End Class

Friend Class PersonService
	Public Function GetPersonEmail(ByVal person As Person) As String
		Return person.Email
	End Function
End Class

Here, the Person class has several properties such as Id, Name, Email, and IsMarried, while PersonService contains a method GetPersonEmail() that returns the email of a given Person.

Test Classes and Test data

using Xunit;

public class PersonTests
{
     [Fact]
     public void GetPersonEmail_ReturnCorrectEmail()
     {
         // Arrange
         var service = new PersonService();
         string expectedEmail = "Tom@email.com";
         
         // Create a person with specific name and email using NBuilder
         var person = Builder<Person>.CreateNew()
             .With(p => p.Name = "Tom")
             .With(p => p.Email = "Tom@email.com")
             .Build();
         
         // Act
         var actualEmail = service.GetPersonEmail(person);
         
         // Assert
         Assert.Equal(expectedEmail, actualEmail);
     }
}

using Xunit;

public class PersonTests
{
     [Fact]
     public void GetPersonEmail_ReturnCorrectEmail()
     {
         // Arrange
         var service = new PersonService();
         string expectedEmail = "Tom@email.com";
         
         // Create a person with specific name and email using NBuilder
         var person = Builder<Person>.CreateNew()
             .With(p => p.Name = "Tom")
             .With(p => p.Email = "Tom@email.com")
             .Build();
         
         // Act
         var actualEmail = service.GetPersonEmail(person);
         
         // Assert
         Assert.Equal(expectedEmail, actualEmail);
     }
}

Imports Xunit

Public Class PersonTests
    <Fact>
    Public Sub GetPersonEmail_ReturnCorrectEmail()
        ' Arrange
        Dim service = New PersonService()
        Dim expectedEmail As String = "Tom@email.com"

        ' Create a person with specific name and email using NBuilder
        Dim person = Builder(Of Person).CreateNew() _
            .With(Function(p) p.Name = "Tom") _
            .With(Function(p) p.Email = "Tom@email.com") _
            .Build()

        ' Act
        Dim actualEmail = service.GetPersonEmail(person)

        ' Assert
        Assert.Equal(expectedEmail, actualEmail)
    End Sub
End Class

Imports Xunit

Public Class PersonTests
    <Fact>
    Public Sub GetPersonEmail_ReturnCorrectEmail()
        ' Arrange
        Dim service = New PersonService()
        Dim expectedEmail As String = "Tom@email.com"

        ' Create a person with specific name and email using NBuilder
        Dim person = Builder(Of Person).CreateNew() _
            .With(Function(p) p.Name = "Tom") _
            .With(Function(p) p.Email = "Tom@email.com") _
            .Build()

        ' Act
        Dim actualEmail = service.GetPersonEmail(person)

        ' Assert
        Assert.Equal(expectedEmail, actualEmail)
    End Sub
End Class

This unit test verifies that the GetPersonEmail method of the PersonService class correctly returns the email address of a Person object with the expected email "Tom@email.com". It uses the Arrange-Act-Assert pattern to set up the test data, execute the method, and then check that the actual result matches the expected result.

Integrating NBuilder with IronPDF

Learn About IronPDF is a powerful C# library designed for creating PDFs from HTML within .NET applications. With its intuitive API, developers can seamlessly integrate PDF functionality into their projects, whether they're generating invoices, reports, or interactive forms.

NBuilder .NET (How It Works For Developers): Figure 7 - IronPDF

Installing IronPDF

Open the NuGet Package Manager console, and run the following command:

PM > Install-Package IronPdf

Install-Package IronPdf

Populate the list of 5 Person objects

// Generating instances of the Person class with NBuilder
var people = Builder<Person>.CreateListOfSize(5).Build();

// Generating instances of the Person class with NBuilder
var people = Builder<Person>.CreateListOfSize(5).Build();

' Generating instances of the Person class with NBuilder
Dim people = Builder(Of Person).CreateListOfSize(5).Build()

' Generating instances of the Person class with NBuilder
Dim people = Builder(Of Person).CreateListOfSize(5).Build()

Creating PDF Document using IronPDF

This code sets the IronPDF license key and generates HTML content from a list of Person objects.

// Setting the IronPDF license key
IronPdf.License.LicenseKey = "Your-License-Key";

// Building HTML content from Person object list
var htmlContent = "<h1>Person List</h1>";
foreach (var person in people)
{
    htmlContent += $"<p>Id: {person.Id}, Name: {person.Name}, Email: {person.Email}, IsMarried: {person.IsMarried}</p>";
}

// Setting the IronPDF license key
IronPdf.License.LicenseKey = "Your-License-Key";

// Building HTML content from Person object list
var htmlContent = "<h1>Person List</h1>";
foreach (var person in people)
{
    htmlContent += $"<p>Id: {person.Id}, Name: {person.Name}, Email: {person.Email}, IsMarried: {person.IsMarried}</p>";
}

' Setting the IronPDF license key
IronPdf.License.LicenseKey = "Your-License-Key"

' Building HTML content from Person object list
Dim htmlContent = "<h1>Person List</h1>"
For Each person In people
	htmlContent &= $"<p>Id: {person.Id}, Name: {person.Name}, Email: {person.Email}, IsMarried: {person.IsMarried}</p>"
Next person

' Setting the IronPDF license key
IronPdf.License.LicenseKey = "Your-License-Key"

' Building HTML content from Person object list
Dim htmlContent = "<h1>Person List</h1>"
For Each person In people
	htmlContent &= $"<p>Id: {person.Id}, Name: {person.Name}, Email: {person.Email}, IsMarried: {person.IsMarried}</p>"
Next person

The IronPdf.License.LicenseKey is set with a specific license key to enable the features of IronPDF. HTML content is dynamically constructed by iterating over the people list, appending each Person object's details (Id, Name, Email, IsMarried) into the HTML structure.

Rendering the Person List in PDF Document Using IronPDF

This code converts HTML content to a PDF document using IronPDF's ChromePdfRenderer.

// Rendering HTML content into a PDF document using IronPDF
var renderer = new ChromePdfRenderer();
var pdfDoc = renderer.RenderHtmlAsPdf(htmlContent);
pdfDoc.SaveAs("PersonList.pdf");

// Rendering HTML content into a PDF document using IronPDF
var renderer = new ChromePdfRenderer();
var pdfDoc = renderer.RenderHtmlAsPdf(htmlContent);
pdfDoc.SaveAs("PersonList.pdf");

' Rendering HTML content into a PDF document using IronPDF
Dim renderer = New ChromePdfRenderer()
Dim pdfDoc = renderer.RenderHtmlAsPdf(htmlContent)
pdfDoc.SaveAs("PersonList.pdf")

' Rendering HTML content into a PDF document using IronPDF
Dim renderer = New ChromePdfRenderer()
Dim pdfDoc = renderer.RenderHtmlAsPdf(htmlContent)
pdfDoc.SaveAs("PersonList.pdf")

ChromePdfRenderer is instantiated to render the HTML content stored in htmlContent into a PDF document. The resulting PDF document is saved to the file system with the name "PersonList.pdf".

Output

Below is the output of the PersonList generated by IronPDF. It contains five persons, each with default values.

NBuilder .NET (How It Works For Developers): Figure 8 - PDF Output

Conclusion

In conclusion, NBuilder is a robust and flexible tool for generating test data in .NET, streamlining the creation of complex object graphs, and enhancing the efficiency of testing processes. By integrating with IronPDF, developers can easily extend their applications to include PDF generation capabilities for those who find it valuable for their projects. Together, NBuilder and IronPDF can significantly enhance development workflows, making testing and document generation seamless and efficient.

Jacob Mellor

Chat with engineering team now

Chief Technology Officer

Jacob Mellor is Chief Technology Officer at Iron Software and a visionary engineer pioneering C# PDF technology. As the original developer behind Iron Software's core codebase, he has shaped the company's product architecture since its inception, transforming it alongside CEO Cameron Rimington into a 50+ person company serving NASA, Tesla, and global government agencies.

...