.NET开发文档 聚焦 C#、.NET 平台、ASP.NET Core 与工程实践的静态文档站
版本: 3.1.0 文档中心

.NET CLI 与项目结构

系统讲解 .NET CLI、解决方案结构、csproj、NuGet、配置文件与发布流程，帮助建立 .NET 工程基础认知。

.NET CLI 与项目结构

很多人学习 .NET 时，一开始就只会在 Visual Studio 或 Rider 里点按钮，结果一离开 IDE 就不知道项目是怎么创建、构建、运行和发布的。长期来看，这种学习方式会让你对工程结构缺乏理解。

所以，学习 .NET 时一定要把 .NET CLI 和项目结构单独拿出来系统掌握。因为这部分不是“可有可无的命令行知识”，而是 .NET 工程能力的基础。

第一章 为什么要先学 .NET CLI

.NET CLI 的核心价值在于：它把项目生命周期里的关键动作都统一了。

你需要能回答下面这些问题：

  • 项目是怎么创建出来的？
  • 依赖是怎么恢复的？
  • 代码是怎么编译的？
  • 程序是怎么运行的？
  • 测试和发布命令在哪里执行？

如果这些问题只会在 IDE 里机械点按钮，不理解命令本身，那么你进入真实项目后会很容易卡住。

可以把 .NET CLI 理解成 .NET 项目的统一入口：

创建 -> 恢复依赖 -> 构建 -> 运行 -> 测试 -> 发布

第二章 认识 dotnet 命令

2.1 查看当前环境

最基础的两个命令：

dotnet --version
dotnet --info
  • dotnet --version：查看 SDK 版本
  • dotnet --info：查看更完整的环境信息，包括 SDK、Runtime、系统平台等

如果你本机安装了多个 SDK，后续还可能会接触 global.json 来锁定版本。

2.2 常见高频命令

dotnet new
dotnet restore
dotnet build
dotnet run
dotnet test
dotnet publish
dotnet add package
dotnet add reference

它们可以这样理解：

命令 作用
dotnet new 创建项目或解决方案模板
dotnet restore 恢复 NuGet 依赖
dotnet build 编译项目
dotnet run 运行项目
dotnet test 执行测试
dotnet publish 发布构建产物
dotnet add package 引入 NuGet 包
dotnet add reference 添加项目引用

第三章 从零创建一个 .NET 项目

3.1 查看模板

dotnet new list

这个命令会列出本机可用模板。常见模板包括：

  • console
  • classlib
  • webapi
  • mvc
  • xunit

3.2 创建控制台项目

dotnet new console -n DemoConsole

创建完成后，进入目录运行：

dotnet run

3.3 创建 Web API 项目

dotnet new webapi -n DemoApi

运行：

dotnet run

如果启动成功，终端通常会看到监听地址，例如：

Now listening on: http://localhost:5000
Now listening on: https://localhost:5001

第四章 .sln 和 .csproj 到底是什么

这是初学者最容易混淆的两个概念。

4.1 解决方案：.sln

.sln 是解决方案文件，用来组织多个项目。

它更像一个“项目集合清单”，本身不是业务代码配置文件。

4.2 项目文件：.csproj

.csproj 是单个项目的核心配置文件。它描述：

  • 项目使用哪种 SDK
  • 目标框架是什么
  • 引用了哪些 NuGet 包
  • 引用了哪些其他项目
  • 编译与发布配置是什么

4.3 一个典型的后端项目结构

DemoSolution.sln
src/
  Demo.Api/
    Demo.Api.csproj
  Demo.Application/
    Demo.Application.csproj
  Demo.Domain/
    Demo.Domain.csproj
  Demo.Infrastructure/
    Demo.Infrastructure.csproj
tests/
  Demo.Tests/
    Demo.Tests.csproj

你可以这样理解：

  • .sln 负责组织多个项目
  • 每个 .csproj 负责描述各自项目

第五章 手把手创建一个解决方案

5.1 创建解决方案

dotnet new sln -n DemoSolution

