checkbinarycompat 1.0.11

CheckBinaryCompat

checkbinarycompat 是一个 dotnet 全局工具，它检查一组 .NET 程序集并查找潜在的兼容性问题。它可以在构建后运行，检查输出并生成报告或与基线进行验证。

它跟踪每个 .dll 中的每个程序集引用。对于每个引用，它检查被引用的 .dll 中是否有引用的 .dll 所期望的所有 API。这是为了在构建时检测二进制不匹配。这可以防止运行时异常，如 MissingMethodException、ReflectionTypeLoadException 等。

此外，它还会查看指定的 app.config 文件，并进行额外的检查，例如验证绑定重定向范围是否一致，以及被重定向到的 .dll 版本是否实际上存在。

它还可以确定给定一组“根”的所有递归程序集引用的闭包，并列出在闭包中未引用的程序集（可能未使用）。

安装

dotnet tool update -g checkbinarycompat

示例使用

在您的输出目录中运行工具（例如 bin\Debug\net472）。您可以使用 -s 递归地找到所有文件。默认为当前目录（非递归）。您可以选择一个或多个目录来查找，而不是当前目录。

checkbinarycompat

它将输出一个包含它找到的诊断的文件 BinaryCompatReport.txt。您可以通过排除文件和目录来调整和修剪报告文件。通过传递 -l 还可以输出 BinaryCompatReport.Assemblies.txt，其中包含分析的所有程序集及其版本和目标框架。

源代码

https://github.com/KirillOsenkov/MetadataTools/tree/main/src/BinaryCompatChecker

NuGet

https://nuget.net.cn/packages/checkbinarycompat

命令行参数

Usage: checkbinarycompat <file-spec>* <option>* @<response-file>*

Inspects assemblies and app.config files in a directory and reports potential issues.
Writes a report of possible issues to BinaryCompatReport.txt (sorted alphabetically).
File name/path can be customized using -out:<reportPath.txt>
If the file exists, it is used as a baseline.
If the report matches the baseline, it succeeds and returns exit code 0.
If the report doesn't match the baseline, the report is written and exit code is 1.
You can specify a separate baseline file using -baseline:<baselinePath.txt>
This way you can compare with the baseline and write the report to a different file.

File specs may be specified more than once. Each file spec is one of the following:

    * absolute directory path
    * directory relative to current directory
    * may include ** to indicate recursive subtree
    * may optionally end with:
        - a file name (a.dll)
        - a pattern such as *.dll
        - semicolon-separated patterns such as *.dll;*.exe;*.exe.config

    When no file-specs are specified, uses the current directory
    non-recursively. Pass -s for recursion.
    When no patterns are specified, uses *.dll;*.exe;*.dll.config;*.exe.config.

Options:
    All options with parameters (other than -out:) may be specified more than once.

    !<exclude-pattern>       Exclude a relative path or file pattern from analysis.
    -l                       Output list of visited assemblies to BinaryCompatReport.Assemblies.txt
    -s                       Recursive (visit specified directories recursively). Default is non-recursive.
    -closure:<file.dll>      Path to a root assembly of a closure (to report unused references).
    -resolve:<directory>     Additional directory to resolve reference assemblies from.
    -p:<pattern>             Semicolon-separated file pattern(s) such as *.dll;*.exe.
    -baseline:<baseline.txt> Optional, read <baseline.txt> instead of BinaryCompatReport.txt.
    -out:<report.txt>        Write report to <report.txt> instead of BinaryCompatReport.txt.
    -ignoreVersionMismatch   Do not report assembly version mismatches.
    -ivt                     Report internal API surface area consumed via InternalsVisibleTo.
    -embeddedInteropTypes    Report embedded interop types.
    @response.rsp            Response file containing additional command-line arguments, one per line.
    -?:                      Display help.

基线

默认情况下，所有错误和不一致记录到 BinaryCompatReport.txt。您可以传递 -out:<file.txt> 选项选择不同的文件。

文件已签入，并且在运行时，工具会检查实际的 BinaryCompatReport.txt 是否与签入的文件相同。如果它们不相同，工具将失败并覆盖签入的基础线。如果更改构建过程或依赖项导致报告了新的错误，并且这些错误都是合法的，需要更新签入的 BinaryCompatReport.txt 文件。为便利比较，文件已排序。

配置文件

工具可以选择性地接受零个或多个带有附加参数的 @response.rsp 文件。它们可以有任意的名称和扩展名。您可以列出多个目录、.dll 文件和应该包含或排除在分析之外的模板。如果工具在多个文件中看到了相同的程序集，它将随机选择一个。这是一个非确定性的来源，应该避免（每个程序集名称排除除了一个外的所有 .dll 文件）。在目录或文件路径前加上 ! 以排除它。请按方便进行排序文件。

配置文件还可以指定一个或多个 exe.config 或 dll.config 文件。将检查这些文件以查找绑定重定向和版本号。

输出构建工件

CI 构建可以发布“真实”的 BinaryCompatReport.txt 作为构建工件，以便您可以下载它，并用真实文件替换签入的副本。它还可以发布一些可能有帮助的其它报告文件。

• BinaryCompatReport.Assemblies.txt - 工具用作输入的所有程序集文件的有序列表以及它们的版本。指定 -l 选项以生成此文件。
• BinaryCompatReport.ivt.txt - 所有内部 API 消费列表，按暴露的 .dll 分组，然后是消费 .dll。指定 -ivt 选项以生成此文件。