Visual Studio 容器工具搭配 ASP.NET Core

發行項
11/30/2023

Visual Studio 2017 和更新版本支援建置、偵錯和執行以 .NET Core 為目標的容器化 ASP.NET Core 應用程式。同時支援 Windows 和 Linux 容器。

必要條件

適用於 Windows 的 Docker
已安裝 .NET Core 跨平台開發工作負載的 Visual Studio 2019

安裝和設定

若要進行 Docker 安裝，請先檢閱 Docker for Windows: What to know before you install 中的資訊。接下來，安裝適用於 Windows 的 Docker。

Docker for Windows 中的 Shared Drives (共用磁碟機) 必須設定為支援磁碟區對應和偵錯。以滑鼠右鍵按一下系統匣的 Docker 圖示，並選取 [設定]，然後選取 [共用磁碟機]。選取 Docker 儲存檔案的磁碟機。按一下套用。

Dialog to select local C drive sharing for containers

提示

未設定 [共用磁碟機] 時，Visual Studio 2017 15.6 版和更新版本會顯示提示。

將專案新增至 Docker 容器

若要將 ASP.NET Core 專案容器化，專案必須以 .NET Core 為目標。同時支援 Linux 和 Windows 容器。

將 Docker 支援新增至專案時，請選擇 Windows 或 Linux 容器。 Docker 主機必須執行相同的容器類型。若要變更執行中 Docker 執行個體中的容器類型，請以滑鼠右鍵按一下系統匣的 Docker 圖示，然後選擇 [Switch to Windows containers...] (切換至 Windows 容器...) 或 [Switch to Linux containers] (切換至 Linux 容器...)。

全新應用程式

