project.json プロパティと csproj プロパティの間のマッピング

作成者: Nate McMaster

.NET Core ツールの開発中、重要なデザイン変更が行われました。project.json ファイルのサポートが終了となり、代わりに.NET Core プロジェクトが MSBuild/csproj 形式に移行されました。

この記事では、project.json の設定が MSBuild/csproj 形式でどのように表示されるか説明します。最新バージョンのツールにプロジェクトをアップグレードするとき、新しい形式の利用方法を知り、移行ツールで行われた変更を理解できます。

csproj 形式

新しい形式の *.csproj は XML ベースの形式です。 次の例は、Microsoft.NET.Sdk を利用した .NET Core プロジェクトのルート ノードです。 Web プロジェクトの場合、使用される SDK は Microsoft.NET.Sdk.Web です。

<Project Sdk="Microsoft.NET.Sdk">
...
</Project>

一般的な最上位プロパティ

name

{
  "name": "MyProjectName"
}

サポート対象から除外されました。 csproj では、これは、ディレクトリ名により定義される、プロジェクト ファイル名により決定されます。 たとえば、MyProjectName.csproj のようにします。

既定では、プロジェクト ファイル名により、<AssemblyName> プロパティと <PackageId> プロパティの値も指定されます。

<PropertyGroup>
  <AssemblyName>MyProjectName</AssemblyName>
  <PackageId>MyProjectName</PackageId>
</PropertyGroup>

project.json に buildOptions\outputName プロパティが定義されている場合、<AssemblyName> には <PackageId> 以外の値が設定されます。 詳細については、「その他の共通ビルド オプション」を参照してください。

version

{
  "version": "1.0.0-alpha-*"
}

VersionPrefix プロパティおよび VersionSuffix プロパティを使用します。

<PropertyGroup>
  <VersionPrefix>1.0.0</VersionPrefix>
  <VersionSuffix>alpha</VersionSuffix>
</PropertyGroup>

Version プロパティを使用することもできますが、これにより、パッケージ処理中にバージョン設定が上書きされることがあります。

<PropertyGroup>
  <Version>1.0.0-alpha</Version>
</PropertyGroup>

その他の共通のルートレベル オプション

{
  "authors": [ "Anne", "Bob" ],
  "company": "Contoso",
  "language": "en-US",
  "title": "My library",
  "description": "This is my library.\r\nAnd it's really great!",
  "copyright": "Nugetizer 3000",
  "userSecretsId": "xyz123"
}
<PropertyGroup>
  <Authors>Anne;Bob</Authors>
  <Company>Contoso</Company>
  <NeutralLanguage>en-US</NeutralLanguage>
  <AssemblyTitle>My library</AssemblyTitle>
  <Description>This is my library.
And it's really great!</Description>
  <Copyright>Nugetizer 3000</Copyright>
  <UserSecretsId>xyz123</UserSecretsId>
</PropertyGroup>

frameworks

1 つのターゲット フレームワーク

{
  "frameworks": {
    "netcoreapp1.0": {}
  }
}
<PropertyGroup>
  <TargetFramework>netcoreapp1.0</TargetFramework>
</PropertyGroup>

複数のターゲット フレームワーク

{
  "frameworks": {
    "netcoreapp1.0": {},
    "net451": {}
  }
}

TargetFrameworks プロパティを使用し、ターゲット フレームワークの一覧を定義します。 複数のフレームワーク値を区切るには、セミコロンを使用します。

<PropertyGroup>
  <TargetFrameworks>netcoreapp1.0;net451</TargetFrameworks>
</PropertyGroup>

依存関係

重要

依存関係がパッケージではなく、プロジェクトの場合、形式は異なります。 詳細については、「依存関係の種類」セクションを参照してください。

NETStandard.Library のメタパッケージ

{
  "dependencies": {
    "NETStandard.Library": "1.6.0"
  }
}
<PropertyGroup>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Microsoft.NETCore.App のメタパッケージ

