MSBuild モダナイゼーション: レガシーから SDK-style への移行

レガシープロジェクトと SDK-style プロジェクトの区別

レガシーの指標:

• <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
• 明示的なファイルリスト（すべての .cs ファイルに対する <Compile Include="..." /> ）
• <Project> 要素の ToolsVersion 属性
• packages.config ファイルが存在
• Properties\AssemblyInfo.cs にアセンブリレベルの属性あり

SDK-style の指標:

• ルート要素の <Project Sdk="Microsoft.NET.Sdk"> 属性
• 最小限の内容 — シンプルなプロジェクトは 10～15 行程度
• 明示的なファイル指定がない（暗黙的なグロブ）
• packages.config の代わりに <PackageReference> アイテム

クイックチェック: シンプルなクラスライブラリやコンソールアプリの .csproj が 50 行以上の場合、レガシー形式の可能性が高いです。

<!-- レガシー: シンプルなライブラリで ~80+ 行 -->
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <OutputType>Library</OutputType>
    <RootNamespace>MyLibrary</RootNamespace>
    <AssemblyName>MyLibrary</AssemblyName>
    <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
    <FileAlignment>512</FileAlignment>
    <Deterministic>true</Deterministic>
  </PropertyGroup>
  <!-- ... 60+ 行以上 ... -->
  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
</Project>

<!-- SDK-style: 同じライブラリで ~8 行 -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net472</TargetFramework>
  </PropertyGroup>
</Project>

移行チェックリスト: レガシー → SDK-style

ステップ 1: プロジェクトのルート要素を置き換える

変更前:

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props"
          Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <!-- ... プロジェクト内容 ... -->
  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
</Project>

変更後:

<Project Sdk="Microsoft.NET.Sdk">
  <!-- ... プロジェクト内容 ... -->
</Project>

XML 宣言、ToolsVersion、xmlns、および両方の <Import> 行を削除します。Sdk 属性がそれらすべてに置き換わります。

ステップ 2: TargetFramework を設定

変更前:

<PropertyGroup>
  <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
</PropertyGroup>

変更後:

<PropertyGroup>
  <TargetFramework>net472</TargetFramework>
</PropertyGroup>

TFM マッピング表:

レガシー TargetFrameworkVersion	SDK-style TargetFramework
v4.6.1	net461
v4.7.2	net472
v4.8	net48
(.NET 6 への移行)	net6.0
(.NET 8 への移行)	net8.0

ステップ 3: 明示的なファイル指定を削除

変更前:

<ItemGroup>
  <Compile Include="Controllers\HomeController.cs" />
  <Compile Include="Models\User.cs" />
  <Compile Include="Models\Order.cs" />
  <Compile Include="Services\AuthService.cs" />
  <Compile Include="Services\OrderService.cs" />
  <Compile Include="Properties\AssemblyInfo.cs" />
  <!-- ... さらに 50+ 行 ... -->
</ItemGroup>
<ItemGroup>
  <Content Include="Views\Home\Index.cshtml" />
  <Content Include="Views\Shared\_Layout.cshtml" />
  <!-- ... さらにコンテンツファイル ... -->
</ItemGroup>

変更後:

これらの <Compile> と <Content> アイテムグループをすべて削除します。SDK-style プロジェクトは暗黙的なグロブを通じて自動的にそれらを含めます。

例外: プロジェクトディレクトリの外に存在するか特殊なメタデータが必要なファイルのみ明示的なエントリを保持します:

<ItemGroup>
  <Content Include="..\shared\config.json" Link="config.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

ステップ 4: AssemblyInfo.cs を削除

変更前 (Properties\AssemblyInfo.cs):

using System.Reflection;
using System.Runtime.InteropServices;

[assembly: AssemblyTitle("MyLibrary")]
[assembly: AssemblyDescription("A useful library")]
[assembly: AssemblyCompany("Contoso")]
[assembly: AssemblyProduct("MyLibrary")]
[assembly: AssemblyCopyright("Copyright © Contoso 2024")]
[assembly: ComVisible(false)]
[assembly: Guid("...")]
[assembly: AssemblyVersion("1.2.0.0")]
[assembly: AssemblyFileVersion("1.2.0.0")]

変更後 (.csproj 内):

<PropertyGroup>
  <AssemblyTitle>MyLibrary</AssemblyTitle>
  <Description>A useful library</Description>
  <Company>Contoso</Company>
  <Product>MyLibrary</Product>
  <Copyright>Copyright © Contoso 2024</Copyright>
  <Version>1.2.0</Version>
