Skip to content

Commit 1a33d7c

Browse files
rojiroji
authored
Document new EF/Npgsql configuration experience (#353)
1 parent 2f7ed1f commit 1a33d7c

2 files changed

Lines changed: 144 additions & 40 deletions

File tree

‎conceptual/EFCore.PG/index.md‎

Lines changed: 114 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -19,63 +19,139 @@ Below is a `.csproj` file for a console application that uses the Npgsql EF Core
1919
```xml
2020
<Project Sdk="Microsoft.NET.Sdk">
2121
<PropertyGroup>
22-
<TargetFramework>netcoreapp3.0</TargetFramework>
22+
<TargetFramework>net8.0</TargetFramework>
2323
</PropertyGroup>
2424
<ItemGroup>
25-
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="3.1.3" />
25+
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.4" />
2626
</ItemGroup>
2727
</Project>
2828
```
2929

30-
## Defining a `DbContext`
30+
## Defining a model and a `DbContext`
31+
32+
Let's say you want to store blogs and their posts in their database; you can model these as .NET types as follows:
3133

3234
```c#
33-
using System.Collections.Generic;
34-
using Microsoft.EntityFrameworkCore;
35+
public class Blog
36+
{
37+
public int BlogId { get; set; }
38+
public string Url { get; set; }
39+
40+
public List<Post> Posts { get; set; }
41+
}
3542

36-
namespace ConsoleApp.PostgreSQL
43+
public class Post
3744
{
38-
public class BloggingContext : DbContext
39-
{
40-
public DbSet<Blog> Blogs { get; set; }
41-
public DbSet<Post> Posts { get; set; }
42-
43-
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
44-
=> optionsBuilder.UseNpgsql("Host=my_host;Database=my_db;Username=my_user;Password=my_pw");
45-
}
46-
47-
public class Blog
48-
{
49-
public int BlogId { get; set; }
50-
public string Url { get; set; }
51-
52-
public List<Post> Posts { get; set; }
53-
}
54-
55-
public class Post
56-
{
57-
public int PostId { get; set; }
58-
public string Title { get; set; }
59-
public string Content { get; set; }
60-
61-
public int BlogId { get; set; }
62-
public Blog Blog { get; set; }
63-
}
45+
public int PostId { get; set; }
46+
public string Title { get; set; }
47+
public string Content { get; set; }
48+
49+
public int BlogId { get; set; }
50+
public Blog Blog { get; set; }
6451
}
6552
```
6653

67-
## Additional configuration for ASP.NET Core applications
54+
You then define a `DbContext` type which you'll use to interact with the database:
55+
56+
### [OnConfiguring](#tab/onconfiguring)
6857

69-
Consult [this tutorial](https://docs.microsoft.com/en-us/aspnet/core/data/ef-rp/intro) for general information on how to make ASP.NET work with EF Core. For Npgsql specifically, simply place the following in your `ConfigureServices` method in `Startup.cs`:
58+
Using `OnConfiguring()` to configure your context is the easiest way to get started, but is discouraged for most production applications:
7059

7160
```c#
72-
public void ConfigureServices(IServiceCollection services)
61+
public class BloggingContext : DbContext
7362
{
74-
// Other DI initializations
63+
public DbSet<Blog> Blogs { get; set; }
64+
public DbSet<Post> Posts { get; set; }
7565

76-
services.AddDbContext<BloggingContext>(options =>
77-
options.UseNpgsql(Configuration.GetConnectionString("BloggingContext")));
66+
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
67+
=> optionsBuilder.UseNpgsql("<connection string>");
7868
}
69+
70+
// At the point where you need to perform a database operation:
71+
using var context = new BloggingContext();
72+
// Use the context...
73+
```
74+
75+
### [DbContext pooling](#tab/context-pooling)
76+
77+
```c#
78+
var dbContextFactory = new PooledDbContextFactory<BloggingContext>(
79+
new DbContextOptionsBuilder<BloggingContext>()
80+
.UseNpgsql("<connection string>")
81+
.Options);
82+
83+
// At the point where you need to perform a database operation:
84+
using var context = dbContextFactory.CreateDbContext();
85+
// Use the context...
86+
```
87+
88+
### [ASP.NET / DI](#tab/aspnet)
89+
90+
When using ASP.NET - or any application with dependency injection - the context instance will be injected into your code. Use the following to configure EF with your DI container:
91+
92+
```c#
93+
var builder = WebApplication.CreateBuilder(args);
94+
95+
builder.Services.AddDbContextPool<BloggingContext>(opt =>
96+
opt.UseNpgsql(builder.Configuration.GetConnectionString("BloggingContext")));
97+
98+
public class BloggingContext(DbContextOptions<BloggingContext> options) : DbContext(options)
99+
{
100+
public DbSet<Blog> Blogs { get; set; }
101+
public DbSet<Post> Posts { get; set; }
102+
}
103+
```
104+
105+
***
106+
107+
For more information on getting started with EF, consult the [EF getting started documentation](https://learn.microsoft.com/en-us/ef/core/get-started/overview/first-app?tabs=netcore-cli).
108+
109+
## Additional Npgsql configuration
110+
111+
The Npgsql EF provider is built on top of the lower-level Npgsql ADO.NET provider ([docs](https://www.npgsql.org/doc/index.html)); these two separate components support various options you may want to configure.
112+
113+
If you're using EF 9.0 or above, the `UseNpgsql()` is a single point where you can configure everything related to Npgsql. For example:
114+
115+
```c#
116+
builder.Services.AddDbContextPool<BloggingContext>(opt =>
117+
opt.UseNpgsql(
118+
builder.Configuration.GetConnectionString("BloggingContext"),
119+
o => o
120+
.SetPostgresVersion(13, 0)
121+
.UseNodaTime()
122+
.MapEnum<Mood>("mood")));
123+
```
124+
125+
The above configures the EF provider to produce SQL for PostgreSQL version 13 (avoiding newer incompatible features), adds a plugin allowing use of NodaTime for date/time type mapping, and maps a .NET enum type. Note that the last two also require configuration at the lower-level ADO.NET layer, which the code above does for you automatically.
126+
127+
If you need to configure something at the lower-level ADO.NET layer, use `ConfigureDataSource()` as follows:
128+
129+
```c#
130+
builder.Services.AddDbContextPool<BloggingContext>(opt =>
131+
opt.UseNpgsql(
132+
builder.Configuration.GetConnectionString("BloggingContext"),
133+
o => o.ConfigureDataSource(dataSourceBuilder => dataSourceBuilder.UseClientCertificate(certificate))));
134+
```
135+
136+
`ConfigureDataSource()` provides access to a lower-level [`NpgsqlDataSourceBuilder`](../doc/basic-usage.html#data-source) which you can use to configure all aspects of the Npgsql ADO.NET provider.
137+
138+
> [!WARNING]
139+
> The EF provider internally creates an NpgsqlDataSource and uses that; for most configuration (e.g. connection string), the provider knows to switch between NpgsqlDataSources automatically.
140+
> However, it's not possible to detect configuration differences within the `ConfigureDataSource()`; as a result, avoid performing varying configuration inside `ConfigureDataSource()`, since you may
141+
> get the wrong NpgsqlDataSource. If you find yourself needing to vary Npgsql ADO.NET configuration, create an external NpgsqlDataSource yourself with the desired configuration and pass that to
142+
> `UseNpgsql()` as described below.
143+
144+
### Using an external NpgsqlDataSource
145+
146+
If you're using a version of EF prior to 9.0, the above configuration methods aren't available. You can still create an `NpgsqlDataSource` yourself, and then pass it EF's `UseNpgsql()`:
147+
148+
```c#
149+
var dataSourceBuilder = new NpgsqlDataSourceBuilder(builder.Configuration.GetConnectionString("BloggingContext"));
150+
dataSourceBuilder.MapEnum<Mood>();
151+
dataSourceBuilder.UseNodaTime();
152+
var dataSource = dataSourceBuilder.Build();
153+
154+
builder.Services.AddDbContextPool<BloggingContext>(opt => opt.UseNpgsql(dataSource));
79155
```
80156

81157
## Using an Existing Database (Database-First)

‎conceptual/EFCore.PG/release-notes/9.0.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,40 @@ Npgsql.EntityFrameworkCore.PostgreSQL version 9.0 is under development; previews
55
> [!NOTE]
66
> The following release notes and breaking changes are partial. More will be added nearer to the 9.0 final release.
77
8-
## Improved configuration for enums and plugins
8+
## Improved, unified configuration experience
9+
10+
The Npgsql EF provider is built on top of the lower-level Npgsql ADO.NET provider; the configuration interface between these two layers was less than ideal, and configuration been more difficult than it should have been. For version 9.0, the configuration experience has been considerably improved.
11+
12+
Since version 7, the Npgsql ADO.NET provider has been moving to [NpgsqlDataSource](../../doc/basic-usage.html#data-source) as the preferred way of configuration connections and obtaining them. At the EF level, it has been possible to pass an NpgsqlDataSource instance to `UseNpgsql()`; but this required that the user separately configure a data source and manage it. In addition, features such as plugins and enums require support from both the EF and ADO.NET layers, forcing users to perform multiple setup actions at the different layers.
13+
14+
With version 9, `UseNpgsql()` becomes a single point for configuration, for both the EF and ADO.NET levels. EF can now internally set up an NpgsqlDataSource, automatically applying all the necessary configuration to it, and also exposes an API to allow users to apply arbitrary configuration to it as well:
15+
16+
```c#
17+
builder.Services.AddDbContextPool<BloggingContext>(opt =>
18+
opt.UseNpgsql(
19+
builder.Configuration.GetConnectionString("BloggingContext"),
20+
o => o
21+
.SetPostgresVersion(13, 0)
22+
.UseNodaTime()
23+
.MapEnum<Mood>("mood")
24+
.ConfigureDataSource(dataSourceBuilder => dataSourceBuilder.UseClientCertificate(certificate))));
25+
```
26+
27+
In the above code, the following configuration gestures are performed:
28+
29+
1. `SetPostgresVersion()` is an EF-only option to produce SQL for PostgreSQL version 13 (avoiding newer incompatible features)
30+
2. `UseNodaTime()`, adds a plugin allowing use of NodaTime for date/time type mapping. This also requires an ADO.NET NodaTime plugin which needed to be configured separately, but this is now done automatically.
31+
3. `MapEnum()` maps a .NET enum type. Like `UseNodaTime()`, this also used to require a separate ADO.NET configuration gesture, but is now done automatically. As an added bonus, doing this now also adds the enum to the model, causing the enum to be created in the database via EF's migrations.
32+
4. `ConfigureDataSource()` exposes an NpgsqlDataSourceBuilder, which you can use to configure arbitrary ADO.NET options. In this example, the certificate is defined for the TLS authentication process.
33+
34+
For more information, see the [getting started docs](../index.html).
35+
36+
### Improved configuration for enums and plugins
937

1038
Previously, configuration around enums and plugins (NodaTime, NetTopologySuite) was complicated, requiring multiple setup actions at both the EF and the lower-level Npgsql layers. EF 9.0 improves the configuration story, allowing you to configure enums and plugins via a single EF gesture:
1139

1240
```c#
13-
builder.Services.AddDbContext<MyContext>(options => options.UseNpgsql(
41+
builder.Services.AddPooledDbContext<MyContext>(options => options.UseNpgsql(
1442
"<connection string>",
1543
o => o.MapEnum<Mood>("mood")));
1644
```

0 commit comments

Comments
 (0)