.NET Framework から .NET Core への移植の概要Overview of porting from .NET Framework to .NET Core

現在 .NET Framework で実行しているコードの .NET Core への移植を検討する場合があります。You might have code that currently runs on the .NET Framework that you're interested in porting to .NET Core. この記事では、次について説明します。This article provides:

  • 移植プロセスの概要。An overview of the porting process.
  • コードを .NET Core に移植するときに役立つ場合があるツールの一覧。A list of tools that you may find helpful when you're porting your code to .NET Core.

移植プロセスの概要Overview of the porting process

多くのプロジェクトは、.NET Framework から .NET Core (または .NET Standard) に比較的簡単に移植できます。Porting to .NET Core (or .NET Standard) from .NET Framework for many projects is relatively straight forward. 多数の変更が必要ですが、その多くは次に示すパターンどおりです。There are a number of changes that are required, but many of them follow the patterns outlined below. .NET Core にアプリ モデルがあるプロジェクト (ライブラリ、コンソール アプリ、デスクトップ アプリケーションなど) では、通常ほとんど変更することはありません。Projects where the app-model is available in .NET Core (such as libraries, console apps, and desktop applications) usually require little changes. ASP.NET から ASP.NET Core への移行など、新しいアプリケーション モデルを必要とするプロジェクトでは、多少の作業が必要になりますが、多くのパターンには変換時に使用できるアナログがあります。Projects that require a new app model, such as moving to ASP.NET Core from ASP.NET, require a bit more work, but many patterns have analogs that can be used during the conversion. このドキュメントでは、ユーザーがどのような主戦略を使用してコード ベースをターゲットの .NET Standard または .NET Core に正常に変換したか理解し、ソリューション全体とプロジェクト別の 2 つのレベルで変換を行う方法について説明します。This document should help with identifying the main strategies that have been employed by users to successfully convert their code bases to target .NET Standard or .NET Core and will address the conversion at two levels: solution-wide and project specific. アプリ モデル固有の変換については、下部にあるリンクを参照してください。See the links at the bottom for directions on app-model specific conversions.

ご自分のプロジェクトを .NET Core に移植する場合は、次の手順を使用することをお勧めします。We recommend you use the following process when porting your project to .NET Core. これらの各手順では、動作が変わってしまう可能性がある場所を示しています。それ以降の手順に進む前に、ご自分のライブラリまたはアプリケーションは十分にテストしてください。Each of these steps introduces potential places for behavior changes, so ensure that you adequately test your library or application before continuing on to later steps. 最初の手順では、ご自分のプロジェクトを .NET Standard または .NET Core に切り替えられることができるように準備します。The first steps are to get your project ready for a switch to .NET Standard or .NET Core. 単体テストがある場合は、最初にそれらを変換して、作業中の製品の変更のテストを継続できるようにすることをお勧めします。If you have unit tests, it's best to convert them first so that you can continue testing changes in the product you're working on. .NET Core への移植はコードベースにとって大きな変更となるため、テスト プロジェクトを移植して、ご自分のコードの移植時にテストを実行できるようにすることを強くお勧めします。Because porting to .NET Core is such a significant change to your codebase, it's highly recommended to port your test projects so that you can run tests as you port your code over. MSTest、xUnit、NUnit はすべて .NET Core で動作します。MSTest, xUnit, and NUnit all work on .NET Core.

作業の開始Getting started

このプロセスを通して、次のツールを使用します。The following tools will be used throughout the process:

ソリューションの移植Porting a solution

ソリューションに複数のプロジェクトがある場合は、特定の順序でプロジェクトに対応する必要があるため、移植が複雑に思える場合があります。When there are multiple projects in a solution, the porting can seem more complicated because you must address projects in a specific order. 他のプロジェクトに依存しないソリューション内のプロジェクトを最初に変換してから、ソリューション全体を変換し続ける、ボトムアップ アプローチでこの変換プロセスは行う必要があります。The conversion process should be a bottom-up approach, where the projects with no dependencies on other projects in the solution are converted first, and continue up through the whole solution.

