Publicar aplicativos .NET com a CLI do .NET

Artigo
10/15/2024

Este artigo demonstra como você pode publicar seu aplicativo .NET por meio da linha de comando. O .NET fornece três maneiras de publicar seus aplicativos. A implantação dependente de estrutura gera um arquivo .dll multiplataforma que usa o runtime do .NET instalado localmente. O executável dependente de estrutura gera um executável específico da plataforma que usa o runtime do .NET instalado localmente. O executável autossuficiente gera um executável específico da plataforma e inclui uma cópia local do runtime do .NET.

Para obter uma visão geral desses modos de publicação, confira Implantação de aplicativos no .NET.

Procurando uma ajuda rápida de como usar a CLI? A tabela a seguir mostra alguns exemplos de como publicar o aplicativo. Especifique a estrutura de destino com o parâmetro -f <TFM> ou editando o arquivo de projeto. Para obter mais informações, confira Noções básicas de publicação.

Modo de publicação	Comando
Implantação dependente de estrutura	`dotnet publish -c Release -p:UseAppHost=false`
Executável dependente de estrutura	`dotnet publish -c Release -r <RID> --self-contained false` `dotnet publish -c Release`
Implantação autossuficiente	`dotnet publish -c Release -r <RID> --self-contained true`

Observação

O parâmetro -c Release não é obrigatório. Ele é fornecido como um lembrete para publicar a compilação Release do seu aplicativo.
No SDK do .NET 3.1 ou versão superior, o executável dependente de estrutura será o modo de publicação padrão durante a execução do comando básico dotnet publish.

Noções básicas de publicação

A configuração <TargetFramework> do arquivo de projeto especifica a estrutura de destino padrão quando o aplicativo é publicado. Altere a estrutura de destino para qualquer TFM (Moniker da Estrutura de Destino) válido. Por exemplo, se o projeto usa <TargetFramework>net8.0</TargetFramework>, um binário direcionado ao .NET 8 é criado. O TFM especificado nessa configuração é o destino padrão usado pelo comando dotnet publish.

Caso deseje direcionar a mais de uma estrutura, defina a configuração <TargetFrameworks> com mais de um valor de TFM, separados por ponto-e-vírgula. Quando você cria seu aplicativo, uma compilação é produzida para cada estrutura de destino. No entanto, ao publicar seu aplicativo, você deve especificar a estrutura de destino desejada com o comando dotnet publish -f <TFM>.

O modo CONFIGURAÇÃO DE BUILD padrão é Depuração, a menos que seja alterado com o parâmetro -c.

O diretório de saída padrão do comando dotnet publish é ./bin/<BUILD-CONFIGURATION>/<TFM>/publish/. Por exemplo, dotnet publish -c Release -f net8.0 publica em ./bin/Release/net8.0/publish/. No entanto, você pode optar por um caminho de saída simplificado e uma estrutura de pastas para todas as saídas de build. Para obter mais informações, confira Layout de saída de artefatos.

Dependências nativas

Se o aplicativo tiver dependências nativas, ele poderá não ser executado em um sistema operacional diferente. Por exemplo, se o aplicativo usar a API nativa do Windows, ele não será executado no macOS nem no Linux. Você precisará fornecer um código específico da plataforma e compilar um executável para cada plataforma.

Considere também que, se uma biblioteca referenciada tiver uma dependência nativa, o aplicativo poderá não ser executado em todas as plataformas. No entanto, é possível que um pacote NuGet referenciado tenha incluído versões específicas da plataforma para lidar com as dependências nativas necessárias para você.

Ao distribuir um aplicativo com dependências nativas, talvez você precise usar a opção dotnet publish -r <RID> para especificar a plataforma de destino na qual deseja publicar. Para obter uma lista de identificadores de runtime, confira o Catálogo do RID (Identificador de Runtime).

Mais informações sobre binários específicos da plataforma são abordadas nas seções Executável dependente de estrutura e Implantação autossuficiente.

