Verwenden des .NET Core SDK und der zugehörigen Tools in Continuous Integration (CI)Using .NET Core SDK and tools in Continuous Integration (CI)

ÜbersichtOverview

In diesem Dokument wird die Verwendung des .NET Core SDK und der zugehörigen Tools auf einem Buildserver beschrieben.This document outlines using the .NET Core SDK and its tools on a build server. Das .NET Core-Toolset arbeitet sowohl interaktiv – der Entwickler gibt Befehle an der Eingabeaufforderung ein – als auch automatisch, wenn ein Continuous Integration-Server (CI) ein Buildskript ausführt.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. Die Befehle, Optionen, Eingaben und Ausgaben sind dieselben, Sie stellen lediglich eine Methode zum Download der Tools und ein System zur Erstellung Ihrer App bereit.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. Dieses Dokument konzentriert sich auf Szenarien für den Tooldownload für CI mit Empfehlungen zum Entwerfen und Strukturieren Ihrer Buildskripts.This document focuses on scenarios of tool acquisition for CI with recommendations on how to design and structure your build scripts.

Installationsoptionen für CI-BuildserverInstallation options for CI build servers

Verwenden der nativen InstallationsprogrammeUsing the native installers

Native Installationsprogramme stehen für macOS, Linux und Windows zur Verfügung.Native installers are available for macOS, Linux, and Windows. Für die Installationsprogramme benötigen Sie Administratorzugriff (sudo) auf den Buildserver.The installers require admin (sudo) access to the build server. Der Vorteil der Verwendung eines nativen Installationsprogramms liegt darin, dass alle nativen Abhängigkeiten installiert werden, die zum Ausführen der Tools benötigt werden.The advantage of using a native installer is that it installs all of the native dependencies required for the tooling to run. Native Installationsprogramme ermöglichen außerdem eine systemweite Installation des SDK.Native installers also provide a system-wide installation of the SDK.

macOS-Benutzer sollten die PKG-Installationsprogramme verwenden.macOS users should use the PKG installers. Unter Linux können Sie entweder einen feedbasierten Paket-Manager, z.B. apt-get für Ubuntu oder yum für CentOS, oder die Pakete selbst (also DEB oder RPM) verwenden.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. Verwenden Sie unter Windows den MSI-Installer.On Windows, use the MSI installer.

Die neuesten stabilen Binärdateien finden Sie unter Erste Schritte mit .NET Core.The latest stable binaries are found at Get Started with .NET Core. Wenn Sie die neuesten (möglicherweise instabilen) Vorabtools verwenden möchten, nutzen Sie die Links im dotnet/cli-GitHub-Repository.If you wish to use the latest (and potentially unstable) pre-release tooling, use the links provided at the dotnet/cli GitHub repository. Für Linux-Distributionen stehen tar.gz-Archive (auch bekannt als tarballs) zur Verfügung. Verwenden Sie die Installationsskripts in den Archiven, um .NET Core zu installieren.For Linux distributions, tar.gz archives (also known as tarballs) are available; use the installation scripts within the archives to install .NET Core.

Verwenden des InstallationsprogrammskriptsUsing the installer script

Das Installationsprogrammskript ermöglicht eine Installation ohne Administratorrechte auf dem Buildserver und bietet eine einfache Automatisierung zum Download der Tools.Using the installer script allows for non-administrative installation on your build server and easy automation for obtaining the tooling. Das Skript kümmert sich um das Herunterladen der Tools und extrahiert diese zur Verwendung an einem Standardspeicherort bzw. dem von Ihnen angegebenen Speicherort.The script takes care of downloading the tooling and extracting it into a default or specified location for use. Sie können außerdem angeben, welche Version der Tools Sie verwenden möchten und ob das gesamte SDK oder nur die freigegebene Runtime installiert werden soll.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.

