dotnet-inspect-compatibility

dotnet-inspect：互換性と変更の分析

このスキルを使って、変更を安全に採用できるかどうかを判断します。2 つのバージョン間で何が変わったか、またライブラリがどのような API サーフェスを公開しているかを確認できます。このシナリオでは、コマンドを使い分けます。変更には diff、単一バージョンが公開するサーフェスには library／package を使います。

dnx dotnet-inspect -y -- <command>

API サーフェスに変更はありましたか？

diff は、パッケージ、プラットフォーム（インボックス）ライブラリ、または 2 つのローカルビルドのバージョン範囲を比較します。回答する質問に応じて、比較方法を選んでください。

dnx dotnet-inspect -y -- diff --package [email protected] --breaking
dnx dotnet-inspect -y -- diff --platform [email protected] --additive
dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll --changed

移行作業には --breaking、リリースノートには --additive、既存メンバーの変更には --changed、簡易リストには --name-only を使います。-t TypeName で範囲を絞り、--all で広げます。

各側に 1 つの Library がある通常の API 差分では、比較するエンドポイントのアセンブリ名、カルチャ、公開キー トークンが一致している必要があります。アセンブリバージョンは異なっていてもかまいません。CLI は、Web サイトの Compare を対象としたポータブルな Library 比較コントラクトを使用します。互換性評価がない型定義またはメンバーの変更も、Other API Changes（-S Changes --json／--jsonl／--tsv では unclassified）として表示されます。これらを安全または破壊的と見なさないでください。--breaking と --additive で選択されるのは、評価済みの分類のみです。

比較が不完全または拒否された場合は、ゼロ以外の値が返され、not compared と報告されます。ジェネリック制約の依存関係が見つからない場合は、検査失敗の証拠が保持されます。無効なマネージドイメージ入力の場合は、標準エラー出力に受け入れエラーが報告されます。これらの結果を「API に変更なし」と解釈しないでください。複数の Library を含むパッケージ、-m フィルタリング、Analysis Diff、Implementation Diff、Finding Transitions、および複数セクションを含むリクエストは、従来のルートを引き続き使用します。

共有された単一 Library の API 結果を完全な形で取得するには、投影なしの --json を使います。これは LibraryApiDiffOutcome を出力します。outcome は available、unavailable、または rejected で、完全な Document または型付きの失敗エンドポイントの証拠が含まれます。これは、以前の投影なしの {changes: ...} ビューに代わるものです。フィルターやセクションを明示的に指定した JSON では、引き続きプレゼンテーションスキーマが使われます。

同じ Content に Share と診断情報を加えるには、--envelope を使います。schema_version: 1 と result_kind: "library-api-diff" が含まれます。--all は指定できますが、型／分類フィルター、セクション、明示的な詳細度、行／行数の範囲指定、その他の Diff モードは指定できません。どちらの JSON 形式にも --compact を追加すると、空白をコンパクトにできます。投影を伴う操作やその他の Diff 操作との併用は拒否されます。Share は、順序付きの比較エンドポイントでは投影できません。 これによって Evidence のキャプチャが追加されることも、現在の Browser 投影が変更されることもありません。

この API 座標はどこに移動しましたか？

すべての API 変更ではなく、1 つの Type または Member の対応関係を確認する場合は、対象が所有する --match を使用します。

dnx dotnet-inspect -y -- type System.Text.Json.Schema.JsonSchemaExporter \
  --package [email protected] --match
dnx dotnet-inspect -y -- member System.Text.Json.JsonSerializer Deserialize:1 \
  --package [email protected] --match

エンドポイントは 2 つのリテラルなバージョンで、呼び出し元の順序を維持します。Member セレクターはソース側でのみ解決されます。一意の名前、Name:N、Name~digest、または --index N を使用してください。宛先の座標は API の対応関係から取得されるため、宛先側で同じ序数を個別に解決しないでください。この操作はアクセサー本体ではなく、宣言を照合します。Foo:1 や Foo~digest:1 のようなセレクターで、単一の Property／Event のアクセサーが序数によって選択される場合、そのセレクターは拒否されます。宣言を照合するには、アクセサーの序数を省略してください。オーバーロードされたインデクサー宣言から選択する序数は引き続き有効です。--tfm は 1 つの API サーフェスを選択し、--library はソース側の Library のみを絞り込み、--all は既存の IncludeAll API スコープに限りソース選択を広げます。宛先の宣言照合は、通常のアクセシビリティ変更とは独立して厳密に行われます。完全な Content には --json を、Content、Share、診断情報には --envelope を使用してください。このモードを History、--at、行プロジェクション、プロジェクションフィルター、セクション、body／source／Analysis リクエスト、またはパッケージ以外のソースと組み合わせないでください。ルートの match は、無関係な実装クローンの比較です。

Library 全体の API Diff と同様に、type／member --match は現在、ポータブルなシナリオでは順序付きの対応エンドポイントを表現できないため、share.kind: "nonProjectable" を報告します。それでも、完全な型付き照合結果と診断情報を確認するには、このエンベロープが役立ちます。ユーザーに一方のエンドポイントを渡すには、別途、正確な Package ベースの member ... --share url を実行してください。この URL は公開 API Overview を開き、対応関係の操作は保持しません。

