---
updatedAt: 2025-05-05T20:57:13.000Z
agentTools:
  projectIndex: https://dossier.teststack.net/llms.txt
---

# Getting Started with Dossier

This page will help you get started with Dossier. You'll be up and running in a jiffy!

## Add NuGet package

The best way to get started with Dossier is to install the package into your test project via NuGet:

> Install-Package TestStack.Dossier

## Building an object, creating a custom test data builder or generating a value?

Are you:

* [Building a DTO, view model, or other class you don't want to write a custom test data builder class for](https://dossier.teststack.net/docs/create-object-without-requiring-custom-builder-cla)?
* [Generating a value](https://dossier.teststack.net/docs/anonymous-values-and-equivalence-classes)?
* Creating a custom test data builder class? Carry on reading...

## Create a custom test data builder class

If you want to build a custom builder class, e.g. for a domain object, you can use the builder as documentation and also to make the experience of building that class in your tests more rich.

Consider the following example of a domain object:

```csharp
public class Customer
{
    protected Customer() {}

    public Customer(string firstName, string lastName, int yearJoined)
    {
        if (string.IsNullOrEmpty(firstName))
            throw new ArgumentNullException("firstName");
        if (string.IsNullOrEmpty(lastName))
            throw new ArgumentNullException("lastName");

        FirstName = firstName;
        LastName = lastName;
        YearJoined = yearJoined;
    }

    public virtual int CustomerForHowManyYears(DateTime since)
    {
        if (since.Year < YearJoined)
            throw new ArgumentException("Date must be on year or after year that customer joined.", "since");
        return since.Year - YearJoined;
    }

    public virtual string FirstName { get; private set; }
    public virtual string LastName { get; private set; }
    public virtual int YearJoined { get; private set; }
}
```

If you decide to create a `CustomerBuilder` custom test data builder class for it then you start by extending Dossier's `TestDataBuilder` class. The first generic parameter is the class that you are writing a builder for (the `Customer` class in this case) and the second generic parameter is the builder class itself (`CustomerBuilder` in this case).

It might be surprising to have this recursive type definition, but it is needed to facilitate fluent method chaining for the base class methods (e.g. [Set](https://dossier.teststack.net/docs/basic-builder-methods)).

```csharp
public class CustomerBuilder : TestDataBuilder<Customer, CustomerBuilder>
{
  public CustomerBuilder()
  {
    // Can set up defaults here - any that you don't set or subsequently override
    //   will have an anonymous value generated by default
    WhoJoinedIn(2013);
  }

  // Note: the methods are virtual - this is important if you want to build lists (as per below)
  public virtual CustomerBuilder WithFirstName(string firstName)
  {
    return Set(x => x.FirstName, firstName);
  }

  // Note: we typically only start with the methods that are strictly needed so the
  //   builders are quick to write and aren't bloated
  public virtual CustomerBuilder WithLastName(string lastName)
  {
    return Set(x => x.LastName, lastName);
  }

  public virtual CustomerBuilder WhoJoinedIn(int yearJoined)
  {
    return Set(x => x.YearJoined, yearJoined);
  }

  // This method is optional, by default it uses `BuildUsing<PublicPropertySettersFactory>()`
  protected override Customer BuildObject()
  {
    return BuildUsing<CallConstructorFactory>();
    // or, if you need more control / can't use the auto-construction assumptions
    return new Customer(
      Get(x => x.FirstName),
      Get(x => x.LastName),
      Get(x => x.YearJoined)
    );
  }
}
```

Note: that overriding the BuildObject method is [optional](https://dossier.teststack.net/docs/build-objects-without-calling-constructor).

## Use the builder in a test

```csharp
var customer = new CustomerBuilder()
	.WithFirstName("Robert")
  .Build();
```

## Where next?

Consider using the [Object Mother pattern](http://martinfowler.com/bliki/ObjectMother.html) in combination with the builders. See [Rob Moore's blog post](https://robdmoore.id.au/blog/2013/05/25/test-data-generation-the-right-way-object-mother-test-data-builders-nsubstitute-nbuilder) for a description of the theory behind this approach.

The usage documentation should get you across the other capabilities of this library. It's probably best to start with [Basic builder methods](https://dossier.teststack.net/docs/basic-builder-methods).