Partilhar via

Empacotamento de distribuição .NET

À 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)
├── dnx                          (22)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host                                          (*)
│   └── fxr                                       (*)
│       └── <fxr version>        (2)
├── sdk                                           (*)
│   └── <sdk version>            (3)
├── sdk-manifests                (4)              (*)
│   └── <sdk feature band version>
├── library-packs                (21)             (*)
├── 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)
│   └── Microsoft.NETCore.App.Runtime.NativeAOT.<rid> (*)
│       └── <runtime version>            (20)
├── 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)
        └── dnx                  (23)

  • (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 {dotnet_root} deve ser agnóstico de 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).

  • (22) dnx O dnx script é um shell script executável cuja finalidade é encaminhar comandos do usuário para o comando dentro de dotnet dnx um SDK. Essa funcionalidade existe principalmente para tornar a aquisição e o lançamento de vários tipos de aplicativos .NET, como o .NET Tools, mais fácil para os usuários finais. Pense nisso de forma semelhante ao npx comando do Node. Ele é independente de versão, uma vez que a maior parte da funcionalidade real do processo de execução única é gerida na implementação da CLI no diretório versionado do SDK.

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) < host/fxr/>versão fxr contém a lógica de resolução da framework 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) sdk/<versão do sdk> O SDK (também conhecido como "as ferramentas") é um conjunto de ferramentas geridas que são usadas para escrever e criar bibliotecas e aplicações .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) sdk-manifests/<versão de banda de funcionalidades do 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) partilhado/Microsoft.AspNetCore.{App,All}/<versão aspnetcore> 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) shared/Microsoft.Desktop.App/<versão da aplicação de ambiente de trabalho> 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, 23) dotnet.1.gz, dotnetdotnet.1.gz é a página de manual do dotnet. dotnet é um link simbólico para o host dotnet(1). dnx é um link simbólico para o dnx shell script (22). 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) templates contém os modelos utilizados pelo SDK. Por exemplo, dotnet new encontra modelos de projeto aqui.

  • (18) Microsoft.NETCore.App.Runtime.<rid>/<versão do runtime>, Microsoft.AspNetCore.App.Runtime.<rid>/<versão do aspnetcore> Estes ficheiros permitem a criação de aplicações autónomas. 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 na plataforma de destino. No .NET 9, permite criar aplicativos NativeAOT para a plataforma de destino também. Pode estar presente no .NET 9 e mais recente.

  • (20) Microsoft.NETCore.App.Runtime.NativeAOT.<rid>/<runtime version> Esses ficheiros permitem construir aplicações NativeAOT para a plataforma de destino. Pode estar presente no .NET 10 e mais recente.

  • (21) library-packs contém arquivos de pacote 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 (21) podem ser pacotes que a library-packs 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		 ☑ NativeAOT

O versionamento do .NET é baseado nos números de versão do componente de tempo de execução [major].[minor]. A versão do SDK usa o mesmo [major].[minor] e dispõe de um [patch] independente que combina a semântica de funcionalidades e correções 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. A restante parte da versão não está incluída 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),(21)
    • 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, 20)
    • 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),(22),(23)

  • 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 runtime não mais atualizado

    • Versão:<versão 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 direcionar uma versão específica do 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 de versão igual ou maior que. 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).

Pacotes de depuração

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 pacote dotnet-sdk-[major].[minor] deve ser incluído num pacote chamado dotnet-sdk-dbg-[major].[minor]. Você deve instalar o conteúdo de debug no local onde estão 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 o pacote dotnet-sdk-[major].[minor]
  • dotnet.pdb - instalado com o pacote dotnet-sdk-dbg-[major].[minor]

{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 o pacote dotnet-runtime-[major].[minor]
  • System.Text.Json.pdb - instalado com o pacote dotnet-runtime-dbg-[major].[minor]

{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 utilizando 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 ficheiro tar de depuração, nem todo o conteúdo tem a mesma importância. 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 os 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: conteúdo de depuração 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: conteúdo de depuração 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, não se deve empacotar o conteúdo de depuração no tarball de depuração packs.

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.

  • Last updated on