containerize-aspnetcore

ASP.NET Core Docker 容器化提示詞

容器化需求

請依據下方設定檔中的指定內容，將 ASP.NET Core (.NET) 專案進行容器化，並專注於使應用程式能在 Linux Docker 容器中運作所需的變更。容器化過程應完整考量此處指定的所有設定。

請遵循 .NET Core 應用程式容器化的最佳實踐，確保容器在效能、安全性與可維護性上皆經過最佳化。

容器化設定

本區段包含容器化 ASP.NET Core 應用程式所需的具體設定與組態。執行此提示詞前，請先填入必要的資訊。請注意，在多數情況下僅需填寫前幾項主要設定；若後續設定不適用於當前專案，可直接保留為預設值。

任何未指定的設定均會採用預設值。預設值標示於[中括號]內。

專案基本資訊

1. 欲容器化的專案：

   • [專案名稱 (提供 .csproj 檔案的路徑)]

2. 使用的 .NET 版本：

   • [8.0 或 9.0 (預設 8.0)]

3. 使用的 Linux 發行版：

   • [debian, alpine, ubuntu, chiseled 或 Azure Linux (mariner) (預設 debian)]

4. Docker 映像檔建置階段 (build stage) 的自訂基礎映像檔 (填 "None" 則使用 Microsoft 標準基礎映像檔)：

   • [指定建置階段採用的基礎映像檔 (預設 None)]

5. Docker 映像檔執行階段 (run stage) 的自訂基礎映像檔 (填 "None" 則使用 Microsoft 標準基礎映像檔)：

   • [指定執行階段採用的基礎映像檔 (預設 None)]

容器組態

1. 容器映像檔需對外開放的連接埠 (Ports)：

   • 主要 HTTP 連接埠：[例如：8080]
   • 其他連接埠：[列出任何額外的連接埠，或填 "None"]

2. 容器運行時採用的使用者帳號：

   • [使用者帳號，或預設為 "$APP_UID"]

3. 應用程式 URL 設定：

   • [指定 ASPNETCORE_URLS，或預設為 "http://+:8080"]

建置組態

1. 建置容器映像檔前必須執行的自訂建置步驟：

   • [列出任何特定的建置步驟，或填 "None"]

2. 建置容器映像檔後必須執行的自訂建置步驟：

   • [列出任何特定的建置步驟，或填 "None"]

3. 必須設定的 NuGet 套件來源：

   • [列出任何包含驗證資訊的私有 NuGet Feed，或填 "None"]

相依性

1. 容器映像檔中必須安裝的系統套件：

   • [所選 Linux 發行版的套件名稱，或填 "None"]

2. 必須複製到容器映像檔的原生程式庫 (Native libraries)：

   • [程式庫名稱與路徑，或填 "None"]

3. 必須安裝的額外 .NET 工具：

   • [工具名稱與版本，或填 "None"]

系統組態

1. 容器映像檔中必須設定的環境變數：
   • [變數名稱與數值，或填 "Use defaults"]

檔案系統

1. 需要複製到容器映像檔的檔案/目錄：

   • [相對於專案根目錄的路徑，或填 "None"]
   • 容器內的目標位置：[容器路徑，或填 "Not applicable"]

2. 容器化時需要排除的檔案/目錄：

   • [欲排除的路徑，或填 "None"]

3. 應設定的 Volume 掛載點：

   • [用於持久化資料的 Volume 路徑，或填 "None"]

.dockerignore 組態

1. 應包含在 .dockerignore 檔案中的模式 (Patterns)（.dockerignore 已包含常見預設值，此處為額外模式）：
   • 額外模式：[列出任何額外的模式，或填 "None"]

健康檢查組態

1. 健康檢查端點 (Endpoint)：

   • [健康檢查的 URL 路徑，或填 "None"]

2. 健康檢查的時間間隔與超時時間 (Timeout)：

   • [時間間隔與超時數值，或填 "Use defaults"]

額外指令與說明

1. 容器化專案時必須遵循的其他說明：

   • [具體需求，或填 "None"]

2. 需要處理的已知問題：

   • [描述任何已知問題，或填 "None"]

適用範圍

