Generating Sample Data with Bogus
Tags: csharp, dotnet
Published: 2023-02-05 23:36:12

---
title: Generating Sample Data with Bogus
published: true
date: 2023-01-29 00:00:00 UTC
tags: 
  - csharp
  - dotnet
canonical_url: https://wildermuth.com/2023/01/29/generating-sample-data-with-bogus/
cover_image: "https://wilderminds.blob.core.windows.net/img/2023/01/29/cover.jpg"
---

Most of my job these days is creating tutorials or examples. This means I often start from scratch with a new type of project. I usually just cruft up some sample data for my project to start. While investigating some alternatives to Automapper (video and blog coming soon), I wanted to be able to create a bunch of sample data. I, luckily, ran into a tool that I was surprised I’d never heard of: Bogus. Let’s talk about it.

I also made a Coding Short video that covers this same topic, if you’d rather watch than read:

<iframe src="https://www.youtube.com/embed/14NGiQTioas" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen=""></iframe>

## What is Bogus?

Bogus is a library that works with C#, F# and [VB.NET](http://vb.net/) that can be used to create repeatable, fake data for applications. It is somewhat a port of a similar library Bogus.js. It accompished this by creating generators (called Fakers) that have a set of rules for generating one or more fake objects. Built-into Bogus is a set of generalized rules for common data categories (i.e. Addresses, Companies, People, Phone Numbers, etc.). Enough talk, let’s see how it works. The full repo is at:

