project.json 和 csproj 属性之间的映射A mapping between project.json and csproj properties

本文内容

作者 Nate McMaster

.NET Core 工具的开发过程中实施了一项重要的设计更改，即不再支持 project.json 文件，而是将 .NET Core 项目转移到 MSBuild/csproj 格式。

本文介绍 project.json 中的设置如何以 MSBuild/csproj 格式表示，以便用户可学习如何使用新格式，并了解将项目升级到最新版本的工具时由迁移工具做出的更改。

csproj 格式The csproj format

新格式 *.csproj 是一种基于 XML 的格式。以下示例演示使用 Microsoft.NET.Sdk 的 .NET Core 项目的根节点。对于 Web 项目，所使用的 SDK 是 Microsoft.NET.Sdk.Web。

  1. <Project Sdk="Microsoft.NET.Sdk">
  2. ...
  3. </Project>

常见顶级属性Common top-level properties

namename

  1. {
  2.   "name": "MyProjectName"
  3. }

不再支持。在 csproj 中，这取决于项目文件名（通常与目录名称匹配）。例如 MyProjectName.csproj。

默认情况下，项目文件名还指定 <AssemblyName> 和 <PackageId> 属性的值。

  1. <PropertyGroup>
  2.   <AssemblyName>MyProjectName</AssemblyName>
  3.   <PackageId>MyProjectName</PackageId>
  4. </PropertyGroup>

如果 buildOptions\outputName 属性是在 project.json 中定义的，<AssemblyName> 将具有不同于 <PackageId> 的其他值。有关详细信息，请参阅其他常用生成选项。

versionversion

  1. {
  2.   "version": "1.0.0-alpha-*"
  3. }

使用 VersionPrefix 和 VersionSuffix 属性：

  1. <PropertyGroup>
  2.   <VersionPrefix>1.0.0</VersionPrefix>
  3.   <VersionSuffix>alpha</VersionSuffix>
  4. </PropertyGroup>

还可以使用 Version 属性，但这可能会在打包过程中替代版本设置：

  1. <PropertyGroup>
  2.   <Version>1.0.0-alpha</Version>
  3. </PropertyGroup>

其他常用根级别选项Other common root-level options

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

框架frameworks

一个目标框架One target framework

  1. {
  2.   "frameworks": {
  3.     "netcoreapp1.0": {}
  4.   }
  5. }
  1. <PropertyGroup>
  2.   <TargetFramework>netcoreapp1.0</TargetFramework>
  3. </PropertyGroup>

多个目标框架Multiple target frameworks

  1. {
  2.   "frameworks": {
  3.     "netcoreapp1.0": {},
  4.     "net451": {}
  5.   }
  6. }

使用 TargetFrameworks 属性定义目标框架的列表。使用分号来分隔多个框架值。

  1. <PropertyGroup>
  2.   <TargetFrameworks>netcoreapp1.0;net451</TargetFrameworks>
  3. </PropertyGroup>

依赖项dependencies

重要

如果依赖项是一个项目而不是包，则格式不同。有关详细信息，请参阅依赖项类型部分。

NETStandard.Library 元包NETStandard.Library metapackage

  1. {
  2.   "dependencies": {
  3.     "NETStandard.Library": "1.6.0"
  4.   }
  5. }
  1. <PropertyGroup>
  2.   <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
  3. </PropertyGroup>

Microsoft.NETCore.App 元包Microsoft.NETCore.App metapackage

  1. {
  2.   "dependencies": {
  3.     "Microsoft.NETCore.App": "1.0.0"
  4.   }
  5. }
  1. <PropertyGroup>
  2.   <RuntimeFrameworkVersion>1.0.3</RuntimeFrameworkVersion>
  3. </PropertyGroup>

请注意，迁移项目中的 <RuntimeFrameworkVersion> 值由已安装的 SDK 版本确定。

顶级依赖项Top-level dependencies

  1. {
  2.   "dependencies": {
  3.     "Microsoft.AspNetCore": "1.1.0"
  4.   }
  5. }
  1. <ItemGroup>
  2.   <PackageReference Include="Microsoft.AspNetCore" Version="1.1.0" />
  3. </ItemGroup>

依赖项（按框架）Per-framework dependencies

  1. {
  2.   "framework": {
  3.     "net451": {
  4.       "dependencies": {
  5.         "System.Collections.Immutable": "1.3.1"
  6.       }
  7.     },
  8.     "netstandard1.5": {
  9.       "dependencies": {
  10.         "Newtonsoft.Json": "9.0.1"
  11.       }
  12.     }
  13.   }
  14. }
  1. <ItemGroup Condition="'$(TargetFramework)'=='net451'">
  2.   <PackageReference Include="System.Collections.Immutable" Version="1.3.1" />
  3. </ItemGroup>
  5. <ItemGroup Condition="'$(TargetFramework)'=='netstandard1.5'">
  6.   <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
  7. </ItemGroup>

