.NET Framework の互換性の診断

 

本記事は、マイクロソフト本社の .NET Blog の記事を抄訳したものです。 【元記事】 .NET Framework Compatibility Diagnostics 2016/3/3

 

今回は、.NET チームでソフトウェア エンジニアを務める Taylor Southwick の記事をご紹介します。

 

概要

.NET Framework 4 の更新は互換性の高いインプレース更新として配信されているため、ユーザーはアプリケーションをそのまま、最も安全性の高い最新バージョンの .NET Framework で実行させることができます。しかし、一部の保証外の動作、またはドキュメントに記載されていない動作に依存するアプリケーションでは、以前のバージョンのときと挙動が変わってしまうことがあります。これまではこのような変化を見つけることは困難でしたが、.NET のバージョンをアップグレードする際の動作の変化を識別できるようにするために、.NET の互換性診断ツール「.NET Compatibility Diagnostics」が公開されました。

 

.NET Compatibility Diagnostics

特定のバージョンでどのような更新が実装されたかを確認するには、これまで MSDN のドキュメントを参照するか、ApiPort ツール (英語) を実行するかしかありませんでした。このため、既存のアプリケーションを新しいバージョンの .NET Framework で実行する場合に、特定の API を使用することで対象のアプリケーションの機能にどのような影響があるのかを詳細に把握できるツールが必要とされていました。アップグレードによる影響やそれに対してどのような変更を行う必要があるのかを判断できれば、新しいバージョンの .NET Framework で問題なく動作させることができます。

この診断ツールは Roslyn で構築されているため、Visual Studio 2015 を必要とし、通常のコンパイル処理の一部として実行されます。このツールの目的は、新しいバージョンの .NET Framework に移行した場合に、意図しない動作の変化が確認されているかまたはその可能性がある API の使用方法やパターンを通知することです。動作が変化するケースは非常にまれで、めったに起こるものではありませんが、特定のタイプのコードでは発生しやすい傾向があります。マイクロソフトでは、互換性に関する問題が発生する一般的な使用パターンを特定、分析し、プロジェクト内に存在するこのような問題を探し出すことに最善を尽くしています。しかし、互換性に関する問題にはさまざまな要素が絡んでいるため、診断結果については、断定的なものではなく注意喚起とお考えください。リスク分析や移行プロセスの中の 1 つの選択肢としては、このツールの使用を強くお勧めします。

この診断機能は .NET Framework 4.x シリーズのバージョン (.NET Framework 4.0 から 4.6.1 への移行、.NET Framework 4.5 から 4.5.2 への移行など) に関する情報の提供を想定しており、現時点では他のバージョンの .NET Framework からの移行には対応していません。

 

セットアップ

.NET Compatibility Diagnostics は nuget.org で公開されています。通常の NuGet のインストール方法で .NET 4.0 またはそれ以降をターゲットとする任意のプロジェクトにインストールできます。この診断ツールをプロジェクトに追加するには、次の手順に従います。

1. Visual Studio 2015 でソリューションを開きます。
2. プロジェクト ノードを右クリックして [Manage NuGet Packages] をクリックします。
3. 検索ボックスで「Microsoft.DotNet.FrameworkCompatibilityDiagnostics」を検索します。
4. [Install] をクリックします。ライセンスと使用条件が表示されるので、内容を確認して承諾します。

これでプロジェクトにアナライザーがインストールされ、通常のコンパイル処理中にコードの分析が実行されるようになります。dotnet_compatibility.json というファイルがプロジェクトに追加されますが、このファイルは、分析時に移行計画をアナライザーに伝える役割を果たします。既定ではファイルは次のようになっています。

 {
  "TargetFramework": {
    "Current": "4.0",
    "Planned": "4.0"
  },
  "RuntimeFramework": {
    "Current": "4.0",
    "Planned": "4.6.1"
  }
}

この設定により、互換性に影響する疑いのある更新のうち必要なものだけを検査することができます。ファイルには、TargetFramework と RuntimeFramework. の 2 つのセクションがあります。コード ベースを新しいバージョンの .NET に移行するときには、ターゲットとするフレームワークと実行時のフレームワークについて理解することが重要です (詳細については「.NET Framework 4.5 移行のバージョンをターゲットにして実行する」を参照してください)。移行パスとしては、ターゲット フレームワークを変更せずランタイムのみを変更することをお勧めします。そうすることで、新しいバージョンのフレームワークをターゲットとしてコンパイルすることを宣言したために、意図せず不測の動作を引き起こすという事態を回避できます。より新しいバージョンのランタイムに多数の更新が実装されていても、ターゲットフレームワークを変更しないことでそれらが無効化されるため、新しいバージョンでの更新を無視して従来の動作を維持することができます。

