単一ファイルの配置と実行可能ファイルSingle file deployment and executable

アプリケーションに依存するすべてのファイルを単一のバイナリにバンドルすることで、アプリケーション開発者は、アプリケーションを単一ファイルとして配置し、配布することができます。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. このデプロイ モデルは、.NET Core 3.0 以降で利用可能であり、.NET 5.0 で拡張されています。This deployment model has been available since .NET Core 3.0 and has been enhanced in .NET 5.0. 以前の .NET Core 3.0 では、ユーザーが単一ファイル アプリを実行する場合、そのアプリケーションが実行される前に、まず .NET Core ホストがすべてのファイルを一時ディレクトリに抽出します。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. .NET 5.0 では、アプリからファイルを抽出する必要がなく、コードを直接実行するので、このエクスペリエンスが向上しています。.NET 5.0 improves this experience by directly running the code without the need to extract the files from the app.

フレームワークに依存するデプロイ モデル自己完結型アプリケーションの両方で、単一ファイルの配置が可能です。Single File deployment is available for both the framework-dependent deployment model and self-contained applications. 自己完結型アプリケーション内にある単一ファイルは、ランタイム ライブラリとフレームワーク ライブラリが含まれるため、大きなサイズとなります。The size of the single file in a self-contained application will be large since it will include the runtime and the framework libraries. 単一ファイル配置オプションは、ReadyToRunTrim (.NET 5.0 の試験的な機能) の各発行オプションと組み合わせることができます。The single file deployment option can be combined with ReadyToRun and Trim (an experimental feature in .NET 5.0) publish options.

API の非互換性API incompatibility

一部の API は、単一ファイルの配置と互換性がありません。また、これらの API を使用する場合、アプリケーションで変更が必要になることがあります。Some APIs are not compatible with single-file deployment and applications may require modification if they use these APIs. サードパーティのフレームワークまたはパッケージを使用する場合、それらでこれらの API のいずれかが使用されていて、変更が必要になる可能性があります。If you use a third-party framework or package, it's possible that they may also use one of these APIs and need modification. 問題の最も一般的な原因は、アプリケーションに付属するファイルまたは DLL のファイル パスに依存していることです。The most common cause of problems is dependence on file paths for files or DLLs shipped with the application.

次の表では、単一ファイルの使用に関連するランタイム ライブラリ API の詳細を示します。The table below has the relevant runtime library API details for single-file use.

APIAPI NoteNote
Assembly.Location 空の文字列を返します。Returns an empty string.
Module.FullyQualifiedName 値が <Unknown> である文字列が返されるか、例外がスローされます。Returns a string with the value of <Unknown> or throws an exception.
Module.Name 値が <Unknown> である文字列が返されます。Returns a string with the value of <Unknown>.
Assembly.GetFile IOException をスローします。Throws IOException.
Assembly.GetFiles IOException をスローします。Throws IOException.
Assembly.CodeBase PlatformNotSupportedException をスローします。Throws PlatformNotSupportedException.
Assembly.EscapedCodeBase PlatformNotSupportedException をスローします。Throws PlatformNotSupportedException.
AssemblyName.CodeBase null を返します。Returns null.
AssemblyName.EscapedCodeBase null を返します。Returns null.

一般的なシナリオを修正するための推奨事項がいくつかあります。We have some recommendations for fixing common scenarios:

デバッガーのアタッチAttaching a debugger

Linux では、自己完結型の単一ファイル プロセスにアタッチしたり、クラッシュ ダンプをデバッグしたりできる唯一のデバッガーは、LLDB を使用する SOS です。On Linux, the only debugger which can attach to self-contained single-file processes or debug crash dumps is SOS with LLDB.

Windows と Mac では、Visual Studio と VS Code を使用してクラッシュ ダンプをデバッグできます。On Windows and Mac, Visual Studio and VS Code can be used to debug crash dumps. 実行中の自己完結型単一ファイルの実行可能ファイルにアタッチするには、余分なファイル mscordbi.{dll,so} が必要です。Attaching to a running self-contained single-file executable requires an extra file: mscordbi.{dll,so}.

このファイルがないと、Visual Studio で次のエラーが発生することがあります: "プロセスにアタッチできません。Without this file Visual Studio may produce the error "Unable to attach to the process. デバッグ コンポーネントはインストールされていません。"A debug component is not installed." また、VS Code では、次のエラーが発生することがあります: "プロセスにアタッチできませんでした: 不明なエラー: 0x80131c3c。"and VS Code may produce the error "Failed to attach to process: Unknown Error: 0x80131c3c."

