Entity Framework Core

https://learn.microsoft.com/en-us/ef/core/
Admin
Entity Framework Core is a lightweight, extensible, open source object-relational mapper (O/RM) that...
Tokens:510,807
Snippets:4,098
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Initial Blog model

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations

Initial model used in the getting started example. It is the starting point before creating the first migration.

```csharp
public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
}

```

--------------------------------

### Install Microsoft.EntityFrameworkCore.Tools package

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/install

Installs the Package Manager Console tools for EF Core from Visual Studio. Use this to get the PMC tools.

```PowerShell
Install-Package Microsoft.EntityFrameworkCore.Tools

```

--------------------------------

### Verify EF Core tools installation with Get-Help

Source: https://learn.microsoft.com/en-us/ef/core/cli/powershell

Verifies that the Entity Framework Core tools are installed. The output displays the about_EntityFrameworkCore help topic but does not indicate the installed version.

```powershell
Get-Help about_EntityFrameworkCore
```

--------------------------------

### Install EF Core provider with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/providers

Install an EF Core database provider NuGet package using the .NET CLI.

```bash
dotnet add package provider_package_name

```

--------------------------------

### Example dotnet-ef.json configuration

Source: https://learn.microsoft.com/en-us/ef/core/cli/dotnet

Example JSON configuration file with all supported properties. All properties are optional; only include the ones you need. Explicit command-line options take precedence over these values.

```json
{
  "project": "src/App.Infrastructure",
  "startupProject": "src/App.Api",
  "framework": "net11.0",
  "configuration": "Debug",
  "context": "AppDbContext",
  "runtime": "win-x64",
  "verbose": true,
  "noColor": false,
  "prefixOutput": false
}

```

--------------------------------

### Install Microsoft.EntityFrameworkCore.Cosmos package

Source: https://learn.microsoft.com/en-us/ef/core/providers/cosmos

Install the Microsoft.EntityFrameworkCore.Cosmos NuGet package using either the .NET CLI or PowerShell. The .NET CLI command is `dotnet add package Microsoft.EntityFrameworkCore.Cosmos` and the PowerShell command is `Install-Package Microsoft.EntityFrameworkCore.Cosmos`.

```bash
dotnet add package Microsoft.EntityFrameworkCore.Cosmos

```

```powershell
Install-Package Microsoft.EntityFrameworkCore.Cosmos

```

--------------------------------

### Install dotnet-counters tool

Source: https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/metrics

Installs the dotnet-counters tool globally, which is required to monitor EF Core event counters.

```console
dotnet tool install --global dotnet-counters
```

--------------------------------

### Install Microsoft.EntityFrameworkCore.SqlServer.HierarchyId package

Source: https://learn.microsoft.com/en-us/ef/core/providers/sql-server/hierarchyid

Install the Microsoft.EntityFrameworkCore.SqlServer.HierarchyId package using either the .NET CLI or the Package Manager Console. The package brings in Microsoft.EntityFrameworkCore.SqlServer.Abstractions and Microsoft.SqlServer.Types as transitive dependencies.

```bash
dotnet add package Microsoft.EntityFrameworkCore.SqlServer.HierarchyId

```

```powershell
Install-Package Microsoft.EntityFrameworkCore.SqlServer.HierarchyId

```

--------------------------------

### Install Microsoft.EntityFrameworkCore.InMemory with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/providers/in-memory

Use this command to install the Microsoft.EntityFrameworkCore.InMemory NuGet package via the .NET CLI.

```dotnet CLI
dotnet add package Microsoft.EntityFrameworkCore.InMemory

```

--------------------------------

### Install EF Core provider with PowerShell

Source: https://learn.microsoft.com/en-us/ef/core/providers

Install an EF Core database provider NuGet package using the Visual Studio Package Manager Console.

```powershell
install-package provider_package_name

```

--------------------------------

### Install dotnet-ef as a global tool

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/install

Installs the .NET CLI tools for EF Core as a global tool. Requires the .NET SDK. Use `dotnet tool update` to update the tools.

```dotnet CLI
dotnet tool install --global dotnet-ef

```

--------------------------------

### Define Blog and Post models

Source: https://learn.microsoft.com/en-us/ef/core/modeling/keyless-entity-types

Defines the Blog and Post entity classes used in the example. These are standard entity types with navigation properties and are prerequisites for the keyless entity type example.