> [Bogus](https://github.com/bchavez/Bogus)

To install Bogus, you can use the Package Manager or just the dotnet CLI:

```
> dotnet add package Bogus

```

## Creating a Faker

You start out by creating an instance of a class called `Faker<T>`. From that class you would use a fluent syntax to set up rules on creating sample data. But let’s start with our POCO for a `Customer`:

```
public class Customer
{
  public int Id { get; set; }
  public string? CompanyName { get; set; }
  public string? Phone { get; set; }
  public string? ContactName { get; set; }
  public int AddressId { get; set; }
  public Address? Address { get;set;}
  public IEnumerable<Order>? Orders {get;set;}
}

```

You can notice that aside from simple properties, we have a one-to-one relationship to an `Address` and a one-to-many relationship with `Orders`. Let’s start by creating a faker for the `Customer` object and the simple properties:

```
var customerFaker = new Faker<Customer>();

```

We can then use the `RuleFor` method to specify a rule for the Company Name:

```
var customerFaker = new Faker<Customer>()
  .RuleFor(c => c.CompanyName, f => f.Company.CompanyName())

```

The first parameter of the `RuleFor` method is a lambda to pick the property on `Customer` that I want to fake. The second parameter is another lambda to pass in how to generate the property. While we could write any code we need here, the most-common case is to use the `Faker` object passed to use the built-in semantics. In this case we are using the Company category to generate a company name.

If we continue this, we can fake more simple properties like so:

```
var customerFaker = new Faker<Customer>()
  .RuleFor(c => c.CompanyName, f => f.Company.CompanyName())
  .RuleFor(c => c.ContactName, f => f.Name.FullName())
  .RuleFor(c => c.Phone, f => f.Phone.PhoneNumberFormat());

```

You can see here that we’re using the Name category and the Phone category. The Bogus library has a large set of these built-in semantics. Sometimes we’ll need to use custom code to generate data we need. For example, we’ll want to generate IDs for the generated customers. One strategy is to just create a local integer and assign it with simple code:

```
var id = 1;

var customerFaker = new Faker<Customer>()
  .RuleFor(c => c.Id, _ => id++)
  .RuleFor(c => c.CompanyName, f => f.Company.CompanyName())
  .RuleFor(c => c.ContactName, f => f.Name.FullName())
  .RuleFor(c => c.Phone, f => f.Phone.PhoneNumberFormat());

```

Here we can see that we just have an integer (which will become a closure to the rule) and we just increment it everytime a new customer is created.

To use the Faker, we can just call `Generate()` with how many you want:

```
var customers = customerFaker.Generate(1000);

```

This will create a thousand fake customers.

## Repeatable Fake Data

By default, the generation of customers is random. So that everytime you create an instance of the Faker object (e.g. `new Faker<Customer>`), you would get different customers. When you want a consistent set of fake data, you can use a seeder to ensure that you get the same data every time. To do this, you just need to set a seed value to the same number:

```
public class CustomerFaker : Faker<Customer>
{
	public CustomerFaker()
  {
    var id = 1;

    UseSeed(1969) // Use any number
      .RuleFor(c => c.Id, _ => id++)
      .RuleFor(c => c.CompanyName, f => f.Company.CompanyName())
      .RuleFor(c => c.ContactName, f => f.Name.FullName())
      .RuleFor(c => c.Phone, f => f.Phone.PhoneNumberFormat());
  }
}

var customers = new CustomerFaker().Generate(1000);

```

When you do this, you can guarantee to get the same customers. But this affects the entire instance of the faker. This is because every call to `Generate` will generate the **next** set of faked data. For example:

```
var customerFaker = new CustomerFaker();

var customers = customerFaker.Generate(1);
var companyName = customers.First().CompanyName;

var newCustomers = customerFaker.Generate(1);

Assert.IsTrue(companyName == newCustomers.First().CompanyName); // FAILS

```

This is because the seed is the repeatable data is per-instance. So that the the first call to `Generate` will give you the first repeatable object; and the second call to `Generate` gives you the second object.

But if you create a new instance, the names will be guaranteed:

```
var customerFaker = new CustomerFaker();

var customers = customerFaker.Generate(1);
var companyName = customers.First().CompanyName;

var newFaker = new CustomerFaker();
var newCustomers = newFaker.Generate(1);

Assert.IsTrue(companyName == newCustomers.First().CompanyName); // TRUE

```

This support the idea of repeatable sample data!

## Creating Related Sample Data

In our `Customer` class, we have a property for an `Address`. We can create a Faker for the `Address` too:

```
public class AddressFaker : Faker<Address>
{
  public AddressFaker()
  {
    var id = 0;
    UseSeed(1969)
      .RuleFor(c => c.Id, f => ++id)
      .RuleFor(c => c.Address1, f => f.Address.StreetAddress())
      .RuleFor(c => c.Address2, f => f.Address.SecondaryAddress())
      .RuleFor(c => c.City, f => f.Address.City())
      .RuleFor(c => c.StateProvince, f => f.Address.State())
      .RuleFor(c => c.PostalCode, f => f.Address.ZipCode());
  }
}

```

Again, there is a category for the type of data we need and can decide how to generate sample addresses. One thing you might want is to optionally not create certain parts of the fake data. For example, for our addresses, I want some of the `Address2` properties to be null to replicate some apartment/suite numbers and addresses that do not have them. To do this, you can use `OrNull()` method:

```
.RuleFor(c => c.Address2, f => f.Address.SecondaryAddress()
                                        .OrNull(f, .5f))

```

The `OrNull` method takes the faker object and a value between 0 and 1 to determine how often to generate a `null` value. In this example, we’re specifying that we want half (or 50%) of the Addresses to have a null for it’s secondary address.

Now that we have a faker that does what we want, let’s use it to generate addresses too!

```
public class CustomerFaker : Faker<Customer>
{
  AddressFaker _addrFaker = new AddressFaker();

	public CustomerFaker()
  {
    var id = 1;

    UseSeed(1969) // Use any number
      .RuleFor(c => c.Id, _ => id++)
      .RuleFor(c => c.CompanyName, f => f.Company.CompanyName())
      .RuleFor(c => c.ContactName, f => f.Name.FullName())
      .RuleFor(c => c.Phone, f => f.Phone.PhoneNumberFormat())
      .RuleFor(c => c.Address, _ => _addrFaker.Generate(1)
                                              .First()
                                              .OrNull(_, .1f));
  }
}

```

You can notice that we’re creating an instance of the `AddressFaker` and then using it when we specify the rule for the `Customer`’s `Address` property. We can even use `OrNull` to only generate Addresses for 90% of the customers.

There is a lot more to the Bogus library, but hopefully this will get you started. To get the example code from the video and this blog post, see the Github Repo:

> [FixingIt Code](https://github.com/shawnwildermuth/codingshorts/tree/main/bogus)

[![Creative Commons License](http://i.creativecommons.org/l/by-nc-nd/3.0/88x31.png)](http://creativecommons.org/licenses/by-nc-nd/3.0/)

 This work by [Shawn Wildermuth](http://wildermuth.com) is licensed under a [Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License](http://creativecommons.org/licenses/by-nc-nd/3.0/).  
 Based on a work at [wildermuth.com](http://wildermuth.com).

* * *

If you liked this article, see Shawn's courses on [Pluralsight](http://shawnw.me/pscourses).