Mapping tra le proprietà di project.json e csprojA mapping between project.json and csproj properties

di Nate McMasterBy Nate McMaster

Durante lo sviluppo degli strumenti di .NET Core, è stata apportata una modifica importante che non supporta più i file project.json e sposta invece i progetti .NET Core nel formato MSBuild/csproj.During the development of the .NET Core tooling, an important design change was made to no longer support project.json files and instead move the .NET Core projects to the MSBuild/csproj format.

Questo articolo illustra come vengono rappresentate le impostazioni di project.json nel formato MSBuild/csproj, offre informazioni sull'uso del nuovo formato e consente di capire le modifiche apportate dagli strumenti di migrazione quando si aggiorna un progetto alla nuova versione degli strumenti.This article shows how the settings in project.json are represented in the MSBuild/csproj format so you can learn how to use the new format and understand the changes made by the migration tools when you're upgrading your project to the latest version of the tooling.

Formato csprojThe csproj format

Il nuovo formato, *.csproj, è un formato basato su XML.The new format, *.csproj, is an XML-based format. L'esempio seguente illustra il nodo radice di un progetto .NET Core usando Microsoft.NET.Sdk.The following example shows the root node of a .NET Core project using the Microsoft.NET.Sdk. Per i progetti Web, l'SDK usato è Microsoft.NET.Sdk.Web.For web projects, the SDK used is Microsoft.NET.Sdk.Web.

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

Proprietà comuni di livello superioreCommon top-level properties

namename

{
  "name": "MyProjectName"
}

Non è più supportato.No longer supported. In csproj è determinato dal nome del file di progetto, che in genere corrisponde al nome della directory.In csproj, this is determined by the project filename, which usually matches the directory name. Ad esempio, MyProjectName.csproj.For example, MyProjectName.csproj.

Per impostazione predefinita, il nome del file di progetto specifica anche il valore delle proprietà <AssemblyName> e <PackageId>.By default, the project filename also specifies the value of the <AssemblyName> and <PackageId> properties.

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

La proprietà <AssemblyName> avrà un valore diverso da <PackageId> se la proprietà buildOptions\outputName è stata definita in project.json.The <AssemblyName> will have a different value than <PackageId> if buildOptions\outputName property was defined in project.json. Per altre informazioni, vedere Altre opzioni comuni di compilazione.For more information, see Other common build options.

versionversion

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

Usare le proprietà VersionPrefix e VersionSuffix:Use the VersionPrefix and VersionSuffix properties:

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

È anche possibile usare la proprietà Version, ma questa operazione potrebbe causare la sovrascrittura delle impostazioni della versione durante la creazione di pacchetti:You can also use the Version property, but this may override version settings during packaging:

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

Altre opzioni comuni a livello radiceOther common root-level options

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

frameworksframeworks

Un solo framework di destinazioneOne target framework

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

Più framework di destinazioneMultiple target frameworks

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

Usare la proprietà TargetFrameworks per definire l'elenco dei framework di destinazione.Use the TargetFrameworks property to define your list of target frameworks. Usare un punto e virgola per separare più valori di framework.Use semi-colon to separate multiple framework values.

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

dipendenzedependencies

Importante

Se la dipendenza è un progetto e non un pacchetto, il formato è diverso.If the dependency is a project and not a package, the format is different. Per altre informazioni, vedere la sezione Tipo di dipendenza.For more information, see the dependency type section.

Metapacchetto NETStandard.LibraryNETStandard.Library metapackage

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

Metapacchetto Microsoft.NETCore.AppMicrosoft.NETCore.App metapackage

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

Si noti che il valore <RuntimeFrameworkVersion> nel progetto migrato è determinato dalla versione dell'SDK installato.Note that the <RuntimeFrameworkVersion> value in the migrated project is determined by the version of the SDK you have installed.

Dipendenze di livello superioreTop-level dependencies

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

Dipendenze per frameworkPer-framework dependencies

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

importazioniimports

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

Tipo di dipendenzadependency type

Tipo: progettotype: project

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

Nota

Questa operazione interrompe il modo in cui dotnet pack --version-suffix $suffix determina la versione di dipendenza di un riferimento al progetto.This will break the way that dotnet pack --version-suffix $suffix determines the dependency version of a project reference.

Tipo: compilazionetype: build

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

Tipo: piattaformatype: platform

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

Non è disponibile nessuna opzione equivalente in csproj.There is no equivalent in csproj.

runtimesruntimes

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

App indipendenti (distribuzione autonoma)Standalone apps (self-contained deployment)

In project.json, la definizione di una sezione runtimes indica che l'app era indipendente durante la compilazione e la pubblicazione.In project.json, defining a runtimes section means the app was standalone during build and publish. In MSBuild, tutti i progetti sono portatili durante la creazione, ma possono essere pubblicati come autonomi.In MSBuild, all projects are portable during build, but can be published as standalone.

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