```csharp
public class Blog
{
    public int BlogId { get; set; }
    public string Name { get; set; }
    public string Url { get; set; }
    public ICollection<Post> Posts { get; set; }
}

public class Post
{
    public int PostId { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public int BlogId { get; set; }
}
```

--------------------------------

### Install EF Core SQL Server provider with Package Manager Console

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/install

Run this command in the Package Manager Console to install the SQL Server provider. Use 'Update-Package' to update, and '-Version' to specify a version, e.g., '-Version 6.0.14'.

```powershell
Install-Package Microsoft.EntityFrameworkCore.SqlServer

```

--------------------------------

### Install EF Core SQL Server provider with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/install

Use this command to install or update the Microsoft.EntityFrameworkCore.SqlServer package. Append '-v 6.0.14' to specify a version, e.g., for EF Core 6.0.14.

```dotnetcli
dotnet add package Microsoft.EntityFrameworkCore.SqlServer

```

--------------------------------

### Output of Get-Help about_EntityFrameworkCore

Source: https://learn.microsoft.com/en-us/ef/core/cli/powershell

Example output from running Get-Help about_EntityFrameworkCore. It shows the help topic header and a note that the list of available commands is omitted.

```output

                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\/\\

TOPIC
    about_EntityFrameworkCore

SHORT DESCRIPTION
    Provides information about the Entity Framework Core Package Manager Console Tools.

<A list of available commands follows, omitted here.>

```

--------------------------------

### Create database with .NET CLI migrations

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/first-app

Run these commands to install dotnet-ef and the design package, scaffold an initial migration, and create the database. Requires the project to be set up first.

```bash
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet ef migrations add InitialCreate
dotnet ef database update

```

--------------------------------

### Historical data output after restore

Source: https://learn.microsoft.com/en-us/ef/core/providers/sql-server/temporal-tables

Example output showing the historical data for Rainbow Dash after re-insertion, listing each period with start and end times.

```text
Historical data for Rainbow Dash:
  Employee Rainbow Dash was 'Ponyville weather patrol' from 8/26/2021 4:38:58 PM to 8/26/2021 4:40:29 PM
  Employee Rainbow Dash was 'Wonderbolt Trainee' from 8/26/2021 4:40:29 PM to 8/26/2021 4:41:59 PM
  Employee Rainbow Dash was 'Wonderbolt Reservist' from 8/26/2021 4:41:59 PM to 8/26/2021 4:43:29 PM
  Employee Rainbow Dash was 'Wonderbolt' from 8/26/2021 4:43:29 PM to 8/26/2021 4:44:59 PM
  Employee Rainbow Dash was 'Wonderbolt Trainee' from 8/26/2021 4:44:59 PM to 12/31/9999 11:59:59 PM
```

--------------------------------

### Create a new console project with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/first-app

Use the .NET CLI to create a new console project named EFGetStarted and navigate into the project directory.

```bash
dotnet new console -o EFGetStarted
cd EFGetStarted

```

--------------------------------

### FreeTextTable() with specific column

Source: https://learn.microsoft.com/en-us/ef/core/providers/sql-server/full-text-search

Searches a specific column (a.Contents) using FreeTextTable() and joins with the entity to get ranking. Requires explicit generic type parameters as in the previous example.

```C#
var results = await context.Articles
    .Join(
        context.Articles.FreeTextTable<Article, int>("veggies", a => a.Contents),
        a => a.Id,
        ftt => ftt.Key,
        (a, ftt) => new { Article = a, ftt.Rank })
    .OrderByDescending(r => r.Rank)
    .ToListAsync();

```

--------------------------------

### Create and apply a new migration in one step

Source: https://learn.microsoft.com/en-us/ef/core/cli/dotnet

Creates a new migration and applies it to the database in a single step. The first example uses the default output directory and namespace; the second specifies a custom output directory and namespace.

```dotnet CLI
dotnet ef database update InitialCreate --add
```

```dotnet CLI
dotnet ef database update AddProducts --add --output-dir Migrations/Products --namespace MyApp.Migrations
```

--------------------------------

### Rewritten non-dynamic queries (precompilable)

Source: https://learn.microsoft.com/en-us/ef/core/performance/nativeaot-and-precompiled-queries

This example shows how to rewrite the dynamic query into two non-dynamic queries using a conditional expression. Each query can be statically analyzed from start to finish, so precompilation can handle them.