{
  "dependencies": {
    "Microsoft.NETCore.App": "1.0.0"
  }
}
<PropertyGroup>
  <RuntimeFrameworkVersion>1.0.3</RuntimeFrameworkVersion>
</PropertyGroup>

移行されたプロジェクトの <RuntimeFrameworkVersion> 値はインストールした SDK のバージョンにより決定されます。

最上位の依存関係

{
  "dependencies": {
    "Microsoft.AspNetCore": "1.1.0"
  }
}
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="1.1.0" />
</ItemGroup>

フレームワーク別の依存関係

{
  "framework": {
    "net451": {
      "dependencies": {
        "System.Collections.Immutable": "1.3.1"
      }
    },
    "netstandard1.5": {
      "dependencies": {
        "Newtonsoft.Json": "9.0.1"
      }
    }
  }
}
<ItemGroup Condition="'$(TargetFramework)'=='net451'">
  <PackageReference Include="System.Collections.Immutable" Version="1.3.1" />
</ItemGroup>

<ItemGroup Condition="'$(TargetFramework)'=='netstandard1.5'">
  <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
</ItemGroup>

インポート

{
  "dependencies": {
    "YamlDotNet": "4.0.1-pre309"
  },
  "frameworks": {
    "netcoreapp1.0": {
      "imports": [
        "dnxcore50",
        "dotnet"
      ]
    }
  }
}
<PropertyGroup>
  <PackageTargetFallback>dnxcore50;dotnet</PackageTargetFallback>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="YamlDotNet" Version="4.0.1-pre309" />
</ItemGroup>

依存関係の種類

type: project

{
  "dependencies": {
    "MyOtherProject": "1.0.0-*",
    "AnotherProject": {
      "type": "project"
    }
  }
}
<ItemGroup>
  <ProjectReference Include="..\MyOtherProject\MyOtherProject.csproj" />
  <ProjectReference Include="..\AnotherProject\AnotherProject.csproj" />
</ItemGroup>

注意

dotnet pack --version-suffix $suffix がプロジェクト参照の依存関係バージョンを決定する方法が無効になります。

type: build

{
  "dependencies": {
    "Microsoft.EntityFrameworkCore.Design": {
      "version": "1.1.0",
      "type": "build"
    }
  }
}
<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="1.1.0" PrivateAssets="All" />
</ItemGroup>

type: platform

{
  "dependencies": {
    "Microsoft.NETCore.App": {
      "version": "1.1.0",
      "type": "platform"
    }
  }
}

csproj には同等のものがありません。

runtimes

{
  "runtimes": {
    "win7-x64": {},
    "osx.10.11-x64": {},
    "ubuntu.16.04-x64": {}
  }
}
<PropertyGroup>
  <RuntimeIdentifiers>win7-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

スタンドアロン アプリ (自己完結型の展開)

project.json では、runtimes セクションを定義することは、ビルドと公開の間にアプリがスタンドアロンであったことを意味します。 MSBuild では、ビルド中、すべてのプロジェクトが移植可能ですが、スタンドアロンとして公開できます。

dotnet publish --framework netcoreapp1.0 --runtime osx.10.11-x64

詳細については、「自己完結型の展開 (SCD)」を参照してください。

ツール

{
  "tools": {
    "Microsoft.EntityFrameworkCore.Tools.DotNet": "1.0.0-*"
  }
}
<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="1.0.0" />
</ItemGroup>

注意

ツールの imports は、csproj ではサポートされません。 インポートを必要とするツールは、新しい Microsoft.NET.Sdk で機能しません。

buildOptions

Files」も参照してください。

emitEntryPoint

{
  "buildOptions": {
    "emitEntryPoint": true
  }
}
<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

emitEntryPointfalse であった場合、OutputType の値は Library に変換されます。これが既定値です。

{
  "buildOptions": {
    "emitEntryPoint": false
  }
}
<PropertyGroup>
  <OutputType>Library</OutputType>
  <!-- or, omit altogether. It defaults to 'Library' -->
</PropertyGroup>

keyFile