</PropertyGroup>

Properties\AssemblyInfo.cs を削除します — SDK がこれらのプロパティからアセンブリ属性を自動生成します。

代替案: AssemblyInfo.cs を保持したい場合、自動生成を無効にします:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

ステップ 5: packages.config → PackageReference に移行

変更前 (packages.config):

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Newtonsoft.Json" version="13.0.3" targetFramework="net472" />
  <package id="Serilog" version="3.1.1" targetFramework="net472" />
  <package id="Microsoft.Extensions.DependencyInjection" version="8.0.0" targetFramework="net472" />
</packages>

変更後 (.csproj 内):

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  <PackageReference Include="Serilog" Version="3.1.1" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
</ItemGroup>

移行後に packages.config を削除します。

移行オプション:

• Visual Studio: packages.config を右クリック → Migrate packages.config to PackageReference
• CLI: dotnet migrate-packages-config またはマニュアル変換
• バインディング リダイレクト: SDK-style プロジェクトは自動的にバインディング リダイレクトを生成します — 存在する場合は app.config の <runtime> セクションを削除します

ステップ 6: 不要なボイラープレートを削除

以下のすべてを削除します — SDK が適切なデフォルトを提供します:

<!-- 削除: SDK のインポート (Sdk 属性で置き換わり) -->
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" ... />
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

<!-- 削除: デフォルトの Configuration/Platform (SDK が提供) -->
<PropertyGroup>
  <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
  <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
  <ProjectGuid>{...}</ProjectGuid>
  <OutputType>Library</OutputType>  <!-- Library でない場合のみ保持 -->
  <AppDesignerFolder>Properties</AppDesignerFolder>
  <FileAlignment>512</FileAlignment>
  <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
  <Deterministic>true</Deterministic>
</PropertyGroup>

<!-- 削除: 標準的な Debug/Release 構成 (SDK のデフォルトと一致) -->
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
  <DebugSymbols>true</DebugSymbols>
  <DebugType>full</DebugType>
  <Optimize>false</Optimize>
  <OutputPath>bin\Debug\</OutputPath>
  <DefineConstants>DEBUG;TRACE</DefineConstants>
  <ErrorReport>prompt</ErrorReport>
  <WarningLevel>4</WarningLevel>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <DebugType>pdbonly</DebugType>
  <Optimize>true</Optimize>
  <OutputPath>bin\Release\</OutputPath>
  <DefineConstants>TRACE</DefineConstants>
  <ErrorReport>prompt</ErrorReport>
  <WarningLevel>4</WarningLevel>
</PropertyGroup>

<!-- 削除: フレームワーク アセンブリ参照 (SDK で暗黙的) -->
<ItemGroup>
  <Reference Include="System" />
  <Reference Include="System.Core" />
  <Reference Include="System.Data" />
  <Reference Include="System.Xml" />
  <Reference Include="System.Xml.Linq" />
  <Reference Include="Microsoft.CSharp" />
</ItemGroup>

<!-- 削除: packages.config 参照 -->
<None Include="packages.config" />

<!-- 削除: デザイナー サービス エントリ -->
<Service Include="{508349B6-6B84-11D3-8410-00C04F8EF8E0}" />

保持する: SDK のデフォルトと異なるプロパティのみ (例: <OutputType>Exe</OutputType>、アセンブリ名と異なる場合の <RootNamespace>、カスタムな <DefineConstants>)。

ステップ 7: モダン機能を有効にする

移行後、モダン C# 機能の有効化を検討します:

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

• <Nullable>enable</Nullable> — nullable 参照型の分析を有効化
• <ImplicitUsings>enable</ImplicitUsings> — 共通名前空間を自動インポート (.NET 6+)
• <LangVersion>latest を避けてください — 有効な言語バージョンは TFM だけではなく SDK/コンパイラのデフォルトで決定されるため、異なる SDK がインストールされているマシン間でビルドが異なる可能性があります。<LangVersion> を省略してください。特定バージョンをピン留めする必要がない限り。再現可能なビルドの場合、リポジトリ全体で global.json を使用して SDK バージョンをピン留めします (これは間接的にデフォルト言語バージョンを固定します)、または各プロジェクトで明示的な数値 <LangVersion> (例: <LangVersion>12</LangVersion>) を設定して言語バージョンを直接制御します。

完全な変更前後の例