これらのエラーを修正するには、実行可能ファイルの隣に mscordbi をコピーする必要があります。To fix these errors, mscordbi needs to be copied next to the executable. mscordbi は、既定では、アプリケーションのランタイム ID でサブディレクトリに publish されます。mscordbi is published by default in the subdirectory with the application's runtime ID. そのため、たとえば、dotnet CLI と -r win-x64 パラメーターを使用して Windows 用に自己完結型単一ファイルの実行可能ファイルを発行する場合、実行可能ファイルは bin/Debug/net5.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. mscordbi.dll のコピーは bin/Debug/net5.0/win-x64 にあります。A copy of mscordbi.dll would be present in bin/Debug/net5.0/win-x64.

その他の考慮事項Other considerations

既定では、単一ファイルを使用してネイティブ ライブラリをバンドルすることができません。Single-file doesn't bundle native libraries by default. Linux では、ランタイム ライブラリをバンドルに事前にリンクして、アプリケーション ネイティブ ライブラリのみを単一ファイル アプリと同じディレクトリに配置します。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. Windows では、ホスト コードのみを事前にリンクして、ランタイム ライブラリとアプリケーション ネイティブ ライブラリの両方を単一ファイル アプリと同じディレクトリに配置します。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. これにより、優れたデバッグ エクスペリエンスが確保されます。それには、ネイティブ ファイルを単一ファイルから除外する必要があります。This is to ensure a good debugging experience, which requires native files to be excluded from the single file. 単一ファイル バンドルにネイティブ ライブラリを含めるようにフラグ IncludeNativeLibrariesForSelfExtract を設定するオプションがありますが、これらのファイルは、単一ファイル アプリケーションが実行されるときに、クライアント コンピューターの一時ディレクトリに抽出されます。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.

単一ファイル アプリケーションでは、関連するすべての PDB ファイルは隣に配置され、既定ではバンドルされません。Single-file application will have all related PDB files alongside it and will not be bundled by default. ビルドするプロジェクトのアセンブリ内に PDB を含めるには、以下で詳しく説明するように、DebugTypeembedded に設定します。If you want to include PDBs inside the assembly for projects you build, set the DebugType to embedded as described below in detail.

マネージド C++ コンポーネントは、単一ファイルの配置には適していません。単一ファイルとの互換性を確保するには、アプリケーションを C# または別の非マネージド C++ 言語で記述することをお勧めします。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.

ファイルを埋め込み対象から除外するExclude files from being embedded

次のメタデータを設定すると、特定のファイルを単一ファイルの埋め込み対象から明示的に除外することができます。Certain files can be explicitly excluded from being embedded in the single-file by setting following metadata:

<ExcludeFromSingleFile>true</ExcludeFromSingleFile>

たとえば、いくつかのファイルを発行ディレクトリに配置するものの、単一ファイルへのバンドルは行わない場合などです。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>

バンドル内に PDB ファイルを含めるInclude PDB files inside the bundle

アセンブリの PDB ファイルは、次の設定を使用して、アセンブリ自体 (.dll) に埋め込むことができます。The PDB file for an assembly can be embedded into the assembly itself (the .dll) using the setting below. シンボルはアセンブリの一部であるため、単一ファイル アプリケーションの一部にもなります。Since the symbols are part of the assembly, they will be part of the single-file application as well:

<DebugType>embedded</DebugType>

たとえば、アセンブリに PDB ファイルを埋め込むには、そのアセンブリのプロジェクト ファイルに次のプロパティを追加します。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>

単一のファイル アプリを発行する - サンプル プロジェクト ファイルPublish a single file app - sample project file

単一ファイルの発行を指定するサンプル プロジェクト ファイルを次に示します。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>

これらのプロパティには、次の関数があります。These properties have the following functions:

  • PublishSingleFile - 単一ファイルの発行を有効にします。PublishSingleFile - Enables single-file publishing.
  • SelfContained - アプリが自己完結型またはフレームワーク依存であるかを判断します。SelfContained - Determines whether the app will be self-contained or framework-dependent.
  • RuntimeIdentifier - ターゲットとする OS と CPU の種類を指定します。RuntimeIdentifier - Specifies the OS and CPU type you are targeting.
  • PublishTrimmed - 自己完結型アプリでのみサポートされているアセンブリのトリミングの使用を有効にします。PublishTrimmed - Enables use of assembly trimming, which is only supported for self-contained apps.
  • PublishReadyToRun - Ahead-Of-Time (AOT) コンパイルを有効にします。PublishReadyToRun - Enables ahead-of-time (AOT) compilation.

