Uso de .NET Core SDK y herramientas de integración continua (CI)Using .NET Core SDK and tools in Continuous Integration (CI)

En este documento se describe el uso del SDK de .NET Core y sus herramientas en un servidor de compilación.This document outlines using the .NET Core SDK and its tools on a build server. El conjunto de herramientas de .NET Core funciona tanto de forma interactiva, donde un desarrollador escribe comandos en un símbolo del sistema, como de manera automática, donde un servidor de integración continua (CI) ejecuta un script de compilación.The .NET Core toolset works both interactively, where a developer types commands at a command prompt, and automatically, where a Continuous Integration (CI) server runs a build script. Los comandos, las opciones, las entradas y las salidas son los mismos, y solo lo que el usuario especifica sirve para adquirir las herramientas y un sistema para compilar la aplicación.The commands, options, inputs, and outputs are the same, and the only things you supply are a way to acquire the tooling and a system to build your app. Este documento se centra en escenarios de adquisición de herramientas de integración continua, donde además se ofrecen recomendaciones sobre cómo diseñar y estructurar los scripts de compilación.This document focuses on scenarios of tool acquisition for CI with recommendations on how to design and structure your build scripts.

Opciones de instalación para los servidores de compilación de CIInstallation options for CI build servers

Uso de instaladores nativosUsing the native installers

Los instaladores nativos están disponibles para macOS, Linux y Windows.Native installers are available for macOS, Linux, and Windows. Los instaladores requieren acceso de administrador (sudo) para el servidor de compilación.The installers require admin (sudo) access to the build server. El instalador nativo ofrece la ventaja de que instala todas las dependencias nativas necesarias para la ejecución de las herramientas.The advantage of using a native installer is that it installs all of the native dependencies required for the tooling to run. Además, los instaladores nativos instalan el SDK en todo el sistema.Native installers also provide a system-wide installation of the SDK.

Los usuarios de macOS deben usar los instaladores PKG.macOS users should use the PKG installers. En Linux, se ofrece la posibilidad de usar un administrador de paquetes basado en fuentes, como apt-get para Ubuntu o yum para CentOS, o de usar los mismos paquetes (DEB o RPM).On Linux, there's a choice of using a feed-based package manager, such as apt-get for Ubuntu or yum for CentOS, or using the packages themselves, DEB or RPM. En Windows, utilice el instalador MSI.On Windows, use the MSI installer.

Los archivos binarios estables más recientes se encuentran en Descargas de .NET.The latest stable binaries are found at .NET downloads. Si desea utilizar las herramientas de la última versión preliminar, que posiblemente sean inestables, use los vínculos proporcionados en el repositorio de GitHub dotnet/core-sdk.If you wish to use the latest (and potentially unstable) pre-release tooling, use the links provided at the dotnet/core-sdk GitHub repository. Para las distribuciones de Linux, se encuentran disponibles los archivos tar.gz (conocidos también como tarballs); use los scripts de instalación dentro de los archivos para instalar .NET Core.For Linux distributions, tar.gz archives (also known as tarballs) are available; use the installation scripts within the archives to install .NET Core.

Uso del script del instaladorUsing the installer script

El uso del script del instalador permite la instalación sin derechos administrativos en el servidor de compilación y una sencilla automatización para obtener las herramientas.Using the installer script allows for non-administrative installation on your build server and easy automation for obtaining the tooling. El script se encarga de descargar las herramientas y extraerlas en una ubicación predeterminada o especificada para su uso.The script takes care of downloading the tooling and extracting it into a default or specified location for use. También puede especificar la versión de las herramientas que desea instalar y si prefiere instalar el SDK completo o solo el runtime compartido.You can also specify a version of the tooling that you wish to install and whether you want to install the entire SDK or only the shared runtime.

El script del instalador se puede automatizar para que se ejecute al principio de la compilación, a fin de obtener e instalar la versión deseada del SDK.The installer script is automated to run at the start of the build to fetch and install the desired version of the SDK. La versión deseada se corresponde con cualquier versión del SKD que los proyectos necesitan para la compilación.The desired version is whatever version of the SDK your projects require to build. El script permite instalar el SDK en un directorio local del servidor, ejecutar las herramientas desde la ubicación de instalación y limpiar después de la compilación, o bien dejar que el servicio de CI realice dicha limpieza.The script allows you to install the SDK in a local directory on the server, run the tools from the installed location, and then clean up (or let the CI service clean up) after the build. Esto permite encapsular y aislar todo el proceso de compilación.This provides encapsulation and isolation to your entire build process. La referencia del script de instalación se encuentra en el artículo dotnet-install.The installation script reference is found in the dotnet-install article.