次のツールを使用すると、どのプロジェクトから移行するかを割り出すことができます。In order to identify the order projects should be migrated, you can use the following tools:

  • Visual Studio の依存関係図に関する説明からは、ソリューション内のコードの有向グラフを作成できます。Dependency Diagrams in Visual Studio can create a directed graph of the code in a solution.
  • msbuild _SolutionPath_ /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.dg.json を実行すると、プロジェクト参照の一覧を含む json ドキュメントを生成できます。Run msbuild _SolutionPath_ /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.dg.json to generate a json document that includes list of project references.
  • アセンブリの依存関係図を取得するには、-r DGML スイッチを使用して .NET Portability Analyzer を実行します。Run .NET Portability Analyzer with the -r DGML switch to retrieve a dependency diagram of the assemblies. 詳細については、このページを参照してください。For more information, see here.

依存関係の情報を取得した後は、その情報を使用してリーフ ノードから開始し、次のセクションのステップを適用して依存関係ツリーを操作できます。Once you have dependency information, you can use that information to start at the leaf nodes and work your way up the dependency tree applying the steps in the next section.

プロジェクト別の手順Per project steps

プロジェクトを .NET Core に移植する場合は、次の手順を使用することをお勧めします。We recommend you use the following process when porting your project to .NET Core:

  1. Visual Studio の変換ツールを使用して、すべての packages.config の依存関係を PackageReference 形式に変換します。Convert all of your packages.config dependencies to the PackageReference format with the conversion tool in Visual Studio.

    この手順では、依存関係を従来の packages.config 形式から変換します。This step involves converting your dependencies from the legacy packages.config format. packages.config は .NET Core では機能しないため、パッケージの依存関係がある場合は、この変換が必須です。packages.config doesn't work on .NET Core, so this conversion is required if you have package dependencies. また、プロジェクトで直接使用される依存関係のみに対して実行します。これにより、管理する必要がある依存関係の数を減らせるので、後の手順を楽にできます。It also only requires the dependencies you are directly using in a project, which makes later steps easier by reducing the number of dependencies you must manage.

  2. ご自分のプロジェクト ファイルのファイル構造を新しい SDK 形式のものに変換します。Convert your project file to the new SDK-style files structure. .NET Core 用の新しいプロジェクトを作成してソース ファイルをコピーするか、ツールを使ってお使いの既存のプロジェクト ファイルを変換することができます。You can create new projects for .NET Core and copy over source files, or attempt to convert your existing project file with a tool.

    .NET Core では、.NET Framework よりも簡素化された (異なる) プロジェクト ファイル形式が使用されます。.NET Core uses a simplified (and different) project file format than .NET Framework. 続行するには、プロジェクト ファイルをこの形式に変換する必要があります。You'll need to convert your project files into this format to continue. このプロジェクト形式では、この時点では、まだターゲットとしたい .NET Framework もターゲットにすることができます。This project style allows you to also target .NET Framework, which at this point you'll still want to target.

    dotnet try-convert ツールを使用すると、より小規模なソリューションや個々のプロジェクトを、1 回の操作で .NET Core プロジェクトのファイル形式に移植することが可能です。You can attempt to port smaller solutions or individual projects in one operation to the .NET Core project file format with the dotnet try-convert tool. dotnet try-convert がすべてのプロジェクトに対して動作する保証はありません。また、これが原因となって、依存していた動作に微妙な変更が生じる可能性があります。dotnet try-convert is not guaranteed to work for all your projects, and it may cause subtle changes in behavior that you depended on. これは、自動化できる基本的なことを自動化するための "開始点" としてお使いください。Use it as a starting point that automates the basic things that can be automated. SDK 形式のプロジェクトで使用されるターゲットと旧形式のプロジェクト ファイルで使用されるものとの間には違いが多数あるため、このソリューションではプロジェクトの移行は保証されません。It isn't a guaranteed solution to migrating a project, as there are many differences in the targets used by the SDK style projects compared to the old-style project files.

  3. 移植するすべてのプロジェクトを、.NET Framework 4.7.2 以降をターゲットとするように再ターゲットします。Retarget all projects you wish to port to target .NET Framework 4.7.2 or higher.

    この手順により、.NET Core で特定の API がサポートされない場合に、.NET Framework 固有のターゲットに対して API の代替を確実に使用できます。This step ensures that you can use API alternatives for .NET Framework-specific targets when .NET Core doesn't support a particular API.

  4. すべての依存関係を最新バージョンに更新します。Update all dependencies to the latest version. プロジェクトで、.NET Standard でサポートされていない古いバージョンのライブラリが使用されている場合があります。Projects may be using older versions of libraries that may not have .NET Standard support. ただし、単純に切り替えれば以降のバージョンでサポートされるようにできる場合があります。However, later versions may support it with a simple switch. ライブラリに破壊的変更がある場合は、コードの変更が必要になることがあります。This may require code changes if there are breaking changes in libraries.

  5. .NET Portability Analyzer を使ってアセンブリを分析し、それらが .NET Core に移植可能かどうかを確認します。Use the .NET Portability Analyzer to analyze your assemblies and see if they're portable to .NET Core.

    .NET Portability Analyzer ツールでは、ご自分のコンパイル済みのアセンブリを分析し、レポートを生成します。The .NET Portability Analyzer tool analyzes your compiled assemblies and generates a report. このレポートには、移植性に関する大まかな概要と、使用している API のうち NET Core では利用できないものそれぞれについての内訳が表示されます。This report shows a high-level portability summary and a breakdown of each API you're using that isn't available on NET Core. このツールを使用する場合、変更する必要がある可能性がある API に集中して取り組めるよう、変更するプロジェクトを個々に送信してください。While using the tool, only submit the individual project you are converting to focus on the API changes that are potentially needed. .NET Core には、多くの API と同等の、ユーザーが切り替えたいと思うものが用意されています。Many of the APIs have equivalent availability in .NET Core, which you'll want to switch to.

    Analyzer で生成されたレポートを確認するときの重要な情報は、使用されている実際の API です。必ずしもターゲットのプラットフォームのサポートのパーセンテージではありません。While reading the reports generated by the analyzer, the important information is the actual APIs that are being used and not necessarily the percentage of support for the target platform. .NET Standard と Core には、多くの API と同等の選択肢があります。そのため、お使いのライブラリまたはアプリケーションでの API の使われ方のシナリオを理解しておくと、移植において何をする必要があるかを判断することができます。Many APIs have equivalent options in .NET Standard/Core, and so understanding the scenarios your library or application needs the API for will help determine the implication for portability.

    同等の API がなく、コンパイラ プリプロセッサ ディレクティブ (つまり、#if NET45) を多少使用して、そのプラットフォームに特別対応をする必要がある場合もあります。There are some cases where APIs are not equivalent and you'll need to do some compiler preprocessor directives (that is, #if NET45) to special case the platforms. この時点では、あなたのプロジェクトでは、変わらず .NET Framework をターゲットにしています。At this point, your project will still be targeting .NET Framework. これらのターゲットがあるケースでは、シナリオとして理解できる広く知られた条件を都度使用することをお勧めします。For each of these targeted cases, it is recommended to use well-known conditionals that can be understood as a scenario. たとえば、.NET Core では限定的にしか AppDomain をサポートしていません。しかし、アセンブリを読み込みアンロードするシナリオ用に .NET Core では利用できない新しい API があります。For example, AppDomain support in .NET Core is limited, but for the scenario of loading and unloading assemblies, there is a new API that's not available in .NET Core. これをコードで処理するには、一般的に次のような方法を使用します。A common way to handle this in code would be something like this:

    #if FEATURE_APPDOMAIN_LOADING
    // Code that uses appdomains
    #elif FEATURE_ASSEMBLY_LOAD_CONTEXT
    // Code that uses assembly load context
    #else
    #error Unsupported platform
    #endif
    
  6. .NET API アナライザーをプロジェクトにインストールして、一部のプラットフォームで PlatformNotSupportedException をスローする API と、発生する可能性のあるその他の互換性の問題を識別します。Install the .NET API analyzer into your projects to identify APIs that throw PlatformNotSupportedException on some platforms and some other potential compatibility issues.

    このツールは移植性アナライザーに似ていますが、.NET Core 上にコードをビルドできるかどうかが分析されるのではなく、実行時に PlatformNotSupportedException をスローするような方法で API を使っているかどうかが分析されます。This tool is similar to the portability analyzer, but instead of analyzing if code can build on .NET Core, it analyzes whether you're using an API in a way that will throw a PlatformNotSupportedException at run time. .NET Framework 4.7.2 以上から移行する場合、これは一般的ではありませんが、確認することをお勧めします。Although this isn't common if you're moving from .NET Framework 4.7.2 or higher, it's good to check. .NET Core で例外をスローする API の詳細については、「.NET Core で常に例外をスローする API」を参照してください。For more information about APIs that throw exceptions on .NET Core, see APIs that always throw exceptions on .NET Core.

  7. この時点で、ターゲットを .NET Core (一般的にはアプリケーション用) または .NET Standard (ライブラリ用) に切り替えることができます。At this point, you can switch to targeting .NET Core (generally for applications) or .NET Standard (for libraries).

    .NET Core と .NET Standard のどちらを選択するかは、プロジェクトの実行場所に大きく関係します。The choice between .NET Core and .NET Standard is largely dependent on where the project will be run. 他のアプリケーションで使用されたり、NuGet 経由で配布されるのがライブラリである場合は、通常は .NET Standard がターゲットとなります。If it is a library that will be consumed by other applications or distributed via NuGet, the preference is usually to target .NET Standard. ただし、パフォーマンスやその他の理由で .NET Core にしかない API がある場合があります。そのような場合、パフォーマンスや機能が低い .NET Standard のビルドがあっても .NET Core をターゲットにする必要があります。However, there may be APIs that are only available on .NET Core for performance or other reasons; if that's the case, .NET Core should be targeted with potentially a .NET Standard build available as well with reduced performance or functionality. .NET Standard をターゲットにすると、(WebAssembly などの) 新しいプラットフォームでプロジェクトを実行できます。By targeting .NET Standard, the project will be ready to run on new platforms (such as WebAssembly). プロジェクトが (ASP.NET Core など) 特定のアプリケーション フレームワークに依存している場合、ターゲットは依存関係がサポートする内容によって制限されます。If the project has dependencies on specific app frameworks (such as ASP.NET Core), then the target will be limited by what the dependencies support.

    .NET Framework または .NET Standard 用に条件付きでコードをコンパイルするプリプロセッサ ディレクティブがない場合は、プロジェクト ファイルで次を検索するのと同じくらいこれは簡単です。If there are no preprocessor directives to conditional compile code for .NET Framework or .NET Standard, this will be as simple as finding the following in the project file:

    <TargetFramework>net472</TargetFramework>
    

    目的のフレームワークに切り替えます。and switch it to the desired framework. .NET Core 3.1 の場合、次のようになります。For .NET Core 3.1, this would be:

    <TargetFramework>netcoreapp3.1</TargetFramework>
    

    ただし、このライブラリに .NET Framework の特定のビルドを引き続きサポートさせたい場合は、次のように置き換えてマルチターゲット化させることができます。However, if this is a library for which you want to continue supporting .NET Framework-specific builds, you can multi-target by replacing it with the following:

    <TargetFrameworks>net472;netstandard2.0</TargetFrameworks>
    

    (レジストリ アクセスなどの) Windows 専用の API を使用する場合は、Windows 互換機能パックをインストールしてください。If you're using Windows-specific APIs (such as registry access), install the Windows Compatibility Pack.

次の手順Next steps