Creación de un paquete NuGet con MSBuildCreate a NuGet package using MSBuild

Cuando crea un paquete NuGet a partir del código, empaqueta la funcionalidad en un componente que se pueda compartir con otros desarrolladores, así como que estos puedan usarlo.When you create a NuGet package from your code, you package that functionality into a component that can be shared with and used by any number of other developers. En este artículo se describe cómo crear un paquete con MSBuild.This article describes how to create a package using MSBuild. MSBuild viene preinstalado con cada carga de trabajo de Visual Studio que incluya NuGet.MSBuild comes preinstalled with every Visual Studio workload that contains NuGet. Además, también se puede usar MSBuild mediante la CLI de dotnet con dotnet msbuild.Additionally you can also use MSBuild through the dotnet CLI with dotnet msbuild.

Con los proyectos .NET Core y .NET Standard que usan el formato de estilo SDK y cualquier otro proyecto de estilo SDK, NuGet usa la información del archivo de proyecto directamente para crear un paquete.For .NET Core and .NET Standard projects that use the SDK-style format, and any other SDK-style projects, NuGet uses information in the project file directly to create a package. En el caso de un proyecto sin SDK que use <PackageReference>, NuGet también usará el archivo del proyecto para crear un paquete.For a non-SDK-style project that uses <PackageReference>, NuGet also uses the project file to create a package.

Los proyectos con SDK tienen la funcionalidad de paquetes disponible de forma predeterminada.SDK-style projects have the pack functionality available by default. En el caso de los proyectos PackageReference sin SDK, deberá agregar el paquete NuGet.Build.Tasks.Pack a las dependencias del proyecto.For non SDK-style PackageReference projects, you need to add the NuGet.Build.Tasks.Pack package to the project dependencies. Para obtener información detallada sobre los destinos de paquete de MSBuild, vea pack y restore de NuGet como destinos de MSBuild.For detailed information about MSBuild pack targets, see NuGet pack and restore as MSBuild targets.

El comando que crea un paquete, msbuild -t:pack, es equivalente funcionalmente a dotnet pack.The command that creates a package, msbuild -t:pack, is functionality equivalent to dotnet pack.

Importante

Este tema se aplica a los proyectos con SDK, que suelen ser proyectos de .NET Core y .NET Standard, así como a los paquetes sin SDK que usan PackageReference.This topic applies to SDK-style projects, typically .NET Core and .NET Standard projects, and to non-SDK-style projects that use PackageReference.

Establecimiento de las propiedadesSet properties

Las propiedades siguientes se requieren para crear un paquete.The following properties are required to create a package.

  • PackageId, el identificador de paquete, que debe ser único en la galería que hospeda el paquete.PackageId, the package identifier, which must be unique across the gallery that hosts the package. Si no se especifica, el valor predeterminado es AssemblyName.If not specified, the default value is AssemblyName.
  • Version, un número de versión específico con el formato Principal.Secundaria.Revisión[-Sufijo] donde -Sufijo identifica las versiones preliminares.Version, a specific version number in the form Major.Minor.Patch[-Suffix] where -Suffix identifies pre-release versions. Si no se especifica, el valor predeterminado es 1.0.0.If not specified, the default value is 1.0.0.
  • El título del paquete como debe aparecer en el host (por ejemplo, nuget.org)The package title as it should appear on the host (like nuget.org)
  • Authors, información del autor y el propietario.Authors, author and owner information. Si no se especifica, el valor predeterminado es AssemblyName.If not specified, the default value is AssemblyName.
  • Company, el nombre de la empresa.Company, your company name. Si no se especifica, el valor predeterminado es AssemblyName.If not specified, the default value is AssemblyName.

En Visual Studio, puede establecer estos valores en las propiedades del proyecto (haga clic con el botón derecho en el proyecto en el Explorador de soluciones, elija Propiedades y seleccione la pestaña Paquete).In Visual Studio, you can set these values in the project properties (right-click the project in Solution Explorer, choose Properties, and select the Package tab). También puede establecer estas propiedades directamente en los archivos del proyecto ( .csproj).You can also set these properties directly in the project files (.csproj).

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

Importante

Asigne al paquete un identificador que sea único en nuget.org o en el origen de paquete que esté usando.Give the package an identifier that's unique across nuget.org or whatever package source you're using.

En el ejemplo siguiente se muestra un archivo del proyecto sencillo y completo que incluye estas propiedades.The following example shows a simple, complete project file with these properties included.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

También puede establecer las propiedades opcionales, como Title, PackageDescription y PackageTags, tal como se describe en los destinos de paquetes de MSBuild, la sección Controlar los recursos de dependencias y Propiedades de los metadatos de NuGet.You can also set the optional properties, such as Title, PackageDescription, and PackageTags, as described in MSBuild pack targets, Controlling dependency assets, and NuGet metadata properties.

