EntityFramework.Exceptions

Handle database errors easily when working with Entity Framework Core and ADO.NET. Supports SQLServer, PostgreSQL, SQLite, Oracle and MySql

Entity Framework Community Standup Live Show

OSS Power-Ups: EntityFramework.Exceptions

Nick Chapsas - The Smart Way to Handle EF Core Exceptions

Sponsors

A huge thanks to everyone (individuals or organisations) who have sponsored EntityFramework.Exceptions, but a massive thanks in particular to

• Entity Framework Extensions and Dapper Plus are major sponsors and are proud to contribute to the development of EntityFramework.Exceptions
• JetBrains is sponsoring the EntityFramework.Exceptions project as part of their OSS Power-Ups series

What does EntityFramework.Exceptions do?

When using Entity Framework Core for data access all database exceptions are wrapped in DbUpdateException. If you need to find whether the exception was caused by a unique constraint, value being too long or value missing for a required column you need to dig into the concrete DbException subclass instance and check the error code to determine the exact cause.

EntityFramework.Exceptions simplifies this by handling all the database specific details and throwing different exceptions. All you have to do is to configure DbContext by calling UseExceptionProcessor and handle the exception(s) you need, such as UniqueConstraintException, CannotInsertNullException, MaxLengthExceededException, NumericOverflowException, ReferenceConstraintException, or DeadlockException.

In case of UniqueConstraintException and ReferenceConstraintException you can get the name of the associated constraint with ConstraintName property. The ConstraintProperties will contain the properties that are part of the constraint.

[!WARNING] ConstraintName and ConstraintProperties will be populated only if the index is defined in the Entity Framework Model. These properties will not be populated if the index exists in the database but isn't part of the model or if the index is added with MigrationBuilder.Sql method.

[!WARNING] ConstraintName and ConstraintProperties will not be populated when using SQLite.

All these exceptions inherit from DbUpdateException for backwards compatibility.

How do I get started?

First, install the package corresponding to your database:

dotnet add package EntityFrameworkCore.Exceptions.SqlServer

dotnet add package EntityFrameworkCore.Exceptions.MySql

dotnet add package EntityFrameworkCore.Exceptions.MySql.Pomelo

dotnet add package EntityFrameworkCore.Exceptions.PostgreSQL

dotnet add package EntityFrameworkCore.Exceptions.Sqlite

dotnet add package EntityFrameworkCore.Exceptions.Oracle

Next, in your DbContext OnConfiguring method call UseExceptionProcessor extension method:

class DemoContext : DbContext
{
    public DbSet<Product> Products { get; set; }
    public DbSet<ProductSale> ProductSale { get; set; }

    protected override void OnModelCreating(ModelBuilder builder)
    {
        builder.Entity<Product>().HasIndex(u => u.Name).IsUnique();
    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseExceptionProcessor();
    }
}

You will now start getting different exception for different database error. For example, when a unique constraints fails you will get UniqueConstraintException exception:

using (var demoContext = new DemoContext())
{
    demoContext.Products.Add(new Product
    {
        Name = "demo",
        Price = 10
    });

    demoContext.Products.Add(new Product
    {
        Name = "demo",
        Price = 100
    });

    try
    {
        demoContext.SaveChanges();
    }
    catch (UniqueConstraintException e)
    {
        //Handle exception here
        Console.WriteLine($"Unique constraint {e.ConstraintName} violated. Duplicate value for {e.ConstraintProperties[0]}");
    }
}

[!TIP] If you want to use another native SQLite binary instead of e_sqlite3.dll use the EntityFrameworkCore.Exceptions.Sqlite.Core package. This package depends on Microsoft.Data.Sqlite.Core package, which doesn't include SQLite native binary so you can use any native binary you want.

Usage with DbContext pooling

Instead of calling UseExceptionProcessor in the OnConfiguring method, add it where you add your DbContextPool:

// Replace UseNpgsql with the sql flavor you're using
builder.Services.AddDbContextPool<DemoContext>(options => options
    .UseNpgsql(config.GetConnectionString("DemoConnection"))
    .UseExceptionProcessor());

DbExceptionClassifier

If you don't use Entity Framework Core, you can use the DbExceptionClassifier packages to classify ADO.NET database exceptions directly. They provide a unified IDbExceptionClassifier interface without any EF Core dependency.

dotnet add package DbExceptionClassifier.PostgreSQL

var classifier = new PostgreSQLExceptionClassifier();

try
{
    await command.ExecuteNonQueryAsync();
}
catch (DbException ex) when (classifier.IsUniqueConstraintError(ex))
{
    // Handle unique constraint violation
}

See the DbExceptionClassifier README for full documentation.