変更前 (レガシー — 65 行):

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props"
          Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <ProjectGuid>{12345678-1234-1234-1234-123456789ABC}</ProjectGuid>
    <OutputType>Library</OutputType>
    <AppDesignerFolder>Properties</AppDesignerFolder>
    <RootNamespace>MyLibrary</RootNamespace>
    <AssemblyName>MyLibrary</AssemblyName>
    <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
    <FileAlignment>512</FileAlignment>
    <Deterministic>true</Deterministic>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <OutputPath>bin\Debug\</OutputPath>
    <DefineConstants>DEBUG;TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <OutputPath>bin\Release\</OutputPath>
    <DefineConstants>TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <ItemGroup>
    <Reference Include="System" />
    <Reference Include="System.Core" />
    <Reference Include="System.Xml.Linq" />
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
  <ItemGroup>
    <Compile Include="Models\User.cs" />
    <Compile Include="Models\Order.cs" />
    <Compile Include="Services\UserService.cs" />
    <Compile Include="Services\OrderService.cs" />
    <Compile Include="Helpers\StringExtensions.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="packages.config" />
  </ItemGroup>
  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
</Project>

変更後 (SDK-style — 11 行):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net472</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageReference Include="Serilog" Version="3.1.1" />
  </ItemGroup>
</Project>

移行の一般的な問題

埋め込みリソース: 標準的な場所にないファイルは明示的な指定が必要な場合があります:

<ItemGroup>
  <EmbeddedResource Include="..\shared\Schemas\*.xsd" LinkBase="Schemas" />
</ItemGroup>

CopyToOutputDirectory 付きコンテンツ ファイル: これらもまだ明示的なエントリが必要です:

<ItemGroup>
  <Content Include="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
  <None Include="scripts\*.sql" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

マルチターゲット: 要素名を単数形から複数形に変更します:

<!-- 単一ターゲット -->
<TargetFramework>net8.0</TargetFramework>

<!-- 複数ターゲット -->
<TargetFrameworks>net472;net8.0</TargetFrameworks>

WPF/WinForms プロジェクト: 適切な SDK またはプロパティを使用します:

<!-- オプション A: WindowsDesktop SDK -->
<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">

<!-- オプション B: 標準 SDK 内のプロパティ (.NET 5+ 推奨) -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <UseWPF>true</UseWPF>
    <!-- または -->
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>
</Project>

テスト プロジェクト: テスト フレームワーク パッケージを使用して標準 SDK を使用します:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <IsPackable>false</IsPackable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="xunit" Version="2.7.0" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.7" />
  </ItemGroup>
</Project>

一元化パッケージ管理への移行

複数プロジェクトソリューション全体で NuGet バージョン管理を一元化します。詳細は https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management を参照してください。

ステップ 1: リポジトリルートに Directory.Packages.props を作成し、<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> とすべてのパッケージの <PackageVersion> アイテムを配置します。

ステップ 2: 各プロジェクトの PackageReference から Version を削除します:

<!-- 変更前 -->
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

<!-- 変更後 -->
<PackageReference Include="Newtonsoft.Json" />

Directory.Build の統合

複数の .csproj ファイルで繰り返されるプロパティを特定し、共有ファイルに移動します。

Directory.Build.props (プロパティ用 — リポジトリまたは src ルートに配置):

<Project>
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <Company>Contoso</Company>
    <Copyright>Copyright © Contoso 2024</Copyright>
  </PropertyGroup>
</Project>

Directory.Build.targets (ターゲット/タスク用 — リポジトリまたは src ルートに配置):

<Project>
  <Target Name="PrintBuildInfo" AfterTargets="Build">
    <Message Importance="High" Text="Built $(AssemblyName) → $(TargetPath)" />
  </Target>
</Project>

個別の .csproj ファイルに保持: プロジェクト固有のもののみ:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <AssemblyName>MyApp</AssemblyName>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Serilog" />
    <ProjectReference Include="..\MyLibrary\MyLibrary.csproj" />
  </ItemGroup>
</Project>

ツールと自動化

ツール	用途
dotnet try-convert	レガシー から SDK への自動変換。インストール: dotnet tool install -g try-convert
.NET Upgrade Assistant	API 変更を含む全体的な移行。インストール: dotnet tool install -g upgrade-assistant
Visual Studio	packages.config を右クリック → Migrate packages.config to PackageReference
マニュアル移行	シンプルなプロジェクトでは最もクリーン — 上記のチェックリストに従う

推奨アプローチ:

1. try-convert を実行して最初のパスを行う
2. 出力をレビューしマニュアルでクリーンアップ
3. ビルドして問題を修正
4. モダン機能を有効にする (nullable、implicit usings)
5. 共有設定を Directory.Build.props に統合