Una asignación entre propiedades project.json y csprojA mapping between project.json and csproj properties

Por Nate McMasterBy Nate McMaster

Durante el desarrollo de las herramientas de .NET Core, se realizó un cambio de diseño importante para dejar de admitir los archivos project.json y trasladar en su lugar los proyectos .NET Core al 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.

En este artículo se muestra cómo se representa la configuración de project.json en el formato MSBuild/csproj para que pueda aprender a usar el nuevo formato y comprender los cambios realizados por las herramientas de migración cuando actualice el proyecto a la versión más reciente de la herramienta.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.

El formato csprojThe csproj format

El nuevo formato, *.csproj, está basado en XML.The new format, *.csproj, is an XML-based format. En el ejemplo siguiente se muestra el nodo raíz de un proyecto .NET Core con el SDK Microsoft.NET.Sdk.The following example shows the root node of a .NET Core project using the Microsoft.NET.Sdk. Para proyectos web, el SDK que se usa es Microsoft.NET.Sdk.Web.For web projects, the SDK used is Microsoft.NET.Sdk.Web.

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

Propiedades comunes de nivel superiorCommon top-level properties

namename

{
  "name": "MyProjectName"
}

Ya no se admite.No longer supported. En csproj, viene determinado por el nombre de archivo del proyecto, que normalmente coincide con el nombre del directorio.In csproj, this is determined by the project filename, which usually matches the directory name. Por ejemplo: MyProjectName.csproj.For example, MyProjectName.csproj.

De forma predeterminada, el nombre de archivo del proyecto también especifica el valor de las propiedades <AssemblyName> y <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 propiedad <AssemblyName> tendrá un valor diferente a <PackageId> si se ha definido la propiedad buildOptions\outputName en project.json.The <AssemblyName> will have a different value than <PackageId> if buildOptions\outputName property was defined in project.json. Para obtener más información, consulte Otras opciones de compilación comunes.For more information, see Other common build options.

versionversion

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

Use las propiedades VersionPrefix y VersionSuffix:Use the VersionPrefix and VersionSuffix properties:

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

También puede usar la propiedad Version, pero esto puede invalidar la configuración de la versión durante el empaquetado:You can also use the Version property, but this may override version settings during packaging:

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

Otras opciones comunes de nivel de raízOther 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 marco de trabajo de destinoOne target framework

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

Varios marcos de trabajo de destinoMultiple target frameworks

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

Use la propiedad TargetFrameworks para definir la lista de los marcos de trabajo de destino.Use the TargetFrameworks property to define your list of target frameworks. Use el punto y coma para separar varios valores de marco de trabajo.Use semi-colon to separate multiple framework values.

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

dependenciasdependencies

Importante

Si la dependencia es un proyecto y no un paquete, el formato es diferente.If the dependency is a project and not a package, the format is different. Para obtener más información, consulte la sección tipo de dependencia.For more information, see the dependency type section.

Metapaquete NETStandard.LibraryNETStandard.Library metapackage

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

Metapaquete Microsoft.NETCore.AppMicrosoft.NETCore.App metapackage

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

El valor <RuntimeFrameworkVersion> del proyecto migrado viene determinado por la versión del SDK que ha instalado.The <RuntimeFrameworkVersion> value in the migrated project is determined by the version of SDK that's installed.

Dependencias de nivel superiorTop-level dependencies

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

Dependencias por marco de trabajoPer-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>

importsimports

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

dependency typedependency type

type: projecttype: project

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

Nota

Esto interrumpirá la forma en que dotnet pack --version-suffix $suffix determina la versión de dependencia de una referencia de proyecto.This will break the way that dotnet pack --version-suffix $suffix determines the dependency version of a project reference.

type: buildtype: 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: platformtype: platform

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

No existe ningún equivalente en 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>

Aplicaciones independientes (implementación autocontenida)Standalone apps (self-contained deployment)

