dotnet-inspect-compatibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dotnet-inspect: compatibility and change analysis

dotnet-inspect: 兼容性与变更分析

Use this skill to decide whether a change is safe to adopt: what changed between two versions and what surface a library exposes. The scenario crosses commands —

diff

for change,

library

package

for the surface a single version exposes.

bash

dnx dotnet-inspect -y -- <command>

使用该工具判断某项变更是否可以安全采用：查看两个版本之间的差异，以及某个库暴露的接口面。该场景涉及多个命令——

diff

用于查看变更，

library

package

用于查看单个版本的接口面。

bash

dnx dotnet-inspect -y -- <command>

Did the API surface change?

API表面是否发生变更？

diff

compares a version range from a package, a platform (in-box) library, or two local builds. Pick the lens for the question you are answering:

bash

dnx dotnet-inspect -y -- diff --package System.Text.Json@9.0.0..10.0.0 --breaking
dnx dotnet-inspect -y -- diff --platform System.Runtime@9.0.0..10.0.0 --additive
dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll --changed

--breaking

for migration work,

--additive

for release notes,

--changed

for in-place member changes,

--name-only

for a quick list. Narrow with

-t TypeName

; widen with

--all

diff

命令用于比较包、平台（内置）库或两个本地构建版本之间的版本范围。根据你要解答的问题选择合适的视角：

bash

dnx dotnet-inspect -y -- diff --package System.Text.Json@9.0.0..10.0.0 --breaking
dnx dotnet-inspect -y -- diff --platform System.Runtime@9.0.0..10.0.0 --additive
dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll --changed

--breaking

用于迁移工作，

--additive

用于生成发布说明，

--changed

用于查看成员的原地变更，

--name-only

用于快速获取变更列表。使用

-t TypeName

缩小范围；使用

--all

扩大范围。

Did runtime behavior change? (allocations, exceptions)

运行时行为是否发生变更？（内存分配、异常）

-S "Analysis Diff"

compares body-level signal deltas between the two versions, not just the API shape. Rows are

Member | Signal | Old | New | Delta

, where

Signal

covers

allocations

copies

reflection

throws

catches

finallys

unsafe

constructed-exceptions

, and

optimization

shapes. This is how you catch an allocation regression or a change in exception coverage across versions. (For what these signals mean on a single version, see the

performance

and

correctness

skills.)

bash

dnx dotnet-inspect -y -- diff --package Foo@1.0.0..2.0.0 -S "Analysis Diff"
dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll -S "Analysis Diff" --changed

Use

Analysis Diff

for aggregate regression triage. To confirm whether one allocation occurrence was introduced at a caller-selected boundary, resolve one method and request the native Analysis Finding pairs:

bash

dnx dotnet-inspect -y -- diff --package Foo@1.4.0..1.5.0 \
  -t Foo.Parser -m Parse \
  --finding analysis.allocation

PairFinding.Added

with

Old=absent

and

New=present

confirms allocation onset.

Present

Removed

, and

Changed

remain distinct; do not infer onset from an aggregate allocation-count delta.

For a direct-call boundary in one caller method, select the call-site producer:

bash

dnx dotnet-inspect -y -- diff --package Foo@1.4.0..1.5.0 \
  -t Foo.Parser -m Parse \
  --finding analysis.call-site

Rows identify the callees.

PairFinding.Added

confirms a new direct-call occurrence;

Changed

reports retained-call facet changes such as moving into a loop.

For a definite unsafe-operation boundary in one method, select the unsafety producer:

bash

dnx dotnet-inspect -y -- diff --package Foo@1.4.0..1.5.0 \
  -t Foo.Parser -m Parse \
  --finding analysis.unsafety

Rows identify unsafe operation kinds and details.

PairFinding.Added

confirms introduction;

Present

and

Removed

distinguish persistence from disappearance without treating endpoint-local IL offsets as identity.

-S "Analysis Diff"

用于比较两个版本之间方法体层面的信号差异，而不仅仅是API形状。结果行格式为

成员 | 信号 | 旧值 | 新值 | 差异

，其中信号涵盖

allocations

（内存分配）、

copies

（复制操作）、

reflection

（反射）、

throws

（抛出异常）、

catches

（捕获异常）、

finallys

（finally块）、

unsafe

（不安全操作）、

constructed-exceptions

（构造异常）以及

optimization

（优化形状）。通过这种方式可以发现版本间的内存分配退化或异常覆盖范围的变化。（关于单个版本中这些信号的含义，请查看

performance

和

correctness

工具。）

bash

dnx dotnet-inspect -y -- diff --package Foo@1.0.0..2.0.0 -S "Analysis Diff"
dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll -S "Analysis Diff" --changed

使用

Analysis Diff

进行聚合退化问题分类。要确认某个内存分配是否是在调用者指定的边界处引入的，可以解析某个方法并请求原生的Analysis Finding对：

bash

dnx dotnet-inspect -y -- diff --package Foo@1.4.0..1.5.0 \
  -t Foo.Parser -m Parse \
  --finding analysis.allocation

PairFinding.Added

且

Old=absent