注:Notes:

  • アプリは OS とアーキテクチャに固有のものです。Apps are OS and architecture-specific. Linux x64、Linux ARM64、Windows x64 など、構成ごとに発行する必要があります。You need to publish for each configuration, such as Linux x64, Linux ARM64, Windows x64, and so forth.
  • 構成ファイル ( *.runtimeconfig.json など) は、単一ファイルに含まれています。Configuration files, such as *.runtimeconfig.json, are included in the single file. 追加の構成ファイルが必要な場合は、その単一ファイルの横に配置することができます。If an additional configuration file is needed, you can place it beside the single file.

単一ファイル アプリを発行する - CLIPublish a single file app - CLI

dotnet publish コマンドを使用して、単一ファイル アプリケーションを発行します。Publish a single file application using the dotnet publish command. アプリを発行する場合、次のプロパティを設定します。When you publish your app, set the following properties:

  • 特定のランタイムに対して発行する: -r win-x64Publish for a specific runtime: -r win-x64
  • 単一ファイルとして発行する: -p:PublishSingleFile=truePublish as a single-file: -p:PublishSingleFile=true

次の例では、Windows 用のアプリを自己完結型の単一ファイル アプリケーションとして発行します。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

次の例では、Linux 用のアプリをフレームワークに依存する単一ファイル アプリケーションとして発行します。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

詳細については、「.NET Core CLI を使用して .NET Core アプリを発行する」を参照してください。For more information, see Publish .NET Core apps with .NET Core CLI.

単一ファイル アプリを発行する - Visual StudioPublish a single file app - Visual Studio

Visual Studio を使用すると、アプリケーションの発行方法を制御する再利用可能な発行プロファイルを作成できます。Visual Studio creates reusable publishing profiles that control how your application is published.

  1. [ソリューション エクスプローラー] ペインで、発行するプロジェクトを右クリックします。On the Solution Explorer pane, right-click on the project you want to publish. [発行] を選択します。Select Publish.

    右クリック メニューの [発行] オプションが強調表示されたソリューション エクスプローラー。

    発行プロファイルがまだない場合は、指示に従って作成し、ターゲットの種類として [フォルダー] を選択します。If you don't already have a publishing profile, follow the instructions to create one and choose the Folder target-type.

  2. [編集] を選択します。Choose Edit.

    Visual Studio の発行プロファイルと [編集] ボタン

  3. [プロファイル設定] ダイアログで、次のオプションを設定します。In the Profile settings dialog, set the following options:

    • [配置モード][自己完結] に設定します。Set Deployment mode to Self-contained.
    • [ターゲット ランタイム] を発行先のプラットフォームに設定します。Set Target runtime to the platform you want to publish to.
    • [単一ファイルの作成] を選択します。Select Produce single file.

    [保存] を選択して設定を保存し、 [発行] ダイアログに戻ります。Choose Save to save the settings and return to the Publish dialog.

    [配置モード]、[ターゲット ランタイム]、[単一ファイルの作成] の各オプションが強調表示されている [プロファイル設定] ダイアログ。

  4. [発行] を選択して、アプリを単一ファイルとして発行します。Choose Publish to publish your app as a single file.

詳細については、Visual Studio を使用した .NET Core アプリの発行に関するページを参照してください。For more information, see Publish .NET Core apps with Visual Studio.

単一ファイル アプリを発行する - Visual Studio for MacPublish a single file app - Visual Studio for Mac

Visual Studio for Mac には、アプリを単一ファイルとして発行するためのオプションがありません。Visual Studio for Mac doesn't provide options to publish your app as a single file. 単一ファイル アプリを発行する - CLI」セクションの手順に従って、手動で発行する必要があります。You'll need to publish manually by following the instructions from the Publish a single file app - CLI section. 詳細については、「.NET Core CLI を使用して .NET Core アプリを発行する」を参照してください。For more information, see Publish .NET Core apps with .NET Core CLI.

関連項目See also