```csharp
IAsyncEnumerable<Blog> GetBlogs(BlogContext context, bool applyFilter)
    => applyFilter
        ? context.Blogs.OrderBy(b => b.Id).Where(b => b.Name != "foo").AsAsyncEnumerable()
        : context.Blogs.OrderBy(b => b.Id).AsAsyncEnumerable();
```

--------------------------------

### Get EntityEntry for a tracked entity

Source: https://learn.microsoft.com/en-us/ef/core/change-tracking/entity-entries

Shows how to obtain an EntityEntry<TEntity> for a tracked entity by passing the entity instance to DbContext.Entry. The example uses a BlogsContext and queries a blog with Id 1 before calling Entry.

```csharp
using var context = new BlogsContext();

var blog = await context.Blogs.SingleAsync(e => e.Id == 1);
var entityEntry = context.Entry(blog);

```

--------------------------------

### TPC database schema for Blogs and RssBlogs

Source: https://learn.microsoft.com/en-us/ef/core/modeling/inheritance

Shows the database schema EF creates for the TPC mapping example above. Each concrete type gets its own table with columns for all properties, and primary keys use a sequence default.

```sql
CREATE TABLE [Blogs] (
    [BlogId] int NOT NULL DEFAULT (NEXT VALUE FOR [BlogSequence]),
    [Url] nvarchar(max) NULL,
    CONSTRAINT [PK_Blogs] PRIMARY KEY ([BlogId])
);

CREATE TABLE [RssBlogs] (
    [BlogId] int NOT NULL DEFAULT (NEXT VALUE FOR [BlogSequence]),
    [Url] nvarchar(max) NULL,
    [RssUrl] nvarchar(max) NULL,
    CONSTRAINT [PK_RssBlogs] PRIMARY KEY ([BlogId])
);
```

--------------------------------

### Controller method with explicit transaction

Source: https://learn.microsoft.com/en-us/ef/core/testing/testing-with-the-database

Controller method that explicitly starts a serializable transaction before updating a blog URL. It is used as an example for tests that manage transactions, where the transaction cannot be used for test isolation because the product code needs it.

```C#
[HttpPost]
public async Task<ActionResult> UpdateBlogUrl(string name, string url)
{
    // Note: it isn't usually necessary to start a transaction for updating. This is done here for illustration purposes only.
    await using var transaction = await _context.Database.BeginTransactionAsync(IsolationLevel.Serializable);

    var blog = await _context.Blogs.FirstOrDefaultAsync(b => b.Name == name);
    if (blog is null)
    {
        return NotFound();
    }

    blog.Url = url;
    await _context.SaveChangesAsync();

    await transaction.CommitAsync();
    return Ok();
}
```

--------------------------------

### Update EF Core template package with dotnet new update

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/scaffolding/templates

Updates the installed EF Core template package to the latest version. Run this before adding the default templates to a new project to ensure you get the most recent templates.

```console
dotnet new update

```

--------------------------------

### dotnet ef migrations list, script, and bundle with project options

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/projects

Shows the same project options applied to other dotnet ef commands: list, script, and bundle. Run from the solution directory.

```dotnet CLI
dotnet ef migrations list \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

dotnet ef migrations script --output artifacts/migrations.sql \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

dotnet ef migrations bundle --output artifacts/efbundle \
    --project WebApplication1.Migrations \
    --startup-project WebApplication1.Migrations

```

--------------------------------

### Add migrations for multiple providers with --context and --output-dir

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/providers

Commands to add an initial migration for each provider context. Use the .NET CLI or Visual Studio Package Manager Console. Subsequent migrations are created as siblings to the last one, so the output directory is only needed for the first migration.

```bash
dotnet ef migrations add InitialCreate --context BlogContext --output-dir Migrations/SqlServerMigrations
dotnet ef migrations add InitialCreate --context SqliteBlogContext --output-dir Migrations/SqliteMigrations
```

```powershell
Add-Migration InitialCreate -Context BlogContext -OutputDir Migrations\SqlServerMigrations
Add-Migration InitialCreate -Context SqliteBlogContext -OutputDir Migrations\SqliteMigrations
```

--------------------------------

### Include nested complex type property in index (EF Core 11.0+)

Source: https://learn.microsoft.com/en-us/ef/core/modeling/indexes

Starting with EF Core 11.0, SQL Server included columns can refer to scalar properties nested inside complex types. This example includes Address.City in the index.

