Nasazení s jedním souborem

  • Článek

Sdružování všech souborů závislých na aplikaci do jednoho binárního souboru poskytuje vývojáři aplikací atraktivní možnost nasazení a distribuce aplikace jako jednoho souboru. Nasazení s jedním souborem je k dispozici pro model nasazení závislý na rozhraní i pro samostatné aplikace.

Velikost jednoho souboru v samostatné aplikaci je velká, protože zahrnuje modul runtime a knihovny architektury. V .NET 6 můžete publikovat oříznutí , abyste snížili celkovou velikost aplikací kompatibilních s oříznutím. Možnost nasazení s jedním souborem lze kombinovat s možnostmi publikování ReadyToRun a Trim .

Důležité

Pokud chcete spustit jednu souborovou aplikaci ve Windows 7, musíte použít .NET Runtime 6.0.3 nebo novější.

Ukázkový soubor projektu

Tady je ukázkový soubor projektu, který určuje publikování jednoho souboru:

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

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

</Project>

Tyto vlastnosti mají následující funkce:

  • PublishSingleFile. Povolí publikování s jedním souborem. Umožňuje také upozornění na jeden soubor během dotnet build.
  • SelfContained. Určuje, jestli je aplikace samostatná nebo závislá na rozhraní.
  • RuntimeIdentifier. Určuje typ operačního systému a procesoru, na který cílíte. <SelfContained>true</SelfContained> Nastaví se také ve výchozím nastavení.

Jednosouborové aplikace jsou vždy specifické pro operační systém a architekturu. Potřebujete publikovat každou konfiguraci, například Linux x64, Linux Arm64, Windows x64 atd.

Konfigurační soubory modulu runtime, například *.runtimeconfig.json a *.deps.json, jsou součástí jednoho souboru. Pokud potřebujete další konfigurační soubor, můžete ho umístit vedle jednoho souboru.

Publikování jednosouborové aplikace

Publikujte jednu souborovou aplikaci pomocí příkazu dotnet publish .

  1. Přidejte <PublishSingleFile>true</PublishSingleFile> do souboru projektu.

    Tato změna vytvoří jednu souborovou aplikaci v samostatném publikování. Během sestavování se také zobrazují upozornění kompatibility s jedním souborem.

    <PropertyGroup>
    <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>

  2. Publikování aplikace pro konkrétní identifikátor modulu runtime pomocí dotnet publish -r <RID>

    Následující příklad publikuje aplikaci pro Windows jako samostatnou aplikaci s jedním souborem.

    dotnet publish -r win-x64

    Následující příklad publikuje aplikaci pro Linux jako samostatnou souborovou aplikaci závislé na rozhraní.

    dotnet publish -r linux-x64 --self-contained false

<PublishSingleFile> soubor projektu by měl být nastavený tak, aby umožňoval analýzu souborů během sestavování, ale je také možné předat tyto možnosti jako dotnet publish argumenty:

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

Další informace najdete v tématu Publikování aplikací .NET Core pomocí .NET CLI.

Vyloučení souborů z vložení

Některé soubory je možné explicitně vyloučit z vložení do jednoho souboru nastavením následujících metadat:

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

Pokud například chcete některé soubory umístit do adresáře publikování, ale ne je seskupit do souboru:

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

Zahrnutí souborů PDB do sady

Soubor PDB pro sestavení lze vložit do samotného sestavení (the .dll) pomocí následujícího nastavení. Vzhledem k tomu, že symboly jsou součástí sestavení, jsou součástí aplikace také:

<DebugType>embedded</DebugType>

Přidejte například do souboru projektu sestavení následující vlastnost pro vložení souboru PDB do tohoto sestavení:

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

Ostatní úvahy

Aplikace s jedním souborem mají všechny související PDB soubory spolu s aplikací, nikoli sbalené ve výchozím nastavení. Pokud chcete zahrnout soubory PDB do sestavení pro projekty, které sestavíte, nastavte na DebugType hodnotu embedded. Viz Zahrnutí souborů PDB do sady.

Spravované komponenty C++ nejsou vhodné pro nasazení jednoho souboru. Doporučujeme psát aplikace v jazyce C# nebo jiném nespravovaném jazyce C++, aby byly kompatibilní s jedním souborem.

Nativní knihovny

Pouze spravované knihovny DLL jsou součástí aplikace do jednoho spustitelného souboru. Při spuštění aplikace se spravované knihovny DLL extrahují a načtou do paměti, aby se zabránilo extrahování do složky. Díky tomuto přístupu jsou spravované binární soubory vložené do jedné sady souborů, ale nativní binární soubory samotného základního modulu runtime jsou samostatné soubory.

Chcete-li vložit tyto soubory pro extrakci a získat jeden výstupní soubor, nastavte vlastnost IncludeNativeLibrariesForSelfExtract na true.

Určení extrahuje IncludeAllContentForSelfExtract všechny soubory, včetně spravovaných sestavení, před spuštěním spustitelného souboru. To může být užitečné pro vzácné problémy s kompatibilitou aplikací.