5.2 创建多个项目

dotnet new webapi -n Demo.Api
dotnet new classlib -n Demo.Application
dotnet new classlib -n Demo.Domain
dotnet new classlib -n Demo.Infrastructure
dotnet new xunit -n Demo.Tests

5.3 加入解决方案

dotnet sln DemoSolution.sln add .\Demo.Api\Demo.Api.csproj
dotnet sln DemoSolution.sln add .\Demo.Application\Demo.Application.csproj
dotnet sln DemoSolution.sln add .\Demo.Domain\Demo.Domain.csproj
dotnet sln DemoSolution.sln add .\Demo.Infrastructure\Demo.Infrastructure.csproj
dotnet sln DemoSolution.sln add .\Demo.Tests\Demo.Tests.csproj

5.4 添加项目引用

例如让 Demo.Api 依赖 Demo.Application：

dotnet add .\Demo.Api\Demo.Api.csproj reference .\Demo.Application\Demo.Application.csproj

如果 Demo.Application 又依赖 Demo.Domain：

dotnet add .\Demo.Application\Demo.Application.csproj reference .\Demo.Domain\Demo.Domain.csproj

这一步本质上会修改 .csproj 里的 ProjectReference。

第六章 csproj 文件详解

6.1 一个常见的 csproj 示例

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
  </ItemGroup>
</Project>

6.2 核心字段解释

Sdk

<Project Sdk="Microsoft.NET.Sdk.Web">

表示当前项目使用哪种 SDK。

常见值：

  • Microsoft.NET.Sdk：普通类库、控制台项目
  • Microsoft.NET.Sdk.Web：Web 项目

TargetFramework

<TargetFramework>net8.0</TargetFramework>

表示项目的目标框架版本。

常见值：

  • net8.0
  • net9.0

Nullable

<Nullable>enable</Nullable>

启用可空引用类型分析，有助于尽早发现空引用问题。

ImplicitUsings

<ImplicitUsings>enable</ImplicitUsings>

表示自动引入一批常见命名空间，减少样板 using。

6.3 NuGet 依赖引用

<ItemGroup>
  <PackageReference Include="Dapper" Version="2.1.35" />
</ItemGroup>

6.4 项目引用

<ItemGroup>
  <ProjectReference Include="..\Demo.Application\Demo.Application.csproj" />
</ItemGroup>

区分这两种引用很重要：

  • PackageReference：引用外部包
  • ProjectReference：引用本解决方案里的其他项目

第七章 NuGet 包管理

7.1 安装包

dotnet add package Dapper

如果要指定版本：

dotnet add package Dapper --version 2.1.35

7.2 删除包

dotnet remove package Dapper

7.3 恢复依赖

dotnet restore

通常 dotnet build 和 dotnet run 会隐式触发 restore，但在 CI 或排查环境问题时，你仍然要知道 restore 是一个独立动作。

7.4 常见问题

包恢复失败

可能原因：

  • 网络问题
  • NuGet 源配置错误
  • 包版本写错
  • 本地缓存异常

不同项目包版本不一致

中大型项目里应尽量统一版本，否则容易出现兼容性问题。

第八章 构建、运行、测试与发布

8.1 构建

dotnet build

作用：

  • 还原依赖
  • 编译代码
  • 生成构建输出

8.2 运行

dotnet run

如果是 Web 项目，也可以指定项目：

dotnet run --project .\src\Demo.Api\Demo.Api.csproj

8.3 测试

dotnet test

如果是多项目解决方案，执行测试时往往会自动识别测试项目。

8.4 发布

dotnet publish -c Release -o .\publish

常见参数说明：

  • -c Release：使用 Release 配置
  • -o：指定输出目录

发布后的目录通常包含：

  • 应用程序集
  • 依赖项
  • 配置文件
  • 运行所需资源

第九章 配置文件如何组织

在 ASP.NET Core 项目中，最常见的配置文件包括：

  • appsettings.json
  • appsettings.Development.json
  • 环境变量
  • 命令行参数

