作为一名 .NET 开发者，你是否曾经在面对数据库交互的繁琐代码时感到头疼？不得不编写大量的 SQL 语句，处理繁琐的数据读取器，还要担心 SQL 注入的风险？别担心，我们都有过这样的经历。
好消息是，Entity Framework Core (EF Core) 这款强大的对象关系映射器 (ORM) 已经成为了我们手中的“瑞士军刀”。虽然 EF Core 最初是为了配合 SQL Server 而设计的，但现在的它已经非常成熟，能够完美支持 PostgreSQL 这样强大且开源的关系型数据库。
在今天的这篇文章中，我们将一起深入探索 如何使用 Entity Framework Core 访问 PostgreSQL 数据库。我们将从基础配置讲起，一直覆盖到 EF Core 8 的最新核心功能，最后还会分享一些实战中的性能优化技巧和常见陷阱。无论你是刚开始接触 PostgreSQL，还是希望优化现有的数据访问层，我相信你都能在这里找到有用的答案。
目录
为什么要将 EF Core 与 PostgreSQL 结合使用？
在开始写代码之前，让我们先聊聊为什么要这样做。
Entity Framework Core 允许我们使用 C# 对象来操作数据库，这意味着我们可以摆脱大多数原始 SQL 查询的编写，让代码更加类型安全且易于维护。而 PostgreSQL 作为世界上最先进的开源数据库，以其卓越的可靠性、强大的数据类型支持（如 JSONB）和优异的性能著称。
将这两者结合，我们既能享受到 EF Core 带来的开发效率提升，又能利用 PostgreSQL 的强大功能。这种“强强联合”是目前构建 .NET 后端服务非常流行且稳健的选择。
第一步：集成环境与核心配置
要将 EF Core 与 PostgreSQL 数据库打通，关键在于“桥梁”的搭建——也就是我们需要一个专门的 PostgreSQL 提供程序。在 .NET 生态中，最成熟、官方推荐的提供程序是由 Npgsql 团队开发的 Npgsql.EntityFrameworkCore.PostgreSQL。
1. 安装必要的 NuGet 包
首先，我们需要打开终端或包管理器控制台，安装核心的 EF Core 包以及 PostgreSQL 提供程序。这是我们要做的第一步基础工作。
你可以使用以下命令来安装所需的包：
# 安装 PostgreSQL 提供程序，这是连接 EF Core 和 PG 的桥梁
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
# 如果需要通过命令行工具生成迁移，还需要安装这个设计包
dotnet add package Microsoft.EntityFrameworkCore.Design
2. 配置数据库连接字符串
安装好包之后，接下来的任务就是告诉我们的应用程序该如何找到数据库。在 appsettings.json 文件中，我们通常会定义连接字符串。
{
"ConnectionStrings": {
"DefaultConnection": "Host=localhost;Port=5432;Database=YourDatabaseName;Username=postgres;Password=your_password"
}
}
3. 设置 DbContext
DbContext 是我们与数据库交互的上下文环境。我们需要在这里配置 EF Core 使用 PostgreSQL 提供程序，并读取上面的连接字符串。
// Program.cs 或 Startup.cs 中
using Microsoft.EntityFrameworkCore;
// 配置依赖注入
services.AddDbContext(options =>
// 使用 UseNpgsql 指定 PostgreSQL 提供程序
options.UseNpgsql(Configuration.GetConnectionString("DefaultConnection")));
注意：在生产环境中，建议你使用环境变量或密钥管理服务来存储数据库密码，而不是直接硬编码在配置文件中。这属于安全最佳实践。
第二步：定义模型与生成数据库架构
有了连接，我们还需要定义数据模型。EF Core 会通过这些类（实体）来映射数据库中的表。
定义实体模型
让我们来看一个简单的例子。假设我们正在构建一个博客系统，我们需要一个 Post 实体：
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
namespace YourApp.Models
{
// Table 属性显式指定表名，如果不写，默认为 Posts
[Table("posts")]
public class Post
{
[Key]
public int Id { get; set; }
[Required]
[MaxLength(200)]
public string Title { get; set; }
public string Content { get; set; }
public DateTime PublishedAt { get; set; } = DateTime.UtcNow;
}
}
配置 DbContext
接着，我们需要在 INLINECODEd2cd2827 中包含这个 INLINECODE8aa47d8b：
using Microsoft.EntityFrameworkCore;
using YourApp.Models;
public class YourDbContext : DbContext
{
public YourDbContext(DbContextOptions options) : base(options)
{
}
// DbSet 代表数据库中的 Posts 表
public DbSet Posts { get; set; }
}
使用迁移功能管理架构
一旦定义好了模型，我们不需要手动去数据库建表。EF Core 提供了 迁移 功能，可以将 C# 代码转换为数据库结构。这是我们最爱的功能之一，因为它允许我们像管理代码一样管理数据库结构的变化。
首先，生成初始迁移：
# 这将在 Migrations 文件夹下创建一个 InitialCreate 的快照文件
dotnet ef migrations add InitialCreate
然后，将这个变更应用到数据库：
# 这会执行生成的 SQL 语句，在 PostgreSQL 中创建表
dotnet ef database update
此时，如果你连接到 PostgreSQL 数据库查看，你会看到一张崭新的 posts 表已经被创建好了，列名和数据类型都与我们定义的 C# 类一一对应。
第三步：实战 CRUD 操作
现在万事俱备，让我们来看看如何在代码中实际操作数据。我们将通过完整的代码示例来展示增删改查 (CRUD)。
1. 插入新数据
向 PostgreSQL 插入数据非常直观。我们只需要创建一个对象，告诉上下文，然后保存。
public void CreatePost()
{
using (var context = new YourDbContext())
{
// 1. 创建实例：用你想要插入的数据实例化你的实体类
var newPost = new Post
{
Title = "EF Core 与 PostgreSQL 之旅",
Content = "这是一篇关于如何配置数据库的详细指南..."
};
// 2. 添加到 DbContext：此时数据还未进入数据库，仅被上下文追踪
context.Posts.Add(newPost);
// 3. 保存更改：调用 SaveChanges 将新数据持久化到 PostgreSQL
// 这里会开启一个事务，并执行 INSERT 语句
context.SaveChanges();
Console.WriteLine($"新文章已创建，ID: {newPost.Id}");
}
}
实战见解：SaveChanges() 是一个原子操作。如果在添加多个对象时其中一个出错，整个操作都会回滚，这保证了数据的一致性。
2. 读取与查询数据
EF Core 最强大的地方在于 LINQ 查询。我们可以使用强类型的 C# 语法来写查询，EF Core 会将其转化为高效的 SQL 语句。
public void GetPosts()
{
using (var context = new YourDbContext())
{
// 查询所有标题包含 "EF Core" 的文章
var posts = context.Posts
.Where(p => p.Title.Contains("EF Core"))
.OrderByDescending(p => p.PublishedAt)
.ToList();
foreach (var post in posts)
{
Console.WriteLine($"标题: {post.Title}, 发布时间: {post.PublishedAt}");
}
}
}
3. 更新现有数据
更新数据需要我们先把它“查”出来，修改属性，然后再保存。EF Core 会自动追踪实体的状态变化。
public void UpdatePost(int postId)
{
using (var context = new YourDbContext())
{
// 1. 检索实体：从数据库中查询我们要更新的实体
var postToUpdate = context.Posts.Find(postId);
if (postToUpdate != null)
{
// 2. 修改属性
postToUpdate.Title = "(更新后) EF Core 与 PostgreSQL 之旅";
postToUpdate.Content = "添加了更多关于性能优化的内容...";
// 3. 保存更改
// EF Core 检测到属性变化，自动生成 UPDATE 语句
context.SaveChanges();
Console.WriteLine("文章更新成功！");
}
else
{
Console.WriteLine("未找到指定的文章。");
}
}
}
4. 删除数据
删除操作同样简单，只需调用 Remove 方法。
public void DeletePost(int postId)
{
using (var context = new YourDbContext())
{
// 先查找
var postToDelete = context.Posts.Find(postId);
if (postToDelete != null)
{
// 标记为删除
context.Posts.Remove(postToDelete);
// 执行删除
context.SaveChanges();
Console.WriteLine("文章已删除。");
}
}
}
深入 EF Core 8 的核心新功能
如果你使用的是最新的 .NET 8 或更高版本，你将享受到 EF Core 8 带来的许多增强特性。这些功能不仅提升了性能，还填补了与 PostgreSQL 特性集成的许多空白。
1. 原生 JSON 列支持
这是我个人最喜欢的功能之一。PostgreSQL 拥有非常强大的 JSON 数据类型支持。以前在 EF Core 中操作 JSON 列比较麻烦，但在 EF Core 8 中，我们可以像操作普通对象一样映射 JSON 列。
假设我们在 INLINECODEbeca55e6 表中有一个 INLINECODE9029337f 列，类型是 jsonb，存储了一些额外的灵活信息：
// 定义一个用于 JSON 映射的类
public class PostMetadata
{
public int Views { get; set; }
public List Tags { get; set; }
}
public class Post
{
public int Id { get; set; }
public string Title { get; set; }
// 将这个类映射到数据库的 JSONB 列
public PostMetadata Metadata { get; set; }
}
// 在 DbContext OnModelCreating 中配置
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
modelBuilder.Entity()
.OwnsOne(p => p.Metadata, builder =>
{
builder.ToJson(); // 核心配置：告诉 EF Core 这是一个 JSON 列
});
}
现在，当你查询或保存 Post 时，EF Core 会自动处理 C# 对象和 PostgreSQL JSONB 之间的转换。这极大地简化了半结构化数据的处理。
2. 性能优化改进
EF Core 8 在查询执行效率上做了很多底层优化。
- 更快的 SQL 生成：生成的 SQL 语句更加简洁，减少了数据库的处理开销。
- 更智能的更改追踪：EF Core 能够更精准地检测实体的变化，减少不必要的 UPDATE 操作。
实用建议：在处理大量数据更新时，可以考虑使用 INLINECODE2c56c410 或 INLINECODE19f2be4e，这是 EF Core 7/8 引入的批量操作方法，速度比先查再改快得多：
// 不需要先查询，直接生成 SQL: UPDATE Posts SET PublishedAt = NOW() WHERE Id > 100
context.Posts.Where(p => p.Id > 100).ExecuteUpdate(setters => setters.SetProperty(p => p.PublishedAt, DateTime.UtcNow));
常见问题与故障排除
在将 EF Core 与 PostgreSQL 结合使用的过程中，你可能会遇到一些常见的问题。让我们来看看如何解决它们。
1. 连接错误与防火墙
问题：抛出 Npgsql.PostgresException (0x80004005): Connection refused。
解决方案：这通常意味着 PostgreSQL 服务未运行，或者防火墙阻止了连接。首先检查 PostgreSQL 服务是否启动，然后检查 pg_hba.conf 文件，确保允许来自你 IP 地址的连接。另外，云数据库通常需要配置“安全组”或“防火墙规则”来允许特定 IP 访问。
2. 迁移脚本中的编码问题
问题：在迁移中插入中文数据时出现乱码。
解决方案：确保你的数据库创建时使用了 UTF-8 编码。Npgsql 默认使用 UTF-8，但如果数据库本身是 SQL_ASCII 编码，可能会出现问题。创建数据库时请指定编码：
CREATE DATABASE my_db WITH ENCODING=‘UTF8‘ TEMPLATE=template0;
3. 选择正确的提供程序版本
问题：升级 .NET 版本后报错。
解决方案：务必保证 INLINECODE0052dcc5 的版本与你安装的 INLINECODEbf3dd46a 版本匹配。通常情况下，NuGet 会自动处理依赖关系，但手动调整版本号时要注意版本兼容性矩阵。
性能优化与最佳实践
为了让你的应用在生产环境中跑得更快、更稳，这里有几点经验之谈：
- AsNoTracking：当你只需要读取数据而不需要修改时，使用
AsNoTracking()。这告诉 EF Core 不需要追踪这些实体的变化，可以显著提高查询性能并减少内存占用。
var posts = context.Posts.AsNoTracking().ToList();
- 拆分 DbContext：如果你的应用非常大，考虑将 INLINECODE8ef6b08f 拆分为多个不同的上下文（例如 INLINECODE166551a2 和
WriteDbContext），或者按业务模块拆分。这可以减少模型初始化的开销。
- 索引优化：别忘了在数据库层面为经常查询的字段（如 INLINECODE5cbdb052, INLINECODE3342c1a6）建立索引。你可以在 EF Core 的迁移脚本中使用
HasIndex()方法来定义索引。
总结
今天，我们像搭积木一样，从零开始构建了 Entity Framework Core 与 PostgreSQL 的集成环境。我们不仅学习了如何安装、配置和进行基本的 CRUD 操作，还深入探讨了 EF Core 8 中的高级 JSON 支持和性能优化技巧。
通过 EF Core，我们能够用面向对象的方式优雅地处理数据库逻辑；而 PostgreSQL 则为我们提供了坚实的后端存储支持。掌握这两者的结合使用，无疑会大大提升你的 .NET 开发效率。
接下来你可以尝试：
- 在你的实际项目中配置一个简单的 PostgreSQL 数据库。
- 尝试使用 EF Core 的 JSON 功能来存储一些非结构化配置数据。
- 使用
AsNoTracking优化你的查询性能。
希望这篇指南能帮助你顺利开启 PostgreSQL 和 .NET 的开发之旅！如果你在配置过程中遇到任何问题，欢迎查阅官方文档或在社区中寻求帮助。祝你编码愉快！