上の例では、現在および移行後の TargetFramework と、現在の RuntimeFramework には 4.0 が設定され、移行後の RuntimeFramework のみ違う値が設定されています。これによりアナライザーは、ターゲット フレームワークが .NET 4.0 のままランタイムを 4.0 から 4.6.1 (現時点の最新バージョン) にアップグレードする場合にコードに影響を与える可能性のある更新のみを警告します。この設定はプロジェクトごとに dotnet_compatibility.json ファイルに保存されます。

 

使用方法

ここまででアナライザーがインストールされ、構成が完了しました。これで、問題がある場合に Visual Studio のエラー リストに追加されるようになりました。すべての問題を表示するには、フィルターのドロップダウンリストで [Build + Intellisense] を選択します。重要度が情報レベルの診断結果は、このように選択した場合にのみ表示されます。

リストに表示された問題は、新しいランタイムまたはターゲット フレームワークに移行したときにアプリケーションの動作に影響を与える可能性があります。この部分に的を絞って動作テストを実施し、意図したとおりに動作しているかどうかを確認することを強くお勧めします。

対象バージョンでの更新によっては、使用パターンや API を変更して対応する必要があります。これについては、Visual Studio の電球マークで情報を提供します。たとえば 4.6.1 に実装された更新では、HtmlTextWriter で <br /> トークンを使用した際に影響があります。このため、従来と同じように動作する新しいパターンに切り替えて、バージョンの移行に対応します。

このような対応方法は .NET Compatibility Diagnostics で検出された問題の一部に対してのみ有効であり、問題の大部分では、アナライザーが判断を下すうえで利用する情報以外の情報も必要となります。このため、問題を解決するには開発者のみが入手できる情報も併せて考慮することが不可欠です。場合によっては、リファクタリングするケースや、注意事項に対して何も対処しないケースも考えられます (その方法については後のセクションで説明します)。このツールは、コード内の影響を受ける可能性のある部分について注意を喚起するものであり、決定的な指示を与えるものではありません。この注意事項と開発者のコードに関する知識を組み合わせることで、新しいバージョンのフレームワークへうまく移行するために最善の判断を下せるようになります。

 

アナライザーの警告のカスタマイズ

コンパイル中に、さまざまなメッセージが Visual Studio のエラー リストに表示されます。重要度のレベルは、マイクロソフトが認識しているコードへの影響度によって決まります。

 

重要度	説明
情報	更新内容について把握しておいたほうがよいが、コードへの影響はほとんどないと考えられます。詳細な調査を行い、意図しない副次的な影響がないように確認することをお勧めします。
注意	更新によりコードが影響を受け、意図しない動作の変化が発生する可能性があります。詳細な調査が必要です。
エラー	更新によりコードが影響を受け、意図しない動作の変化が発生する原因となります。詳細な調査が必要です。
なし	診断の結果、アナライザーによる警告がありませんでした。

重要度のレベルは主観的なものであるため、特定のアプリケーションで診断された問題に対して誤った重要度が割り当てられた場合、Visual Studio のソリューションエクスプローラーでアナライザー ノードを開いて、そのプロジェクトでのレベルを変更することができます。重要度を変更する場合は、Microsoft.DotNet.FrameworkCompatibilityDiagnostics(.CSharp|.VisualBasic) の表示されているアナライザー中から該当する問題を見つけて右クリックします。

この操作によって、{プロジェクト名}.ruleset というファイルがプロジェクト内に作成されます。このファイルは、他のユーザーがこのプロジェクトを開いたときに同じエクスペリエンスが提供されるためのバージョン管理に使用されます。

 

まとめ

.NET Compatibility Diagnostics は、新しいバージョンの .NET Framework にアップグレードする際に発生する可能性のある互換性関連の問題について情報を提供します。診断結果は疑いのある問題について注意を促すためのものであり、すべての問題が検出されることを保証するものではありません。また、検出された問題によって必ず動作に変化が生じるとは限りません。この診断ツールの目的は、リスク分析や .NET Framework 4.x バージョン間でのコード ベース移行プロセスを支援することです。このツール (英語) をご利用になり、netfxcompat@microsoft.com までご意見をお寄せいただけますと幸いです。