You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>Using <code>OnConfiguring()</code> to configure your context is the easiest way to get started, but is discouraged for most production applications:</p>
143
+
<pre><codeclass="lang-c#">public class BloggingContext : DbContext
// At the point where you need to perform a database operation:
153
+
using var context = new BloggingContext();
154
+
// Use the context...
140
155
</code></pre>
141
-
<h2id="additional-configuration-for-aspnet-core-applications">Additional configuration for ASP.NET Core applications</h2>
142
-
<p>Consult <ahref="https://docs.microsoft.com/en-us/aspnet/core/data/ef-rp/intro">this tutorial</a> for general information on how to make ASP.NET work with EF Core. For Npgsql specifically, simply place the following in your <code>ConfigureServices</code> method in <code>Startup.cs</code>:</p>
<p>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:</p>
public class BloggingContext(DbContextOptions<BloggingContext> options) : DbContext(options)
178
+
{
179
+
public DbSet<Blog> Blogs { get; set; }
180
+
public DbSet<Post> Posts { get; set; }
149
181
}
150
182
</code></pre>
183
+
</section>
184
+
</div>
185
+
186
+
<p>For more information on getting started with EF, consult the <ahref="https://learn.microsoft.com/en-us/ef/core/get-started/overview/first-app?tabs=netcore-cli">EF getting started documentation</a>.</p>
<p>The Npgsql EF provider is built on top of the lower-level Npgsql ADO.NET provider (<ahref="https://www.npgsql.org/doc/index.html">docs</a>); these two separate components support various options you may want to configure.</p>
189
+
<p>If you're using EF 9.0 or above, the <code>UseNpgsql()</code> is a single point where you can configure everything related to Npgsql. For example:</p>
<p>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.</p>
199
+
<p>If you need to configure something at the lower-level ADO.NET layer, use <code>ConfigureDataSource()</code> as follows:</p>
o => o.ConfigureDataSource(dataSourceBuilder => dataSourceBuilder.UseClientCertificate(certificate))));
204
+
</code></pre>
205
+
<p><code>ConfigureDataSource()</code> provides access to a lower-level <ahref="../doc/basic-usage.html#data-source"><code>NpgsqlDataSourceBuilder</code></a> which you can use to configure all aspects of the Npgsql ADO.NET provider.</p>
206
+
<divclass="WARNING">
207
+
<h5>Warning</h5>
208
+
<p>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.
209
+
However, it's not possible to detect configuration differences within the <code>ConfigureDataSource()</code>; as a result, avoid performing varying configuration inside <code>ConfigureDataSource()</code>, since you may
210
+
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
211
+
<code>UseNpgsql()</code> as described below.</p>
212
+
</div>
213
+
<h3id="using-an-external-npgsqldatasource">Using an external NpgsqlDataSource</h3>
214
+
<p>If you're using a version of EF prior to 9.0, the above configuration methods aren't available. You can still create an <code>NpgsqlDataSource</code> yourself, and then pass it EF's <code>UseNpgsql()</code>:</p>
215
+
<pre><codeclass="lang-c#">var dataSourceBuilder = new NpgsqlDataSourceBuilder(builder.Configuration.GetConnectionString("BloggingContext"));
<h2id="using-an-existing-database-database-first">Using an Existing Database (Database-First)</h2>
152
223
<p>The Npgsql EF Core provider also supports reverse-engineering a code model from an existing PostgreSQL database ("database-first"). To do so, use dotnet CLI to execute the following:</p>
153
224
<pre><codeclass="lang-bash">dotnet ef dbcontext scaffold "Host=my_host;Database=my_db;Username=my_user;Password=my_pw" Npgsql.EntityFrameworkCore.PostgreSQL
<p>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.</p>
95
+
<p>Since version 7, the Npgsql ADO.NET provider has been moving to <ahref="../../doc/basic-usage.html#data-source">NpgsqlDataSource</a> as the preferred way of configuration connections and obtaining them. At the EF level, it has been possible to pass an NpgsqlDataSource instance to <code>UseNpgsql()</code>; 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.</p>
96
+
<p>With version 9, <code>UseNpgsql()</code> 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:</p>
<p>In the above code, the following configuration gestures are performed:</p>
107
+
<ol>
108
+
<li><code>SetPostgresVersion()</code> is an EF-only option to produce SQL for PostgreSQL version 13 (avoiding newer incompatible features)</li>
109
+
<li><code>UseNodaTime()</code>, 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.</li>
110
+
<li><code>MapEnum()</code> maps a .NET enum type. Like <code>UseNodaTime()</code>, 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.</li>
111
+
<li><code>ConfigureDataSource()</code> 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.</li>
112
+
</ol>
113
+
<p>For more information, see the <ahref="../index.html">getting started docs</a>.</p>
114
+
<h3id="improved-configuration-for-enums-and-plugins">Improved configuration for enums and plugins</h3>
94
115
<p>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:</p>
0 commit comments