、

New=present

则确认内存分配是新增的。

Present

、

Removed

和

Changed

是不同的状态；不要从聚合的内存分配计数差异中推断新增情况。

对于某个调用方法中的直接调用边界，选择调用站点生成器：

bash

dnx dotnet-inspect -y -- diff --package Foo@1.4.0..1.5.0 \
  -t Foo.Parser -m Parse \
  --finding analysis.call-site

结果行标识被调用方。

PairFinding.Added

确认新的直接调用出现；

Changed

报告保留调用的方面变化，例如移入循环中。

对于某个方法中明确的不安全操作边界，选择不安全操作生成器：

bash

dnx dotnet-inspect -y -- diff --package Foo@1.4.0..1.5.0 \
  -t Foo.Parser -m Parse \
  --finding analysis.unsafety

结果行标识不安全操作的类型和细节。

PairFinding.Added

确认新增；

Present

和

Removed

区分持续存在和消失的情况，不会将端点本地的IL偏移视为标识。

Did the implementation change? (decompiled C# + IL + authored Source)

实现是否发生变更？（反编译C# + IL + 原始源代码）

-S "Implementation Diff"

selects Research-composed body evidence instead of the default API compatibility view. Rows identify the member, producer (

C#

IL

, or

Source

), change kind, and producer-owned evidence.

C#

is decompiled text;

Source

is checksum-verified authored SourceLink text. The lanes are peers: Source absence or failure stays visible and never replaces the C# lane. Narrow with

-t

and

-m

; use

--table

--tsv

, or

--jsonl

for columnar output.

bash

dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll \
  -S "Implementation Diff" --authored-source --repo /path/to/Foo \
  -t MyType -m HotPath

--repo

requires a fully qualified clone path. For

raw.githubusercontent.com

SourceLink URLs, it reads the committed blob at the SourceLink commit and verifies it against the PDB checksum before fetching the source body remotely. Package or PDB acquisition may still use the network; other SourceLink hosts do not use the local-repository path. Treat these rows as implementation evidence, not semantic-equivalence proof.

-S "Implementation Diff"

选择由Research合成的方法体证据，而非默认的API兼容性视图。结果行标识成员、生成器（

C#

、

IL

或

Source

）、变更类型以及生成器提供的证据。

C#

是反编译文本；

Source

是经过校验和验证的原始SourceLink文本。这些视图是对等的：源代码缺失或获取失败会保持可见，不会替换C#视图。使用

-t

和

-m

缩小范围；使用

--table

、

--tsv

或

--jsonl

获取列格式输出。

bash

dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll \
  -S "Implementation Diff" --authored-source --repo /path/to/Foo \
  -t MyType -m HotPath

--repo

需要完整的克隆路径。对于

raw.githubusercontent.com

的SourceLink URL，它会读取SourceLink提交中的已提交Blob，并在远程获取源代码主体前验证其与PDB校验和是否匹配。包或PDB的获取仍可能使用网络；其他SourceLink主机不使用本地仓库路径。请将这些结果视为实现证据，而非语义等价的证明。

What can be configured? (feature switches)

可配置项有哪些？（功能开关）

-S Switches

library

package --library

reports the behavior and trim/AOT knobs:

[FeatureSwitchDefinition]

s, runtime host configuration options, and

AppContext

switches.

bash

dnx dotnet-inspect -y -- library System.Text.Json -S Switches

在

library

或

package --library

命令中使用

-S Switches

，可查看行为和裁剪/AOT旋钮：

[FeatureSwitchDefinition]

、运行时主机配置选项以及

AppContext

开关。

bash

dnx dotnet-inspect -y -- library System.Text.Json -S Switches

Which versions to compare

要比较哪些版本

Version resolution is source-scoped. Use

Foo --version

for the best-known listed version: it reuses each source's matching latest entry and queries sources without one. Use

Foo --latest-version

to bypass those caches and refresh the newest version across all eligible configured sources, and

Foo --versions [N]

(add

--preview

) to list published versions. Unlisted versions are hidden unless

--include-unlisted

is explicit.

--versions-with-feed

retains each version/feed pair when source identity matters. Source declaration order is not precedence; load the

private-feeds

skill for source and credential workflows. Pin with

Foo@9.0.0

Foo@latest

For caller-driven onset or bisect work, resolve an inclusive addressable vector, then probe only the cells you choose:

bash

dnx dotnet-inspect -y -- package Foo@1.0.0..2.0.0 --versions
dnx dotnet-inspect -y -- type TargetType --package Foo@1.0.0..2.0.0 --at '#5'
dnx dotnet-inspect -y -- member TargetType TargetMember --package Foo@1.0.0..2.0.0 --at 1.6.0
dnx dotnet-inspect -y -- timeline --package Foo@1.0.0..2.0.0 \
  --type TargetType --members --at first --at last
dnx dotnet-inspect -y -- timeline --package Foo@1.0.0..2.0.0 \
  --type TargetType --member TargetMember \
  --finding analysis.unsafety --at first --at last

--at

accepts an exact version, one-based

#N

first

, or

last

. Vector resolution does not download every package; only the selected probe is acquired. The agent owns the search policy and bound. For recurrence-safe current onset, walk backward from the bad version until the first successful absence; use binary search only for a predicate known to be monotonic.

timeline

renders

Evaluations

and

Transitions

over the same vector. Omit

--at

for a zero-payload address view and midpoint recommendation, repeat

--at

for sparse probes, or pass

--at all

for explicit dense traversal. Choose the type-focused census with

--type-presence

--members

, or

--attributes

(aliases for

api.type

api.member

, and

api.attribute

). Add

--member

api.member

for one exact member identity track. The same member selector scopes

analysis.allocation

analysis.call-site

, and

analysis.unsafety

timelines to one method body. Gap-spanning transitions are evidence across the selected probes, not claims about the exact introduction or removal version.

The range and point probes identify a candidate boundary. Confirm the adjacent pair with Metadata's real Finding comparison rather than inferring introduction from probe text:

bash

dnx dotnet-inspect -y -- diff \
  --package System.Text.Json@8.0.6..9.0.0 \
  -t System.Text.Json.Schema.JsonSchemaExporter \
  -S "Finding Transitions"

An introduction boundary is a row with

PairFinding.Added

Old=absent

, and

New=present

PairFinding.Present

means the target exists at both endpoints; for a type target, no row means it exists at neither. Use

-m Type.Member:1

for an API member boundary. Use

--finding analysis.allocation

--finding analysis.call-site

, or

--finding analysis.unsafety

with exactly one method target for the corresponding Analysis boundary. Use

--finding csharp.line

--finding il.op

with exactly one method target to inspect native implementation-census transitions. Those lenses preserve complete, absent, and failed outcomes, including added or removed methods.

版本解析是源范围的。使用

Foo --version

获取最知名的列出版本：它会重用每个源的匹配最新条目，并查询没有条目的源。使用

Foo --latest-version

绕过这些缓存，刷新所有符合条件的配置源中的最新版本；使用

Foo --versions [N]

（添加

--preview

）列出已发布版本。未列出的版本默认隐藏，除非显式使用

--include-unlisted

。当源标识很重要时，

--versions-with-feed

会保留每个版本/源对。源声明顺序不代表优先级；加载

private-feeds

工具以处理源和凭据工作流。使用

固定版本：

Foo@9.0.0

、

Foo@latest

。

对于调用者驱动的起始点或二分查找工作，解析一个可寻址的向量，然后仅探查你选择的部分：

bash

dnx dotnet-inspect -y -- package Foo@1.0.0..2.0.0 --versions
dnx dotnet-inspect -y -- type TargetType --package Foo@1.0.0..2.0.0 --at '#5'
dnx dotnet-inspect -y -- member TargetType TargetMember --package Foo@1.0.0..2.0.0 --at 1.6.0
dnx dotnet-inspect -y -- timeline --package Foo@1.0.0..2.0.0 \
  --type TargetType --members --at first --at last
dnx dotnet-inspect -y -- timeline --package Foo@1.0.0..2.0.0 \
  --type TargetType --member TargetMember \
  --finding analysis.unsafety --at first --at last

--at

接受精确版本、基于1的

#N

、

first

或

last

。向量解析不会下载每个包；仅会获取选定的探查内容。工具负责搜索策略和边界。对于当前起始点的 recurrence-safe 检查，从有问题的版本向后遍历，直到首次发现问题不存在；仅当已知谓词是单调的时才使用二分查找。

timeline

在同一向量上呈现

Evaluations

和

Transitions

。省略

--at

可查看零负载地址视图和中点建议；重复

--at

可进行稀疏探查；或传递

--at all

进行显式密集遍历。选择以类型为中心的统计信息，使用

--type-presence

、

--members

或

--attributes

（分别是

api.type

、

api.member

和

api.attribute

的别名）。在

api.member

中添加

--member

可跟踪一个精确的成员标识。相同的成员选择器会将

analysis.allocation

、

analysis.call-site

和

analysis.unsafety

时间线限定为单个方法体。跨越间隙的转换是选定探查之间的证据，而非关于确切引入或移除版本的声明。

范围和点探查可确定候选边界。使用Metadata的真实Finding比较来确认相邻版本对，而非从探查文本中推断引入情况：

bash

dnx dotnet-inspect -y -- diff \
  --package System.Text.Json@8.0.6..9.0.0 \
  -t System.Text.Json.Schema.JsonSchemaExporter \
  -S "Finding Transitions"

引入边界是一行

PairFinding.Added

、

Old=absent

且

New=present

的结果。

PairFinding.Present

表示目标在两个端点都存在；对于类型目标，没有结果行表示它在两个端点都不存在。使用

-m Type.Member:1

查看API成员边界。对于恰好一个方法目标，使用

--finding analysis.allocation

、

--finding analysis.call-site

或

--finding analysis.unsafety

查看对应的Analysis边界。对于恰好一个方法目标，使用

--finding csharp.line

或

--finding il.op

检查原生实现统计的转换。这些视角会保留完整、缺失和失败的结果，包括新增或移除的方法。