
<Sponsorships>

Are you seeking a more user-friendly Git experience?
Try [**Tower,**](https://www.git-tower.com/windows?utm_source=newsletter&utm_medium=sponsor&utm_campaign=milans-net-weekly)
the most powerful Git client for Windows.
Currently on sale for Black Friday at a 50% discount!
[**Get Tower here.**](https://www.git-tower.com/windows?utm_source=newsletter&utm_medium=sponsor&utm_campaign=milans-net-weekly)

[**Iron Software**](https://buzz.ironsoftware.com/cyber-rally-2023?utm_source=milan&utm_medium=email&utm_campaign=milan)
are hosting a Cyber Rally.
If you buy a Plus (or above) single product license you might walk away with a full Iron Suite at no extra cost.
[**Find out more here.**](https://buzz.ironsoftware.com/cyber-rally-2023?utm_source=milan&utm_medium=email&utm_campaign=milan)

</Sponsorships>

Refactoring is a technique for restructuring existing code without changing its behavior.
You can think of refactoring as a series of small code transformations.

One change (refactoring) does little.
But a sequence of refactors produces a significant transformation.

There's no better way to learn refactoring than practicing.

So I prepared a refactoring exercise for you.

Today I'm going to refactor some poorly written code.

And I'll show you 5 awesome refactoring techniques along the way:

- Extract method
- Extract interface
- Extract class
- Functional code
- Pushing logic down

## Starting Point

We will refactor the `CustomerService` below to try to improve the code.

I want to achieve three goals with this refactor.

Or rather, I want to improve three qualities of the `CustomerService`:

- Testability
- Readability
- Maintainability

To improve these qualities, we need to figure out what's preventing us from attaining them.

So, let's first understand what the `CustomerService` is doing on a high level:

- Validation of the input arguments
- Fetching the `Company` and creating a new `Customer`
- Calculating if the `Customer` has a credit limit and the amount
- Saving the `Customer` to the database if they meet a specific condition

You can see quite a few things are happening inside the `AddCustomer` method.

It's almost 100 lines of code, which reduces readability.

It's difficult to test because we can't control any external dependencies.

It's impossible to extend the behavior of the `CustomerService` without changing the code.

But we can fix all these problems.
Let me show you how.

```csharp
public class CustomerService
{
    public bool AddCustomer(
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        int companyId)
    {
        if (string.IsNullOrEmpty(firstName) || string.IsNullOrEmpty(lastName))
        {
            return false;
        }

        if (!email.Contains('@') && !email.Contains('.'))
        {
            return false;
        }

        var now = DateTime.Now;
        var age = now.Year - dateOfBirth.Year;
        if (dateOfBirth.Date > now.AddYears(-age))
        {
            age -= 1;
        }

        if (age < 21)
        {
            return false;
        }

        var companyRepository = new CompanyRepository();
        var company = companyRepository.GetById(companyId);

        var customer = new Customer
        {
            Company = company,
            DateOfBirth = dateOfBirth,
            EmailAddress = email,
            Firstname = firstName,
            Surname = lastName
        };

        if (company.Type == "VeryImportantClient")
        {
            // Skip credit check
            customer.HasCreditLimit = false;
        }
        else if (company.Type == "ImportantClient")
        {
            // Do credit check and double credit limit
            customer.HasCreditLimit = true;
            using var creditService = new CustomerCreditServiceClient();

            var creditLimit = creditService.GetCreditLimit(
                customer.Firstname,
                customer.Surname,
                customer.DateOfBirth);

            creditLimit *= 2;
            customer.CreditLimit = creditLimit;
        }
        else
        {
            // Do credit check
            customer.HasCreditLimit = true;
            using var creditService = new CustomerCreditServiceClient();

            var creditLimit = creditService.GetCreditLimit(
                customer.Firstname,
                customer.Surname,
                customer.DateOfBirth);

            customer.CreditLimit = creditLimit;
        }

        if (customer.HasCreditLimit && customer.CreditLimit < 500)
        {
            return false;
        }

        var customerRepository = new CustomerRepository();
        customerRepository.AddCustomer(customer);

        return true;
    }
}
```

## Refactoring the Validation

The first part of the code validating input parameters is pretty concise.
It also follows the early return principle.

The validation consists of simple input validation and a calculation for the customer's age.

I would start with an **extract method** refactor to move the validation into one place.

```csharp
if (string.IsNullOrEmpty(firstName) || string.IsNullOrEmpty(lastName))
{
    return false;
}

if (!email.Contains('@') && !email.Contains('.'))
{
    return false;
}

var now = DateTime.Now;
var age = now.Year - dateOfBirth.Year;
if (dateOfBirth.Date > now.AddYears(-age))
{
    age -= 1;
}

if (age < 21)
{
    return false;
}
```

Calculating the age isn't part of the validation flow, so I'll extract that into the `CalculateAge` method.

```csharp
int CalculateAge(DateTime dateOfBirth, DateTime now)
{
    var age = now.Year - dateOfBirth.Year;
    if (dateOfBirth.Date > now.AddYears(-age))
    {
        age -= 1;
    }

    return age;
}
```

Then, I'll create the `IsValid` method to encapsulate all the validation rules.
Instead of writing many `if-else` statements, I can write a single `bool` expression.

I also introduced a `minimumAge` constant to improve readability.

You can see how the `CalculateAge` method helps simplify the validation check.

```csharp
bool IsValid(
    string firstName,
    string lastName,
    string email,
    DateTime dateOfBirth)
{
    const int minimumAge = 21;

    return !string.IsNullOrEmpty(firstName) &&
           !string.IsNullOrEmpty(lastName) &&
           (email.Contains('@') || email.Contains('.')) &&
           CalculateAge(dateOfBirth, DateTime.Now) >= minimumAge;
}
```

This simplifies the validation code in `AddCustomer` to:

```csharp
if (!IsValid(firstName, lastName, email, dateOfBirth))
{
    return false;
}
```

## Refactoring Towards Dependency Injection

The next problem I want to solve is introducing [dependency injection](improving-aspnetcore-dependency-injection-with-scrutor) to the `CustomerService`.

Dependency injection allows us to achieve **Inversion of Control (IoC).**
We depend only on interfaces at compile time and on implementations at run time.

The dependency injection pattern has a few important benefits.

You don't have to know how to initialize or dispose of external dependencies.

It also improves testability since you now depend on interfaces.
Interfaces can be mocked to make unit testing easier.

So let's update the `CustomerService` not to initialize the dependencies directly:

```csharp
var companyRepository = new CompanyRepository();

using var creditService = new CustomerCreditServiceClient();

var customerRepository = new CustomerRepository();
```

Instead, we will inject them as constructor arguments.
You can even use the [C# 12 primary constructor](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/tutorials/primary-constructors) feature.

```csharp {2-4}
public class CustomerService(
    CompanyRepository companyRepository,
    CustomerRepository customerRepository,
    CustomerCreditServiceClient creditService)
{
    // ...
}
```

The next step would be introducing interfaces for these dependencies.
This comes down to an **extract interface** refactor.

## Refactoring the Credit Limit Calculation

The credit limit calculation is the most complicated part of the code.
There are different business rules based on the company type.

I try to notice patterns in the code before refactoring.
So here are a few of my observations.

Multiple `if-else` statements based on the `Type` property make me wonder if I'll need to extend this in the future.
Adding a new rule would mean another `if-else` check.
The [strategy pattern](https://refactoring.guru/design-patterns/strategy) could be an alternative, but a `switch` statement will also work fine.

Another thing that stands out is the **code duplication** in the last two blocks.
This usually means I can do an **extract method** refactoring to reduce code duplication.

```csharp
if (company.Type == "VeryImportantClient")
{
    // Skip credit check
    customer.HasCreditLimit = false;
}
else if (company.Type == "ImportantClient")
{
    // Do credit check and double credit limit
    customer.HasCreditLimit = true;
    using var creditService = new CustomerCreditServiceClient();

    var creditLimit = creditService.GetCreditLimit(
        customer.Firstname,
        customer.Surname,
        customer.DateOfBirth);

    creditLimit *= 2;
    customer.CreditLimit = creditLimit;
}
else
{
    // Do credit check
    customer.HasCreditLimit = true;
    using var creditService = new CustomerCreditServiceClient();

    var creditLimit = creditService.GetCreditLimit(
        customer.Firstname,
        customer.Surname,
        customer.DateOfBirth);

    customer.CreditLimit = creditLimit;
}
```

The first thing I want to do is introduce an `enum` for the `CompanyType`.

This is a [clean coding principle](8-tips-to-write-clean-code) I often use.
It improves the readability and extensibility of the code.

```csharp
public enum CompanyType
{
    Regular = 0,
    ImportantClient = 1,
    VeryImportantClient = 2
}
```

The next thing that bothers me is that the credit limit calculation doesn't belong to the `CustomerService`.
It violates the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle).

So I want to introduce a dedicated `CreditLimitCalculator` using an **extract class** refactoring.
I replaced the `if-else` statements with a [switch expression](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/switch-expression) that I can easily extend in the future.

```csharp
public class CreditLimitCalculator(
    CustomerCreditServiceClient customerCreditServiceClient)
{
    public (bool HasCreditLimit, decimal? CreditLimit) Calculate(
        Customer customer,
        Company company)
    {
        return company.Type switch
        {
            CompanyType.VeryImportantClient => (false, null),
            CompanyType.ImportantClient => (true, GetCreditLimit(customer) * 2),
            _ => (true, GetCreditLimit(customer))
        };
    }

    private decimal GetCreditLimit(Customer customer)
    {
        return customerCreditServiceClient.GetCreditLimit(
            customer.FirstName,
            customer.LastName,
            customer.DateOfBirth);
    }
}
```

## Reviewing the Refactoring (So Far)

Let's pause momentarily and review the refactored version of the `CustomerService`.
I'm confident you will find it more readable and easier to understand.
We can easily test this class and verify that the behavior is correct.

I would usually stop the refactoring at this point, since I'm happy with the results.

But can we take this further?

```csharp
public class CustomerService(
    CompanyRepository companyRepository,
    CustomerRepository customerRepository,
    CreditLimitCalculator creditLimitCalculator)
{
    public bool AddCustomer(
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        int companyId)
    {
        if (!IsValid(firstName, lastName, email, dateOfBirth))
        {
            return false;
        }

        var company = companyRepository.GetById(companyId);

        var customer = new Customer
        {
            Company = company,
            DateOfBirth = dateOfBirth,
            EmailAddress = email,
            FirstName = firstName,
            LastName = lastName
        };

        (customer.HasCreditLimit, customer.CreditLimit) =
            creditLimitCalculator.Calculate(customer, company);

        if (customer is { HasCreditLimit: true, CreditLimit: < 500 })
        {
            return false;
        }

        customerRepository.AddCustomer(customer);

        return true;
    }
}
```

## Taking It Further - Pushing Logic Down

This part is optional, but I want to show you how to simplify the `CustomerService` by pushing logic into the domain.

What if we moved the responsibility of creating a `Customer` into the class?

I often use the **static factory** pattern to implement this.
The caveat is I have to take a dependency on `CreditLimitCalculator`.
I'm trading off domain model purity to get business rules completeness.

I also added the `IsUnderCreditLimit` method to wrap the credit limit check.

```csharp
public class Customer
{
    // Properties omited

    public static Customer Create(
        Company company,
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        CreditLimitCalculator creditLimitCalculator)
    {
        var customer = new Customer
        {
            Company = company,
            DateOfBirth = dateOfBirth,
            EmailAddress = email,
            FirstName = firstName,
            LastName = lastName
        };

        (customer.HasCreditLimit, customer.CreditLimit) =
            creditLimitCalculator.Calculate(customer, company);

        return customer;
    }

    public bool IsUnderCreditLimit() => HasCreditLimit && CreditLimit < 500;
}
```

This is what the `CustomerService` looks like now:

```csharp
public class CustomerService(
    CompanyRepository companyRepository,
    CustomerRepository customerRepository,
    CreditLimitCalculator creditLimitCalculator)
{
    public bool AddCustomer(
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth,
        int companyId)
    {
        if (!IsValid(firstName, lastName, email, dateOfBirth))
        {
            return false;
        }

        var company = companyRepository.GetById(companyId);

        var customer = Customer.Create(
            company,
            firstName,
            lastName,
            email,
            dateOfBirth,
            creditLimitCalculator);

        if (customer.IsUnderCreditLimit())
        {
            return false;
        }

        customerRepository.AddCustomer(customer);

        return true;
    }
}
```

What do you think about this implementation?

## Next Steps

First of all, congrats on making it to the end.
This was a much longer newsletter issue than usual.
What do you think of this format?

Writing unit tests before starting the refactoring would be a great idea.
Unit tests will help detect any changes in behavior.

Remember, refactoring is transforming the existing code without changing the behavior.

Here are a few ideas on how you could further refactor the code:

- [**Strategy pattern**](https://refactoring.guru/design-patterns/strategy) for the credit limit calculation
- [**Result object**](functional-error-handling-in-dotnet-with-the-result-pattern) to represent the method status

If you want to try this refactoring exercise, you can find the complete [**source code here.**](https://github.com/m-jovanovic/refactoring-katas)

Hope this was helpful.

See you next week.

---



<Sponsorships>

[**Telerik UI for Blazor**](https://www.telerik.com/blogs/basic-themes-customization-telerik-ui-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-content-exposure)
makes it easy to tailor your app to your design specifications.
Its wide range of high-quality components, such as Grid, Charts, Forms, and Scheduler, speed up development significantly.
[**Learn more in this post.**](https://www.telerik.com/blogs/basic-themes-customization-telerik-ui-blazor?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=blazor-awareness-hdibt-blazor-content-exposure)

[**ABP Commercial**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w64)
is a complete platform built on ABP Framework for enterprise-grade ASP.NET Core based web applications.
It comes with pre-built application modules, advanced startup templates, and premium support.
[**Check it out here.**](https://commercial.abp.io/pricing?utm_source=milanw&utm_medium=w64)

</Sponsorships>

EF Core is my favorite ORM for .NET applications.
Yet, its many fantastic features sometimes go unnoticed.
For example, [**query splitting**](how-to-improve-performance-with-ef-core-query-splitting),
[**query filters**](how-to-use-global-query-filters-in-ef-core),
and interceptors.

EF interceptors are interesting because you can do powerful things with them.
For example, you can hook into materialization, handle optimistic concurrency errors, or add query hints.

The most practical use case is adding behavior when saving changes to the database.

Today I want to show you three unique use cases for EF Core interceptors:

- Audit logging
- Publishing domain events
- Persisting Outbox messages

## What are EF Interceptors?

[EF Core interceptors](https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/interceptors)
allow you to intercept, change, or suppress EF Core operations.
Every interceptor implements the `IInterceptor` interface.
A few common derived interfaces include `IDbCommandInterceptor`, `IDbConnectionInterceptor`, and `IDbTransactionInterceptor`.

The most popular one is the `ISaveChangesInterceptor`. It allows you to add behavior before or after saving changes.

Interceptors are registered for each `DbContext` instance when configuring the context.

```csharp
public interface IInterceptor
{
}
```

You don't have to implement these interfaces directly.
It's better to use concrete implementations and override the needed methods.

For example, I'll show you how to use the `SaveChangesInterceptor`.

## Audit Logging With EF Interceptors

An audit log of entity changes is a valuable feature in some applications.
You write additional audit information every time an entity is created or modified.
The audit log could also contain the complete before/after values, depending on your requirements.

However, let's use a simple example to make it easy to understand.

I have an `IAuditable` interface with two properties representing when an entity was created or modified.

```csharp
public interface IAuditable
{
    DateTime CreatedOnUtc { get; }

    DateTime? ModifiedOnUtc { get; }
}
```

Next, I'll implement an `UpdateAuditableInterceptor` interceptor to write the audit values.
It uses the `ChangeTracker` to find all `IAuditable` instances and sets the respective property value.

I want to highlight that I'm overriding the `SavingChangesAsync` method here.
`SavingChangesAsync` runs before the changes are saved in the database and any updates applied inside the `UpdateAuditableInterceptor`
are also part of the current database transaction.

This implementation can be easily extended to include the information about the current user.

```csharp
internal sealed class UpdateAuditableInterceptor : SaveChangesInterceptor
{
    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            UpdateAuditableEntities(eventData.Context);
        }

        return base.SavingChangesAsync(eventData, result, cancellationToken);
    }

    private static void UpdateAuditableEntities(DbContext context)
    {
        DateTime utcNow = DateTime.UtcNow;
        var entities = context.ChangeTracker.Entries<IAuditable>().ToList();

        foreach (EntityEntry<IAuditable> entry in entities)
        {
            if (entry.State == EntityState.Added)
            {
                SetCurrentPropertyValue(
                    entry, nameof(IAuditable.CreatedOnUtc), utcNow);
            }

            if (entry.State == EntityState.Modified)
            {
                SetCurrentPropertyValue(
                    entry, nameof(IAuditable.ModifiedOnUtc), utcNow);
            }
        }

        static void SetCurrentPropertyValue(
            EntityEntry entry,
            string propertyName,
            DateTime utcNow) =>
            entry.Property(propertyName).CurrentValue = utcNow;
    }
}
```

## Publish Domain Events With EF Interceptors

Another use case for EF interceptors is [**publishing domain events.**](how-to-use-domain-events-to-build-loosely-coupled-systems)
Domain events are a DDD tactical pattern to create loosely coupled systems.

Domain events allow you to express side effects explicitly and provide a better separation of concerns in the domain.

You can create an `IDomainEvent` interface, which derives from `MediatR.INotification`.
This allows you to use the `IPublisher` to publish domain events and handle them asynchronously.

```csharp
using MediatR;

public interface IDomainEvent : INotification
{
}
```

Then, I'll create a `PublishDomainEventsInterceptor` that also inherits from `SaveChangesInterceptor`.
However, this time, we're using the `SavedChangesAsync` to publish the domain events _after_ saving changes in the database.

This has two important implications:

1. The entire workflow is now eventually consistent. Domain event handlers will save changes to the database after the original transaction.
2. If any domain event handlers fail, we risk failing the request even though the initial transaction was completed successfully.

You can make this process more reliable by using an [**Outbox.**](outbox-pattern-for-reliable-microservices-messaging)

```csharp
internal sealed class PublishDomainEventsInterceptor : SaveChangesInterceptor
{
    private readonly IPublisher _publisher;

    public PublishDomainEventsInterceptor(IPublisher publisher)
    {
        _publisher = publisher;
    }

    public override async ValueTask<int> SavedChangesAsync(
        SaveChangesCompletedEventData eventData,
        int result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            await PublishDomainEventsAsync(eventData.Context);
        }

        return result;
    }

    private async Task PublishDomainEventsAsync(DbContext context)
    {
        var domainEvents = context
            .ChangeTracker
            .Entries<Entity>()
            .Select(entry => entry.Entity)
            .SelectMany(entity =>
            {
                List<IDomainEvent> domainEvents = entity.DomainEvents;

                entity.ClearDomainEvents();

                return domainEvents;
            })
            .ToList();

        foreach (IDomainEvent domainEvent in domainEvents)
        {
            await _publisher.Publish(domainEvent);
        }
    }
}
```

## Store Outbox Messages With EF Interceptors

Instead of [**publishing domain events**](how-to-use-domain-events-to-build-loosely-coupled-systems) as part of the EF transaction, you can convert them to Outbox messages.

Here's an `InsertOutboxMessagesInterceptor` that does precisely this.

It overrides the `SavingChangesAsync` method.
Which means it runs inside the current EF transaction before saving changes.

The `InsertOutboxMessagesInterceptor` converts any domain events into an `OutboxMessage` and adds it to the respective `DbSet<OutboxMessage>`.
This means they will be saved to the database with any existing changes inside the same transaction.

This is an atomic operation.

Either everything succeeds or everything fails.

There's no in-between state like in the `PublishDomainEventsInterceptor`.

You can then create a background worker that will process the Outbox messages.

And this is how you implement the [**Outbox pattern**](outbox-pattern-for-reliable-microservices-messaging) with EF Core.

```csharp
using Newtonsoft.Json;

public sealed class InsertOutboxMessagesInterceptor : SaveChangesInterceptor
{
    private static readonly JsonSerializerSettings Serializer = new()
    {
        TypeNameHandling = TypeNameHandling.All
    };

    public override ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        if (eventData.Context is not null)
        {
            InsertOutboxMessages(eventData.Context);
        }

        return base.SavingChangesAsync(eventData, result, cancellationToken);
    }

    private static void InsertOutboxMessages(DbContext context)
    {
        context
            .ChangeTracker
            .Entries<Entity>()
            .Select(entry => entry.Entity)
            .SelectMany(entity =>
            {
                List<IDomainEvent> domainEvents = entity.DomainEvents;

                entity.ClearDomainEvents();

                return domainEvents;
            })
            .Select(domainEvent => new OutboxMessage
            {
                Id = domainEvent.Id,
                OccurredOnUtc = domainEvent.OccurredOnUtc,
                Type = domainEvent.GetType().Name,
                Content = JsonConvert.SerializeObject(domainEvent, Serializer)
            })
            .ToList();

        context.Set<OutboxMessage>().AddRange(outboxMessages);
    }
}
```

## Configuring EF Interceptors Using Dependency Injection

EF interceptors should be lightweight and stateless.
You can add them to the `DbContext` by calling `AddInterceptors` and passing in the interceptor instances.

I like to configure the interceptors with Dependency Injection for two reasons:

- It allows me also to use DI in the interceptors (be mindful that they are singletons)
- To simplify adding the interceptors to the `DbContext` using `AddDbContext`

Here's how you can configure the `UpdateAuditableInterceptor` and `InsertOutboxMessagesInterceptor` with the `ApplicationDbContext`:

```csharp
services.AddSingleton<UpdateAuditableInterceptor>();
services.AddSingleton<InsertOutboxMessagesInterceptor>();

services.AddDbContext<IApplicationDbContext, ApplicationDbContext>(
    (sp, options) => options
        .UseSqlServer(connectionString)
        .AddInterceptors(
            sp.GetRequiredService<UpdateAuditableInterceptor>(),
            sp.GetRequiredService<InsertOutboxMessagesInterceptor>()));
```

## Closing Thoughts

Interceptors allow you to do almost anything with an EF Core operation.
But with great power comes great responsibility.
You should be mindful that interceptors have an impact on performance.
Calls to external services or handling events will slow down the operation.

Remember, you don't necessarily have to use EF interceptors.
You can achieve the same behavior by overriding the `SaveChangesAsync` method on the `DbContext` and adding your custom logic there.

I showed you a few practical use cases for EF interceptors in this week's issue.

But, if you want to see more examples, I have a few videos about:

- [**Auditing logging**](https://youtu.be/mAlO3OuoQvo)
- [**Publishing domain events**](https://youtu.be/AHzWJ_SMqLo)
- [**Implementing the Outbox pattern**](https://youtu.be/XALvnX7MPeo)

Thanks for reading, and stay awesome!

---



<Sponsorships>

[**Progress**](https://www.telerik.com/campaigns/discover-the-magic-of-dot-net-8-and-beyond-webinar?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=devcraft-webinar-standardization-dot-net-8)
is holding a free webinar: [**Discover the Magic of .NET 8 and Beyond!**](https://www.telerik.com/campaigns/discover-the-magic-of-dot-net-8-and-beyond-webinar?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=devcraft-webinar-standardization-dot-net-8)
Join the webinar and find out all the hot news in .NET 8.
[**Register today for FREE!**](https://www.telerik.com/campaigns/discover-the-magic-of-dot-net-8-and-beyond-webinar?utm_medium=cpm&utm_source=milanjovanovic&utm_campaign=devcraft-webinar-standardization-dot-net-8)

How do you [**choose the right PDF library?**](https://ironpdf.com/blog/case-studies/jeff-fritz-pdf-library-comparison/?utm_source=milan&utm_medium=email&utm_campaign=milan)
Microsoft MVP Jeff Fritz compared the most popular HTML-to-PDF libraries: iTextSharp, Syncfusion, Aspose, and IronPDF.
Take a look at his findings and [**find out which PDF library is the best.**](https://ironpdf.com/blog/case-studies/jeff-fritz-pdf-library-comparison/?utm_source=milan&utm_medium=email&utm_campaign=milan)

</Sponsorships>

Reporting is essential for business applications like e-commerce, shipping, fintech, etc.

One of the most popular document formats for reporting purposes is [PDF.](https://en.wikipedia.org/wiki/PDF)

PDF stands for Portable Document Format.
It's a file format to present documents (including text formatting and images) independently of application software, hardware, and operating systems.

Some common problems .NET developers will face when working with PDF files:

- Creating dynamic PDF documents
- Designing a consistent page layout
- Customizing fonts on printed documents

Today I want to show you a few interesting ways to generate PDF files in .NET.

## Creating PDF Files With QuestPDF

[QuestPDF](https://www.questpdf.com/) is an open-source .NET library for generating PDF documents.
It exposes a fluent API you can use to compose together many simple elements to create complex documents.
Unlike other libraries, it does not rely on HTML-to-PDF conversion.

Let's install the QuestPDF NuGet package:

```powershell
Install-Package QuestPDF
```

Here's how you can generate a simplified invoice with QuestPDF:

```csharp
using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Margin(50);
        page.Size(PageSizes.A4);
        page.PageColor(Colors.White);
        page.DefaultTextStyle(x => x.FontSize(16));

        page.Header()
            .AlignCenter()
            .Text("Invoice #: 2023-77")
            .SemiBold().FontSize(24).FontColor(Colors.Grey.Darken4);

        page.Content()
            .Table(table =>
            {
                table.ColumnsDefinition(columns =>
                {
                    columns.ConstantColumn(20);
                    columns.RelativeColumn();
                    columns.RelativeColumn();
                });

                table.Header(header =>
                {
                    header.Cell().Text("#");
                    header.Cell().Text("Product");
                    header.Cell().AlignRight().Text("Price");
                });

                foreach (var lineItem in lineItems)
                {
                    table.Cell().Text(lineItem.Index.ToString());
                    table.Cell().Text(lineItem.Name);
                    table.Cell().Text($"${lineItem.Price}");
                }
            });
    });
})
.GeneratePdf("invoice.pdf");;
```

What I like about QuestPDF:

- Fluent API
- Easy to use
- Good [documentation](https://www.questpdf.com/introduction.html)

What I don't like about QuestPDF:

- Having to write a lot of code to create documents
- Limited scope of features
- No HTML-to-PDF support

**Licensing**

QuestPDF is free for small companies and development use.
There's also a commercial license for larger companies.
You can check out the licensing details [here.](https://www.questpdf.com/license/)

## HTML to PDF Conversion With IronPDF

The more common approach for generating PDF files is using an HTML template.

My favorite library that supports this is [IronPDF.](https://ironpdf.com/)

IronPDF is a C# PDF library that allows for fast and efficient manipulation of PDF files.
It also has many valuable features, like [exporting to PDF/A format](https://ironpdf.com/how-to/pdfa/)
and [digitally signing PDF documents.](https://ironpdf.com/how-to/signing/)

But what's the idea behind using an HTML template?

First of all, you have more control over formatting the document.
You can use CSS to style the HTML markup, which will be applied when exporting to a PDF document.

An interesting implementation approach is using [ASP.NET Core MVC views](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/overview?view=aspnetcore-7.0)
and the [Razor syntax.](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-7.0)
You can pass an object to the view at runtime to render dynamic HTML content.

I've used this approach with MVC views on a few projects with excellent results.

Let's start by installing the IronPDF NuGet package:

```powershell
Install-Package IronPdf
```

I'm using a strongly typed Razor view to define my markup.
The `InoviceViewModel` class is the model, and it's used to create dynamic content.

```tsx
@model ViewModels.InoviceViewModel

<div>Invoice number: @Model.InvoiceNumber</div>
<div>Invoice date: @Model.InvoiceDate</div>
<br/>
<span>Line items:</span>
<ul>
    @foreach(var lineItem in Model.LineItems)
    {
        <li>@lineItem.Name | @lineItem.Price</li>
    }
</ul>
```

Now, you need to use the IronPDF `ChromePdfRenderer` to convert the HTML to a PDF document.

```csharp
var html = ConvertRazorViewToHtml(invoice);

var renderer = new ChromePdfRenderer();

var pdf = renderer.RenderHtmlAsPdf(html);

pdf.SaveAs($"invoice-{invoice.InvoiceNumber}.pdf");
```

It really is that simple.

**Licensing**

IronPDF is free for development use and has multiple pricing tiers for commercial use that you can check out [here.](https://ironpdf.com/licensing/)

## Merging Multiple PDF Files

Another common requirement I've seen is merging multiple PDF files.
For example, you could implement a feature to merge the monthly receipts for the accounting department.

You can use the `PdfDocument.Merge` method to implement this.
It accepts a `PdfDocument` collection as the argument.
You'll first have to load the PDF documents into memory before merging them.

Here's an example:

```csharp
var pdfs = new List<PdfDocument>();

pdfs.Add(PdfDocument.FromFile("google-invoice.pdf"));
pdfs.Add(PdfDocument.FromFile("google-ads-invoice.pdf"));
pdfs.Add(PdfDocument.FromFile("converkit-invoice.pdf"));

PdfDocument mergedPdfDocument = PdfDocument.Merge(pdfs);

mergedPdfDocument.SaveAs("merged-invoices.pdf");
```

## Exporting PDF Files From an API

It's pretty straightforward to return a PDF file from an API endpoint in ASP.NET Core.

Minimal APIs have the `Results.File` method accepting either a file path, stream, or byte array.
You also need to specify the content type and an optional file name.
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
for PDF files is `application/pdf`.

Here's how you can return a PDF file from a byte array:

```csharp
app.MapGet("newsletter/download", () =>
{
    var renderer = new ChromePdfRenderer();

    var pdf = renderer.RenderHtmlAsPdf("<h1>The .NET Weekly</h1>");

    return Results.File(pdf.BinaryData, "application/pdf", "newsletter.pdf");
});
```

## Takeaway

Choosing which PDF library you will use in .NET is an important consideration to make.
And while pricing is a significant factor, the features you want to use will also dictate your choice.

QuestPDF is an excellent choice if you're looking for a (mostly) free option with rich features.
The library is constantly improved, and new features are being added.
However, it doesn't support HTML-to-PDF conversion and modifying existing documents.

IronPDF is the library I've used most often on commercial projects.
It has fantastic features for working with PDF files, with many customization options.
The HTML-to-PDF conversion works like a charm.

The hardest part is picking the right tool for the job.

So I hope this is helpful.

See you next week.

---


Latest On YouTube

Let's connect