导入imports

  1. {
  2.   "dependencies": {
  3.     "YamlDotNet": "4.0.1-pre309"
  4.   },
  5.   "frameworks": {
  6.     "netcoreapp1.0": {
  7.       "imports": [
  8.         "dnxcore50",
  9.         "dotnet"
  10.       ]
  11.     }
  12.   }
  13. }
  1. <PropertyGroup>
  2.   <PackageTargetFallback>dnxcore50;dotnet</PackageTargetFallback>
  3. </PropertyGroup>
  4. <ItemGroup>
  5.   <PackageReference Include="YamlDotNet" Version="4.0.1-pre309" />
  6. </ItemGroup>

依赖项类型dependency type

类型：项目type: project

  1. {
  2.   "dependencies": {
  3.     "MyOtherProject": "1.0.0-*",
  4.     "AnotherProject": {
  5.       "type": "project"
  6.     }
  7.   }
  8. }
  1. <ItemGroup>
  2.   <ProjectReference Include="..\MyOtherProject\MyOtherProject.csproj" />
  3.   <ProjectReference Include="..\AnotherProject\AnotherProject.csproj" />
  4. </ItemGroup>

备注

这将打破 dotnet pack —version-suffix $suffix 确定项目引用的依赖项版本的方式。

类型：生成type: build

  1. {
  2.   "dependencies": {
  3.     "Microsoft.EntityFrameworkCore.Design": {
  4.       "version": "1.1.0",
  5.       "type": "build"
  6.     }
  7.   }
  8. }
  1. <ItemGroup>
  2.   <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="1.1.0" PrivateAssets="All" />
  3. </ItemGroup>

类型：平台type: platform

  1. {
  2.   "dependencies": {
  3.     "Microsoft.NETCore.App": {
  4.       "version": "1.1.0",
  5.       "type": "platform"
  6.     }
  7.   }
  8. }

csproj 中没有等效项。

runtimesruntimes

  1. {
  2.   "runtimes": {
  3.     "win7-x64": {},
  4.     "osx.10.11-x64": {},
  5.     "ubuntu.16.04-x64": {}
  6.   }
  7. }
  1. <PropertyGroup>
  2.   <RuntimeIdentifiers>win7-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
  3. </PropertyGroup>

独立应用（独立部署）Standalone apps (self-contained deployment)

在 project.json 中，定义 runtimes 部分意味着应用在生成和发布期间独立。在 MSBuild 中，生成期间所有项目均可移植，但可发布为独立。

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

有关详细信息，请参阅独立部署 (SCD)。

工具tools

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

备注

csproj 中不支持工具上的 imports。需要导入的工具无法用于新的 Microsoft.NET.Sdk。

buildOptionsbuildOptions

另请参阅文件。

emitEntryPointemitEntryPoint

  1. {
  2.   "buildOptions": {
  3.     "emitEntryPoint": true
  4.   }
  5. }
  1. <PropertyGroup>
  2.   <OutputType>Exe</OutputType>
  3. </PropertyGroup>

如果 emitEntryPoint 为 false，OutputType 的值会转换为 Library（这是默认值）：

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

keyFilekeyFile

  1. {
  2.   "buildOptions": {
  3.     "keyFile": "MyKey.snk"
  4.   }
  5. }

keyFile 元素在 MSBuild 中扩展为三个属性：

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

其他常用生成选项Other common build options

  1. {
  2.   "buildOptions": {
  3.     "warningsAsErrors": true,
  4.     "nowarn": ["CS0168", "CS0219"],
  5.     "xmlDoc": true,
  6.     "preserveCompilationContext": true,
  7.     "outputName": "Different.AssemblyName",
  8.     "debugType": "portable",
  9.     "allowUnsafe": true,
  10.     "define": ["TEST", "OTHERCONDITION"]
  11.   }
  12. }
  1. <PropertyGroup>
  2.   <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  3.   <NoWarn>$(NoWarn);CS0168;CS0219</NoWarn>
  4.   <GenerateDocumentationFile>true</GenerateDocumentationFile>
  5.   <PreserveCompilationContext>true</PreserveCompilationContext>
  6.   <AssemblyName>Different.AssemblyName</AssemblyName>
  7.   <DebugType>portable</DebugType>
  8.   <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  9.   <DefineConstants>$(DefineConstants);TEST;OTHERCONDITION</DefineConstants>
  10. </PropertyGroup>

packOptionspackOptions

另请参阅文件。

常用包选项Common pack options

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

MSBuild 中没有 owners 元素的等效项。对于 summary，可使用 MSBuild <Description> 属性 - 即使 summary 的值未自动迁移到该属性，因为该属性已映射到 description 元素。

