Usar o SDK do .NET em ambientes de integração contínua (CI)

Artigo
03/02/2024

Este artigo descreve como usar o SDK do .NET e suas ferramentas em um servidor de compilação. O conjunto de ferramentas .NET funciona interativamente, onde um desenvolvedor digita comandos em um prompt de comando, e automaticamente, onde um servidor de integração contínua (CI) executa um script de compilação. Os comandos, opções, entradas e saídas são os mesmos, e as únicas coisas que você fornece são uma maneira de adquirir as ferramentas e um sistema para criar seu aplicativo. Este artigo se concentra em cenários de aquisição de ferramentas para CI com recomendações sobre como projetar e estruturar seus scripts de construção.

Opções de instalação para servidores de compilação de CI

Se você estiver usando o GitHub, a instalação é simples. Você pode confiar nas Ações do GitHub para instalar o SDK do .NET em seu fluxo de trabalho. A maneira recomendada de instalar o SDK do .NET em um fluxo de trabalho é com a actions/setup-net-core-sdk ação. Para obter mais informações, consulte a ação Setup .NET Core SDK no mercado GitHub. Para obter exemplos de como isso funciona, consulte Guia de início rápido: criar um fluxo de trabalho do GitHub de validação de compilação.

Instaladores nativos

Instaladores nativos estão disponíveis para macOS, Linux e Windows. Os instaladores requerem acesso admin (sudo) ao servidor de compilação. A vantagem de usar um instalador nativo é que ele instala todas as dependências nativas necessárias para que as ferramentas sejam executadas. Os instaladores nativos também fornecem uma instalação do SDK em todo o sistema.

Os usuários do macOS devem usar os instaladores PKG. No Linux, há a opção de usar um gerenciador de pacotes baseado em feed, como apt-get para Ubuntu ou yum para CentOS, ou usar os próprios pacotes, DEB ou RPM. No Windows, use o instalador MSI.

Os binários estáveis mais recentes são encontrados em downloads do .NET. Se você deseja usar as ferramentas de pré-lançamento mais recentes (e potencialmente instáveis), use os links fornecidos no repositório GitHub dotnet/installer. Para distribuições Linux, tar.gz arquivos (também conhecidos como tarballs) estão disponíveis, use os scripts de instalação dentro dos arquivos para instalar o .NET.

Script de instalação

O uso do script do instalador permite a instalação não administrativa em seu servidor de compilação e fácil automação para obter as ferramentas. O script se encarrega de baixar as ferramentas e extraí-las para um local padrão ou especificado para uso. Você também pode especificar uma versão das ferramentas que deseja instalar e se deseja instalar o SDK inteiro ou apenas o tempo de execução compartilhado.

O script do instalador é automatizado para ser executado no início da compilação para buscar e instalar a versão desejada do SDK. A versão desejada é qualquer versão do SDK que seus projetos exijam para compilar. O script permite que você instale o SDK em um diretório local no servidor, execute as ferramentas do local instalado e, em seguida, limpe (ou deixe o serviço CI limpar) após a compilação. Isso fornece encapsulamento e isolamento para todo o seu processo de compilação. A referência do script de instalação é encontrada no artigo dotnet-install .

Nota

Serviços de DevOps do Azure

Ao usar o script do instalador, as dependências nativas não são instaladas automaticamente. Você deve instalar as dependências nativas se o sistema operacional não as tiver. Para obter mais informações, consulte Dependências e requisitos do .NET.

Exemplos de configuração de CI

Esta seção descreve uma configuração manual usando um script PowerShell ou bash, juntamente com descrições de soluções de CI de software como serviço (SaaS). As soluções de CI SaaS cobertas são Travis CI, AppVeyor e Azure Pipelines. Para ações do GitHub, consulte Ações do GitHub e .NET

Configuração manual

Cada serviço SaaS tem seus métodos para criar e configurar um processo de compilação. Se você usar uma solução SaaS diferente das listadas ou precisar de personalização além do suporte pré-empacotado, deverá executar pelo menos alguma configuração manual.

Em geral, uma configuração manual requer que você adquira uma versão das ferramentas (ou as últimas compilações noturnas das ferramentas) e execute seu script de construção. Você pode usar um script PowerShell ou bash para orquestrar os comandos .NET ou usar um arquivo de projeto que descreve o processo de compilação. A seção de orquestração fornece mais detalhes sobre essas opções.

Depois de criar um script que executa uma configuração manual do servidor de compilação de CI, use-o em sua máquina de desenvolvimento para criar seu código localmente para fins de teste. Depois de confirmar que o script está funcionando bem localmente, implante-o no servidor de compilação de CI. Um script PowerShell relativamente simples demonstra como obter o SDK do .NET e instalá-lo em um servidor de compilação do Windows:

