Die Zuordnung zwischen project.json und csproj-Eigenschaften

Von Nate McMaster

Bei der Entwicklung von .NET Core-Tools wurde eine wichtige Änderung durchgeführt. project.json-Dateien werden nicht länger unterstützt und die .NET Core-Projekte stattdessen in das Format MSBuild/Csproj verschoben.

Dieser Artikel zeigt, wie die Einstellungen in project.json im MSBuild/Csproj-Format dargestellt sind, damit Sie das neue Format verwenden können und die Änderungen durch die Migrationstools kennen, wenn Sie Ihr Projekt auf die neueste Version der Tools aktualisieren.

Das Csproj-Format

Das neue Format *.csproj, ist ein XML-basiertes Format. Im folgenden Beispiel wird der Stammknoten eines .NET Core-Projekts mit Microsoft.NET.Sdk gezeigt. Für Webprojekte ist das verwendete SDK Microsoft.NET.Sdk.Web.

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

Allgemeine Eigenschaften der obersten Ebene

Name

{
  "name": "MyProjectName"
}

Wird nicht mehr unterstützt. In csproj wird dies durch den Dateinamen des Projekts festgelegt, der durch den Namen des Verzeichnisses definiert wird. Beispielsweise MyProjectName.csproj.

Standardmäßig gibt der Dateiname des Projekts auch den Wert der <AssemblyName>- und <PackageId>- Eigenschaften an.

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

<AssemblyName> wird einen anderen Wert als <PackageId> haben, wenn die Eigenschaft buildOptions\outputName in project.json definiert wurde. Weitere Informationen finden Sie unter Andere gängige Buildoptionen.

Version

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

Verwenden Sie die VersionPrefix- und VersionSuffix-Eigenschaften:

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

Sie können auch die Version-Eigenschaft verwenden, aber dies kann beim Packen Versionseinstellungen überschreiben:

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

Andere allgemeinen Optionen auf der Stammebene

{
  "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

Ein Zielframework

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

Mehrere Zielframeworks

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

Verwenden Sie die TargetFrameworks-Eigenschaft, um Ihre Liste der Zielframeworks zu definieren. Verwenden Sie Semikolons, um mehrere Frameworkwerte zu trennen.

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

Abhängigkeiten

Wichtig

Wenn die Abhängigkeit ein Projekt und kein Paket ist, ist das Format anders. Weitere Informationen finden Sie im Abschnitt Abhängigkeitstyp.

NETStandard.Library-Metapaket

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

Microsoft.NETCore.App-Metapaket

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

Beachten Sie, dass sich der <RuntimeFrameworkVersion>-Wert im migrierten Projekt nach der Version des SDK richtet, das Sie installiert haben.

Abhängigkeiten der obersten Ebene

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

Abhängigkeiten nach Framework

{
  "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>

Importe

{
  "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>

Abhängigkeitstyp

Typ: Projekt

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

Dies wird die Art unterbrechen, in der dotnet pack --version-suffix $suffix die Abhängigkeitsversion eines Projektverweises bestimmt.

Typ: Build

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

Typ: Plattform

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

Es gibt keine Entsprechung in csproj.

Laufzeiten

{
  "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>

Eigenständige Anwendungen (eigenständige Bereitstellung)

In Project.json bedeutet das Definieren eines runtimes-Abschnitts, dass die Anwendung während der Erstellung und Veröffentlichung eigenständig war. Alle Projekte in MSBuild sind während des Buildvorgangs tragbar, werden jedoch eigenständig veröffentlicht.

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

Weitere Informationen finden Sie unter Eigenständige Bereitstellungen (SCD).

Tools

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

imports auf Tools werden nicht in csproj unterstützt. Tools, die Importe benötigen, funktionieren nicht mit dem neuen Microsoft.NET.Sdk.

buildOptions

Siehe auch Dateien.

emitEntryPoint

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

Wenn emitEntryPoint false betrug, wird der Wert von OutputType zu Library konvertiert, der der folgende Standardwert ist:

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

keyFile

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

Das keyFile-Element wird auf drei Eigenschaften in MSBuild erweitert:

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

Andere allgemeine Buildoptionen

{
  "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

Siehe auch Dateien.

Allgemeine Paketoptionen

{
  "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>

Es gibt keine Entsprechung für das owners-Element in MSBuild. Für summary können Sie die <Description>-Eigenschaft von MSBuild verwenden, obwohl der Wert der summary nicht automatisch zur Eigenschaft migriert wird, da die Eigenschaft dem description-Element zugeordnet ist.

Skripts

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

Ihre Entsprechungen in MSBuild sind Ziele:

<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
    }
  }
}

Alle Einstellungen in dieser Gruppe, außer für die Eigenschaft „System.GC.Server“ befinden sich in einer Datei namens runtimeconfig.template.json im Projektordner mit den Optionen, die während der Migration auf das Stammobjekt transformiert werden:

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

Die Eigenschaft „System.GC.Server“ ist in die csproj-Datei migriert:

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

Allerdings können Sie alle diese Werte in der csproj sowie den MSBuild-Eigenschaften festlegen:

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

Freigegeben

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

Wird nicht in csproj unterstützt. Stattdessen müssen Sie Dateien zum Einschließen von Inhalten in Ihrer .nuspec-Datei erstellen. Weitere Informationen finden Sie unter Inhaltsdateien einschließen.

Dateien

In project.json könnten Build und das Paket erweitert werden, um aus unterschiedlichen Ordnern zu kompilieren und einzubetten. In MSBuild wird dies unter Verwendung von Elementen erledigt. Im folgenden Beispiel sehen Sie eine allgemeine Konversion:

{
  "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>
Hinweis

Viele der Standardglobmuster werden automatisch durch das .NET Core SDK hinzugefügt. Weitere Informationen finden Sie unter Werte für Standardkompilierungselemente.

Alle ItemGroup-Elemente von MSBuild unterstützen Include, Exclude und Remove.

Paketlayout in der .nupkg kann mit PackagePath="path" geändert werden.

Mit Ausnahme von Content erfordern die meisten Artikelgruppen das explizite Hinzufügen von Pack="true" in das Paket. Content wird in den Ordner Inhalt in einem Paket versetzt werden, da die <IncludeContentInPack>-Eigenschaft von MSBuild standardmäßig auf true festgelegt ist. Weitere Informationen finden Sie unter Inhalt in ein Paket einschließen.

PackagePath="%(Identity)" ist eine mühelose Möglichkeit, mit der ein Paketpfad auf den projektspezifischen Dateipfad festgelegt werden kann.

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>

Siehe auch

Allgemeine Übersicht über Änderungen in CLI