{
  "buildOptions": {
    "keyFile": "MyKey.snk"
  }
}

keyFile 要素は、MSBuild で 3 つのプロパティになりました。

<PropertyGroup>
  <AssemblyOriginatorKeyFile>MyKey.snk</AssemblyOriginatorKeyFile>
  <SignAssembly>true</SignAssembly>
  <PublicSign Condition="'$(OS)' != 'Windows_NT'">true</PublicSign>
</PropertyGroup>

その他の共通ビルド オプション

{
  "buildOptions": {
    "warningsAsErrors": true,
    "nowarn": ["CS0168", "CS0219"],
    "xmlDoc": true,
    "preserveCompilationContext": true,
    "outputName": "Different.AssemblyName",
    "debugType": "portable",
    "allowUnsafe": true,
    "define": ["TEST", "OTHERCONDITION"]
  }
}
<PropertyGroup>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <NoWarn>$(NoWarn);CS0168;CS0219</NoWarn>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <PreserveCompilationContext>true</PreserveCompilationContext>
  <AssemblyName>Different.AssemblyName</AssemblyName>
  <DebugType>portable</DebugType>
  <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  <DefineConstants>$(DefineConstants);TEST;OTHERCONDITION</DefineConstants>
</PropertyGroup>

packOptions

Files」も参照してください。

共通パック オプション

{
  "packOptions": {    
    "summary": "numl is a machine learning library intended to ease the use of using standard modeling techniques for both prediction and clustering.",
    "tags": ["machine learning", "framework"],
    "releaseNotes": "Version 0.9.12-beta",
    "iconUrl": "http://numl.net/images/ico.png",
    "projectUrl": "http://numl.net",
    "licenseUrl": "https://raw.githubusercontent.com/sethjuarez/numl/master/LICENSE.md",
    "requireLicenseAcceptance": false,
    "repository": {
      "type": "git",
      "url": "https://raw.githubusercontent.com/sethjuarez/numl"
    },
    "owners": ["Seth Juarez"]
  }
}
<PropertyGroup>
  <!-- summary is not migrated from project.json, but you can use the <Description> property for that if needed. -->
  <PackageTags>machine learning;framework</PackageTags>
  <PackageReleaseNotes>Version 0.9.12-beta</PackageReleaseNotes>
  <PackageIconUrl>http://numl.net/images/ico.png</PackageIconUrl>
  <PackageProjectUrl>http://numl.net</PackageProjectUrl>
  <PackageLicenseUrl>https://raw.githubusercontent.com/sethjuarez/numl/master/LICENSE.md</PackageLicenseUrl>
  <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
  <RepositoryType>git</RepositoryType>
  <RepositoryUrl>https://raw.githubusercontent.com/sethjuarez/numl</RepositoryUrl>
  <!-- owners is not supported in MSBuild -->
</PropertyGroup>

MSBuild では、owners 要素に相当するものはありません。 summary の場合、MSBuild の <Description> プロパティを利用できます (ただし、summary の値はそのプロパティに自動的に移行されません)。そのプロパティが description 要素にマッピングされているためです。

スクリプト

{
  "scripts": {
    "precompile": "generateCode.cmd",
    "postpublish": [ "obfuscate.cmd", "removeTempFiles.cmd" ]
  }
}

MSBuild でこれに相当するものはターゲットです。

<Target Name="MyPreCompileTarget" BeforeTargets="Build">
  <Exec Command="generateCode.cmd" />
</Target>

<Target Name="MyPostCompileTarget" AfterTargets="Publish">
  <Exec Command="obfuscate.cmd" />
  <Exec Command="removeTempFiles.cmd" />
</Target>

runtimeOptions

{
  "runtimeOptions": {
    "configProperties": {
      "System.GC.Server": true,
      "System.GC.Concurrent": true,
      "System.GC.RetainVM": true,
      "System.Threading.ThreadPool.MinThreads": 4,
      "System.Threading.ThreadPool.MaxThreads": 25
    }
  }
}