Das Installationsskript ist automatisiert, sodass es zu Beginn des Buildvorgangs ausgeführt wird, um die gewünschte Version des SDK abzurufen und zu installieren.The installer script is automated to run at the start of the build to fetch and install the desired version of the SDK. Die gewünschte Version ist die Version des SDK, die zum Erstellen Ihrer Projekte benötigt wird.The desired version is whatever version of the SDK your projects require to build. Das Skript ermöglicht es Ihnen, das SDK in einem lokalen Verzeichnis auf dem Server zu installieren, die Tools vom Installationsort auszuführen und nach der Builderstellung eine Bereinigung durchzuführen (Sie können die Bereinigung auch dem CI-Dienst überlassen).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. Dies ermöglicht eine Kapselung und Isolation Ihres gesamten Buildprozesses.This provides encapsulation and isolation to your entire build process. Die Referenz zu den Installationsskripts finden Sie im Thema dotnet-install.The installation script reference is found in the dotnet-install topic.

Hinweis

Bei Verwendung des Installationsskripts werden native Abhängigkeiten nicht automatisch installiert.When using the installer script, native dependencies aren't installed automatically. Sie müssen die nativen Abhängigkeiten installieren, wenn das Betriebssystem diese nicht umfasst.You must install the native dependencies if the operating system doesn't have them. Die Liste der Voraussetzungen finden Sie im Thema .NET Core native prerequisites (Systemvoraussetzungen für .NET Core).See the list of prerequisites in the .NET Core native prerequisites topic.

Beispiele für die CI-EinrichtungCI setup examples

In diesem Abschnitt wird die manuelle Einrichtung unter Verwendung eines PowerShell- oder Bash-Skripts erläutert, und es werden verschiedene SaaS-CI-Lösungen (Software-as-a-Service) beschrieben.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. Die behandelten SaaS-CI-Lösungen sind Travis CI, AppVeyor und Visual Studio Team Services Build.The SaaS CI solutions covered are Travis CI, AppVeyor, and Visual Studio Team Services Build.

Manuelle EinrichtungManual setup

Jeder SaaS-Dienst umfasst eigene Methoden zum Erstellen und Konfigurieren eines Buildprozesses.Each SaaS service has its own methods for creating and configuring a build process. Wenn Sie eine andere SaaS-Lösung als die hier aufgeführten verwenden oder eine über die integrierte Unterstützung hinausgehende Anpassung erforderlich ist, müssen Sie einige manuelle Konfigurationsschritte ausführen.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.

Im Allgemeinen müssen Sie bei einer manuellen Einrichtung eine Version der Tools (oder die neuesten nächtlichen Builds der Tools) herunterladen und Ihr Buildskript ausführen.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. Sie können ein PowerShell- oder ein Bash-Skript verwenden, um die .NET Core-Befehle zu orchestrieren, oder Sie verwenden eine Projektdatei, die den Buildprozess beschreibt.You can use a PowerShell or bash script to orchestrate the .NET Core commands or use a project file that outlines the build process. Diese Optionen werden im Abschnitt zur Orchestrierung weiter ausgeführt.The orchestration section provides more detail on these options.

Nachdem Sie ein Skript zur Ausführung eines manuellen Setups eines CI-Buildservers erstellt haben, verwenden Sie es auf Ihrem Entwicklungscomputer, um lokalen Code zu Testzwecken zu erstellen.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. Nachdem Sie sich davon überzeugt haben, dass das Skript lokal wie erwartet funktioniert, stellen Sie es auf Ihrem CI-Buildserver bereit.Once you confirm that the script is running well locally, deploy it to your CI build server. Ein relativ simples PowerShell-Skript zeigt, wie Sie das .NET Core SDK herunterladen und auf einem Windows-Buildserver installieren: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.

Sie stellen die Implementierung für Ihren Buildprozess am Ende des Skripts bereit.You provide the implementation for your build process at the end of the script. Das Skript ruft die Tools ab und führt dann Ihren Buildprozess aus.The script acquires the tools and then executes your build process. Für UNIX-Computer werden die im PowerShell-Skript beschriebenen Aktionen durch das folgende Bash-Skript in ähnlicher Weise ausgeführt: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