9.1 一个基础示例

{
  "ConnectionStrings": {
    "Default": "Server=.;Database=DemoDb;Trusted_Connection=True;"
  },
  "Jwt": {
    "Issuer": "demo-api",
    "Audience": "demo-client",
    "Key": "your-secret-key"
  }
}

9.2 配置组织建议

  • 公共配置放在 appsettings.json
  • 开发环境差异配置放在 appsettings.Development.json
  • 密钥、连接串等敏感信息优先用环境变量或密钥管理方案

9.3 常见误区

把生产密钥直接提交到仓库

这是非常常见也非常危险的错误。

分环境配置混乱

如果开发、测试、生产环境配置没有明确分层，部署时极容易出问题。

第十章 多项目结构如何思考

初学者经常问：项目为什么要拆这么多层？

10.1 小项目可以简单一些

如果只是学习或小型项目，一个 Web API 项目加少量文件夹就够了。

10.2 中型项目常见分层

例如：

Demo.Api
Demo.Application
Demo.Domain
Demo.Infrastructure
Demo.Tests

大致职责可以这样理解：

项目 作用
Demo.Api 接口入口、控制器、启动配置
Demo.Application 业务服务、应用用例
Demo.Domain 实体、领域对象、接口抽象
Demo.Infrastructure 数据库、缓存、第三方集成
Demo.Tests 测试代码

10.3 不要为了分层而分层

如果项目非常小，强行拆太多层只会增加理解成本。分层的目的是让职责清晰，而不是把简单问题复杂化。

第十一章 global.json、SDK 版本与环境一致性

当团队成员安装了多个 SDK 版本时，项目可能需要显式指定使用哪个 SDK。

示例：

{
  "sdk": {
    "version": "8.0.204"
  }
}

这样可以减少“我这里能跑、你那里不能跑”的环境差异问题。

第十二章 发布时要特别关注什么

发布不只是执行一条 dotnet publish 命令，更要检查下面这些内容：

12.1 目标框架是否正确

比如项目到底是 net8.0，还是更高版本，运行机器是否兼容。

12.2 配置是否完整

需要确认：

  • 连接串
  • JWT 配置
  • 文件存储路径
  • 日志目录
  • 缓存连接信息

12.3 环境变量是否准备好

很多线上问题不是代码错误，而是环境没配完整。

12.4 数据库迁移与初始化

如果项目依赖数据库结构，发布前还要考虑迁移是否已执行。

第十三章 初学者最容易踩的坑

13.1 只知道 dotnet run，不知道项目怎么组织

会启动不代表懂工程。

13.2 把 .sln 和 .csproj 混为一谈

它们职责不同，一定要分清。

13.3 不理解包引用和项目引用的区别

这会导致你看不懂真实项目里的依赖结构。

13.4 遇到问题只会重装 IDE

很多时候问题其实出在：

  • SDK 版本
  • NuGet 恢复
  • 配置文件
  • 环境变量

这些都和 IDE 无关。

第十四章 入门阶段至少要掌握什么

如果你刚开始学 .NET，至少要具备下面这些能力：

  1. 会用 dotnet new 创建项目
  2. 会用 dotnet build、dotnet run、dotnet test、dotnet publish
  3. 能看懂 .sln 和 .csproj
  4. 会添加 NuGet 包和项目引用
  5. 能理解配置文件和环境变量的基本关系
  6. 能看懂一个基础多项目解决方案结构

这部分能力一旦打稳，后面学习 ASP.NET Core、EF Core、测试和部署时，很多问题都会自然串起来。

下一步阅读

本文小结

.NET CLI 和项目结构不是“附属知识”，而是 .NET 开发的工程底座。真正理解这层内容后，你就不再只是“会点 IDE 按钮”，而是能够独立地：

  • 创建项目
  • 组织解决方案
  • 管理依赖
  • 构建运行
  • 测试发布

只有把这一层掌握清楚，后面的 Web 开发、数据库访问和项目交付才会真正顺畅。