dotnet build

Artículo
11/27/2023

Este artículo se aplica a: ✔️ SDK de .NET Core 3.1 y versiones posteriores

NOMBRE

dotnet build: compila un proyecto y todas sus dependencias.

Sinopsis

dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
    [--disable-build-servers]
    [--force] [--interactive] [--no-dependencies] [--no-incremental]
    [--no-restore] [--nologo] [--no-self-contained] [--os <OS>]
    [-o|--output <OUTPUT_DIRECTORY>]
    [-p|--property:<PROPERTYNAME>=<VALUE>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--self-contained [true|false]] [--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

dotnet build -h|--help

Descripción

El comando dotnet build crea el proyecto y sus dependencias en un conjunto de archivos binarios. Los archivos binarios incluyen el código del proyecto en archivos de lenguaje intermedio (IL) con una extensión .dll. Según el tipo de proyecto y la configuración, se pueden incluir otros archivos, como los siguientes:

Un archivo ejecutable que se pueda usar para ejecutar la aplicación, si el tipo de proyecto es un archivo ejecutable que tiene como destino .NET Core 3.0 o versiones posteriores.
Archivos de símbolos usados para la depuración con una extensión .pdb.
Un archivo .deps.json, que muestra las dependencias de la aplicación o la biblioteca.
Un archivo .runtimeconfig.json, que especifica el runtime compartido y su versión de una aplicación.
Otras bibliotecas de las que depende el proyecto (a través de referencias de proyecto o referencias de paquetes NuGet).

En el caso de los proyectos ejecutables que tienen como destino versiones anteriores a .NET Core 3.0, las dependencias de biblioteca de NuGet normalmente no se copian en la carpeta de salida. Se resuelven desde la carpeta de paquetes globales NuGet en tiempo de ejecución. Teniendo eso en cuenta, el producto de dotnet build no está listo para transferirse a otra máquina para ejecutarse. Para crear una versión de la aplicación que se pueda implementar, se debe publicar (por ejemplo, con el comando dotnet publish). Para obtener más información, vea Implementación de aplicaciones de .NET.

En el caso de los proyectos ejecutables que tienen como destino .NET Core 3.0 y versiones posteriores, las dependencias de biblioteca se copian en la carpeta de salida. Esto significa que, si no hay ninguna otra lógica específica de la publicación (como los proyectos web), se debería poder implementar la salida de la compilación.

Restauración implícita

La compilación requiere el archivo project.assets.json, que muestra las dependencias de la aplicación. El archivo se crea cuando se ejecuta dotnet restore. Sin el archivo de recursos en su lugar, las herramientas no pueden resolver los ensamblados de referencia, lo que se traduce en errores.

No es necesario ejecutar dotnet restore porque lo ejecutan implícitamente todos los comandos que necesitan que se produzca una restauración, como dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish y dotnet pack. Para deshabilitar la restauración implícita, use la opción --no-restore.

El comando dotnet restore sigue siendo válido en algunos escenarios donde tiene sentido realizar una restauración explícita, como las compilaciones de integración continua en Azure DevOps Services o en los sistemas de compilación que necesitan controlar explícitamente cuándo se produce la restauración.

Para obtener información sobre cómo administrar fuentes de NuGet, vea la documentación de dotnet restore.

Este comando admite las opciones de dotnet restore cuando se pasan con el formato largo (por ejemplo, --source). No se admiten las opciones de formato corto, como -s.

Salida de biblioteca o ejecutable

Si el proyecto es ejecutable o no viene determinado por la propiedad <OutputType> en el archivo del proyecto. En el ejemplo siguiente se muestra un proyecto en el que se genera código ejecutable:

<PropertyGroup>
  <OutputType>Exe</OutputType>
</PropertyGroup>

Para generar una biblioteca, omita la propiedad <OutputType> o cambie su valor a Library. La DLL de IL para una biblioteca no contiene puntos de entrada y no se puede ejecutar.

MSBuild

dotnet build usa MSBuild para compilar el proyecto, por lo que admite las compilaciones en paralelo e incrementales. Para obtener más información, consulte Compilaciones incrementales.

Además de sus opciones, el comando dotnet build acepta opciones de MSBuild, como -p para establecer propiedades o -l para definir un registrador. Para obtener más información sobre estas opciones, vea la Referencia de la línea de comandos de MSBuild. O también puede usar el comando dotnet msbuild.

Nota

Cuando dotnet build lo ejecuta automáticamente dotnet run, no se respetan argumentos como -property:property=value.

Ejecutar dotnet build es equivalente a ejecutar dotnet msbuild -restore; sin embargo, el nivel de detalle predeterminado de la salida es distinto.

Descargas de manifiestos de cargas de trabajo

Cuando se ejecuta, este comando inicia una descarga asincrónica en segundo plano de manifiestos de publicidad de cargas de trabajo. Si la descarga no ha terminado cuando finaliza el comando, se detiene. Para obtener más información, vea Manifiestos de publicidad.

Argumentos

PROJECT | SOLUTION

El archivo de proyecto o solución para compilar. Si no se especifica un archivo de proyecto o solución, MSBuild busca en el directorio de trabajo actual un archivo que tiene una extensión de archivo que termina por proj o sln y usa ese archivo.

Opciones

-a|--arch <ARCHITECTURE>

Especifica la arquitectura de destino. Se trata de una sintaxis abreviada para establecer el identificador del entorno de ejecución (RID), donde el valor proporcionado se combina con el RID predeterminado. Por ejemplo, en un equipo win-x64, al especificar --arch x86 se establece el RID en win-x86. Si usa esta opción, no use la opción -r|--runtime. Disponible a partir de .NET 6 (versión preliminar 7).

--artifacts-path <ARTIFACTS_DIR>

Todos los archivos de salida de compilación del comando ejecutado se incluirán en subcarpetas en la ruta de acceso especificada, separadas por el proyecto. Para obtener más información, consulte Diseño de salida de artefactos. Disponible a partir del SDK de .NET 8.

-c|--configuration <CONFIGURATION>

Define la configuración de compilación. El valor predeterminado para la mayoría de los proyectos es Debug, pero puede invalidar los valores de configuración de compilación en el proyecto.

--disable-build-servers

Obliga al comando a omitir los servidores de compilación persistentes. Esta opción proporciona una manera coherente de deshabilitar todo el uso del almacenamiento en caché de compilación, lo que fuerza una compilación desde cero. Una compilación que no se basa en memorias caché es útil cuando las memorias caché están dañadas o tienen un estado incorrecto por algún motivo. Disponible a partir del SDK de .NET 7.

-f|--framework <FRAMEWORK>

Compila para un marco de trabajo específico. El marco se debe definir en el archivo de proyecto. Ejemplos: net7.0, net462.
--force

Fuerza la resolución de todas las dependencias, incluso si la última restauración se realizó correctamente. Especificar esta marca es lo mismo que eliminar el archivo project.assets.json.

-?|-h|--help

Imprime una descripción de cómo usar el comando.

--interactive

Permite que el comando se detenga y espere una entrada o una acción del usuario. Por ejemplo, para completar la autenticación. Disponible desde el SDK de .NET Core 3.0.

--no-dependencies

Omite las referencias de proyecto a proyecto (P2P) y solo compila el proyecto raíz especificado.
--no-incremental

Marca la compilación como no segura para la compilación incremental. Esta marca desactiva la compilación incremental y fuerza una recompilación limpia del gráfico de dependencias del proyecto.
--no-restore

No ejecuta una restauración implícita durante la compilación.
--nologo

No se muestra la pancarta de inicio ni el mensaje de copyright.
--no-self-contained

Publica la aplicación como una aplicación dependiente del marco. Debe instalarse un entorno de ejecución de .NET compatible en la máquina de destino para ejecutar la aplicación. Disponible a partir del SDK de .NET 6.
-o|--output <OUTPUT_DIRECTORY>

Directorio donde se colocan los archivos binarios compilados. Si no se especifica la ruta de acceso predeterminada es ./bin/<configuration>/<framework>/. En el caso de los proyectos con varias plataformas de destino (a través de la propiedad TargetFrameworks), también debe definir --framework al especificar esta opción.
- SDK de .NET 7.0.200 y versiones posteriores
  
  Si especifica la opción --output al ejecutar este comando en una solución, la CLI emitirá una advertencia (un error en la versión 7.0.200) debido a la semántica poco clara de la ruta de acceso de salida. No se permite la opción --output porque todas las salidas de todos los proyectos compilados se copiarían en el directorio especificado, que no es compatible con proyectos de varios destinos, así como con proyectos que tienen diferentes versiones de dependencias directas y transitivas. Para más información, consulte la opción Nivel de solución: la opción --output ya no es válida para los comandos relacionados con la compilación.

--os <OS>

Especifica el sistema operativo (SO) de destino. Se trata de una sintaxis abreviada para establecer el identificador del entorno de ejecución (RID), donde el valor proporcionado se combina con el RID predeterminado. Por ejemplo, en un equipo win-x64, al especificar --os linux se establece el RID en linux-x64. Si usa esta opción, no use la opción -r|--runtime. Disponible a partir de .NET 6.

-p|--property:<PROPERTYNAME>=<VALUE>

Establece una o varias propiedades MSBuild. Especifique varias propiedades delimitadas por punto y coma o repitiendo la opción:
```
--property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
--property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
```
-r|--runtime <RUNTIME_IDENTIFIER>

Especifica el tiempo de ejecución de destino. Para obtener una lista de identificadores de tiempo de ejecución (RID), consulte el catálogo de RID. Si usa esta opción con el SDK de .NET 6, use --self-contained o --no-self-contained también. Si no se especifica, lo predeterminado es compilar para el sistema operativo y la arquitectura actuales.
--self-contained [true|false]

Publica el entorno de ejecución de .NET con la aplicación para que no sea necesario instalarlo en el equipo de destino. Si se especifica un identificador de tiempo de ejecución, el valor predeterminado es true. Disponible a partir de .NET 6.
--source <SOURCE>

URI del origen del paquete NuGet que se usará durante la operación de restauración.

--tl:[auto|on|off]

Especifica si se debe usar el registrador de terminal para la salida de compilación. El valor predeterminado es auto, que primero comprueba el entorno antes de habilitar el registro de terminal. La comprobación del entorno comprueba que el terminal sea capaz de usar características de salida modernas y no usa una salida estándar redirigida antes de habilitar el nuevo registrador. La opción on omite la comprobación del entorno y habilita el registro de terminal. La opción off omite la comprobación del entorno y usa el registrador de consola predeterminado.

El registrador de terminal muestra la fase de restauración seguida de la fase de compilación. Durante cada fase, los proyectos en compilación actuales aparecen en la parte inferior del terminal. Cada proyecto que se compila genera una salida del destino de MSBuild que se está compilando actualmente y la cantidad de tiempo invertido en ese destino. Puede buscar en esta información para obtener más información sobre la compilación. Cuando un proyecto termina de compilarse, se escribe una única sección "compilación completada" en la que se captura lo siguiente:
- El nombre del proyecto compilado.
- La plataforma de destino (si es de destino múltiple).
- El estado de esa compilación.
- La salida principal de esa compilación (con hipervínculo).
- Los diagnósticos generados para ese proyecto.
Esta opción está disponible a partir de .NET 8.

-v|--verbosity <LEVEL>

Establece el nivel de detalle del comando. Los valores permitidos son q[uiet], m[inimal], n[ormal], d[etailed] y diag[nostic]. De manera predeterminada, es minimal. De forma predeterminada, MSBuild muestra advertencias y errores en todos los niveles de detalle. Para excluir las advertencias, use /property:WarningLevel=0. Para más información, consulte LoggerVerbosity y WarningLevel.
--use-current-runtime, --ucr [true|false]

Establece RuntimeIdentifier en una plataforma portátil RuntimeIdentifier, en función de la que haya en la máquina. Esto sucede implícitamente con propiedades que requieren un RuntimeIdentifier, como SelfContained, PublishAot, PublishSelfContained, PublishSingleFile, y PublishReadyToRun. Si la propiedad se establece en false, esa resolución implícita ya no se producirá.
--version-suffix <VERSION_SUFFIX>

Establece el valor de la propiedad $(VersionSuffix) que se va a usar al compilar el proyecto. Solo funciona si no se establece la propiedad $(Version). A continuación, $(Version) se establece en $(VersionPrefix) combinada con $(VersionSuffix), separadas por un guion.

Ejemplos

Creación de un proyecto y sus dependencias:
```
dotnet build
```
Creación de un proyecto y sus dependencias mediante la configuración de lanzamiento:
```
dotnet build --configuration Release
```
Compile un proyecto y sus dependencias para un entorno de ejecución específico (en este ejemplo, Linux):
```
dotnet build --runtime linux-x64
```
Compile el proyecto y use el origen del paquete NuGet especificado durante la operación de restauración:
```
dotnet build --source c:\packages\mypackages
```
Compile el proyecto y establezca la versión 1.2.3.4 como un parámetro de compilación mediante la -popción de MSBuild:
```
dotnet build -p:Version=1.2.3.4
```