ランタイムの動作（割り当て、例外）は変わりましたか？

-S "Analysis Diff" は、2 つのバージョン間の本文レベルのシグナルの差分を比較し、API の形状だけにとどまりません。行は Member | Signal | Old | New | Delta で、Signal は allocations、copies、reflection、throws、catches、finallys、unsafe、constructed-exceptions、optimization の形状を対象とします。これにより、バージョン間の割り当ての性能低下や、例外処理範囲の変化を検出できます。（単一バージョンでのこれらのシグナルの意味については、performance と correctness のスキルを参照してください。）

dnx dotnet-inspect -y -- diff --package [email protected] -S "Analysis Diff"
dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll -S "Analysis Diff" --changed

API の Changes、Analysis Diff、Implementation Diff ビューを組み合わせるには、-S @Diff を使用します。Finding Transitions は、エンドポイントの確認に特化したセマンティクスがこれらのビューと組み合わせられないため、引き続き完全一致の名前のみを対象とします。

集約された回帰のトリアージには Analysis Diff を使用します。呼び出し元が選択した境界で割り当ての発生が導入されたかを確認するには、1 つのメソッドを解決し、ネイティブな Analysis Finding のペアをリクエストします。

dnx dotnet-inspect -y -- diff --package [email protected] \
  -t Foo.Parser -m Parse \
  --finding analysis.allocation

Old=absent、New=present の PairFinding.Added は、割り当ての発生を確認するものです。Present、Removed、Changed はそれぞれ異なる状態です。集約された割り当て数の差分から、発生の有無を推測しないでください。

1 つの呼び出し元メソッド内にある直接呼び出し境界については、呼び出しサイトの生成元を選択します。

dnx dotnet-inspect -y -- diff --package [email protected] \
  -t Foo.Parser -m Parse \
  --finding analysis.call-site

行は呼び出し先を示します。PairFinding.Added は新しい直接呼び出しの出現を確認し、Changed はループ内への移動など、継続して存在する呼び出しの属性の変化を報告します。

1 つのメソッド内にある明確な安全でない操作の境界については、安全性違反の生成元を選択します。

dnx dotnet-inspect -y -- diff --package [email protected] \
  -t Foo.Parser -m Parse \
  --finding analysis.unsafety

行は安全でない操作の種類と詳細を示します。PairFinding.Added は導入を確認します。Present と Removed により、エンドポイントごとの IL オフセットを同一性として扱うことなく、継続と消失を区別できます。

実装に変更はありましたか？（逆コンパイルされた C# + IL + PDB ソース）

--implementation は、選択範囲を正確に指定する -S "Implementation Diff" の慣例的な短縮形です。デフォルトの API 互換性ビューの代わりに、Research が構成した本体の証拠を選択します。行には、メンバー、生成元（C#、IL、または PDB Source）、変更の種類、生成元が所有する証拠が示されます。C# は逆コンパイルされたテキストです。PDB Source は Portable-PDB で選択され、チェックサム検証済みのテキストで、ローカルまたは SourceLink 経由で取得されます。各レーンは同等の位置付けです。PDB ソースがない場合や取得に失敗した場合もその状態が表示され、C# レーンに置き換わることはありません。-t と -m で絞り込み、列形式の出力には --table、--tsv、または --jsonl を使用します。

dnx dotnet-inspect -y -- diff --library old/Foo.dll..new/Foo.dll \
  --implementation --pdb-source --repo /path/to/Foo \
  -t MyType -m HotPath

--repo には、完全修飾されたクローンパスが必要です。raw.githubusercontent.com の SourceLink URL の場合、SourceLink のコミット時点でコミットされた blob を読み取り、ソース本体をリモートで取得する前に PDB のチェックサムと照合します。パッケージまたは PDB の取得には、引き続きネットワークを使用する場合があります。他の SourceLink ホストでは、ローカルリポジトリのパスは使用されません。これらの行は実装の証拠として扱い、意味的同等性の証明とはみなさないでください。

エンドポイントごとにライブラリを 1 つ、メソッドを 1 つ明示的に選択した場合、C# と IL に変更がなくても、--pdb-source は作成時のソースを比較します。たとえば、1 + 2 を 3 に変更すると、コンパイル済みのどちらのレーンにも変更はありませんが、ソースには変更が生じる場合があります。選択した Source レーンでは、変更なしまたは利用不可の証拠も報告されます。取得に失敗した場合はその状態を保持し、テキストがないことを削除として扱いません。より広い選択範囲では、ローカルで変更されたメンバーに引き続き情報を追加します。

何を設定できますか？（機能スイッチ）

library または package --library で -S Switches を指定すると、動作とトリミング／AOT の設定項目が報告されます。これには [FeatureSwitchDefinition]、ランタイムホストの構成オプション、および AppContext スイッチが含まれます。

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

比較するバージョン