En project.json, definir una sección runtimes implica que la aplicación se ha mantenido independiente durante la compilación y la publicación.In project.json, defining a runtimes section means the app was standalone during build and publish. En MSBuild, todos los proyectos son portátiles durante la compilación, pero se pueden publicar como independientes.In MSBuild, all projects are portable during build, but can be published as standalone.

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

Para obtener más información, consulte Implementaciones autocontenidas (SCD).For more information, see Self-contained deployments (SCD).

toolstools

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

Nota

En csproj no se admite imports en herramientas.imports on tools are not supported in csproj. Las herramientas que necesitan importaciones no funcionarán con el nuevo SDK Microsoft.NET.Sdk.Tools that need imports will not work with the new Microsoft.NET.Sdk.

buildOptionsbuildOptions

Consulte también Archivos.See also Files.

emitEntryPointemitEntryPoint

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

Si emitEntryPoint era false, el valor de OutputType se convierte en Library, que es el valor predeterminado: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"
  }
}

El elemento keyFile se expande a tres propiedades en 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>

Otras opciones de compilación comunesOther 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

Consulte también Archivos.See also Files.

Opciones comunes de empaquetadoCommon 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>
  <PackageIcon>ico.png</PackageIcon>
  <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>

No hay ningún equivalente del elemento owners en MSBuild.There is no equivalent for the owners element in MSBuild. En summary, puede usar la propiedad <Description> de MSBuild.For summary, you can use the MSBuild <Description> property. El valor de summary no se migra automáticamente a esa propiedad, ya que está asignada al elemento description.The value of summary is not migrated automatically to that property, since that property is mapped to the description element. PackageIconUrl está en desuso en favor de PackageIcon.PackageIconUrl is deprecated in favor of PackageIcon.

scriptsscripts

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

Sus equivalentes en MSBuild son destinos:Their equivalents 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
    }
  }
}

Todos los valores de configuración de este grupo, excepto la propiedad System.GC.Server, se colocan en un archivo denominado runtimeconfig.template.json en la carpeta del proyecto, con opciones elevadas al objeto raíz durante el proceso de migración: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 propiedad System.GC.Server se migra en el archivo csproj:The System.GC.Server property is migrated into the csproj file:

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

En cambio, puede establecer todos esos valores en csproj, así como en propiedades de 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>

sharedshared

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

No se admite en csproj.Not supported in csproj. En su lugar, cree archivos de contenido de inclusión en el archivo .nuspec.Instead, create include content files in your .nuspec file. Para obtener más información, consulte Including content files (Incluir archivos de contenido).For more information, see Including content files.

archivosfiles

En project.json, la compilación y el empaquetado podrían ampliarse para compilar e insertar desde diferentes carpetas.In project.json, build and pack could be extended to compile and embed from different folders. En MSBuild, esto se hace mediante elementos.In MSBuild, this is done using items. En el siguiente ejemplo se muestra una conversión común: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

El SDK de .NET Core agrega automáticamente muchos de los patrones globales predeterminados.Many of the default globbing patterns are added automatically by the .NET Core SDK. Para más información, consulte Inclusiones de compilación predeterminadas.For more information, see Default compilation includes.

Todos los elementos ItemGroup de MSBuild admiten Include, Exclude y Remove.All MSBuild ItemGroup elements support Include, Exclude, and Remove.

Se puede modificar el diseño del paquete dentro de .nupkg con PackagePath="path".Package layout inside the .nupkg can be modified with PackagePath="path".

A excepción de Content, la mayoría de los grupos de elementos requiere que se agregue explícitamente Pack="true" para incluirlos en el paquete.Except for Content, most item groups require explicitly adding Pack="true" to be included in the package. Content se colocará en la carpeta content de un paquete, puesto que la propiedad <IncludeContentInPack> de MSBuild está establecida como true de forma predeterminada.Content will be put in the content folder in a package since the MSBuild <IncludeContentInPack> property is set to true by default. Para obtener más información, consulte Including content in a package (Incluir contenido en un paquete).For more information, see Including content in a package.

PackagePath="%(Identity)" es una forma rápida de establecer la ruta del paquete como la ruta del archivo relativa al proyecto.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>

Vea tambiénSee also