```C#
modelBuilder.Entity<Customer>()
    .HasIndex(c => c.Name)
    .IncludeProperties(c => c.Address.City);

```

--------------------------------

### Create database with Package Manager Console (PMC)

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/first-app

Run these commands in Visual Studio's Package Manager Console to install the PMC tools, scaffold a migration, and create the database.

```powershell
Install-Package Microsoft.EntityFrameworkCore.Tools
Add-Migration InitialCreate
Update-Database

```

--------------------------------

### Iterate all tracked entities with ChangeTracker.Entries()

Source: https://learn.microsoft.com/en-us/ef/core/change-tracking/entity-entries

Use ChangeTracker.Entries() to get an EntityEntry for every entity tracked by the DbContext. The example loads blogs with their posts and prints the entity type name and ID for each tracked entity. The output shows entries for both blogs and posts.

```C#
using var context = new BlogsContext();
var blogs = await context.Blogs.Include(e => e.Posts).ToListAsync();

foreach (var entityEntry in context.ChangeTracker.Entries())
{
    Console.WriteLine($"Found {entityEntry.Metadata.Name} entity with ID {entityEntry.Property("Id").CurrentValue}");
}

```

```Output
Found Blog entity with ID 1
Found Post entity with ID 1
Found Post entity with ID 2

```

--------------------------------

### Using ProjectTo to calculate distance in meters between two points

Source: https://learn.microsoft.com/en-us/ef/core/modeling/spatial

Creates two Point objects with SRID 4326 (WGS84) and projects them to SRID 2855 before calling Distance to get the distance in meters. The example shows that the raw Distance call returns degrees, while projecting first yields meters.

```C#
var seattle = new Point(-122.333056, 47.609722) { SRID = 4326 };
var redmond = new Point(-122.123889, 47.669444) { SRID = 4326 };

// In order to get the distance in meters, we need to project to an appropriate
// coordinate system. In this case, we're using SRID 2855 since it covers the
// geographic area of our data
var distanceInDegrees = seattle.Distance(redmond);
var distanceInMeters = seattle.ProjectTo(2855).Distance(redmond.ProjectTo(2855));
```

--------------------------------

### Create first migration with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations

Creates the first migration named InitialCreate using the .NET CLI.

```bash
dotnet ef migrations add InitialCreate

```

--------------------------------

### appsettings.json with tenant connection strings

Source: https://learn.microsoft.com/en-us/ef/core/miscellaneous/multitenancy

Configuration file with connection strings for each tenant. Add a section per tenant to appsettings.json to support multiple databases.

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "TenantA": "Data Source=tenantacontacts.sqlite",
    "TenantB": "Data Source=tenantbcontacts.sqlite"
  },
  "AllowedHosts": "*"
}
```

--------------------------------

### Example model with foreign keys and navigations

Source: https://learn.microsoft.com/en-us/ef/core/change-tracking/relationship-changes

Example model with four entity types (Blog, BlogAssets, Post, Tag) showing primary keys, foreign keys, reference navigations, collection navigations, and skip collection navigations. The comments indicate which properties are keys and navigations.

```csharp
public class Blog
{
    public int Id { get; set; } // Primary key
    public string Name { get; set; }

    public IList<Post> Posts { get; } = new List<Post>(); // Collection navigation
    public BlogAssets Assets { get; set; } // Reference navigation
}

public class BlogAssets
{
    public int Id { get; set; } // Primary key
    public byte[] Banner { get; set; }

    public int? BlogId { get; set; } // Foreign key
    public Blog Blog { get; set; } // Reference navigation
}

public class Post
{
    public int Id { get; set; } // Primary key
    public string Title { get; set; }
    public string Content { get; set; }

    public int? BlogId { get; set; } // Foreign key
    public Blog Blog { get; set; } // Reference navigation

    public IList<Tag> Tags { get; } = new List<Tag>(); // Skip collection navigation
}

public class Tag
{
    public int Id { get; set; } // Primary key
    public string Text { get; set; }

    public IList<Post> Posts { get; } = new List<Post>(); // Skip collection navigation
}
```

--------------------------------

### Apply migrations with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations

Applies the migration to create the database and schema using the .NET CLI.

```bash
dotnet ef database update

