Einzeldateibereitstellung und ausführbare DateiSingle file deployment and executable

Wenn Sie alle Abhängigkeiten der Anwendung in eine einzelne Binärdatei packen, kann ein Anwendungsentwickler die Anwendung in einer Datei bereitstellen und verteilen.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. Dieses Bereitstellungsmodell wurde mit .NET 3.0 eingeführt und in .NET 5.0 erweitert.This deployment model has been available since .NET Core 3.0 and has been enhanced in .NET 5.0. Wenn ein Benutzer zuvor in .NET Core 3.0 eine Einzeldatei-App ausgeführt hat, hat der .NET Core-Host zuerst alle Dateien in ein temporäres Verzeichnis extrahiert, bevor die Anwendung ausgeführt wurde.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. In .NET 5.0 wurde der Ablauf verbessert, indem der Code direkt ausgeführt wird, ohne die Dateien aus der App zu extrahieren..NET 5.0 improves this experience by directly running the code without the need to extract the files from the app.

Die Einzeldateibereitstellung ist für das frameworkabhängige Bereitstellungsmodell und eigenständige Anwendungen verfügbar.Single File deployment is available for both the framework-dependent deployment model and self-contained applications. Bei einer eigenständigen Anwendung handelt es sich dabei um eine große Datei, da die Runtime und die Frameworkbibliotheken enthalten sind.The size of the single file in a self-contained application will be large since it will include the runtime and the framework libraries. Die Einzeldatei-Bereitstellungsoption kann mit den Veröffentlichungsoptionen ReadyToRun und Trim (ein experimentelles Feature in .NET 5.0) kombiniert werden.The single file deployment option can be combined with ReadyToRun and Trim (an experimental feature in .NET 5.0) publish options.

API-InkompatibilitätAPI incompatibility

Einige APIs sind nicht mit einer Einzeldateibereitstellung kompatibel, und Anwendungen müssen möglicherweise geändert werden, wenn sie diese APIs verwenden.Some APIs are not compatible with single-file deployment and applications may require modification if they use these APIs. Wenn Sie ein Framework oder ein Paket eines Drittanbieters verwenden, verwenden diese möglicherweise auch eine dieser APIs und müssen deshalb geändert werden.If you use a third-party framework or package, it's possible that they may also use one of these APIs and need modification. Die häufigste Ursache für Probleme ist die Abhängigkeit von Dateipfaden für Dateien oder DLLs, die im Lieferumfang der Anwendung enthalten sind.The most common cause of problems is dependence on file paths for files or DLLs shipped with the application.

Die Tabelle unten enthält die relevanten Details zur API der Laufzeitbibliothek für die Verwendung einer einzelnen Datei.The table below has the relevant runtime library API details for single-file use.

APIAPI HinweisNote
Assembly.Location Gibt eine leere Zeichenfolge zurück.Returns an empty string.
Module.FullyQualifiedName Diese API gibt eine Zeichenfolge mit dem Wert <Unknown> zurück oder löst eine Ausnahme aus.Returns a string with the value of <Unknown> or throws an exception.
Module.Name Diese API gibt eine Zeichenfolge mit dem Wert <Unknown>zurück.Returns a string with the value of <Unknown>.
Assembly.GetFile Löst IOException aus.Throws IOException.
Assembly.GetFiles Löst IOException aus.Throws IOException.
Assembly.CodeBase Löst PlatformNotSupportedException aus.Throws PlatformNotSupportedException.
Assembly.EscapedCodeBase Löst PlatformNotSupportedException aus.Throws PlatformNotSupportedException.
AssemblyName.CodeBase Gibt nullzurück.Returns null.
AssemblyName.EscapedCodeBase Gibt nullzurück.Returns null.

Es gibt einige Empfehlungen zum Behandeln häufiger Szenarios:We have some recommendations for fixing common scenarios:

Anfügen eines DebuggersAttaching a debugger

Unter Linux ist SOS with LLDB der einzige Debugger, der an eigenständige Einzeldateiprozesse angefügt werden kann oder Absturzabbilder debuggen kann.On Linux, the only debugger which can attach to self-contained single-file processes or debug crash dumps is SOS with LLDB.

Unter Windows und Mac können Visual Studio und VS Code zum Debuggen von Absturzabbildern verwendet werden.On Windows and Mac, Visual Studio and VS Code can be used to debug crash dumps. Das Anfügen an eine eigenständige ausführbare Einzeldatei erfordert eine zusätzliche Datei: mscordbi.{dll,so} .Attaching to a running self-contained single-file executable requires an extra file: mscordbi.{dll,so}.

Ohne diese Datei erzeugt Visual Studio möglicherweise die Fehlermeldung „Anfügen an den Prozess nicht möglich.Without this file Visual Studio may produce the error "Unable to attach to the process. Eine Debugkomponente ist nicht installiert.“, undA debug component is not installed." VS Code erzeigt möglicherweise den Fehler „Fehler beim Anfügen an Prozess: Unbekannter Fehler: 0x80131c3c.“.and VS Code may produce the error "Failed to attach to process: Unknown Error: 0x80131c3c."