Travis CI kann so konfiguriert werden, dass das .NET Core SDK mit der Sprache csharp und dem Schlüssel dotnet installiert wird.You can configure Travis CI to install the .NET Core SDK using the csharp language and the dotnet key. Weitere Informationen zum Erstellen eines C#-, F#- oder Visual Basic-Projekts finden Sie in der offiziellen Travis CI-Dokumentation.See the official Travis CI docs on Building a C#, F#, or Visual Basic Project for more information. Beachten Sie beim Zugriff auf die Travis CI-Informationen, dass der von der Community verwaltet Sprachbezeichner language: csharp für alle .NET-Sprachen (einschließlich F# und Mono) funktioniert.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 führt sowohl macOS- (OS X 10.11, OS X 10.12) als auch Linux-Aufträge (Ubuntu 14.04) in einer Buildmatrix aus, wobei Sie eine Kombination aus Runtime, Umgebung und Einschlüssen/Ausschlüssen zur Abdeckung der Buildkombinationen für Ihre App angeben.Travis CI runs both macOS (OS X 10.11, OS X 10.12) and Linux (Ubuntu 14.04) jobs in a build matrix, where you specify a combination of runtime, environment, and exclusions/inclusions to cover your build combinations for your app. Weitere Informationen finden Sie in der Datei .travis.yml-Beispiel und unter Customizing the Build (Anpassen des Builds) in der Travis CI-Dokumentation.See the .travis.yml example file and Customizing the Build in the Travis CI docs for more information. Die MSBuild-basierten Tools enthalten die Runtimes LTS (1.0.x) und Current (1.1.x) im Paket. Deshalb verfügen Sie nach der Installation des SDK über alle benötigten Buildkomponenten.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 installiert das .NET Core 1.0.1 SDK mit dem Buildworkerimage Visual Studio 2017.AppVeyor installs the .NET Core 1.0.1 SDK with the Visual Studio 2017 build worker image. Es stehen darüber hinaus weitere Buildimages mit anderen Versionen des .NET Core SDK zur Verfügung. Weitere Informationen hierzu finden Sie im appveyor.yml-Beispiel und im Thema Build worker images (Buildworkerimages) in der AppVeyer-Dokumentation.Other build images with different versions of the .NET Core SDK are available; see the appveyor.yml example and the Build worker images topic in the AppVeyor docs for more information.

Die .NET Core SDK-Binärdateien werden mithilfe des Installationsskripts heruntergeladen, in einem Unterverzeichnis entpackt und anschließend der Umgebungsvariable PATH hinzugefügt.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. Fügen Sie eine Buildmatrix hinzu, um Integrationstests mit mehreren Versionen des .NET Core SDK auszuführen: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

Visual Studio Team Services (VSTS)Visual Studio Team Services (VSTS)

Verwenden Sie einen dieser Ansätze, um Visual Studio Team Services (VSTS) zum Erstellen von .NET Core-Projekten zu konfigurieren:Configure Visual Studio Team Services (VSTS) to build .NET Core projects using one of these approaches:

  1. Führen Sie das Skript aus dem Schritt für die manuelle Einrichtung unter Verwendung Ihrer Befehle aus.Run the script from the manual setup step using your commands.
  2. Erstellen Sie einen Build aus verschiedenen integrierten VSTS-Buildtasks, die zur Verwendung der .NET Core-Tools konfiguriert sind.Create a build composed of several VSTS built-in build tasks that are configured to use .NET Core tools.

Beide Ansätze sind gültige Vorgehensweisen.Both solutions are valid. Mithilfe eines Skripts zur manuellen Einrichtung kontrollieren Sie, welche Version der Tools abgerufen wird, weil Sie die Tools im Rahmen des Builds herunterladen.Using a manual setup script, you control the version of the tools that you receive, since you download them as part of the build. Der Build wird aus einem Skript ausgeführt, das Sie erstellen müssen.The build is run from a script that you must create. In diesem Thema wird nur die manuelle Option behandelt.This topic only covers the manual option. Weitere Informationen zum Erstellen eines Builds mit VSTS-Buildtasks finden Sie im VSTS-Thema Continuous integration and deployment (Continuous Integration und Continuous Deployment).For more information on composing a build with VSTS build tasks, visit the VSTS Continuous integration and deployment topic.