脚本scripts

  1. {
  2.   "scripts": {
  3.     "precompile": "generateCode.cmd",
  4.     "postpublish": [ "obfuscate.cmd", "removeTempFiles.cmd" ]
  5.   }
  6. }

它们在 MSBuild 中的等效项是目标：

  1. <Target Name="MyPreCompileTarget" BeforeTargets="Build">
  2.   <Exec Command="generateCode.cmd" />
  3. </Target>
  5. <Target Name="MyPostCompileTarget" AfterTargets="Publish">
  6.   <Exec Command="obfuscate.cmd" />
  7.   <Exec Command="removeTempFiles.cmd" />
  8. </Target>

runtimeOptionsruntimeOptions

  1. {
  2.   "runtimeOptions": {
  3.     "configProperties": {
  4.       "System.GC.Server": true,
  5.       "System.GC.Concurrent": true,
  6.       "System.GC.RetainVM": true,
  7.       "System.Threading.ThreadPool.MinThreads": 4,
  8.       "System.Threading.ThreadPool.MaxThreads": 25
  9.     }
  10.   }
  11. }

此组中除“System.GC.Server”属性以外的所有设置与迁移过程中提升为根对象的选项一并被置于项目文件夹中名为 runtimeconfig.template.json 的文件中：

  1. {
  2.   "configProperties": {
  3.     "System.GC.Concurrent": true,
  4.     "System.GC.RetainVM": true,
  5.     "System.Threading.ThreadPool.MinThreads": 4,
  6.     "System.Threading.ThreadPool.MaxThreads": 25
  7.   }
  8. }

已将“System.GC.Server”属性迁移到 csproj 文件：

  1. <PropertyGroup>
  2.   <ServerGarbageCollection>true</ServerGarbageCollection>
  3. </PropertyGroup>

但可以在 csproj 以及 MSBuild 属性中设置所有这些值：

  1. <PropertyGroup>
  2.   <ServerGarbageCollection>true</ServerGarbageCollection>
  3.   <ConcurrentGarbageCollection>true</ConcurrentGarbageCollection>
  4.   <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
  5.   <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
  6.   <ThreadPoolMaxThreads>25</ThreadPoolMaxThreads>
  7. </PropertyGroup>

共享shared

  1. {
  2.   "shared": "shared/**/*.cs"
  3. }

在 csproj 中不支持。而必须在 .nuspec 文件中创建要包含的内容文件。有关详细信息，请参阅包含内容文件。

文件files

在 project.json 中，可将生成和打包操作扩展为从不同的文件夹进行编译和嵌入。在 MSBuild 中，使用项实现此操作。以下示例是一个常见转换：

  1. {
  2.   "buildOptions": {
  3.     "compile": {
  4.       "copyToOutput": "notes.txt",
  5.       "include": "../Shared/*.cs",
  6.       "exclude": "../Shared/Not/*.cs"
  7.     },
  8.     "embed": {
  9.       "include": "../Shared/*.resx"
  10.     }
  11.   },
  12.   "packOptions": {
  13.     "include": "Views/",
  14.     "mappings": {
  15.       "some/path/in/project.txt": "in/package.txt"
  16.     }
  17.   },
  18.   "publishOptions": {
  19.     "include": [
  20.       "files/",
  21.       "publishnotes.txt"
  22.     ]
  23.   }
  24. }
  1. <ItemGroup>
  2.   <Compile Include="..\Shared\*.cs" Exclude="..\Shared\Not\*.cs" />
  3.   <EmbeddedResource Include="..\Shared\*.resx" />
  4.   <Content Include="Views\**\*" PackagePath="%(Identity)" />
  5.   <None Include="some/path/in/project.txt" Pack="true" PackagePath="in/package.txt" />
  7.   <None Include="notes.txt" CopyToOutputDirectory="Always" />
  8.   <!-- CopyToOutputDirectory = { Always, PreserveNewest, Never } -->
  10.   <Content Include="files\**\*" CopyToPublishDirectory="PreserveNewest" />
  11.   <None Include="publishnotes.txt" CopyToPublishDirectory="Always" />
  12.   <!-- CopyToPublishDirectory = { Always, PreserveNewest, Never } -->
  13. </ItemGroup>

备注

许多默认 glob 模式)由 .NET Core SDK 自动添加。有关更多信息，请参见默认编译项值。

所有 MSBuild ItemGroup 元素都支持Include、Exclude 和 Remove。

可使用 PackagePath="path" 修改 .nupkg 内的包布局。

除 Content 外，大多数项组需要显式添加要包括在包中的 Pack="true"。Content 将被置于包中的 content 文件夹，因为 <IncludeContentInPack> 属性默认设置为 true。有关详细信息，请参阅在包中包含内容。

PackagePath="%(Identity)" 是一种将包路径设置为项目相对文件路径的快捷方法。

testRunnertestRunner

xUnitxUnit

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

MSTestMSTest

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

请参阅See also