```

--------------------------------

### Tracking query example

Source: https://learn.microsoft.com/en-us/ef/core/querying/tracking

A tracking query example. The change to the blog's rating is detected and persisted to the database during SaveChanges.

```csharp
var blog = await context.Blogs.SingleOrDefaultAsync(b => b.BlogId == 1);
blog.Rating = 5;
await context.SaveChangesAsync();
```

--------------------------------

### Run the app with .NET CLI

Source: https://learn.microsoft.com/en-us/ef/core/get-started/overview/first-app

Use the 'dotnet run' command in the terminal to start the application. This is the .NET CLI method for running the app.

```bash
dotnet run

```

--------------------------------

### Install Microsoft.EntityFrameworkCore.InMemory with PowerShell

Source: https://learn.microsoft.com/en-us/ef/core/providers/in-memory

Use this command to install the Microsoft.EntityFrameworkCore.InMemory NuGet package via the Visual Studio Package Manager Console.

```PowerShell
Install-Package Microsoft.EntityFrameworkCore.InMemory

```

--------------------------------

### timeOnly.IsBetween(start, end)

Source: https://learn.microsoft.com/en-us/ef/core/providers/sql-server/functions

Translates to SQL Server @timeOnly >= @start AND @timeOnly < @end. Checks if a TimeOnly value is between two values.

```APIDOC
## timeOnly.IsBetween(start, end)

### Description
Checks if a TimeOnly value is within the range [start, end).

### Method
TimeOnly.IsBetween

### Parameters
- **start** (TimeOnly) - Required - The start of the range (inclusive).
- **end** (TimeOnly) - Required - The end of the range (exclusive).

### SQL Translation
@timeOnly >= @start AND @timeOnly < @end
```

--------------------------------

### Run bundle with custom connection string

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/applying

Runs the bundle with a different database connection string passed on the command line using the --connection option. All three migrations are applied because none had been applied to the production database.

```powershell
PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe --connection "Data Source=(LocalDb)\MSSQLLocalDB;Database=SixOhProduction"
Applying migration '20210903083845_MyMigration'.
Applying migration '20210903084526_SecondMigration'.
Applying migration '20210903084538_Number3'.
Done.
PS C:\local\AllTogetherNow\SixOh>
```

--------------------------------

### Set environment and generate bundle (Bash)

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/applying

Sets the ASPNETCORE_ENVIRONMENT to Production and generates a migration bundle with dotnet ef migrations bundle, outputting to artifacts/efbundle. Use this in a POSIX-compatible shell.

```bash
ASPNETCORE_ENVIRONMENT=Production \
    dotnet ef migrations bundle --output artifacts/efbundle

```

--------------------------------

### EF.Functions.DateDiffYear(start, end)

Source: https://learn.microsoft.com/en-us/ef/core/providers/sql-server/functions

Translates to SQL Server DATEDIFF(year, @start, @end). Computes the difference in years between two dates.

```APIDOC
## EF.Functions.DateDiffYear(start, end)

### Description
Computes the number of year boundaries crossed between the start and end dates.

### Method
EF.Functions.DateDiffYear

### Parameters
- **start** (DateTime/DateTimeOffset) - Required - The starting date.
- **end** (DateTime/DateTimeOffset) - Required - The ending date.

### SQL Translation
DATEDIFF(year, @start, @end)
```

--------------------------------

### EF.Functions.DateDiffWeek(start, end)

Source: https://learn.microsoft.com/en-us/ef/core/providers/sql-server/functions

Translates to SQL Server DATEDIFF(week, @start, @end). Computes the difference in weeks between two dates.

```APIDOC
## EF.Functions.DateDiffWeek(start, end)

### Description
Computes the number of week boundaries crossed between the start and end dates.

### Method
EF.Functions.DateDiffWeek

### Parameters
- **start** (DateTime/DateTimeOffset) - Required - The starting date.
- **end** (DateTime/DateTimeOffset) - Required - The ending date.

### SQL Translation
DATEDIFF(week, @start, @end)
```

--------------------------------

### Create and apply a migration with Update-Database -Add

Source: https://learn.microsoft.com/en-us/ef/core/cli/powershell

Creates a new migration and applies it to the database in a single step. Requires the -Add parameter and a migration name, which is provided via -Migration. Uses Roslyn to compile the migration at runtime.

```powershell
Update-Database -Migration InitialCreate -Add

```

--------------------------------

### Create first migration with Package Manager Console

Source: https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations

Creates the first migration named InitialCreate using the Package Manager Console tools.

```powershell
Add-Migration InitialCreate

```
Tokens:
Raw