"System.GC.Server" プロパティを除き、このグループのすべての設定がプロジェクト フォルダーの runtimeconfig.template.json というファイルに配置されます。オプションは移行プロセス中にルート オブジェクトに移動します。

{
  "configProperties": {
    "System.GC.Concurrent": true,
    "System.GC.RetainVM": true,
    "System.Threading.ThreadPool.MinThreads": 4,
    "System.Threading.ThreadPool.MaxThreads": 25
  }
}

"System.GC.Server" プロパティは csproj ファイルに移行されます。

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ただし、csproj のこれらの値はすべて MSBuild プロパティと共に設定できます。

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
  <ConcurrentGarbageCollection>true</ConcurrentGarbageCollection>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
  <ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
</PropertyGroup>

shared

{
  "shared": "shared/**/*.cs"
}

csproj ではサポートされていません。 代わりに、.nuspec ファイルにコンテンツ ファイルを追加する必要があります。 詳細については、「Including content files」 (コンテンツ ファイルを追加する) を参照してください。

ファイル

project.json では、ビルドとパックは、複数のフォルダーからのコンパイルと埋め込みまで拡張できます。 MSBuild では、これは項目の使用により行われます。 次の例は一般的な変換です。

{
  "buildOptions": {
    "compile": {
      "copyToOutput": "notes.txt",
      "include": "../Shared/*.cs",
      "exclude": "../Shared/Not/*.cs"
    },
    "embed": {
      "include": "../Shared/*.resx"
    }
  },
  "packOptions": {
    "include": "Views/",
    "mappings": {
      "some/path/in/project.txt": "in/package.txt"
    }
  },
  "publishOptions": {
    "include": [
      "files/",
      "publishnotes.txt"
    ]
  }
}
<ItemGroup>
  <Compile Include="..\Shared\*.cs" Exclude="..\Shared\Not\*.cs" />
  <EmbeddedResource Include="..\Shared\*.resx" />
  <Content Include="Views\**\*" PackagePath="%(Identity)" />
  <None Include="some/path/in/project.txt" Pack="true" PackagePath="in/package.txt" />

  <None Include="notes.txt" CopyToOutputDirectory="Always" />
  <!-- CopyToOutputDirectory = { Always, PreserveNewest, Never } -->

  <Content Include="files\**\*" CopyToPublishDirectory="PreserveNewest" />
  <None Include="publishnotes.txt" CopyToPublishDirectory="Always" />
  <!-- CopyToPublishDirectory = { Always, PreserveNewest, Never } -->
</ItemGroup>

注意

既定の Glob パターンの多くは .NET Core SDK により自動的に追加されます。 詳細については、「Default Compile Item Values」 (既定のコンパイル項目値) を参照してください。

すべての MSBuild ItemGroup 要素で IncludeExcludeRemove がサポートされています。

.nupkg 内のパッケージ レイアウトは PackagePath="path" で変更できます。

Content を除き、ほとんどの項目グループで、パッケージに Pack="true" を明示的に追加する必要があります。 MSBuild の <IncludeContentInPack> プロパティが既定で true に設定されているため、Content はパッケージのコンテンツ フォルダーに置かれます。 詳細については、「Including content in a package」 (パッケージにコンテンツを追加する) を参照してください。

PackagePath="%(Identity)" は、パッケージ パスをプロジェクト関連のファイル パスに設定する簡単な方法です。

testRunner

xUnit

{
  "testRunner": "xunit",
  "dependencies": {
    "dotnet-test-xunit": "<any>"
  }
}
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.0.0-*" />
  <PackageReference Include="xunit" Version="2.2.0-*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="2.2.0-*" />
</ItemGroup>

MSTest

{
  "testRunner": "mstest",
  "dependencies": {
    "dotnet-test-mstest": "<any>"
  }
}
<ItemGroup>
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.0.0-*" />
  <PackageReference Include="MSTest.TestAdapter" Version="1.1.12-*" />
  <PackageReference Include="MSTest.TestFramework" Version="1.1.11-*" />
</ItemGroup>

関連項目

CLI の変更の概要