2. 搭建第一个EF Core数据工程环境

在真正开始写实体类、DbContext 和迁移之前，先把“能跑起来”的环境搭好，是 EF Core 数据工程里最容易被低估的一步。很多初学者第一次失败并不是因为 LINQ 写错，而是 SDK 版本、目标框架、包版本、连接字符串四者之间没有对齐。本节按一条可复现的路径，把环境从零搭到“能连上 SQL Server 并执行一次查询”。

一、先明确环境里到底有哪些角色

一个最小的 EF Core 数据工程环境由四部分组成：.NET SDK 提供编译与运行工具链；控制台项目 作为宿主程序；EF Core 包 提供 ORM 能力与数据库提供程序；SQL Server 连接 提供真实的数据存储。它们之间的依赖关系可以用下面这张结构图表示，注意“包版本必须与目标框架匹配”这条约束贯穿始终。

二、安装 .NET SDK 并确认版本

EF Core 的版本与 .NET 目标框架强绑定：EF Core 8 需要 net8.0，EF Core 9 需要 net9.0。因此第一步不是急着建项目，而是确认本机 SDK 版本。安装完成后在终端执行：

dotnet --list-sdks
dotnet --version

如果输出中能看到 8.0.x 或 9.0.x，说明 SDK 就绪。若同时存在多个版本，dotnet --version 返回的是当前目录下生效的版本，后续创建项目时可用 -f 显式指定目标框架，避免“SDK 是 9、项目却是 net8.0”的隐性错配。

三、创建控制台项目

控制台项目是最轻量的宿主，适合学习 EF Core 的核心机制。执行：

dotnet new console -n EfCoreDemo -f net8.0
cd EfCoreDemo

此时目录中会生成 EfCoreDemo.csproj 和 Program.cs。打开 csproj 确认 <TargetFramework>net8.0</TargetFramework>，这是后面所有包版本选择的依据。建议同时执行一次 dotnet run，看到默认的 “Hello, World!” 输出，说明编译与运行链路是通的——先排除工具链问题，再引入 ORM，排错成本最低。

四、引入 EF Core 相关包

EF Core 采用“核心 + 提供程序 + 工具”的拆分方式。一个连接 SQL Server 的最小组合需要三个包：

• Microsoft.EntityFrameworkCore.SqlServer：SQL Server 提供程序，包含核心包依赖，负责把 LINQ 翻译成 T-SQL。
• Microsoft.EntityFrameworkCore.Design：设计时组件，迁移（migrations）命令依赖它。
• Microsoft.EntityFrameworkCore.Tools：提供 dotnet ef 相关的 PMC/CLI 工具支持。

用 CLI 安装时务必显式指定版本，避免默认拉到与目标框架不匹配的最新版：

dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 8.0.10
dotnet add package Microsoft.EntityFrameworkCore.Design --version 8.0.10
dotnet add package Microsoft.EntityFrameworkCore.Tools --version 8.0.10

安装完成后可用 dotnet list package 复查，三个包的版本应保持一致。版本不一致是后续迁移报错的常见原因，例如 Design 与 SqlServer 主次版本不同，可能导致设计时无法加载提供程序。

五、配置 SQL Server 连接

连接字符串描述“连到哪个实例、哪个数据库、用什么身份”。以本地默认实例为例，常见形式有两种：

// Windows 身份验证
Server=localhost;Database=EfCoreDemoDb;Trusted_Connection=True;TrustServerCertificate=True;

// SQL Server 身份验证
Server=localhost,1433;Database=EfCoreDemoDb;User Id=sa;Password=Your_password123;TrustServerCertificate=True;

其中 TrustServerCertificate=True 用于本地开发时跳过证书校验，生产环境应改用受信任证书。连接字符串不应硬编码在源码里，推荐放在 appsettings.json 中，再通过配置读取。先添加配置包：

dotnet add package Microsoft.Extensions.Configuration.Json --version 8.0.10

创建 appsettings.json：

{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=EfCoreDemoDb;Trusted_Connection=True;TrustServerCertificate=True;"
  }
}

并在 csproj 中确保该文件会被复制到输出目录：

<ItemGroup>
  <None Update="appsettings.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

六、写一个最小 DbContext 并验证连通

定义一个最简单的实体与上下文，用来验证环境是否真正打通：

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

public class AppDbContext : DbContext
{
    public DbSet<Product> Products => Set<Product>();

    protected override void OnConfiguring(DbContextOptionsBuilder options)
    {
        var config = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .Build();
        options.UseSqlServer(config.GetConnectionString("Default"));
    }
}

在 Program.cs 中执行一次 EnsureCreated 或查询，观察结果：

using var db = new AppDbContext();
db.Database.EnsureCreated();
Console.WriteLine($"数据库可访问：{db.Database.CanConnect()}");

如果输出 True，说明 SDK、项目、包、连接四者已经对齐，环境搭建完成。若失败，按下面的判断路径逐层排查，而不是盲目重装。

七、常见失败与判断依据

现象	可能原因	判断与处理
找不到 dotnet ef	未安装全局工具或 Tools 包	执行 dotnet tool install --global dotnet-ef
包还原失败	包版本与目标框架不匹配	核对 csproj 的 TargetFramework 与包主版本
连接超时	实例名/端口错误或服务未启动	先用 SSMS 或 sqlcmd 验证同一连接串
证书错误	未加 TrustServerCertificate	本地开发临时加上，生产改用受信任证书
登录失败	身份验证方式与连接串不符	Windows 验证用 Trusted_Connection，SQL 验证补 User Id/Password

到这里，一个可用的 EF Core 数据工程环境已经建立：SDK 提供工具链，控制台项目作为宿主，三个 EF Core 包提供 ORM 与迁移能力，SQL Server 连接通过配置文件注入。后续的实体建模、迁移生成与查询编写，都建立在这套已经验证连通的环境之上。