バージョン解決はソースごとに行われます。最新の掲載バージョンを1行取得するには package Foo --versions -n 1 を、従来の候補キャッシュを再利用せず、設定済みのすべてのソースから最新情報を取得する必要がある場合は package Foo@latest --versions を使用します。特定のバージョンを検証するには package Foo --version 1.2.3 を、公開済みバージョンを一覧表示するには Foo --versions（N行を表示するには -n N を、プレリリースを表示するには --preview を追加）を使用します。掲載されていないバージョンは、--include-unlisted を明示しない限り非表示になります。ソースの識別が重要な場合は、--versions-with-feed を使うと各バージョンとフィードの組み合わせが保持されます。ソースの宣言順は優先順位を示すものではありません。ソースと認証情報のワークフローについては、private-feeds スキルを読み込んでください。@ を使ってバージョンを固定します：[email protected]、Foo@latest。

呼び出し側主導で開始点を特定したり二分探索したりする場合は、アクセス可能な範囲を両端を含めて解決し、選択した位置だけを調査します。

dnx dotnet-inspect -y -- package [email protected] --versions
dnx dotnet-inspect -y -- type TargetType --package [email protected] --at '#5'
dnx dotnet-inspect -y -- member TargetType TargetMember --package [email protected] --at 1.6.0
dnx dotnet-inspect -y -- diff --history --package [email protected] \
  --type TargetType --members --at first --at last
dnx dotnet-inspect -y -- diff --history --package [email protected] \
  --type TargetType --member TargetMember \
  --finding analysis.unsafety --at first --at last

--at には、正確なバージョン、1 始まりの #N、first、または last を指定できます。範囲の解決時にすべてのパッケージがダウンロードされるわけではありません。取得されるのは、選択されたプローブのみです。検索方針と範囲はエージェントが決定します。再発を考慮した現在の開始点を調べるには、不具合のあるバージョンから後方にたどり、問題が初めて存在しないと確認できた位置まで進みます。述語が単調であると分かっている場合に限り、二分探索を使用してください。

オンラインの API／履歴範囲では、設定済みのフォルダフィードと HTTP フィードがサポートされます。検出を完了させる必要があり、各プローブで取得できるのは、その座標を報告したソースからのみです。これらの範囲は掲載済みバージョンのみを対象とします。--include-unlisted を指定したメタデータ一覧では、序数が異なる場合があります。掲載されていない座標を調べるには、正確なバージョンを指定してください。ローカルのペイロードキャッシュでは設定済みの権限情報が保持されます。HTTP のペイロードは一時ストレージに保存され、次回の実行時に再ダウンロードされます。

Diff History は、同じ範囲に対する Evaluations と Transitions を表示します。範囲全体を評価するには --at を省略し、明示的なチェックポイントを指定するには繰り返し指定し、適応型の二分探索には --max-probes を使用します。母集団に対する決定論的な相対調査を行うには --sample-percent P を追加し、必要に応じて --max-probes で上限を設定します。メジャーバージョンごとに代表バージョンを1つ選ぶには --major-versions を使用します。API の検出結果では、最初の安定版が選ばれます。プレビュー版のみのメジャーバージョンでは、最新のプレリリースが代わりに選ばれます。一方、Analysis の検出結果では、各メジャーバージョンで条件を満たす最新バージョンが選ばれます。型に焦点を当てた調査には、--type-presence、--members、または --attributes（api.type、api.member、api.attribute のエイリアス）を使用します。api.member に --member を追加すると、特定のメンバー識別情報の追跡に絞り込めます。同じメンバーセレクターを使うと、analysis.allocation、analysis.call-site、analysis.unsafety の履歴を1つのメソッド本体に絞り込めます。範囲をまたぐ遷移が示すのは、選択したプローブ間の証拠であり、正確な導入バージョンや削除バージョンを断定するものではありません。オンラインの推奨コマンドには、ソース／構成、TFM、プレリリース、可視性の各オプションが保持されるため、次のプローブを別の作業ディレクトリから実行できます。

範囲プローブと特定バージョンのプローブで候補となる境界を特定します。導入時点をプローブのテキストから推測するのではなく、Metadata の実際の Finding 比較で隣接する2つのバージョンを確認してください。

dnx dotnet-inspect -y -- diff \
  --package [email protected] \
  -t System.Text.Json.Schema.JsonSchemaExporter \
  -S "Finding Transitions"

導入境界とは、PairFinding.Added、Old=absent、New=present の行です。PairFinding.Present は対象が両方の端点に存在することを意味します。型対象の場合、行がないときは、対象がどちらの端点にも存在しません。API メンバーの境界を調べるには -m Type.Member:1 を使用します。対応する Analysis の境界を調べるには、メソッド対象を正確に1つ指定して、--finding analysis.allocation、--finding analysis.call-site、または --finding analysis.unsafety を使用します。ネイティブ実装の調査における遷移を調べるには、メソッド対象を正確に1つ指定して、--finding csharp.line または --finding il.op を使用します。これらのレンズでは、完全、欠落、失敗の各結果に加えて、メソッドの追加や削除も保持されます。