• ✅ 修改應用程式設定，確保應用程式組態與資料庫連線字串 (Connection strings) 可從環境變數讀取
• ✅ 為 ASP.NET Core 應用程式建立與設定 Dockerfile
• ✅ 在 Dockerfile 中指定多個階段，用於建置/發行應用程式並將產出複製到最終映像檔
• ✅ 設定 Linux 容器平台的相容性 (Alpine, Ubuntu, Chiseled 或 Azure Linux (Mariner))
• ✅ 正確處理相依性 (系統套件、原生程式庫、額外工具)
• ❌ 不包含基礎設施架設 (預設另行處理)
• ❌ 不包含容器化所必需之外的任何程式碼修改

執行流程

1. 審視上方的容器化設定，了解相關的容器化需求
2. 建立 progress.md 檔案，透過勾選標記追蹤變更進度
3. 檢查專案的 .csproj 檔案中的 TargetFramework 元素，以確認 .NET 版本
4. 依據以下條件選擇適當的 Linux 容器映像檔：
   • 從專案檢測到的 .NET 版本
   • 在容器化設定中指定的 Linux 發行版 (Alpine, Ubuntu, Chiseled 或 Azure Linux (Mariner))
   • 若使用者未在容器化設定中要求特定的基礎映像檔，則基礎映像檔必須是有效的 mcr.microsoft.com/dotnet 映像檔，其 Tag 需如範例 Dockerfile 或官方文件所示
   • 用於建置與執行階段的 Microsoft 官方 .NET 映像檔：
     • SDK 映像檔 Tag (用於建置階段)：https://github.com/dotnet/dotnet-docker/blob/main/README.sdk.md
     • ASP.NET Core Runtime 映像檔 Tag：https://github.com/dotnet/dotnet-docker/blob/main/README.aspnet.md
     • .NET Runtime 映像檔 Tag：https://github.com/dotnet/dotnet-docker/blob/main/README.runtime.md
5. 在專案根目錄建立 Dockerfile 以進行應用程式容器化
   • Dockerfile 應採用多階段建置 (Multi-stage)：
     • 建置階段 (Build stage)：使用 .NET SDK 映像檔建置應用程式
       • 先複製 csproj 檔案
       • 若存在 NuGet.config 則一併複製，並設定任何私有 Feed
       • 還原 NuGet 套件
       • 接著複製其餘原始碼，並將應用程式建置發行至 /app/publish
     • 最終階段 (Final stage)：使用選定的 .NET Runtime 映像檔執行應用程式
       • 將工作目錄設為 /app
       • 按指示設定使用者 (預設為非 root 使用者，如 $APP_UID)
         • 除非容器化設定另有要求，否則不需要建立新使用者。請直接使用 $APP_UID 變數指定使用者帳號。
       • 將建置階段發行的產出複製到最終映像檔
   • 請務必考量容器化設定中的所有需求：
     • .NET 版本與 Linux 發行版
     • 開放的連接埠
     • 容器的使用者帳號
     • ASPNETCORE_URLS 設定
     • 系統套件安裝
     • 原生程式庫相依性
     • 額外 .NET 工具
     • 環境變數
     • 檔案/目錄複製
     • Volume 掛載點
     • 健康檢查組態
6. 在專案根目錄建立 .dockerignore 檔案，以排除不需要打包進 Docker 映像檔的檔案。.dockerignore 檔案必須至少包含下列項目以及容器化設定中所指定的額外模式：
   • bin/
   • obj/
   • .dockerignore
   • Dockerfile
   • .git/
   • .github/
   • .vs/
   • .vscode/
   • **/node_modules/
   • *.user
   • *.suo
   • **/.DS_Store
   • **/Thumbs.db
   • 容器化設定中所指定的任何額外模式
7. 若容器化設定中有指定，請設定健康檢查：
   • 若提供了健康檢查端點，請在 Dockerfile 中新增 HEALTHCHECK 指令
   • 使用 curl 或 wget 檢查健康檢查端點
8. 將任務標示為已完成：[ ] → [✓]
9. 持續執行直到所有任務完成且 Docker build 成功

建置與執行階段驗證

完成 Dockerfile 後，請確認 Docker build 能成功執行。使用下列命令建置 Docker 映像檔：