Per altre informazioni, vedere Distribuzioni autonome (SCD).For more information, see Self-contained deployments (SCD).

strumentitools

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

Nota

Gli imports sugli strumenti non sono supportati in csproj.imports on tools are not supported in csproj. Gli strumenti che hanno bisogno di imports non funzionano con il nuovo Microsoft.NET.Sdk.Tools that need imports will not work with the new Microsoft.NET.Sdk.

buildOptionsbuildOptions

Vedere anche Files.See also Files.

emitEntryPointemitEntryPoint

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

Se emitEntryPoint fosse false, il valore di OutputType verrebbe convertito in Library, ovvero il valore predefinito:If emitEntryPoint was false, the value of OutputType is converted to Library, which is the default value:

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

keyFilekeyFile

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

L'elemento keyFile si espande a tre proprietà in MSBuild:The keyFile element expands to three properties in MSBuild:

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

Altre opzioni comuni di compilazioneOther common build options

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

packOptionspackOptions

Vedere anche Files.See also Files.

Opzioni comuni di pacchettoCommon pack options

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

Non è disponibile nessuna opzione equivalente per l'elemento owners in MSBuild.There is no equivalent for the owners element in MSBuild. In summary è possibile usare la proprietà <Description> di MSBuild, anche se il valore di summary non viene migrato automaticamente a tale proprietà, poiché tale proprietà è mappata all'elemento description.For summary, you can use the MSBuild <Description> property, even though the value of summary is not migrated automatically to that property, since that property is mapped to the description element.

scriptscripts

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

Gli equivalenti in MSBuild sono i target:Their equivalent in MSBuild are targets:

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

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

runtimeOptionsruntimeOptions

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

Tutte le impostazioni in questo gruppo, ad eccezione della proprietà "System.GC.Server", vengono inserite in un file denominato runtimeconfig.template.json nella cartella del progetto, con le opzioni elevate all'oggetto radice durante il processo di migrazione:All settings in this group, except for the "System.GC.Server" property, are placed into a file called runtimeconfig.template.json in the project folder, with options lifted to the root object during the migration process:

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

La proprietà "System.GC.Server" viene migrata nel file csproj:The "System.GC.Server" property is migrated into the csproj file:

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

È possibile tuttavia impostare tutti questi valori nel file csproj e anche nelle proprietà di MSBuild:However, you can set all those values in the csproj as well as MSBuild properties:

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

condivisoshared

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

Non supportato in csproj.Not supported in csproj. È invece necessario creare e includere i file di contenuto nel file .nuspec.You must instead create include content files in your .nuspec file. Per altre informazioni, vedere Including content files (Includere i file di contenuto).For more information, see Including content files.

filefiles

In project.json, la compilazione e la creazione di pacchetti possono essere estese per compilare e incorporare da cartelle diverse.In project.json, build and pack could be extended to compile and embed from different folders. In MSBuild, questa operazione viene eseguita tramite items.In MSBuild, this is done using items. L'esempio seguente illustra una conversione comune:The following example is a common conversion:

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

Nota

Molti dei criteri GLOB predefiniti vengono aggiunti automaticamente da .NET Core SDK.Many of the default globbing patterns are added automatically by the .NET Core SDK. Per altre informazioni, vedere Default Compile Item Values (Valori predefiniti degli elementi di compilazione).For more information, see Default Compile Item Values.

Tutti gli elementi ItemGroup di MSBuild supportano Include, Exclude e Remove.All MSBuild ItemGroup elements support Include, Exclude, and Remove.

Il layout del pacchetto all'interno di .nupkg può essere modificato con PackagePath="path".Package layout inside the .nupkg can be modified with PackagePath="path".

Ad eccezione di Content, la maggior parte dei gruppi di elementi richiedono in modo esplicito l'aggiunta di Pack="true" nel pacchetto.Except for Content, most item groups require explicitly adding Pack="true" to be included in the package. Content verrà incluso nella cartella content in un pacchetto poiché la proprietà <IncludeContentInPack> di MSBuild è impostata su true per impostazione predefinita.Content will be put in the content folder in a package since the MSBuild <IncludeContentInPack> property is set to true by default. Per altre informazioni, vedere Including content in a package (Includere contenuto in un pacchetto).For more information, see Including content in a package.

PackagePath="%(Identity)" è un modo breve di impostare il percorso di un pacchetto sul percorso del file relativo al progetto.PackagePath="%(Identity)" is a short way of setting package path to the project-relative file path.

testRunnertestRunner

xUnitxUnit

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

MSTestMSTest

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

Vedere ancheSee also