Nota

Azure DevOps ServicesAzure DevOps Services

Cuando se utiliza el script del instalador, las dependencias nativas no se instalan automáticamente.When using the installer script, native dependencies aren't installed automatically. Debe instalarlas en caso de el sistema operativo no las incluya.You must install the native dependencies if the operating system doesn't have them. Para más información, consulte Requisitos previos para .NET Core en Linux.For more information, see Prerequisites for .NET Core on Linux.

Ejemplos de configuración de CICI setup examples

En esta sección se explica un procedimiento de instalación manual con un script de PowerShell o de Bash, además de incluir una descripción de varias soluciones de CI de software como servicio (SaaS).This section describes a manual setup using a PowerShell or bash script, along with a description of several software as a service (SaaS) CI solutions. Las soluciones de CI de SaaS tratadas son Travis CI, AppVeyor y Azure Pipelines.The SaaS CI solutions covered are Travis CI, AppVeyor, and Azure Pipelines.

Instalación manualManual setup

Cada servicio de SaaS tiene sus propios métodos para crear y configurar un proceso de compilación.Each SaaS service has its own methods for creating and configuring a build process. Si usa una solución de SaaS distinta a las que indican o necesita realizar alguna personalización aparte de la compatibilidad preconfigurada, debe realizar al menos alguna configuración manual.If you use different SaaS solution than those listed or require customization beyond the pre-packaged support, you must perform at least some manual configuration.

En general, para realizar una instalación manual, es necesario que adquiera una versión de las herramientas o las últimas compilaciones nocturnas de las herramientas y que, después, ejecute el script de compilación.In general, a manual setup requires you to acquire a version of the tools (or the latest nightly builds of the tools) and run your build script. Puede usar un script de PowerShell o de Bash para orquestar los comandos de .NET Core o utilizar un archivo del proyecto en el que se describa el proceso de compilación.You can use a PowerShell or bash script to orchestrate the .NET Core commands or use a project file that outlines the build process. En la sección de orquestación se ofrece más información sobre estas opciones.The orchestration section provides more detail on these options.

Después de crear un script que realiza una instalación manual del servidor de compilación de CI, úselo en el equipo de desarrollo para compilar el código de forma local con fines de pruebas.After you create a script that performs a manual CI build server setup, use it on your dev machine to build your code locally for testing purposes. Cuando confirme que el script se ejecuta de forma correcta en el entorno local, impleméntelo en el servidor de compilación de CI.Once you confirm that the script is running well locally, deploy it to your CI build server. Un script de PowerShell relativamente sencillo demuestra cómo obtener el SDK de NET Core e instalarlo en un servidor de compilación de Windows:A relatively simple PowerShell script demonstrates how to obtain the .NET Core SDK and install it on a Windows build server:

$ErrorActionPreference="Stop"
$ProgressPreference="SilentlyContinue"

# $LocalDotnet is the path to the locally-installed SDK to ensure the
#   correct version of the tools are executed.
$LocalDotnet=""
# $InstallDir and $CliVersion variables can come from options to the
#   script.
$InstallDir = "./cli-tools"
$CliVersion = "1.0.1"

# Test the path provided by $InstallDir to confirm it exists. If it
#   does, it's removed. This is not strictly required, but it's a
#   good way to reset the environment.
if (Test-Path $InstallDir)
{
    rm -Recurse $InstallDir
}
New-Item -Type "directory" -Path $InstallDir

Write-Host "Downloading the CLI installer..."

# Use the Invoke-WebRequest PowerShell cmdlet to obtain the
#   installation script and save it into the installation directory.
Invoke-WebRequest `
    -Uri "https://dot.net/v1/dotnet-install.ps1" `
    -OutFile "$InstallDir/dotnet-install.ps1"

Write-Host "Installing the CLI requested version ($CliVersion) ..."