Você fornece a implementação para seu processo de compilação no final do script. O script adquire as ferramentas e, em seguida, executa seu processo de compilação.

PowerShell
Bash

$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 = "6.0.7"

# 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.

#!/bin/bash
INSTALLDIR="cli-tools"
CLI_VERSION=6.0.7
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 CI

Você pode configurar o Travis CI para instalar o SDK do .NET usando o idioma e a dotnetcsharp chave. Para obter mais informações, consulte os documentos oficiais do Travis CI sobre a criação de um projeto C#, F# ou Visual Basic. Observe ao acessar as informações do Travis CI que o identificador de idioma mantido language: csharp pela comunidade funciona para todos os idiomas .NET, incluindo F# e Mono.

O Travis CI executa trabalhos do macOS e Linux em uma matriz de compilação, onde você especifica uma combinação de tempo de execução, ambiente e exclusões/inclusões para cobrir as combinações de compilação para seu aplicativo. Para obter mais informações, consulte o artigo Personalizando a compilação na documentação do Travis CI. As ferramentas baseadas em MSBuild incluem os tempos de execução de suporte de longo prazo (LTS) e suporte de prazo padrão (STS) no pacote; assim, ao instalar o SDK, você recebe tudo o que precisa para construir.

AppVeyor

O AppVeyor instala o SDK do .NET 6 com a imagem de trabalho de Visual Studio 2022 compilação. Outras imagens de compilação com diferentes versões do SDK do .NET estão disponíveis. Para obter mais informações, consulte o artigo Criar imagens de trabalho nos documentos do AppVeyor.

Os binários do SDK do .NET são baixados e descompactados em um subdiretório usando o script de instalação e, em seguida, são adicionados à PATH variável de ambiente. Adicione uma matriz de compilação para executar testes de integração com várias versões do SDK do .NET:

environment:
  matrix:
    - CLI_VERSION: 6.0.7
    - CLI_VERSION: Latest

Serviços de DevOps do Azure

Configure os Serviços de DevOps do Azure para criar projetos .NET usando uma destas abordagens:

Execute o script a partir da etapa de configuração manual usando seus comandos.
Crie uma compilação composta por várias tarefas de compilação internas dos Serviços de DevOps do Azure configuradas para usar ferramentas .NET.

Ambas as soluções são válidas. Usando um script de configuração manual, você controla a versão das ferramentas que recebe, já que as baixa como parte da compilação. A compilação é executada a partir de um script que você deve criar. Este artigo aborda apenas a opção manual. Para obter mais informações sobre como compor uma compilação com tarefas de compilação dos Serviços de DevOps do Azure, consulte a documentação do Azure Pipelines .

Para usar um script de instalação manual nos Serviços de DevOps do Azure, crie uma nova definição de compilação e especifique o script a ser executado para a etapa de compilação. Isso é feito usando a interface do usuário dos Serviços de DevOps do Azure:

Comece criando uma nova definição de compilação. Quando chegar à tela que fornece uma opção para definir que tipo de compilação você deseja criar, selecione a opção Vazio .
Depois de configurar o repositório para compilação, você é direcionado para as definições de compilação. Selecione Adicionar etapa de compilação:
O catálogo de tarefas é apresentado. O catálogo contém tarefas que você usa na compilação. Como você tem um script, selecione o botão Adicionar para PowerShell: Executar um script do PowerShell.
Configure a etapa de compilação. Adicione o script do repositório que você está criando:

Orquestrando a construção

A maior parte deste documento descreve como adquirir as ferramentas .NET e configurar vários serviços de CI sem fornecer informações sobre como orquestrar, ou realmente criar, seu código com o .NET. As escolhas sobre como estruturar o processo de construção dependem de muitos fatores que não podem ser abordados de uma forma geral aqui. Para obter mais informações sobre como orquestrar suas compilações com cada tecnologia, explore os recursos e exemplos fornecidos nos conjuntos de documentação do Travis CI, AppVeyor e Azure Pipelines.

Duas abordagens gerais que você usa na estruturação do processo de compilação para código .NET usando as ferramentas .NET estão usando MSBuild diretamente ou usando os comandos de linha de comando .NET. A abordagem que você deve adotar é determinada pelo seu nível de conforto com as abordagens e compensações na complexidade. O MSBuild fornece a capacidade de expressar seu processo de compilação como tarefas e destinos, mas ele vem com a complexidade adicional de aprender a sintaxe do arquivo de projeto do MSBuild. Usar as ferramentas de linha de comando do .NET talvez seja mais simples, mas requer que você escreva a lógica de orquestração em uma linguagem de script como bash o PowerShell.

Gorjeta

Uma propriedade MSBuild que você vai querer definir como trueContinuousIntegrationBuild. Esta propriedade permite configurações que se aplicam apenas a compilações oficiais, em oposição a compilações de desenvolvimento local.