Důležité

Pokud se použije extrakce, soubory se před spuštěním aplikace extrahují na disk:

  • DOTNET_BUNDLE_EXTRACT_BASE_DIR Pokud je proměnná prostředí nastavená na cestu, soubory se extrahují do adresáře pod touto cestou.
  • V opačném případě, pokud běží v Linuxu nebo macOS, soubory se extrahují do adresáře v části $HOME/.net.
  • Pokud běží ve Windows, soubory se extrahují do adresáře v části %TEMP%/.net.

Aby se zabránilo manipulaci, neměly by být tyto adresáře zapisovatelné uživateli nebo službami s různými oprávněními. Nepoužívejte /tmp nebo /var/tmp ve většině systémů Linux a macOS.

Poznámka:

V některých linuxových prostředích, například v části systemd, výchozí extrakce nefunguje, protože $HOME není definovaná. V takových případech se doporučuje explicitně nastavit $DOTNET_BUNDLE_EXTRACT_BASE_DIR .

Dobrou systemdalternativou je definovat DOTNET_BUNDLE_EXTRACT_BASE_DIR soubor jednotek vaší služby jako %h/.net, který systemd se správně rozšíří na $HOME/.net účet, na kterém je služba spuštěna.

[Service]
Environment="DOTNET_BUNDLE_EXTRACT_BASE_DIR=%h/.net"

Nekompatibilitu rozhraní API

Některá rozhraní API nejsou kompatibilní s nasazením jednoho souboru. Aplikace můžou vyžadovat úpravy, pokud tato rozhraní API používají. Pokud používáte architekturu nebo balíček třetí strany, je možné, že můžou používat jedno z těchto rozhraní API a vyžadovat úpravy. Nejběžnější příčinou problémů je závislost na cestě k souborům nebo knihovnám DLL dodávaným s aplikací.

Následující tabulka obsahuje relevantní podrobnosti rozhraní API knihovny modulu runtime pro použití s jedním souborem.

rozhraní API Poznámka:
Assembly.CodeBase Vyhodí PlatformNotSupportedException.
Assembly.EscapedCodeBase Vyhodí PlatformNotSupportedException.
Assembly.GetFile Vyhodí IOException.
Assembly.GetFiles Vyhodí IOException.
Assembly.Location Vrátí prázdný řetězec.
AssemblyName.CodeBase Vrací objekt null.
AssemblyName.EscapedCodeBase Vrací objekt null.
Module.FullyQualifiedName Vrátí řetězec s hodnotou <Unknown> nebo vyvolá výjimku.
Marshal.GetHINSTANCE Vrátí hodnotu -1.
Module.Name Vrátí řetězec s hodnotou <Unknown>.

Pro řešení běžných scénářů máme několik doporučení:

Binární soubory po zpracování před sloučením

Některé pracovní postupy před sdružováním vyžadují následné zpracování binárních souborů. Běžným příkladem je podepisování. Sada dotnet SDK poskytuje body rozšíření MSBuild, které umožňují zpracování binárních souborů těsně před sdružováním s jedním souborem. Dostupná rozhraní API jsou:

  • Cíl PrepareForBundle , který bude volána před GenerateSingleFileBundle
  • Obsahující <ItemGroup><FilesToBundle /></ItemGroup> všechny soubory, které se sbalí
  • Vlastnost AppHostFile , která určí šablonu apphost. Po zpracování může být vhodné vyloučit z zpracování hostitele apphost.

To zahrnuje vytvoření cíle, který se provede mezi PrepareForBundle a GenerateSingleFileBundle.

Představte si následující příklad uzlu projektu Target .NET:

<Target Name="MySignedBundledFile" BeforeTargets="GenerateSingleFileBundle" DependsOnTargets="PrepareForBundle">

Je možné, že nástroje budou muset kopírovat soubory v procesu podepisování. K tomu může dojít, pokud je původní soubor sdílenou položkou, kterou sestavení nevlastní, například soubor pochází z mezipaměti NuGet. V takovém případě se očekává, že nástroj upraví cestu odpovídající FilesToBundle položky tak, aby odkazovaly na upravenou kopii.

Komprese sestavení v aplikacích s jedním souborem

Jednosouborové aplikace lze vytvořit s povolenou kompresí u vložených sestavení. Nastavte vlastnost EnableCompressionInSingleFile na true. Vytvořený soubor bude mít všechna vložená sestavení komprimovaná, což může výrazně snížit velikost spustitelného souboru.

Komprese se dodává s náklady na výkon. Při spuštění aplikace musí být sestavení dekomprimována do paměti, což nějakou dobu trvá. Než ji začnete používat, doporučujeme změřit jak změnu velikosti, tak náklady na spuštění komprese. Dopad se může výrazně lišit mezi různými aplikacemi.

Kontrola jednosouborové aplikace

Jednosouborové aplikace je možné zkontrolovat pomocí nástroje ILSpy. Nástroj může zobrazit všechny soubory, které jsou součástí aplikace, a může zkontrolovat obsah spravovaných sestavení.

Viz také