# Install the SDK of the version specified in $CliVersion into the
#   specified location ($InstallDir).
& $InstallDir/dotnet-install.ps1 -Version $CliVersion `
    -InstallDir $InstallDir

Write-Host "Downloading and installation of the SDK is complete."

# $LocalDotnet holds the path to dotnet.exe for future use by the
#   script.
$LocalDotnet = "$InstallDir/dotnet"

# Run the build process now. Implement your build script here.

Debe proporcionar la implementación para el proceso de compilación al final del script.You provide the implementation for your build process at the end of the script. El script adquiere las herramientas y, después, ejecuta el proceso de compilación.The script acquires the tools and then executes your build process. En los equipos UNIX, el siguiente script de Bash realiza las acciones descritas en el script de PowerShell de forma similar:For UNIX machines, the following bash script performs the actions described in the PowerShell script in a similar manner:

#!/bin/bash
INSTALLDIR="cli-tools"
CLI_VERSION=1.0.1
DOWNLOADER=$(which curl)
if [ -d "$INSTALLDIR" ]
then
    rm -rf "$INSTALLDIR"
fi
mkdir -p "$INSTALLDIR"
echo Downloading the CLI installer.
$DOWNLOADER https://dot.net/v1/dotnet-install.sh > "$INSTALLDIR/dotnet-install.sh"
chmod +x "$INSTALLDIR/dotnet-install.sh"
echo Installing the CLI requested version $CLI_VERSION. Please wait, installation may take a few minutes.
"$INSTALLDIR/dotnet-install.sh" --install-dir "$INSTALLDIR" --version $CLI_VERSION
if [ $? -ne 0 ]
then
    echo Download of $CLI_VERSION version of the CLI failed. Exiting now.
    exit 0
fi
echo The CLI has been installed.
LOCALDOTNET="$INSTALLDIR/dotnet"
# Run the build process now. Implement your build script here.

Travis CITravis CI

Puede configurar Travis CI para instalar el SDK de .NET Core con el lenguaje csharp y la clave dotnet.You can configure Travis CI to install the .NET Core SDK using the csharp language and the dotnet key. Para más información, consulte los documentos oficiales de Travis CI en Building a C#, F#, or Visual Basic Project (Compilación de un proyecto de C#, F# o Visual Basic).For more information, see the official Travis CI docs on Building a C#, F#, or Visual Basic Project. Al acceder a la información de Travis CI, observará que el identificador de lenguaje language: csharp de cuyo mantenimiento se encarga la comunidad funciona con todos los lenguajes de .NET, incluidos F# y Mono.Note as you access the Travis CI information that the community-maintained language: csharp language identifier works for all .NET languages, including F#, and Mono.

Travis CI se ejecuta tanto en trabajos de macOS como de Linux en una matriz de compilación, donde debe especificar una combinación de runtime, entorno y exclusiones/inclusiones para aceptar las combinaciones de compilación de la aplicación.Travis CI runs both macOS and Linux jobs in a build matrix, where you specify a combination of runtime, environment, and exclusions/inclusions to cover your build combinations for your app. Para más información, vea el artículo Customizing the Build (Personalización de la compilación) en la documentación de Travis CI.For more information, see the Customizing the Build article in the Travis CI documentation. Las herramientas basadas en MSBuild incluyen los runtimes LTS (1.0.x) y Current (1.1.x) en el paquete; por tanto, cuando instala el SDK, recibe todo lo que necesita para la compilación.The MSBuild-based tools include the LTS (1.0.x) and Current (1.1.x) runtimes in the package; so by installing the SDK, you receive everything you need to build.

AppVeyorAppVeyor

AppVeyor instala el SDK de .NET Core 1.0.1 con la imagen de trabajo de compilación de Visual Studio 2017.AppVeyor installs the .NET Core 1.0.1 SDK with the Visual Studio 2017 build worker image. Hay disponibles otras imágenes de compilación con distintas versiones del SDK de .NET Core.Other build images with different versions of the .NET Core SDK are available. Para más información, consulte el ejemplo appveyor.yml y el artículo Build worker images (Imágenes de trabajo de compilación) en los documentos de AppVeyor.For more information, see the appveyor.yml example and the Build worker images article in the AppVeyor docs.

Los archivos binarios del SDK de .NET Core se descargan y descomprimen en un subdirectorio con la utilización del script de instalación y, después, se agregan a la variable de entorno PATH.The .NET Core SDK binaries are downloaded and unzipped in a subdirectory using the install script, and then they're added to the PATH environment variable. Agregue una matriz de compilación para ejecutar las pruebas de integración con varias versiones del SDK de .NET Core:Add a build matrix to run integration tests with multiple versions of the .NET Core SDK:

environment:
  matrix:
    - CLI_VERSION: 1.0.1
    - CLI_VERSION: Latest

install:
  # See appveyor.yml example for install script

Azure DevOps ServicesAzure DevOps Services

Configure Azure DevOps Services para compilar proyectos de .NET Core con alguno de estos enfoques:Configure Azure DevOps Services to build .NET Core projects using one of these approaches:

  1. Ejecute el script del paso de instalación manual con sus comandos.Run the script from the manual setup step using your commands.
  2. Cree una compilación compuesta de varias tareas de compilación integradas en Azure DevOps Services que están configuradas para usar herramientas de .NET Core.Create a build composed of several Azure DevOps Services built-in build tasks that are configured to use .NET Core tools.

Ambas soluciones son válidas.Both solutions are valid. Con la utilización de un script de instalación manual, puede controlar la versión de las herramientas que recibe, ya que las descarga como parte de la compilación.Using a manual setup script, you control the version of the tools that you receive, since you download them as part of the build. La compilación se ejecuta desde un script que debe crear.The build is run from a script that you must create. En este artículo solo se trata la opción manual.This article only covers the manual option. Para más información sobre cómo elaborar una compilación con las tareas de compilación de Azure DevOps Services, consulte la documentación de Azure Pipelines.For more information on composing a build with Azure DevOps Services build tasks, see the Azure Pipelines documentation.

Para usar un script de instalación manual en Azure DevOps Services, cree una definición de compilación y especifique el script que va a ejecutar para el paso de compilación.To use a manual setup script in Azure DevOps Services, create a new build definition and specify the script to run for the build step. Esto se realiza en la interfaz de usuario de Azure DevOps Services:This is accomplished using the Azure DevOps Services user interface:

  1. Empiece por crear una definición de compilación.Start by creating a new build definition. Cuando llegue a la pantalla en la que se ofrece la opción de definir el tipo de compilación que desea crear, seleccione la opción Vacío.Once you reach the screen that provides you an option to define what kind of a build you wish to create, select the Empty option.

    Selección de una definición de compilación vacía

  2. Después de configurar el repositorio que va a compilar, se le remite a las definiciones de compilación.After configuring the repository to build, you're directed to the build definitions. Seleccione Agregar paso de compilación:Select Add build step:

    Agregar un paso de compilación

  3. Se abre el Catálogo de tareas.You're presented with the Task catalog. El catálogo contiene tareas que se utilizan en la compilación.The catalog contains tasks that you use in the build. Como ya tiene un script, haga clic en el botón Agregar en PowerShell: Ejecute un script de PowerShell.Since you have a script, select the Add button for PowerShell: Run a PowerShell script.

    Paso para agregar un script de PowerShell

  4. Configure el paso de compilación.Configure the build step. Agregue el script desde el repositorio que se va a compilar:Add the script from the repository that you're building:

    Especificar el script de PowerShell que va a ejecutar

Orquestación de la compilaciónOrchestrating the build

En la mayor parte de este documento se describe cómo adquirir las herramientas de .NET Core y configurar varios servicios de CI sin ofrecer información sobre cómo orquestar o compilar realmente el código con .NET Core.Most of this document describes how to acquire the .NET Core tools and configure various CI services without providing information on how to orchestrate, or actually build, your code with .NET Core. Las opciones para estructurar el proceso de compilación dependen de muchos factores que no se pueden tratar aquí en términos generales.The choices on how to structure the build process depend on many factors that can't be covered in a general way here. Para más información sobre cómo orquestar las compilaciones con cada tecnología, explore los recursos y los ejemplos que se proporciona en los conjuntos de documentación de Travis CI, AppVeyor y Azure Pipelines.For more information on orchestrating your builds with each technology, explore the resources and samples provided in the documentation sets of Travis CI, AppVeyor, and Azure Pipelines.

Dos enfoques generales que se aplican para estructurar el proceso de compilación del código de .NET Core con herramientas de .NET Core consisten en utilizar directamente MSBuild o en usar los comandos de la línea de comandos de .NET Core.Two general approaches that you take in structuring the build process for .NET Core code using the .NET Core tools are using MSBuild directly or using the .NET Core command-line commands. El enfoque que debe adoptar depende de lo cómo que se sienta con cada uno de ellos y de los inconvenientes que presente su complejidad.Which approach you should take is determined by your comfort level with the approaches and trade-offs in complexity. MSBuild ofrece la posibilidad de expresar el proceso de compilación como tareas y objetivos, pero presenta la complejidad añadida de tener que aprender la sintaxis del archivo de proyecto de MSBuild.MSBuild provides you the ability to express your build process as tasks and targets, but it comes with the added complexity of learning MSBuild project file syntax. Quizá sea más sencillo usar las herramientas de línea de comandos de .NET Core, pero, en este caso, es necesario escribir la lógica de orquestación en un lenguaje de scripting como bash o PowerShell.Using the .NET Core command-line tools is perhaps simpler, but it requires you to write orchestration logic in a scripting language like bash or PowerShell.

Vea tambiénSee also