Nota

En el caso de los paquetes creados para consumo público, preste especial atención la propiedad PackageTags, dado que estas etiquetas ayudan a otros usuarios a encontrar el paquete y comprender lo que hace.For packages built for public consumption, pay special attention to the PackageTags property, as tags help others find your package and understand what it does.

Para obtener más información sobre cómo declarar dependencias y especificar números de versión, vea Referencias del paquete en archivos del proyecto y Control de versiones de paquetes.For details on declaring dependencies and specifying version numbers, see Package references in project files and Package versioning. También es posible exponer recursos directamente desde las dependencias en el paquete mediante los atributos <IncludeAssets> y <ExcludeAssets>.It is also possible to surface assets from dependencies directly in the package by using the <IncludeAssets> and <ExcludeAssets> attributes. Para más información, consulte Controlar los recursos de dependencias.For more information, seee Controlling dependency assets.

Elección de un identificador de paquete único y establecimiento del número de versiónChoose a unique package identifier and set the version number

El identificador del paquete y el número de versión son los dos valores más importantes del proyecto, ya que identifican de forma única el código exacto que se incluye en el paquete.The package identifier and the version number are the two most important values in the project because they uniquely identify the exact code that's contained in the package.

Procedimientos recomendados para el identificador del paquete:Best practices for the package identifier:

  • Unicidad: el identificador debe ser único en nuget.org o en la galería que hospede el paquete.Uniqueness: The identifier must be unique across nuget.org or whatever gallery hosts the package. Antes de decidirse por un identificador, busque en la galería aplicable para comprobar si el nombre ya está en uso.Before deciding on an identifier, search the applicable gallery to check if the name is already in use. Para evitar conflictos, un buen patrón consiste en usar el nombre de la empresa como la primera parte del identificador, por ejemplo Contoso..To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as Contoso..
  • Nombres de tipo espacio de nombres: siguen un patrón similar a los espacios de nombres de .NET, con notación de puntos en lugar de guiones.Namespace-like names: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. Por ejemplo, use Contoso.Utility.UsefulStuff en lugar de Contoso-Utility-UsefulStuff o Contoso_Utility_UsefulStuff.For example, use Contoso.Utility.UsefulStuff rather than Contoso-Utility-UsefulStuff or Contoso_Utility_UsefulStuff. También es útil para los consumidores cuando el identificador del paquete coincide con los espacios de nombres que se usan en el código.Consumers also find it helpful when the package identifier matches the namespaces used in the code.
  • Paquetes de ejemplo: si genera un paquete de código de ejemplo que muestra cómo usar otro paquete, adjunte .Sample como sufijo al identificador, como en Contoso.Utility.UsefulStuff.Sample.Sample Packages: If you produce a package of sample code that demonstrates how to use another package, attach .Sample as a suffix to the identifier, as in Contoso.Utility.UsefulStuff.Sample. (El paquete de ejemplo tendría evidentemente una dependencia en el otro paquete). Cuando cree un paquete de ejemplo, use el valor contentFiles en <IncludeAssets>.(The sample package would of course have a dependency on the other package.) When creating a sample package, use the contentFiles value in <IncludeAssets>. En la carpeta content, organice el código de ejemplo en una carpeta denominada \Samples\<identifier> como en \Samples\Contoso.Utility.UsefulStuff.Sample.In the content folder, arrange the sample code in a folder called \Samples\<identifier> as in \Samples\Contoso.Utility.UsefulStuff.Sample.

Procedimientos recomendados para la versión del paquete:Best practices for the package version:

  • En general, establezca la versión del paquete para que coincida con el proyecto (o ensamblado), aunque esto no es estrictamente necesario.In general, set the version of the package to match the project (or assembly), though this is not strictly required. Esto resulta muy sencillo cuando limita un paquete a un solo ensamblado.This is a simple matter when you limit a package to a single assembly. En general, recuerde que el propio NuGet trabaja con versiones del paquete al resolver las dependencias, no con versiones de ensamblado.Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions.
  • Cuando se usa un esquema de la versión no estándar, asegúrese de tener en cuenta las reglas de control de versiones de NuGet, como se explica en Control de versiones de paquetes.When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in Package versioning. NuGet es principalmente compatible con semver 2.NuGet is mostly semver 2 compliant.

Para información sobre la resolución de las dependencias, consulte Resolución de dependencias con PackageReference.For information on dependency resolution, see Dependency resolution with PackageReference. Para información anterior que también podría ser útil para entender mejor el control de versiones, consulte esta serie de entradas de blog.For older information that may also be helpful to better understand versioning, see this series of blog posts.

Adición del paquete NuGet.Build.Tasks.PackAdd the NuGet.Build.Tasks.Pack package