docker build -t aspnetcore-app:latest .

若建置失敗，請審視錯誤訊息並對 Dockerfile 或專案組態進行必要調整。請回報成功/失敗狀態。

進度追蹤

維護一個具備以下結構的 progress.md 檔案：

# 容器化進度

## 環境檢測
- [ ] .NET 版本檢測 (版本: ___)
- [ ] Linux 發行版選擇 (發行版: ___)

## 組態變更
- [ ] 應用程式組態驗證 (確認支援環境變數)
- [ ] NuGet 套件來源設定 (若適用)

## 容器化
- [ ] Dockerfile 建立
- [ ] .dockerignore 檔案建立
- [ ] 使用 SDK 映像檔建立建置階段 (Build stage)
- [ ] 複製 csproj 檔案以還原套件
- [ ] 複製 NuGet.config (若適用)
- [ ] 使用 Runtime 映像檔建立執行階段 (Runtime stage)
- [ ] 非 root 使用者設定
- [ ] 相依性處理 (系統套件、原生程式庫、工具等)
- [ ] 健康檢查設定 (若適用)
- [ ] 特殊需求實作

## 驗證
- [ ] 審視容器化設定並確認滿足所有需求
- [ ] Docker build 成功

步驟之間請勿停下來等待確認。請按部就班地持續推進，直到應用程式完成容器化且 Docker build 成功。

在所有核取方塊皆被勾選之前，任務並未完成！ 這包括成功建置 Docker 映像檔，並解決建置過程中出現的任何問題。

Dockerfile 範例

使用 Linux 基礎映像檔的 ASP.NET Core (.NET) 應用程式 Dockerfile 範例。

# ============================================================
# 階段 1：建置與發行應用程式
# ============================================================

# 基礎映像檔 - 選擇合適的 .NET SDK 版本與 Linux 發行版
# 可用的 Tag 包含：
# - 8.0-bookworm-slim (Debian 12)
# - 8.0-noble (Ubuntu 24.04)
# - 8.0-alpine (Alpine Linux)
# - 9.0-bookworm-slim (Debian 12)
# - 9.0-noble (Ubuntu 24.04)
# - 9.0-alpine (Alpine Linux)
# 使用 .NET SDK 映像檔來建置應用程式
FROM mcr.microsoft.com/dotnet/sdk:8.0-bookworm-slim AS build
ARG BUILD_CONFIGURATION=Release

WORKDIR /src

# 先複製專案檔以獲得更好的快取效果
COPY ["YourProject/YourProject.csproj", "YourProject/"]
COPY ["YourOtherProject/YourOtherProject.csproj", "YourOtherProject/"]

# 若存在 NuGet 設定檔則一併複製
COPY ["NuGet.config", "."]

# 還原 NuGet 套件
RUN dotnet restore "YourProject/YourProject.csproj"

# 複製原始碼
COPY . .

# 若有需要，在此處執行自訂的前置建置步驟
# RUN echo "Running pre-build steps..."

# 建置並發行應用程式
WORKDIR "/src/YourProject"
RUN dotnet build "YourProject.csproj" -c $BUILD_CONFIGURATION -o /app/build

# 發行應用程式
RUN dotnet publish "YourProject.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

# 若有需要，在此處執行自訂的後置建置步驟
# RUN echo "Running post-build steps..."

# ============================================================
# 階段 2：最終執行階段映像檔
# ============================================================

# 基礎映像檔 - 選擇合適的 .NET Runtime 版本與 Linux 發行版
# 可用的 Tag 包含：
# - 8.0-bookworm-slim (Debian 12)
# - 8.0-noble (Ubuntu 24.04)
# - 8.0-alpine (Alpine Linux)
# - 8.0-noble-chiseled (Ubuntu 24.04 Chiseled)
# - 8.0-azurelinux3.0 (Azure Linux)
# - 9.0-bookworm-slim (Debian 12)
# - 9.0-noble (Ubuntu 24.04)
# - 9.0-alpine (Alpine Linux)
# - 9.0-noble-chiseled (Ubuntu 24.04 Chiseled)
# - 9.0-azurelinux3.0 (Azure Linux)
# 使用 .NET Runtime 映像檔