Um diese Fehler zu beheben, muss mscordbi neben die ausführbare Datei kopiert werden.To fix these errors, mscordbi needs to be copied next to the executable. mscordbi wird standardmäßig mit publish im Unterverzeichnis mit der Runtime-ID der Anwendung veröffentlicht.mscordbi is published by default in the subdirectory with the application's runtime ID. Wenn ein Benutzer zum Beispiel eine eigenständige ausführbare Einzeldatei mithilfe der dotnet-CLI für Windows und den Parametern -r win-x64 veröffentlichen würde, würde die ausführbare Datei in bin/Debug/net5.0/win-x64/publish platziert werden.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. Eine Kopie von mscordbi.dll wäre dann in in/Debug/net5.0/win-x64 enthalten.A copy of mscordbi.dll would be present in bin/Debug/net5.0/win-x64.

Weitere ÜberlegungenOther considerations

Native Bibliotheken werden nicht standardmäßig in die Einzeldatei gepackt.Single-file doesn't bundle native libraries by default. Unter Linux wird die Runtime im Voraus mit dem Paket verknüpft, und nur anwendungsnative Bibliotheken werden im gleichen Verzeichnis wie die Einzeldatei-App bereitgestellt.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. Unter Windows wird nur der Hostingcode im Voraus verknüpft, und die Runtime und anwendungsnative Bibliotheken werden im gleichen Verzeichnis wie die Einzeldatei-App bereitgestellt.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. Dadurch werden Probleme beim Debuggen vermieden, denn dafür wird vorausgesetzt, dass native Dateien nicht in der Einzeldatei enthalten sind.This is to ensure a good debugging experience, which requires native files to be excluded from the single file. Sie können das Flag IncludeNativeLibrariesForSelfExtract festlegen, um native Dateien in das Einzeldateipaket einzufügen. Diese Dateien werden jedoch in ein temporäres Verzeichnis auf dem Clientcomputer extrahiert, wenn die Einzeldatei-App ausgeführt wird.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.

Die Einzeldateianwendung verfügt über alle zugehörigen PDB-Dateien und wird standardmäßig nicht gebündelt.Single-file application will have all related PDB files alongside it and will not be bundled by default. Wenn Sie PDBs in die Assembly für Projekte, die Sie erstellen, einschließen möchten, legen Sie DebugType auf embedded fest, wie unten ausführlich beschrieben.If you want to include PDBs inside the assembly for projects you build, set the DebugType to embedded as described below in detail.

Verwaltete C++-Komponenten eignen sich nicht für die Einzeldateibereitstellung. Es wird empfohlen, Anwendungen in C# oder einer anderen nicht verwalteten C++-Programmiersprache zu schreiben, wenn diese mit der Einzeldateibereitstellung kompatibel sein sollen.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.

Ausschließen von Dateien aus der EinbettungExclude files from being embedded

Bestimmte Dateien können explizit aus der Einbettung in die Einzeldatei ausgeschlossen werden, indem Sie die folgenden Metadaten festlegen:Certain files can be explicitly excluded from being embedded in the single-file by setting following metadata:

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

So können Sie beispielsweise einige Dateien im Veröffentlichungsverzeichnis speichern, ohne diese in die Einzeldatei zu packen: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>

Einschließen von PDB-Dateien in das BündelInclude PDB files inside the bundle

Die PDB-Datei für eine Assembly kann mithilfe der folgenden Einstellung in die Assembly selbst (.dll) eingebettet werden.The PDB file for an assembly can be embedded into the assembly itself (the .dll) using the setting below. Da die Symbole Teil der Assembly sind, sind sie auch Teil der Einzeldateianwendung:Since the symbols are part of the assembly, they will be part of the single-file application as well:

<DebugType>embedded</DebugType>

Fügen Sie z. B. die folgende Eigenschaft in die Projektdatei einer Assembly ein, um die PDB-Datei in diese Assembly einzubetten: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>

Veröffentlichen einer Einzeldatei-App: BeispielprojektdateiPublish a single file app - sample project file

Hier sehen Sie eine Beispielprojektdatei, in der die Veröffentlichung von Einzeldatei-Apps definiert wird: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>

Diese Eigenschaften verfügen über die folgenden Funktionen:These properties have the following functions:

  • PublishSingleFile: aktiviert die Veröffentlichung von EinzeldateienPublishSingleFile - Enables single-file publishing.
  • SelfContained: bestimmt, ob die App eigenständig oder frameworkabhängig istSelfContained - Determines whether the app will be self-contained or framework-dependent.
  • RuntimeIdentifier: gibt das Betriebssystem und den CPU-Typ an, den Sie als Ziel verwendenRuntimeIdentifier - Specifies the OS and CPU type you are targeting.
  • PublishTrimmed: ermöglicht das Kürzen von Assemblys. Dies wird nur für eigenständige Apps unterstützt.PublishTrimmed - Enables use of assembly trimming, which is only supported for self-contained apps.
  • PublishReadyToRun: ermöglicht die Ahead-of-Time-Kompilierung (AOT)PublishReadyToRun - Enables ahead-of-time (AOT) compilation.

