Implantação de arquivo único e executávelSingle file deployment and executable

Agrupar todos os arquivos dependentes do aplicativo em um único binário fornece a um desenvolvedor de aplicativos a opção atrativa para implantar e distribuir o aplicativo como um único arquivo.Bundling all application-dependent files into a single binary provides an application developer with the attractive option to deploy and distribute the application as a single file. Esse modelo de implantação está disponível desde o .NET Core 3,0 e foi aprimorado no .NET 5,0.This deployment model has been available since .NET Core 3.0 and has been enhanced in .NET 5.0. Anteriormente no .NET Core 3,0, quando um usuário executa seu aplicativo de arquivo único, o host do .NET Core primeiro extrai todos os arquivos para um diretório temporário antes de executar o aplicativo.Previously in .NET Core 3.0, when a user runs your single-file app, .NET Core host first extracts all files to a temporary directory before running the application. O .NET 5,0 melhora essa experiência executando diretamente o código sem a necessidade de extrair os arquivos do aplicativo..NET 5.0 improves this experience by directly running the code without the need to extract the files from the app.

A implantação de arquivo único está disponível tanto para o modelo de implantação dependente de estrutura quanto para aplicativos independentes.Single File deployment is available for both the framework-dependent deployment model and self-contained applications. O tamanho do único arquivo em um aplicativo independente será grande, já que incluirá o tempo de execução e as bibliotecas de estrutura.The size of the single file in a self-contained application will be large since it will include the runtime and the framework libraries. A opção de implantação de arquivo único pode ser combinada com as opções de publicação ReadyToRun e Trim (um recurso experimental no .NET 5,0) .The single file deployment option can be combined with ReadyToRun and Trim (an experimental feature in .NET 5.0) publish options.

Incompatibilidade de APIAPI incompatibility

Algumas APIs não são compatíveis com a implantação de arquivo único e os aplicativos podem exigir modificações se usarem essas APIs.Some APIs are not compatible with single-file deployment and applications may require modification if they use these APIs. Se você usar uma estrutura ou pacote de terceiros, é possível que eles também possam usar uma dessas APIs e precisar de modificação.If you use a third-party framework or package, it's possible that they may also use one of these APIs and need modification. A causa mais comum de problemas é a dependência de caminhos de arquivo para arquivos ou DLLs fornecidos com o aplicativo.The most common cause of problems is dependence on file paths for files or DLLs shipped with the application.

A tabela a seguir tem os detalhes relevantes da API da biblioteca de tempo de execução para uso de arquivo único.The table below has the relevant runtime library API details for single-file use.

APIAPI ObservaçãoNote
Assembly.Location Retorna uma cadeia de caracteres vazia.Returns an empty string.
Module.FullyQualifiedName Retorna uma cadeia de caracteres com o valor de <Unknown> ou gera uma exceção.Returns a string with the value of <Unknown> or throws an exception.
Module.Name Retorna uma cadeia de caracteres com o valor de <Unknown> .Returns a string with the value of <Unknown>.
Assembly.GetFile Gera IOException.Throws IOException.
Assembly.GetFiles Gera IOException.Throws IOException.
Assembly.CodeBase Gera PlatformNotSupportedException.Throws PlatformNotSupportedException.
Assembly.EscapedCodeBase Gera PlatformNotSupportedException.Throws PlatformNotSupportedException.
AssemblyName.CodeBase Retorna null.Returns null.
AssemblyName.EscapedCodeBase Retorna null.Returns null.

Temos algumas recomendações para corrigir cenários comuns:We have some recommendations for fixing common scenarios:

Anexando um depuradorAttaching a debugger

No Linux, o único depurador que pode ser anexado a processos de arquivo único independentes ou despejos de memória de depuração é SOS com LLDB.On Linux, the only debugger which can attach to self-contained single-file processes or debug crash dumps is SOS with LLDB.

No Windows e no Mac, o Visual Studio e o VS Code podem ser usados para depurar despejos de memória.On Windows and Mac, Visual Studio and VS Code can be used to debug crash dumps. Anexar a um executável de arquivo único autônomo em execução requer um arquivo extra: MSCorDbi. { dll, portanto}.Attaching to a running self-contained single-file executable requires an extra file: mscordbi.{dll,so}.

Sem esse arquivo, o Visual Studio pode produzir o erro "não é possível anexar ao processo.Without this file Visual Studio may produce the error "Unable to attach to the process. Um componente de depuração não está instalado. "A debug component is not installed." e VS Code podem produzir o erro "falha ao anexar ao processo: erro desconhecido: 0x80131c3c."and VS Code may produce the error "Failed to attach to process: Unknown Error: 0x80131c3c."

Para corrigir esses erros, o MSCorDbi precisa ser copiado ao lado do executável.To fix these errors, mscordbi needs to be copied next to the executable. o MSCorDbi é publish Ed por padrão no subdiretório com a ID de tempo de execução do aplicativo.mscordbi is published by default in the subdirectory with the application's runtime ID. Portanto, por exemplo, se uma delas fosse publicar um executável de arquivo único independente usando a dotnet CLI para Windows usando os parâmetros -r win-x64 , o executável seria colocado em bin/Debug/NET 5.0/Win-x64/Publish.So, for example, if one were to publish a self-contained single-file executable using the dotnet CLI for Windows using the parameters -r win-x64, the executable would be placed in bin/Debug/net5.0/win-x64/publish. Uma cópia de mscordbi.dll estaria presente em bin/Debug/NET 5.0/Win-x64.A copy of mscordbi.dll would be present in bin/Debug/net5.0/win-x64.

Outras consideraçõesOther considerations

Por padrão, o arquivo único não agrupa bibliotecas nativas.Single-file doesn't bundle native libraries by default. No Linux, vinculamos o tempo de execução ao pacote e somente as bibliotecas nativas do aplicativo são implantadas no mesmo diretório que o aplicativo de arquivo único.On Linux, we prelink the runtime into the bundle and only application native libraries are deployed to the same directory as the single-file app. No Windows, previnculo apenas o código de hospedagem e as bibliotecas nativas de tempo de execução e aplicativo são implantadas no mesmo diretório que o aplicativo de arquivo único.On Windows, we prelink only the hosting code and both the runtime and application native libraries are deployed to the same directory as the single-file app. Isso é para garantir uma boa experiência de depuração, que exige que os arquivos nativos sejam excluídos do único arquivo.This is to ensure a good debugging experience, which requires native files to be excluded from the single file. Há uma opção para definir um sinalizador, IncludeNativeLibrariesForSelfExtract , para incluir bibliotecas nativas no único pacote de arquivo, mas esses arquivos serão extraídos para um diretório temporário no computador cliente quando o aplicativo de arquivo único for executado.There is an option to set a flag, IncludeNativeLibrariesForSelfExtract, to include native libraries in the single file bundle, but these files will be extracted to a temporary directory in the client machine when the single file application is run.

Especificar IncludeAllContentForSelfExtract irá extrair todos os arquivos antes de executar o executável.Specifying IncludeAllContentForSelfExtract will extract all files before running the executable. Isso preserva o comportamento original de implantação de arquivo único do .NET Core.This preserves the original .NET Core single-file deployment behavior.

O aplicativo de arquivo único terá todos os arquivos PDB relacionados juntamente com ele e não será agrupado por padrão.Single-file application will have all related PDB files alongside it and will not be bundled by default. Se você quiser incluir PDBs dentro do assembly para projetos que você criar, defina o DebugType como embedded conforme descrito abaixo em detalhes.If you want to include PDBs inside the assembly for projects you build, set the DebugType to embedded as described below in detail.

Os componentes C++ gerenciados não são adequados para implantação de arquivo único e recomendamos que você escreva aplicativos em C# ou em outra linguagem C++ não gerenciada para que seja compatível com arquivo único.Managed C++ components aren't well suited for single-file deployment and we recommend that you write applications in C# or another non-managed C++ language to be single-file compatible.

Excluir arquivos de serem inseridosExclude files from being embedded

Determinados arquivos podem ser explicitamente excluídos de serem inseridos no arquivo único definindo os seguintes metadados:Certain files can be explicitly excluded from being embedded in the single-file by setting following metadata:

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

Por exemplo, para posicionar alguns arquivos no diretório de publicação, mas não agrupá-los no arquivo único:For example, to place some files in the publish directory but not bundle them in the single-file:

<ItemGroup>
  <Content Update="Plugin.dll">
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
  </Content>
</ItemGroup>

Incluir arquivos PDB dentro do pacoteInclude PDB files inside the bundle

O arquivo PDB de um assembly pode ser inserido no próprio assembly (o .dll ) usando a configuração abaixo.The PDB file for an assembly can be embedded into the assembly itself (the .dll) using the setting below. Como os símbolos fazem parte do assembly, eles também serão parte do aplicativo de arquivo único:Since the symbols are part of the assembly, they will be part of the single-file application as well:

<DebugType>embedded</DebugType>

Por exemplo, adicione a seguinte propriedade ao arquivo de projeto de um assembly para inserir o arquivo PDB nesse assembly:For example, add the following property to the project file of an assembly to embed the PDB file to that assembly:

<PropertyGroup>
  <DebugType>embedded</DebugType>
</PropertyGroup>

Publicar um aplicativo de arquivo único-arquivo de projeto de exemploPublish a single file app - sample project file

Aqui está um arquivo de projeto de exemplo que especifica a publicação de arquivo único:Here's a sample project file that specifies single-file publishing:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
    <PublishSingleFile>true</PublishSingleFile>
    <SelfContained>true</SelfContained>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <PublishTrimmed>true</PublishTrimmed>
    <PublishReadyToRun>true</PublishReadyToRun>
  </PropertyGroup>

</Project>

Essas propriedades têm as seguintes funções:These properties have the following functions:

  • PublishSingleFile – Habilita a publicação de arquivo único.PublishSingleFile - Enables single-file publishing.
  • SelfContained -Determina se o aplicativo será independente ou dependente de estrutura.SelfContained - Determines whether the app will be self-contained or framework-dependent.
  • RuntimeIdentifier -Especifica o sistema operacional e o tipo de CPU que você está direcionando.RuntimeIdentifier - Specifies the OS and CPU type you are targeting.
  • PublishTrimmed – Habilita o uso de corte de assembly, que tem suporte apenas para aplicativos independentes.PublishTrimmed - Enables use of assembly trimming, which is only supported for self-contained apps.
  • PublishReadyToRun – Habilita a compilação da AoT (antecipada de tempo).PublishReadyToRun - Enables ahead-of-time (AOT) compilation.

Observações:Notes:

  • OS aplicativos são específicos do sistema operacional e da arquitetura.Apps are OS and architecture-specific. Você precisa publicar para cada configuração, como Linux x64, Linux ARM64, Windows x64 e assim por diante.You need to publish for each configuration, such as Linux x64, Linux ARM64, Windows x64, and so forth.
  • Arquivos de configuração, como *.runtimeconfig.jsno, são incluídos no único arquivo.Configuration files, such as *.runtimeconfig.json, are included in the single file. Se um arquivo de configuração adicional for necessário, você poderá colocá-lo ao lado do único arquivo.If an additional configuration file is needed, you can place it beside the single file.

Publicar um aplicativo de arquivo único-CLIPublish a single file app - CLI

Publicar um aplicativo de arquivo único usando o comando dotnet Publish .Publish a single file application using the dotnet publish command. Ao publicar seu aplicativo, defina as seguintes propriedades:When you publish your app, set the following properties:

  • Publicar para um tempo de execução específico: -r win-x64Publish for a specific runtime: -r win-x64
  • Publicar como um arquivo único: -p:PublishSingleFile=truePublish as a single-file: -p:PublishSingleFile=true

O exemplo a seguir publica um aplicativo para o Windows como um aplicativo de arquivo único independente.The following example publishes an app for Windows as a self-contained single file application.

dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained true

O exemplo a seguir publica um aplicativo para Linux como um aplicativo de arquivo único dependente de estrutura.The following example publishes an app for Linux as a framework dependent single file application.

dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false

Para obter mais informações, consulte publicar aplicativos .NET Core com CLI do .NET Core.For more information, see Publish .NET Core apps with .NET Core CLI.

Publicar um único aplicativo de arquivo-Visual StudioPublish a single file app - Visual Studio

O Visual Studio cria perfis de publicação reutilizáveis que controlam como seu aplicativo é publicado.Visual Studio creates reusable publishing profiles that control how your application is published.

  1. No painel Gerenciador de soluções , clique com o botão direito do mouse no projeto que você deseja publicar.On the Solution Explorer pane, right-click on the project you want to publish. Selecione Publicar.Select Publish.

    Gerenciador de Soluções com um menu de clique com o botão direito do mouse, realçando a opção publicar.

    Se você ainda não tiver um perfil de publicação, siga as instruções para criar um e escolha o tipo de destino da pasta .If you don't already have a publishing profile, follow the instructions to create one and choose the Folder target-type.

  2. Escolha Editar.Choose Edit.

    Perfil de publicação do Visual Studio com o botão Editar.

  3. Na caixa de diálogo configurações de perfil , defina as seguintes opções:In the Profile settings dialog, set the following options:

    • Defina o modo de implantação como independente ou dependente de estrutura.Set Deployment mode to Self-contained or Framework-dependent.
    • Defina o tempo de execução de destino para a plataforma na qual você deseja publicar.Set Target runtime to the platform you want to publish to. (Deve ser algo diferente de portátil).(Must be something other than Portable.)
    • Selecione produzir arquivo único.Select Produce single file.

    Escolha salvar para salvar as configurações e retornar para a caixa de diálogo de publicação .Choose Save to save the settings and return to the Publish dialog.

    Caixa de diálogo Configurações de perfil com modo de implantação, tempo de execução de destino e opções de arquivo único realçadas.

  4. Escolha publicar para publicar seu aplicativo como um único arquivo.Choose Publish to publish your app as a single file.

Para obter mais informações, consulte publicar aplicativos .NET Core com o Visual Studio.For more information, see Publish .NET Core apps with Visual Studio.

Publicar um único aplicativo de arquivo-Visual Studio para MacPublish a single file app - Visual Studio for Mac

Visual Studio para Mac não fornece opções para publicar seu aplicativo como um único arquivo.Visual Studio for Mac doesn't provide options to publish your app as a single file. Você precisará publicar manualmente seguindo as instruções da seção publicar um único arquivo app-CLI .You'll need to publish manually by following the instructions from the Publish a single file app - CLI section. Para obter mais informações, consulte publicar aplicativos .NET Core com CLI do .NET Core.For more information, see Publish .NET Core apps with .NET Core CLI.

Consulte tambémSee also