使用 ASP.NET Core Web 應用程式專案範本來建立新的應用程式時，請選取 [Enable Docker Support] ( (啟用 Docker 支援) 核取方塊：

Enable Docker Support checkbox

如果目標架構是 .NET Core，則 [OS] 下拉式清單會允許選取容器類型。

現有的應用程式

針對以 .NET Core 為目標的 ASP.NET Core 專案，有兩個選項可透過工具來新增 Docker 支援。在 Visual Studio 中開啟專案，然後選擇下列其中一個選項：

選取 [專案] 功能表的 [Docker 支援]。
以滑鼠右鍵按一下方案總管中的專案，然後選取 [新增]>[Docker 支援]。

Visual Studio 容器工具不支援將 Docker 新增至以 .NET Framework 為目標的現有 ASP.NET Core 專案。

Dockerfile 概觀

Dockerfile，是用於建立最終 Docker 映像的配方，會新增至專案根目錄。請參閱 Dockerfile 參考，以了解其內的命令。此特定 Dockerfile 使用多階段建置，包含四個不同的具名建置階段：

FROM mcr.microsoft.com/dotnet/core/aspnet:2.1 AS base
WORKDIR /app
EXPOSE 59518
EXPOSE 44364

FROM mcr.microsoft.com/dotnet/core/sdk:2.1 AS build
WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app

FROM build AS publish
RUN dotnet publish HelloDockerTools.csproj -c Release -o /app

FROM base AS final
WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

上述 Dockerfile 映射包含 ASP.NET Core 執行時間和 NuGet 套件。套件會進行 Just-in-Time (JIT) 編譯，以改善啟動效能。

核取新專案對話方塊的 [設定 HTTPS] 核取方塊時，Dockerfile 會提供兩個連接埠。其中一個連接埠用於 HTTP 流量，另一個連接埠則用於 HTTPS。如果未核取該核取方塊，則會為 HTTP 流量提供單一連接埠 (80)。

FROM microsoft/aspnetcore:2.0 AS base
WORKDIR /app
EXPOSE 80

FROM microsoft/aspnetcore-build:2.0 AS build
WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app

FROM build AS publish
RUN dotnet publish HelloDockerTools.csproj -c Release -o /app

FROM base AS final
WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

上述 Dockerfile 映射包含 ASP.NET Core NuGet 套件，這些套件是編譯的 Just-In-Time （JIT），以改善啟動效能。

為應用程式新增容器協調器支援

Visual Studio 2017 版本 15.7 或更早的版本支援將 Docker Compose 作為唯一的容器協調流程解決方案。透過 [新增]>[Docker 支援] 可新增 Docker Compose 成品。

Visual Studio 2017 版本 15.8 或更新版本只有在指示進行時，才會新增協調流程解決方案。以滑鼠右鍵按一下方案總管中的專案，然後選取 [新增]>[容器協調器支援]。可用的選項如下：

Docker Compose (英文)
Service Fabric
Kubernetes/Helm

Docker Compose (英文)

Visual Studio 容器工具會將 docker-compose 專案新增至包含下列檔案的解決方案：

docker-compose.dcproj：代表專案的檔案。包含 <DockerTargetOS> 項目，指定要使用的 OS。
.dockerignore：列出在產生組建內容時，要排除的檔案與目錄模式。
docker-compose.yml：基礎 Docker Compose 檔案，用於定義分別使用 docker-compose build 和 docker-compose run 建置並執行的映像集合。
docker-compose.override.yml：Docker Compose 將會讀取的選擇性檔案，包含服務的組態覆寫。 Visual Studio 會執行 docker-compose -f "docker-compose.yml" -f "docker-compose.override.yml" 來合併這些檔案。

docker-compose.yml 檔案會參考執行專案時所建立映像的名稱：

version: '3.4'

services:
  hellodockertools:
    image: ${DOCKER_REGISTRY}hellodockertools
    build:
      context: .
      dockerfile: HelloDockerTools/Dockerfile

在上述範例中，image: hellodockertools 會在以偵錯模式執行應用程式時產生 hellodockertools:dev 映像。以發行模式執行應用程式時，會產生 hellodockertools:latest 映像。

如果映像會推送至登錄，會在映像名稱前加上 Docker Hub 使用者名稱 (例如，dockerhubusername/hellodockertools)。或者，根據設定將映像名稱變更為包含私人登錄 URL (例如，privateregistry.domain.com/hellodockertools)。

如果您需要基於組建設定的不同行為 (例如偵錯或發行)，請新增特定於設定的 docker-compose 檔案。應根據組建設定來命名檔案 (例如 docker-compose.vs.debug.yml 和 docker-compose.vs.release.yml) 並放在與 docker-compose-override.yml 檔案相同的位置。

使用特定於設定的覆寫檔案，可以為偵錯和發行組建設定指定不同的組態設定 (例如環境變數或進入點)。

若要讓 Docker Compose 顯示要在 Visual Studio 中執行的選項，Docker 專案必須是啟始專案。

Service Fabric

除了基礎必要條件之外，Service Fabric 協調流程解決方案還需要下列必要條件：

Microsoft Azure Service Fabric SDK 版本 2.6 或更新版本
Visual Studio 的 Azure 開發工作負載

Service Fabric 不支援在 Windows 上的本機開發叢集中執行 Linux 容器。如果專案已在使用 Linux 容器，Visual Studio 會提示您切換至 Windows 容器。

Visual Studio 容器工具會執行下列工作：

將 <project_name>應用程式Service Fabric 應用程式專案，新增至解決方案。

將 Dockerfile 與 .dockerignore 檔案，新增至 ASP.NET Core 專案。如果 ASP.NET Core 專案中已存在 Dockerfile，則會重新命名為 Dockerfile.original。會建立類似如下的新 Dockerfile：

# See https://aka.ms/containerimagehelp for information on how to use Windows Server 1709 containers with Service Fabric.
# FROM microsoft/aspnetcore:2.0-nanoserver-1709
FROM microsoft/aspnetcore:2.0-nanoserver-sac2016
ARG source
WORKDIR /app
COPY ${source:-obj/Docker/publish} .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

將 <IsServiceFabricServiceProject> 元素新增至 ASP.NET Core 專案的 .csproj 檔案：
```
<IsServiceFabricServiceProject>True</IsServiceFabricServiceProject>
```
會將 PackageRoot 資料夾新增至 ASP.NET Core 專案。該資料夾包含服務資訊清單與新服務的設定。

如需詳細資訊，請參閱將 Windows 容器中的 .NET 應用程式部署至 Azure Service Fabric。

偵錯

從工具列的偵錯下拉式清單中選取 [Docker]，然後開始對應用程式進行偵錯。 [輸出] 視窗的 Docker 檢視會顯示下列將採取的動作：

取得 microsoft/dotnet 執行階段映像的 2.1-aspnetcore-runtime 標籤 (若尚未存在於快取中)。映像會安裝 ASP.NET Core 與 .NET Core 執行階段，以及相關聯的程式庫。在生產環境中最好是執行 ASP.NET Core 應用程式。
在容器內，ASPNETCORE_ENVIRONMENT 環境變數設定為 Development。
會提供兩個動態指派的連接埠：一個用於 HTTP，另一個用於 HTTPS。可使用 docker ps 命令，查詢指派到 localhost 的連接埠。
應用程式會複製至容器。
預設瀏覽器會在偵錯工具使用動態指派的連接埠附加至容器的情況下啟動。

產生的應用程式 Docker 映像，會標記為 dev。此映像以 microsoft/dotnet 基底映像的 2.1-aspnetcore-runtime 標籤為基礎。在 [套件管理員主控台] (PMC) 視窗中，執行 docker images 命令。這會顯示電腦上的映像：

REPOSITORY        TAG                     IMAGE ID      CREATED         SIZE
hellodockertools  dev                     d72ce0f1dfe7  30 seconds ago  255MB
microsoft/dotnet  2.1-aspnetcore-runtime  fcc3887985bb  6 days ago      255MB

取得 microsoft/aspnetcore 執行階段映像 (若尚未存在於快取中)。
在容器內，ASPNETCORE_ENVIRONMENT 環境變數設定為 Development。
連接埠 80 會公開並對應至本機主機的動態指派連接埠。連接埠是由 Docker 主機所決定，並且可以使用 docker ps 命令進行查詢。
應用程式會複製至容器。
預設瀏覽器會在偵錯工具使用動態指派的連接埠附加至容器的情況下啟動。

產生的應用程式 Docker 映像，會標記為 dev。映像以 microsoft/aspnetcore 基底映像為基礎。在 [套件管理員主控台] (PMC) 視窗中，執行 docker images 命令。這會顯示電腦上的映像：

REPOSITORY            TAG  IMAGE ID      CREATED        SIZE
hellodockertools      dev  5fafe5d1ad5b  4 minutes ago  347MB
microsoft/aspnetcore  2.0  c69d39472da9  13 days ago    347MB

注意

因為偵錯組態會使用磁碟區掛接來提供重複的體驗，所以 dev 映像不會有應用程式內容。若要推送映像，請使用 [發行] 組態。

在 PMC 中執行 docker ps 命令。請注意是使用容器來執行應用程式：

CONTAINER ID        IMAGE                  COMMAND                   CREATED             STATUS              PORTS                   NAMES
baf9a678c88d        hellodockertools:dev   "C:\\remote_debugge..."   21 seconds ago      Up 19 seconds       0.0.0.0:37630->80/tcp   dockercompose4642749010770307127_hellodockertools_1

編輯後繼續

針對靜態檔案和 Razor 檢視所做的變更會自動更新，而不需要執行編譯步驟。進行變更並儲存，然後重新整理瀏覽器來檢視更新。

程式碼檔案的修改需要編譯以及重新啟動容器內的 Kestrel。完成變更之後，請使用 CTRL+F5 來執行程序，並啟動容器內的應用程式。 Docker 容器不會進行重建或停止。在 PMC 中執行 docker ps 命令。請注意，原始容器在 10 分鐘前仍在執行：

CONTAINER ID        IMAGE                  COMMAND                   CREATED             STATUS              PORTS                   NAMES
baf9a678c88d        hellodockertools:dev   "C:\\remote_debugge..."   10 minutes ago      Up 10 minutes       0.0.0.0:37630->80/tcp   dockercompose4642749010770307127_hellodockertools_1

發行 Docker 映像

當應用程式的開發和偵錯循環完畢之後，Visual Studio 容器工具就會協助建立應用程式的實際執行映像。將組態下拉式清單變更為 [發行] 並建置應用程式。工具會從 Docker Hub (若尚未在快取中) 取得編譯/發行映像。映像會使用最新的標籤產生，其可推送至私人登錄或 Docker Hub。

在 PMC 中執行 docker images 命令，可查看映像清單。會顯示類似下列的輸出：

REPOSITORY        TAG                     IMAGE ID      CREATED             SIZE
hellodockertools  latest                  e3984a64230c  About a minute ago  258MB
hellodockertools  dev                     d72ce0f1dfe7  4 minutes ago       255MB
microsoft/dotnet  2.1-sdk                 9e243db15f91  6 days ago          1.7GB
microsoft/dotnet  2.1-aspnetcore-runtime  fcc3887985bb  6 days ago          255MB

REPOSITORY                  TAG     IMAGE ID      CREATED         SIZE
hellodockertools            latest  cd28f0d4abbd  12 seconds ago  349MB
hellodockertools            dev     5fafe5d1ad5b  23 minutes ago  347MB
microsoft/aspnetcore-build  2.0     7fed40fbb647  13 days ago     2.02GB
microsoft/aspnetcore        2.0     c69d39472da9  13 days ago     347MB

自 .NET Core 2.1 起，上述輸出中所列出的 microsoft/aspnetcore-build 和 microsoft/aspnetcore 映像，會取代為 microsoft/dotnet 映像。如需詳細資訊，請參閱 Docker 存放庫移轉公告。

注意

docker images 命令會傳回存放庫名稱和標記識別為 <無> (上面未列出) 的中繼映像。這些未命名映像是由多階段建置Dockerfile 所產生。這些中繼映像可以改善最終映像的建置效率；發生變更時只會重建必要層。當不再需要中繼映像時，請使用 docker rmi \(英文\) 命令予以刪除。

相較於 dev 映像，生產或發行映像的大小可能需要更小。基於磁碟區對應，偵錯工具和應用程式是從本機電腦執行，而不是在容器內執行。「最新」映像已封裝在主機上執行應用程式所需的應用程式碼。因此，差異是應用程式碼的大小。