Um ein Skript für ein manuelles Setup in VSTS zu verwenden, erstellen Sie eine neue Builddefinition und geben das Skript an, das für den Buildschritt ausgeführt werden soll.To use a manual setup script in VSTS, create a new build definition and specify the script to run for the build step. Dies wird mithilfe der VSTS-Benutzeroberfläche erreicht:This is accomplished using the VSTS user interface:

  1. Beginnen Sie, indem Sie eine neue Builddefinition erstellen.Start by creating a new build definition. Wenn der Bildschirm angezeigt wird, auf dem Sie angeben können, welche Art von Build Sie erstellen möchten, wählen Sie die Option Leer aus.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.

    Auswahl einer leeren Builddefinition

  2. Nachdem Sie das zu erstellende Repository konfiguriert haben, gelangen Sie zu den Builddefinitionen.After configuring the repository to build, you're directed to the build definitions. Wählen Sie Buildschritt hinzufügen aus:Select Add build step:

    Hinzufügen eines Buildschritts

  3. Als Nächstes wird der Taskkatalog angezeigt.You're presented with the Task catalog. Der Katalog enthält Tasks, die Sie im Build verwenden.The catalog contains tasks that you use in the build. Da Sie über ein Skript verfügen, klicken Sie auf die Schaltfläche Hinzufügen für PowerShell: PowerShell-Skript ausführen.Since you have a script, select the Add button for PowerShell: Run a PowerShell script.

    Hinzufügen eines Schritts für ein PowerShell-Skript

  4. Konfigurieren Sie den Buildschritt.Configure the build step. Fügen Sie das Skript aus dem Repository hinzu, das Sie erstellen:Add the script from the repository that you're building:

    Angeben des auszuführenden PowerShell-Skripts

Orchestrieren des BuildsOrchestrating the build

In diesem Dokument wird hauptsächlich beschrieben, wie Sie die .NET Core-Tools herunterladen und verschiedene CI-Dienst konfigurieren, ohne darauf einzugehen, wie Sie Ihren Code mit .NET Core orchestrieren oder tatsächlich einen Build erstellen.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. Die Auswahl bei der Strukturierung des Buildprozesses hängt von vielen Faktoren ab, die hier nicht allgemein abgedeckt werden können.The choices on how to structure the build process depend on many factors that cannot be covered in a general way here. Erkunden Sie die Ressourcen und Beispiele in der Dokumentation von Travis CI, AppVeyor und VSTS, um weitere Informationen zur Orchestrierung Ihrer Builds mit jeder Technologie zu erhalten.Explore the resources and samples provided in the documentation sets of Travis CI, AppVeyor, and VSTS for more information on orchestrating your builds with each technology.

Bei der Strukturierung des Buildprozesses für .NET Core-Code unter Verwendung der .NET Core-Tools können zwei allgemeine Ansätze verfolgt werden: die direkte Verwendung von MSBuild oder die Verwendung von .NET Core-Befehlszeilenbefehlen.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. Sie sollten den verwendeten Ansatz danach auswählen, wie vertraut Sie mit dem jeweiligen Ansatz sind und welche Kompromisse Sie in Bezug auf die Komplexität eingehen möchten.Which approach you should take is determined by your comfort level with the approaches and trade-offs in complexity. Mit MSBuild können Sie Ihren Buildprozess in Form von Tasks und Zielen beschrieben, Sie müssen jedoch die MSBuild-Projektdateisyntax beherrschen.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. Die Verwendung von .NET Core-Befehlszeilentools ist möglicherweise einfacher, erfordert aber, dass Sie Orchestrierungslogik in einer Skriptsprache wie bash oder PowerShell schreiben.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.

Siehe auchSee also

Schritte zum Download von UbuntuUbuntu acquisition steps