msbuild-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MSBuild Server for CLI Caching

用于CLI缓存的MSBuild Server

Use the MSBuild Server to cache evaluation results across CLI builds, matching the performance advantage Visual Studio gets from its long-lived MSBuild process.

使用MSBuild Server在CLI构建之间缓存评估结果，以此匹配Visual Studio从其长期运行的MSBuild进程中获得的性能优势。

When to Use

使用场景

Small incremental builds from CLI (
```
dotnet build
```
) are slower than expected
Developers notice that VS builds are faster than CLI builds for the same project
CI agents run many sequential builds of the same repo

来自CLI的小型增量构建（
```
dotnet build
```
）比预期慢
开发人员注意到对于同一项目，VS构建比CLI构建更快
CI代理对同一仓库运行多次连续构建

When Not to Use

不适用场景

IDE-based builds (Visual Studio already uses a long-lived MSBuild process)
One-off builds where cold-start overhead is acceptable
Build correctness issues are suspected (disable the server to isolate the problem)

基于IDE的构建（Visual Studio已使用长期运行的MSBuild进程）
冷启动开销可接受的一次性构建
怀疑存在构建正确性问题时（禁用服务器以隔离问题）

Inputs

输入项

Input	Required	Description
Shell context	No	The shell where the environment variable will be set (bash, PowerShell, or Windows persistent)

输入项	是否必填	描述
Shell环境	否	将设置环境变量的Shell（bash、PowerShell或Windows持久化环境）

Workflow

工作流程

Step 1: Confirm CLI context

步骤1：确认CLI环境

Verify the developer is building from the command line (

dotnet build

), not from Visual Studio or another IDE. The MSBuild Server provides no benefit inside an IDE.

验证开发人员是否通过命令行（

dotnet build

）进行构建，而非Visual Studio或其他IDE。MSBuild Server在IDE内无法提供任何收益。

Step 2: Set the environment variable

步骤2：设置环境变量

bash

undefined

bash

undefined

Bash / CI

export MSBUILDUSESERVER=1

PowerShell

$env:MSBUILDUSESERVER = "1"

Windows (persistent)

setx MSBUILDUSESERVER 1

undefined

setx MSBUILDUSESERVER 1

undefined

Step 3: Validate improvement

步骤3：验证性能提升

Run two sequential builds of the same project and compare times:

First build (cold):
```
dotnet build
```
-- server starts, no cache benefit
Second build (warm):
```
dotnet build
```
-- should be noticeably faster

The most noticeable improvement is in repos with many projects or complex

Directory.Build.props

chains.

运行同一项目的两次连续构建并比较耗时：

首次构建（冷启动）：
```
dotnet build
```
-- 服务器启动，无缓存收益
第二次构建（热启动）：
```
dotnet build
```
-- 应该明显更快

在包含多个项目或复杂

Directory.Build.props

链的仓库中，性能提升最为显著。

Validation

验证清单

```
MSBUILDUSESERVER=1
```
is set in the shell
Second sequential build is faster than the first
```
dotnet build-server shutdown
```
followed by a rebuild confirms the server restarts cleanly

```
MSBUILDUSESERVER=1
```
已在Shell中设置
第二次连续构建比首次更快
执行
```
dotnet build-server shutdown
```
后重新构建，确认服务器已干净重启

Common Pitfalls

常见陷阱

Pitfall	Solution
Expecting improvement in Visual Studio	VS already uses long-lived MSBuild nodes; the server adds no benefit
Build correctness issues after enabling	Run `dotnet build-server shutdown` to reset; if issues persist, disable the server
Server process using unexpected memory	The server persists in background; shut down with `dotnet build-server shutdown` when idle

陷阱	解决方案
期望在Visual Studio中获得性能提升	VS已使用长期运行的MSBuild节点；服务器无法带来额外收益
启用后出现构建正确性问题	执行 `dotnet build-server shutdown` 重置；若问题仍存在，禁用服务器
服务器进程占用意外内存	服务器在后台持续运行；空闲时使用 `dotnet build-server shutdown` 关闭