Aplicativo de exemplo

Use o aplicativo a seguir para explorar os comandos de publicação. O aplicativo é criado pela execução dos seguintes comandos no terminal:

mkdir apptest1
cd apptest1
dotnet new console
dotnet add package Figgle

O arquivo Program.cs ou Program.vb gerado pelo modelo de console precisa ser alterado para o seguinte:

using System;

namespace apptest1
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine(Figgle.FiggleFonts.Standard.Render("Hello, World!"));
        }
    }
}

Module Program
    Sub Main(args As String())
        Console.WriteLine(Figgle.FiggleFonts.Standard.Render("Hello, World!"))
    End Sub
End Module

Quando você executa o aplicativo (dotnet run), a seguinte saída é exibida:

  _   _      _ _         __        __         _     _ _
 | | | | ___| | | ___    \ \      / /__  _ __| | __| | |
 | |_| |/ _ \ | |/ _ \    \ \ /\ / / _ \| '__| |/ _` | |
 |  _  |  __/ | | (_) |    \ V  V / (_) | |  | | (_| |_|
 |_| |_|\___|_|_|\___( )    \_/\_/ \___/|_|  |_|\__,_(_)
                     |/

Implantação dependente de estrutura

Quando você publica o aplicativo como uma FDD, um arquivo <PROJECT-NAME>.dll é criado na pasta ./bin/<BUILD-CONFIGURATION>/<TFM>/publish/. Para executar o aplicativo, navegue para a pasta de saída e use o comando dotnet <PROJECT-NAME>.dll.

O aplicativo está configurado para ser direcionado a uma versão específica do .NET. Esse runtime do .NET direcionado deve estar em qualquer computador em que o aplicativo seja executado. Por exemplo, se o aplicativo for direcionado ao .NET Core 8, qualquer computador no qual o aplicativo é executado precisará ter o runtime do .NET Core 8 instalado. Conforme indicado na seção Noções básicas de publicação, você pode editar o arquivo de projeto para alterar a estrutura de destino padrão ou para definir mais de uma estrutura como destino.

A publicação de uma FDD cria um aplicativo que efetua roll forward automaticamente para o último patch de segurança do .NET disponível no sistema que executa o aplicativo. Para obter mais informações sobre a associação de versão no tempo de compilação, confira Selecionar a versão do .NET a ser usada.

Modo de publicação	Comando
Implantação dependente de estrutura	`dotnet publish -c Release -p:UseAppHost=false`

Executável dependente de estrutura

O FDE (executável dependente da estrutura) é o modo padrão para o comando básico dotnet publish. Não é preciso especificar outros parâmetros se o sistema operacional atual for o destino desejado.

Nesse modo, um host do executável específico da plataforma é criado para hospedar o aplicativo multiplataforma. Esse modo é semelhante ao FDD, pois o FDD exige um host na forma do comando dotnet. O nome de arquivo executável do host varia de acordo com a plataforma e recebe um nome semelhante a <PROJECT-FILE>.exe. Execute diretamente esse executável em vez de chamar dotnet <PROJECT-FILE>.dll, que ainda é uma forma aceitável de executar o aplicativo.

O aplicativo está configurado para ser direcionado a uma versão específica do .NET. Esse runtime do .NET direcionado deve estar em qualquer computador em que o aplicativo seja executado. Por exemplo, se o aplicativo for direcionado ao .NET Core 8, todo computador no qual o aplicativo é executado precisará ter o runtime do .NET Core 8 instalado. Conforme indicado na seção Noções básicas de publicação, você pode editar o arquivo de projeto para alterar a estrutura de destino padrão ou para definir mais de uma estrutura como destino.

A publicação de um FDE cria um aplicativo que efetua roll forward automaticamente para o último patch de segurança do .NET disponível no sistema que executa o aplicativo. Para obter mais informações sobre a associação de versão no tempo de compilação, confira Selecionar a versão do .NET a ser usada.

Modo de publicação	Comando
Executável dependente de estrutura	`dotnet publish -c Release -r <RID> --self-contained false` `dotnet publish -c Release`

Sempre que você usa a opção -r, o caminho da pasta de saída é alterado para: ./bin/<BUILD-CONFIGURATION>/<TFM>/<RID>/publish/

Se você usar o aplicativo de exemplo, execute dotnet publish -f net6.0 -r win-x64 --self-contained false. Esse comando cria o seguinte executável: ./bin/Debug/net6.0/win-x64/publish/apptest1.exe

Observação

Reduza o tamanho total da implantação habilitando o modo invariável de globalização. Esse modo é útil para aplicativos que não têm reconhecimento global e que podem usar as convenções de formatação, as convenções de uso de maiúsculas, a comparação de cadeia de caracteres e a ordem de classificação da cultura invariável. Para obter mais informações sobre o modo invariável de globalização e como habilitá-lo, confira Modo Invariável de Globalização do .NET.

Configurar o comportamento de pesquisa de instalação do .NET

No .NET 9 e em versões posteriores, você pode configurar os caminhos de pesquisa de instalação do .NET do executável publicado por meio das propriedades AppHostDotNetSearch e AppHostRelativeDotNet.

AppHostDotNetSearch permite especificar um ou mais locais onde o executável procurará uma instalação do .NET:

AppLocal: pasta do executável do aplicativo
AppRelative: caminho relativo ao executável do aplicativo
EnvironmentVariables: valor das variáveis de ambiente DOTNET_ROOT[_<arch>]
Global: locais de instalação globais registrados e padrão

AppHostRelativeDotNet Especifica o caminho relativo ao executável que será pesquisado quando AppHostDotNetSearch contém AppRelative.

Para obter mais informações, consulte AppHostDotNetSearch, AppHostRelativeDotNet e instalar opções de localização no apphost.

Implantação autocontida

Quando você publica uma SCD (implantação autossuficiente), o SDK do .NET cria um executável específico da plataforma. A publicação de um SCD inclui todos os arquivos .NET necessários para executar seu aplicativo, mas não inclui as dependências nativas do .NET (por exemplo, para .NET 6 no Linux ou .NET 8 no Linux). Essas dependências precisam estar presentes no sistema antes da execução do aplicativo.

A publicação de uma SCD cria um aplicativo que não efetua roll forward para o último patch de segurança disponível do .NET. Para obter mais informações sobre a associação de versão em tempo de compilação, confira Selecionar a versão do .NET a ser usada.

É necessário usar as seguintes opções com o comando dotnet publish para publicar uma SCD:

-r <RID>

Essa opção usa um RID (identificador) para especificar a plataforma de destino. Para obter uma lista de identificadores de runtime, confira o Catálogo do RID (Identificador de Runtime).
--self-contained true

Essa opção informa ao SDK do .NET para criar um executável como um SCD.

Modo de publicação	Comando
Implantação autocontida	`dotnet publish -c Release -r <RID> --self-contained true`

Dica

No .NET 6 e versões posteriores, você pode reduzir o tamanho total de aplicativos autossuficientes compatíveis publicando cortados. Isso permite que o aparador remova partes da estrutura e os assemblies referenciados que não estão em nenhum caminho do código ou potencialmente referenciados na reflexão de runtime. Confira as incompatibilidades de corte para determinar se o corte faz sentido para seu aplicativo.
Reduza o tamanho total da implantação habilitando o modo invariável de globalização. Esse modo é útil para aplicativos que não têm reconhecimento global e que podem usar as convenções de formatação, as convenções de uso de maiúsculas, a comparação de cadeia de caracteres e a ordem de classificação da cultura invariável. Para obter mais informações sobre o modo invariável de globalização e como habilitá-lo, confira Modo invariável de globalização do .NET Core.

Compartilhar via