Si usa MSBuild con un proyecto sin SDK y PackageReference, agregue el paquete NuGet.Build.Tasks.Pack al proyecto.If you are using MSBuild with a non-SDK-style project and PackageReference, add the NuGet.Build.Tasks.Pack package to your project.

  1. Abra el archivo del proyecto y agregue lo siguiente tras el elemento <PropertyGroup>:Open the project file and add the following after the <PropertyGroup> element:

    <ItemGroup>
      <!-- ... -->
      <PackageReference Include="NuGet.Build.Tasks.Pack" Version="5.2.0"/>
      <!-- ... -->
    </ItemGroup>
    
  2. Abra un símbolo del sistema para desarrolladores (en el cuadro Búsqueda, escriba Símbolo del sistema para desarrolladores).Open a Developer command prompt (In the Search box, type Developer command prompt).

    Normalmente, es preferible iniciar el símbolo del sistema para desarrolladores de Visual Studio en el menú Inicio, ya que se configurará con todas las rutas de acceso necesarias para MSBuild.You typically want to start the Developer Command Prompt for Visual Studio from the Start menu, as it will be configured with all the necessary paths for MSBuild.

  3. Cambie a la carpeta que contiene el archivo del proyecto y escriba el siguiente comando para instalar el paquete NuGet.Build.Tasks.Pack.Switch to the folder containing the project file and type the following command to install the NuGet.Build.Tasks.Pack package.

    # Uses the project file in the current folder by default
    msbuild -t:restore
    

    Asegúrese de que la salida de MSBuild indica que la compilación se ha completado correctamente.Make sure that the MSBuild output indicates that the build completed successfully.

Ejecución del comando msbuild -t:packRun the msbuild -t:pack command

Para compilar un paquete NuGet (un archivo .nupkg) desde el proyecto, ejecute el comando msbuild -t:pack, que también genera el proyecto automáticamente:To build a NuGet package (a .nupkg file) from the project, run the msbuild -t:pack command, which also builds the project automatically:

En el símbolo del sistema para desarrolladores de Visual Studio, escriba el comando siguiente:In the Developer command prompt for Visual Studio, type the following command:

# Uses the project file in the current folder by default
msbuild -t:pack

El resultado mostrará la ruta de acceso al archivo .nupkg.The output shows the path to the .nupkg file.

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

Generación automática del paquete en la compilaciónAutomatically generate package on build

Para ejecutar automáticamente msbuild -t:pack al compilar o restaurar el proyecto, agregue la siguiente línea al archivo del proyecto en <PropertyGroup>:To automatically run msbuild -t:pack when you build or restore the project, add the following line to your project file within <PropertyGroup>:

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Cuando ejecuta msbuild -t:pack en una solución, se empaquetan todos los proyectos de la solución que se pueden empaquetar (la propiedad se establece en true).When you run msbuild -t:pack on a solution, this packs all the projects in the solution that are packable ( property is set to true).

Nota

Cuando genera automáticamente el paquete, el tiempo de empaquetado aumenta el tiempo de compilación del proyecto.When you automatically generate the package, the time to pack increases the build time for your project.

Prueba de instalación del paqueteTest package installation

Antes de publicar un paquete, normalmente querrá probar el proceso de instalación de un paquete en un proyecto.Before publishing a package, you typically want to test the process of installing a package into a project. Las pruebas aseguran que los archivos necesarios acaban en los lugares correctos en el proyecto.The tests make sure that the necessarily files all end up in their correct places in the project.

Puede probar las instalaciones de forma manual en Visual Studio o en la línea de comandos mediante los pasos de instalación de paquetes normales.You can test installations manually in Visual Studio or on the command line using the normal package installation steps.

Importante

Los paquetes son inmutables.Packages are immutable. Si corrige un problema, cambie el contenido del paquete y vuelva a empaquetar. Cuando vuelva a realizar la prueba, seguirá usando la versión anterior del paquete hasta que bote la carpeta global de paquetes.If you correct a problem, change the contents of the package and pack again, when you retest you will still be using the old version of the package until you clear your global packages folder. Esto resulta especialmente relevante cuando se prueban paquetes que no usan una etiqueta preliminar única en cada compilación.This is especially relevant when testing packages that don't use a unique prerelease label on every build.

Pasos siguientesNext Steps

Una vez haya creado un paquete, que es un archivo .nupkg, puede publicarlo en la galería de su elección como se describe en Publicación de un paquete.Once you've created a package, which is a .nupkg file, you can publish it to the gallery of your choice as described on Publishing a Package.

Es posible que también quiera ampliar las funcionalidades del paquete o admitir otros escenarios, como se describe en los temas siguientes:You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics:

Por último, hay tipos de paquete adicionales que tener en cuenta:Finally, there are additional package types to be aware of: