Partilhar via

Empacotamento de distribuição .NET

  • Artigo

À medida que o .NET 5 (e o .NET Core) e versões posteriores se tornam disponíveis em cada vez mais plataformas, é útil aprender a empacotar, nomear e usar aplicativos e bibliotecas que o usam. Dessa forma, os mantenedores de pacotes podem ajudar a garantir uma experiência consistente, não importa onde os usuários escolham executar o .NET. Este artigo é útil para usuários que são:

  • Tentando criar o .NET a partir do código-fonte.
  • Querer fazer alterações na CLI do .NET que possam afetar o layout resultante ou os pacotes produzidos.

Layout do disco

Quando instalado, o .NET consiste em vários componentes que são dispostos da seguinte forma no sistema de arquivos:

{dotnet_root}                    (0)              (*)
├── dotnet                       (1)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host                                          (*)
│   └── fxr                                       (*)
│       └── <fxr version>        (2)
├── sdk                                           (*)
│   └── <sdk version>            (3)
├── sdk-manifests                (4)              (*)
│   └── <sdk feature band version>
├── library-packs                (20)             (*)
├── metadata                     (4)              (*)
│   └── workloads
│       └── <sdk feature band version>
├── template-packs               (4)              (*)
├── packs                                         (*)
│   ├── Microsoft.AspNetCore.App.Ref              (*)
│   │   └── <aspnetcore ref version>     (11)
│   ├── Microsoft.NETCore.App.Ref                 (*)
│   │   └── <netcore ref version>        (12)
│   ├── Microsoft.NETCore.App.Host.<rid>          (*)
│   │   └── <apphost version>            (13)
│   ├── Microsoft.WindowsDesktop.App.Ref          (*)
│   │   └── <desktop ref version>        (14)
│   ├── NETStandard.Library.Ref                   (*)
│   │   └── <netstandard version>        (15)
│   ├── Microsoft.NETCore.App.Runtime.<rid>       (*)
│   │   └── <runtime version>            (18)
│   ├── Microsoft.AspNetCore.App.Runtime.<rid>    (*)
│   │   └── <aspnetcore version>         (18)
│   └── runtime.<rid>.Microsoft.DotNet.ILCompiler (*)
│       └── <runtime version>            (19)
├── shared                                        (*)
│   ├── Microsoft.NETCore.App                     (*)
│   │   └── <runtime version>     (5)
│   ├── Microsoft.AspNetCore.App                  (*)
│   │   └── <aspnetcore version>  (6)
│   ├── Microsoft.AspNetCore.All                  (*)
│   │   └── <aspnetcore version>  (6)
│   └── Microsoft.WindowsDesktop.App              (*)
│       └── <desktop app version> (7)
└── templates                                     (*)
│   └── <templates version>      (17)
/
├── etc/dotnet
│       └── install_location     (16)
├── usr/share/man/man1
│       └── dotnet.1.gz          (9)
└── usr/bin
        └── dotnet               (10)

  • (0) {dotnet_root} é uma raiz compartilhada para todas as versões principais e secundárias do .NET. Se vários tempos de execução estiverem instalados, eles compartilharão a pasta {dotnet_root} , por exemplo, {dotnet_root}/shared/Microsoft.NETCore.App/6.0.11 e {dotnet_root}/shared/Microsoft.NETCore.App/7.0.0. O nome da pasta deve ser agnóstico de {dotnet_root} versão, ou seja, simplesmente dotnet.

  • (1) dotnet O host (também conhecido como "muxer") tem duas funções distintas: ativar um tempo de execução para iniciar um aplicativo e ativar um SDK para despachar comandos para ele. O host é um executável nativo (dotnet.exe).

Embora haja um único host, a maioria dos outros componentes está em diretórios versionados (2,3,5,6). Isso significa que várias versões podem estar presentes no sistema, uma vez que são instaladas lado a lado.

  • (2) A versão> Host/FXR/<FXR contém a lógica de resolução da estrutura usada pelo host. O host usa o hostfxr mais recente que está instalado. O hostfxr é responsável por selecionar o tempo de execução apropriado ao executar um aplicativo .NET. Por exemplo, um aplicativo criado para o .NET 7.0.0 usa o tempo de execução 7.0.5 quando está disponível. Da mesma forma, o hostfxr seleciona o SDK apropriado durante o desenvolvimento.

  • (3) versão> sdk/<sdk O SDK (também conhecido como "as ferramentas") é um conjunto de ferramentas gerenciadas que são usadas para escrever e criar bibliotecas e aplicativos .NET. O SDK inclui a CLI do .NET, os compiladores de linguagens gerenciadas, MSBuild e tarefas de compilação associadas e destinos, NuGet, novos modelos de projeto e assim por diante.

  • (4) versão de banda> de recursos sdk-manifests/<sdk Os nomes e versões dos ativos que uma instalação de carga de trabalho opcional requer são mantidos em manifestos de carga de trabalho armazenados nesta pasta. O nome da pasta é a versão de banda de recursos do SDK. Portanto, para uma versão do SDK, como 7.0.102, essa pasta ainda seria chamada de 7.0.100. Quando uma carga de trabalho é instalada, as seguintes pastas são criadas conforme necessário para os ativos da carga de trabalho: metadados e pacotes de modelos. Uma distribuição pode criar um arquivo vazio /metadata/workloads/<sdkfeatureband>/userlocal se as cargas de trabalho devem ser instaladas sob um caminho de usuário em vez de na pasta dotnet . Para obter mais informações, consulte GitHub issue dotnet/installer#12104.

A pasta compartilhada contém estruturas. Uma estrutura compartilhada fornece um conjunto de bibliotecas em um local central para que elas possam ser usadas por diferentes aplicativos.

  • (5) shared/Microsoft.NETCore.App/<runtime version> Esta estrutura contém o tempo de execução do .NET e as bibliotecas gerenciadas de suporte.

  • (6) compartilhado/Microsoft.AspNetCore.{ App,All}/<aspnetcore version> contém as bibliotecas ASP.NET Core. As bibliotecas em Microsoft.AspNetCore.App são desenvolvidas e suportadas como parte do projeto .NET. As bibliotecas abaixo Microsoft.AspNetCore.All são um superconjunto que também contém bibliotecas de terceiros.

  • (7) A versão> shared/Microsoft.Desktop.App/<desktop app contém as bibliotecas de ambiente de trabalho do Windows. Isso não está incluído em plataformas que não sejam Windows.

  • (8) LICENSE.txt.ThirdPartyNotices.txt são a licença .NET e as licenças de bibliotecas de terceiros usadas no .NET, respectivamente.

  • (9,10) dotnet.1.gz, dotnet dotnet.1.gz é a página de manual dotnet. dotnet é um link simbólico para o host dotnet(1). Esses arquivos são instalados em locais conhecidos para integração do sistema.

  • (11,12) Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref descrevem a API de uma x.y versão do .NET e do ASP.NET Core, respectivamente. Esses pacotes são usados ao compilar para essas versões de destino.

  • (13) Microsoft.NETCore.App.Host.<rid> contém um binário nativo para a plataforma rid. Esse binário é um modelo ao compilar um aplicativo .NET em um binário nativo para essa plataforma.

  • (14) Microsoft.WindowsDesktop.App.Ref descreve a API da x.y versão das aplicações de ambiente de trabalho do Windows. Esses arquivos são usados ao compilar para esse destino. Isso não é fornecido em plataformas que não sejam Windows.

  • (15) NETStandard.Library.Ref descreve a API netstandard x.y . Esses arquivos são usados ao compilar para esse destino.

  • (16) /etc/dotnet/install_location é um arquivo que contém o caminho completo para {dotnet_root}. O caminho pode terminar com uma nova linha. Não é necessário adicionar este arquivo quando a raiz é /usr/share/dotnet.

  • (17) contém os modelos utilizados pelo SDK. Por exemplo, dotnet new encontre modelos de projeto aqui.

  • (18) Microsoft.NETCore.App.Runtime.<versão rid>/<runtime,Microsoft.AspNetCore.App.Runtime>.<versão> rid>/<aspnetcore Esses arquivos permitem a criação de aplicativos autônomos. Esses diretórios contêm links simbólicos para arquivos em (2), (5) e (6).

  • (19) tempo de execução.<rid>. Microsoft.DotNet.ILCompiler/<runtime version> Esses arquivos permitem a criação de aplicativos NativeAOT para a plataforma de destino.

  • (20) library-packs contém ficheiros de pacotes NuGet. O SDK está configurado para usar essa pasta como uma fonte NuGet. A lista de pacotes NuGet fornecidos por uma compilação .NET é descrita abaixo.

As pastas marcadas com (*) são usadas por vários pacotes. Alguns formatos de pacote (por exemplo, rpm) requerem um tratamento especial dessas pastas. O mantenedor do pacote deve cuidar disso.

Os arquivos de pacote adicionados a library-packs (20) podem ser pacotes que a Microsoft não distribui para a plataforma de destino. Os arquivos também podem ser pacotes que a Microsoft distribui e para os quais library-packs fornece um pacote que foi criado a partir do código-fonte para atender às diretrizes de distribuição de pacotes da plataforma. Os seguintes pacotes estão incluídos pela compilação .NET:

Nome do pacote Publicado por Microsoft Necessário para
Microsoft.DotNet.ILCompiler.<version>.nupkg
Microsoft.NET.ILLink.Tasks.<version>.nupkg		 ☑ NativoAOT

O controle de versão do .NET é baseado nos números de versão do componente [major].[minor] de tempo de execução. A versão do SDK usa o mesmo [major].[minor] e tem um independente [patch] que combina semântica de recurso e patch para o SDK. Por exemplo: SDK versão 7.0.302 é a segunda versão de patch da terceira versão de recurso do SDK que suporta o tempo de execução 7.0. Para obter mais informações sobre como funciona o controle de versão, consulte Visão geral do controle de versão do .NET.

Alguns dos pacotes incluem parte do número da versão em seu nome. Isso permite que você instale uma versão específica. O resto da versão não está incluído no nome da versão. Isso permite que o gerenciador de pacotes do sistema operacional atualize os pacotes (por exemplo, instalando automaticamente correções de segurança). Os gerenciadores de pacotes suportados são específicos do Linux.

A seguir estão listados os pacotes recomendados:

  • dotnet-sdk-[major].[minor] - Instala o SDK mais recente para tempo de execução específico

    • Versão:<versão sdk>
    • Exemplo: dotnet-sdk-7.0
    • Contém: (3),(4),(18),(20)
    • Dependências: dotnet-runtime-[major].[minor], aspnetcore-runtime-[major].[minor], dotnet-targeting-pack-[major].[minor], , aspnetcore-targeting-pack-[major].[minor], netstandard-targeting-pack-[netstandard_major].[netstandard_minor]dotnet-apphost-pack-[major].[minor], ,dotnet-templates-[major].[minor]

  • dotnet-sdk-aot-[major].[minor] - Instala os componentes SDK para a plataforma NativeAOT

    • Versão:<versão sdk>
    • Exemplo: dotnet-sdk-aot-9.0
    • Contém: (19)
    • Dependências: dotnet-sdk-[major].[minor], cadeia de ferramentas do compilador e pacotes de desenvolvedor para bibliotecas das quais o tempo de execução do .NET depende

  • aspnetcore-runtime-[major].[minor] - Instala um tempo de execução específico do ASP.NET Core

    • Versão:<aspnetcore runtime version>
    • Exemplo: aspnetcore-runtime-7.0
    • Contém: (6)
    • Dependências: dotnet-runtime-[major].[minor]

  • dotnet-runtime-deps-[major].[minor](Opcional) - Instala as dependências para executar aplicativos autônomos

    • Versão:<versão de tempo de execução>
    • Exemplo: dotnet-runtime-deps-7.0
    • Dependências: dependências específicas da distribuição

  • dotnet-runtime-[major].[minor] - Instala um tempo de execução específico

    • Versão:<versão de tempo de execução>
    • Exemplo: dotnet-runtime-7.0
    • Contém: (5)
    • Dependências: dotnet-hostfxr-[major].[minor], dotnet-runtime-deps-[major].[minor]

  • dotnet-hostfxr-[major].[minor] - dependência

    • Versão:<versão de tempo de execução>
    • Exemplo: dotnet-hostfxr-7.0
    • Contém: (2)
    • Dependências: dotnet-host

  • dotnet-host - dependência

    • Versão:<versão de tempo de execução>
    • Exemplo: dotnet-host
    • Contém: (1),(8),(9),(10),(16)

  • dotnet-apphost-pack-[major].[minor] - dependência

    • Versão:<versão de tempo de execução>
    • Contém: (13)

  • dotnet-targeting-pack-[major].[minor] - Permite direcionar um tempo de execução não mais recente

    • Versão:<versão de tempo de execução>
    • Contém: (12)

  • aspnetcore-targeting-pack-[major].[minor] - Permite direcionar um tempo de execução não mais recente

    • Versão:<aspnetcore runtime version>
    • Contém: (11)

  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] - Permite segmentar uma versão netstandard

    • Versão:<versão sdk>
    • Contém: (15)

  • dotnet-templates-[major].[minor]

    • Versão:<versão sdk>
    • Contém: (17)

Os dois metapacotes a seguir são opcionais. Eles trazem valor para os usuários finais, pois abstraem o pacote de nível superior (dotnet-sdk), que simplifica a instalação do conjunto completo de pacotes .NET. Esses pacotes meta fazem referência a uma versão específica do SDK do .NET.

  • dotnet[major] - Instala a versão especificada do SDK

    • Versão:<versão sdk>
    • Exemplo: dotnet7
    • Dependências: dotnet-sdk-[major].[minor]

  • dotnet - Instala uma versão específica do SDK determinada pelas distribuições como sendo a versão principal — geralmente a mais recente disponível

    • Versão:<versão sdk>
    • Exemplo: dotnet
    • Dependências: dotnet-sdk-[major].[minor]

O dotnet-runtime-deps-[major].[minor] requer a compreensão das dependências específicas da distro. Como o sistema de compilação de distribuição pode ser capaz de derivar isso automaticamente, o pacote é opcional, caso em que essas dependências são adicionadas diretamente ao dotnet-runtime-[major].[minor] pacote.

Quando o conteúdo do pacote está sob uma pasta versionada, o nome [major].[minor] do pacote corresponde ao nome da pasta versionada. Para todos os pacotes, exceto o netstandard-targeting-pack-[netstandard_major].[netstandard_minor], isso também corresponde à versão .NET.

As dependências entre pacotes devem usar um requisito igual ou maior do que o de versão. Por exemplo, dotnet-sdk-7.0:7.0.401 requer aspnetcore-runtime-7.0 >= 7.0.6. Isso torna possível para o usuário atualizar sua instalação através de um pacote raiz (por exemplo, dnf update dotnet-sdk-7.0).

A maioria das distribuições requer que todos os artefatos sejam construídos a partir da fonte. Isto tem algum impacto nos pacotes:

  • As bibliotecas de terceiros em shared/Microsoft.AspNetCore.All não podem ser facilmente construídas a partir do código-fonte. Portanto, essa pasta é omitida do aspnetcore-runtime pacote.

  • O NuGetFallbackFolder é preenchido usando artefatos binários de nuget.org. Deve permanecer vazio.

Vários dotnet-sdk pacotes podem fornecer os mesmos arquivos para o NuGetFallbackFolder. Para evitar problemas com o gerenciador de pacotes, esses arquivos devem ser idênticos (soma de verificação, data de modificação e assim por diante).

Depurar pacotes

O conteúdo de depuração deve ser empacotado em pacotes nomeados por depuração que seguem a divisão de pacote .NET descrita anteriormente neste artigo. Por exemplo, o conteúdo de depuração para o dotnet-sdk-[major].[minor] pacote deve ser incluído em um pacote chamado dotnet-sdk-dbg-[major].[minor]. Você deve instalar o conteúdo de depuração no mesmo local que os binários.

Aqui estão alguns exemplos binários:

{dotnet_root}/sdk/<sdk version> No diretório, os dois arquivos a seguir são esperados:

  • dotnet.dll - instalado com dotnet-sdk-[major].[minor] pacote
  • dotnet.pdb - instalado com dotnet-sdk-dbg-[major].[minor] pacote

{dotnet_root}/shared/Microsoft.NETCore.App/<runtime version> No diretório, os dois arquivos a seguir são esperados:

  • System.Text.Json.dll - instalado com dotnet-runtime-[major].[minor] pacote
  • System.Text.Json.pdb - instalado com dotnet-runtime-dbg-[major].[minor] pacote

{dotnet_root/shared/Microsoft.AspNetCore.App/<aspnetcore version> No diretório, os dois arquivos a seguir são esperados:

  • Microsoft.AspNetCore.Routing.dll - instalado com aspnetcore-runtime-[major].[minor] pacotes
  • Microsoft.AspNetCore.Routing.pdb - instalado com aspnetcore-runtime-dbg-[major].[minor] pacotes

A partir do .NET 8.0, todo o conteúdo de depuração do .NET (arquivos PDB), produzido pelo source-build, está disponível em um tarball chamado dotnet-symbols-sdk-<version>-<rid>.tar.gz. Este arquivo contém PDBs em subdiretórios que correspondem à estrutura de diretórios do tarball do SDK do .NET - dotnet-sdk-<version>-<rid>.tar.gz.

Embora todo o conteúdo de depuração esteja disponível no tarball de depuração, nem todo o conteúdo de depuração é igualmente importante. Os usuários finais estão principalmente interessados no conteúdo dos shared/Microsoft.AspNetCore.App/<aspnetcore version> diretórios e shared/Microsoft.NETCore.App/<runtime version> .

O conteúdo do SDK em sdk/<sdk version> é útil para depurar conjuntos de ferramentas do SDK do .NET.

Os seguintes pacotes são os pacotes de depuração recomendados:

  • aspnetcore-runtime-dbg-[major].[minor] - Instala conteúdo de depuração para um tempo de execução específico do ASP.NET Core

    • Versão:<aspnetcore runtime version>
    • Exemplo: aspnetcore-runtime-dbg-8.0
    • Contém: depurar conteúdo para (6)
    • Dependências: aspnetcore-runtime-[major].[minor]

  • dotnet-runtime-dbg-[major].[minor] - Instala conteúdo de depuração para um tempo de execução específico

    • Versão:<versão de tempo de execução>
    • Exemplo: dotnet-runtime-dbg-8.0
    • Contém: depurar conteúdo para (5)
    • Dependências: dotnet-runtime-[major].[minor]

O seguinte pacote de depuração é opcional:

  • dotnet-sdk-dbg-[major].[minor] - Instala conteúdo de depuração para uma versão específica do SDK
    • Versão:<versão sdk>
    • Exemplo: dotnet-sdk-dbg-8.0
    • Contém: conteúdo de depuração para (3),(4),(18)
    • Dependências: dotnet-sdk-[major].[minor]

O tarball de depuração também contém algum conteúdo de depuração em packs, que representa cópias do conteúdo em shared. No layout .NET, o packs diretório é usado para criar aplicativos .NET. Não há cenários de depuração, portanto, você não deve empacotar o conteúdo de depuração no packs tarball de depuração.

Pacotes de construção

O repositório dotnet/source-build fornece instruções sobre como criar um tarball de origem do SDK do .NET e todos os seus componentes. A saída do repositório source-build corresponde ao layout descrito na primeira seção deste artigo.