Hinweise:Notes:

  • Apps sind betriebssystem- und architekturspezifisch.Apps are OS and architecture-specific. Sie müssen für jede Konfiguration (z. B. Linux x64, Linux ARM64, Windows x64 usw.) eine App veröffentlichen.You need to publish for each configuration, such as Linux x64, Linux ARM64, Windows x64, and so forth.
  • Konfigurationsdateien (z. B. *.runtimeconfig.json) sind in der Einzeldatei enthalten.Configuration files, such as *.runtimeconfig.json, are included in the single file. Wenn eine zusätzliche Konfigurationsdatei benötigt wird, können Sie sie neben der Einzeldatei platzieren.If an additional configuration file is needed, you can place it beside the single file.

Veröffentlichen einer Einzeldatei-App (CLI)Publish a single file app - CLI

Sie können Ihre Einzeldatei-App mit dem Befehl dotnet publish veröffentlichen.Publish a single file application using the dotnet publish command. Legen Sie die folgenden Eigenschaften fest, wenn Sie Ihre App veröffentlichen:When you publish your app, set the following properties:

  • Veröffentlichung für eine bestimmte Runtime: -r win-x64Publish for a specific runtime: -r win-x64
  • Veröffentlichung als Einzeldatei: -p:PublishSingleFile=truePublish as a single-file: -p:PublishSingleFile=true

Im folgenden Beispiel wird eine App für Windows als eigenständige Einzeldatei-App veröffentlicht.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

Im folgenden Beispiel wird eine App für Linux als frameworkabhängige Einzeldatei-App veröffentlicht.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

Weitere Informationen finden Sie unter Veröffentlichen von .NET Core-Apps mit der .NET Core-CLI.For more information, see Publish .NET Core apps with .NET Core CLI.

Veröffentlichen einer Einzeldatei-App (Visual Studio)Publish a single file app - Visual Studio

Visual Studio erstellt wiederverwendbare Veröffentlichungsprofile, die steuern, wie Ihre App veröffentlicht wird.Visual Studio creates reusable publishing profiles that control how your application is published.

  1. Klicken Sie im Bereich Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, das Sie veröffentlichen möchten.On the Solution Explorer pane, right-click on the project you want to publish. Klicken Sie auf Veröffentlichen.Select Publish.

    Projektmappen-Explorer mit Kontextmenü und markierter Option zum Veröffentlichen

    Wenn Sie noch nicht über ein Veröffentlichungsprofil verfügen, befolgen Sie die Anweisungen zum Erstellen eines solchen Profils, und wählen Sie als Zieltyp Ordner aus.If you don't already have a publishing profile, follow the instructions to create one and choose the Folder target-type.

  2. Wählen Sie Bearbeiten aus.Choose Edit.

    Visual Studio-Veröffentlichungsprofil mit Bearbeitungsschaltfläche

  3. Legen Sie im Dialogfeld Profileinstellungen die folgenden Optionen fest:In the Profile settings dialog, set the following options:

    • Legen Sie den Bereitstellungsmodus auf Eigenständig fest.Set Deployment mode to Self-contained.
    • Legen Sie die Zielrumtime auf die Plattform fest, auf der Sie die App veröffentlichen möchten.Set Target runtime to the platform you want to publish to.
    • Klicken Sie auf Einzelne Datei erstellen.Select Produce single file.

    Klicken Sie auf Speichern, um die Einstellungen zu speichern und zum Dialogfeld Veröffentlichen zurückzukehren.Choose Save to save the settings and return to the Publish dialog.

    Dialogfeld für die Profileinstellungen mit Bereitstellungsmodus, Zielruntime und hervorgehobenen Einzeldateioptionen

  4. Klicken Sie auf Veröffentlichen, um Ihre App als Einzeldatei zu veröffentlichen.Choose Publish to publish your app as a single file.

Weitere Informationen finden Sie unter Veröffentlichen von .NET Core-Apps mit Visual Studio.For more information, see Publish .NET Core apps with Visual Studio.

Veröffentlichen einer Einzeldatei-App (Visual Studio für Mac)Publish a single file app - Visual Studio for Mac

In Visual Studio für Mac ist es nicht möglich, eine App als Einzeldatei zu veröffentlichen.Visual Studio for Mac doesn't provide options to publish your app as a single file. Sie müssen diese manuell veröffentlichen, indem Sie die Anleitung im Abschnitt Veröffentlichen einer Einzeldatei-App (CLI) befolgen.You'll need to publish manually by following the instructions from the Publish a single file app - CLI section. Weitere Informationen finden Sie unter Veröffentlichen von .NET Core-Apps mit der .NET Core-CLI.For more information, see Publish .NET Core apps with .NET Core CLI.

Siehe auchSee also