針對 Azure App Service 設定 ASP.NET Core 應用程式

發行項
08/10/2024

注意

如需 .NET Framework 中的 ASP.NET 資訊，請參閱為 Azure App Service 設定 ASP.NET 應用程式。如果 ASP.NET Core 應用程式在自訂 Windows 或 Linux 容器中執行，請參閱設定 Azure App Service 的自訂容器。

ASP.NET Core 應用程式必須以編譯的二進位檔部署至 Azure App Service。 Visual Studio 發佈工具會組建解決方案，然後直接部署編譯的二進位檔，而 App Service 部署引擎會先部署程式碼存放庫，然後再編譯二進位檔。

本指南為 ASP.NET Core 開發人員提供重要概念和指示。如果您從未使用過 Azure App Service，請先遵循 ASP.NET Core 快速入門和搭配 SQL Database 的 ASP.NET Core 教學課程。

顯示支援的 .NET Core 執行階段版本

在 App Service 中，Windows 執行個體已安裝所有支援的 .NET Core 版本。若要顯示您可用的 .NET Core 執行階段和 SDK 版本，請在瀏覽器型主控台中瀏覽至 https://<app-name>.scm.azurewebsites.net/DebugConsole，並執行下列命令：

dotnet --info

顯示 .NET Core 版本

若要顯示目前的 .NET Core 版本，請在 Cloud Shell 中執行下列命令：

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

若要顯示所有支援的 .NET Core 版本，請在 Cloud Shell 中執行下列命令：

az webapp list-runtimes --os linux | grep DOTNET

設定 .NET Core 版本

在專案檔中設定您 ASP.NET Core 專案的目標框架。如需詳細資訊，請參閱 .NET Core 文件中的選取要使用的 .NET Core 版本。

在 Cloud Shell 中執行下列命令，將 .NET Core 版本設定為 8.0：

az webapp config set --name <app-name> --resource-group <resource-group-name> --linux-fx-version "DOTNETCORE|8.0"

自訂組建自動化

注意

尚不支援使用 MSBuild 或SCM_DO_BUILD，使用 Windows App Service 建置 .NET 9 （STS）應用程式。這些組建案例的支援將會在初始 GA 日期之後，以及到 2024 年 12 月 4 日為止。完全支援透過Visual Studio、Visual Studio Code、GitHub Actions 和 Azure DevOps 建置 App Service 外部的部署。

如果您使用 Git 或已啟用組建自動化的 ZIP 封裝來部署應用程式，App Service 組建自動化會依下列順序逐步執行：

執行自訂指令碼 (如果 PRE_BUILD_SCRIPT_PATH 已指定)。
執行 dotnet restore 以還原 NuGet 相依性。
執行 dotnet publish 以建立適用於生產環境的二進位檔。
執行自訂指令碼 (如果 POST_BUILD_SCRIPT_PATH 已指定)。

PRE_BUILD_COMMAND 和 POST_BUILD_COMMAND 是預設為空值的環境變數。若要執行預先建置命令，請定義 PRE_BUILD_COMMAND。若要執行建置後命令，請定義 POST_BUILD_COMMAND。

下列範例會將兩個變數指定給一系列的命令 (以逗號分隔)。

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

若要了解其他可自訂組建自動化的環境變數，請參閱 Oryx 設定。

如需 App Service 如何在 Linux 中執行和建立 ASP.NET Core 應用程式的詳細資訊，請參閱 Oryx 文件：如何偵測和建立 .NET Core 應用程式。

存取環境變數

在 App Service 中，您可以於應用程式的程式碼外部設定應用程式設定。然後，您可以使用標準 ASP.NET Core 相依性插入模式，在任何類別中存取這些設定：

using Microsoft.Extensions.Configuration;

namespace SomeNamespace 
{
    public class SomeClass
    {
        private IConfiguration _configuration;
    
        public SomeClass(IConfiguration configuration)
        {
            _configuration = configuration;
        }
    
        public SomeMethod()
        {
            // retrieve nested App Service app setting
            var myHierarchicalConfig = _configuration["My:Hierarchical:Config:Data"];
            // retrieve App Service connection string
            var myConnString = _configuration.GetConnectionString("MyDbConnection");
        }
    }
}

例如，如果您在 App Service 和 appsettings.json 中設定具有相同名稱的應用程式設定，則 App Service 值會優先於 appsettings.json 值。本機 appsettings.json 值可讓您在本機位置對應用程式進行偵錯，但 App Service 值可讓您使用生產設定在生產環境中執行應用程式。連接字串的運作方式與其相同。如此一來，您就可以在程式碼存放庫之外的位置保留應用程式秘密，並存取適當的值，而不需變更您的程式碼。

注意

請考慮更安全的連線選項，完全不需要連線秘密。如需詳細資訊，請參閱從 Azure App 服務保護 Azure 服務和資料庫的連線。

注意

請注意，appsettings.json中的階層式設定資料是使用 __ (雙底線) 分隔符號進行存取，這是 Linux 上的 .NET Core 標準。若要覆寫 App Service 中的特定階層式設定資料，請在索引鍵中設定使用相同分隔格式的應用程式設定名稱。您可以在 Cloud Shell 中執行下列範例：

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings My__Hierarchical__Config__Data="some value"

注意

請注意，appsettings.json中的階層式設定資料是使用 : 分隔符號進行存取，這是 .NET Core 標準。若要覆寫 App Service 中的特定階層式設定資料，請在索引鍵中設定使用相同分隔格式的應用程式設定名稱。您可以在 Cloud Shell 中執行下列範例：

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings My:Hierarchical:Config:Data="some value"

部署多專案解決方案

當 Visual Studio 解決方案包含多個專案時，Visual Studio 的發佈流程已經包含選取要部署的專案。當您部署至 App Service 部署引擎時 (例如 Git，或使用已啟用組建自動化的 ZIP 部署)，App Service 部署引擎會挑選其發現的第一個網站或 Web 應用程式當作 App Service應用程式。您可以藉由指定 PROJECT 應用程式設定來指定 App Service 應該使用的專案。例如，在 Cloud Shell 中執行下列命令：

az webapp config appsettings set --resource-group <resource-group-name> --name <app-name> --settings PROJECT="<project-name>/<project-name>.csproj"

存取診斷記錄

ASP.NET Core 提供適用於 App Service 的內建記錄提供者。在您專案的 Program.cs 中，透過 ConfigureLogging 擴充方法將提供者新增至您的應用程式，如以下範例所示：

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.AddAzureWebAppDiagnostics();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

然後您才能使用標準 .NET Core 模式設定和產生記錄。

若要存取 App Service 中應用程式程式碼內部產生的主控台記錄，請在 Cloud Shell 中執行下列命令，以開啟診斷記錄功能：

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

--level 的可能值為：Error、Warning、Info 和 Verbose。後續的每個層級都包含上一個層級。例如：Error 只包含錯誤訊息，而 Verbose 包含所有訊息。

開啟診斷記錄後，請執行下列命令來查看記錄資料流：

az webapp log tail --resource-group <resource-group-name> --name <app-name>

如果您沒有立即看到主控台記錄，請在 30 秒後再查看。

注意

您也可以在瀏覽器中的 https://<app-name>.scm.azurewebsites.net/api/logs/docker 檢查記錄檔。

若要隨時停止記錄資料流，請輸入 Ctrl+C。

如需在 App Service 中針對 ASP.NET Core 應用程式進行疑難排解的詳細資訊，請參閱針對 Azure App Service 和 IIS 上的 ASP.NET Core 進行疑難排解

取得詳細的例外狀況頁面

當您的 ASP.NET Core 應用程式在 Visual Studio 調試程式中產生例外狀況時，瀏覽器會顯示詳細的例外狀況頁面，但在 App Service 中，頁面會取代為一般 HTTP 500 或處理您的要求時發生錯誤。若要在 App Service 中顯示詳細的例外狀況頁面，請在 Cloud Shell 中執行下列命令，將應用程式設定新增ASPNETCORE_ENVIRONMENT至您的應用程式。

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings ASPNETCORE_ENVIRONMENT="Development"

偵測 HTTPS 工作階段

在 App Service 中，TLS/SSL 終止發生在網路負載平衡器上，因此，所有 HTTPS 要求都以未加密的 HTTP 要求的形式到達應用程式。如果您的應用程式邏輯必須知道是否已加密使用者要求，請在 Startup.cs 中設定轉送標頭中介軟體：

請使用 ForwardedHeadersOptions 來設定中介軟體以轉送 Startup.ConfigureServices 中的 X-Forwarded-For 和 X-Forwarded-Proto 標頭。
將私人 IP 位址範圍新增至已知網路，讓中介軟體可以信任 App Service 負載平衡器。
在呼叫其他中介軟體之前，先在 Startup.Configure 中叫用 UseForwardedHeaders 方法。

將這三個元素放在一起，您的程式碼看起來會像下列範例：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    services.Configure<ForwardedHeadersOptions>(options =>
    {
        options.ForwardedHeaders =
            ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
        // These three subnets encapsulate the applicable Azure subnets. At the moment, it's not possible to narrow it down further.
        options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("::ffff:10.0.0.0"), 104));
        options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("::ffff:192.168.0.0"), 112));
        options.KnownNetworks.Add(new IPNetwork(IPAddress.Parse("::ffff:172.16.0.0"), 108));
    });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseForwardedHeaders();

    ...

    app.UseMvc();
}

如需詳細資訊，請參閱設定 ASP.NET Core 以處理 Proxy 伺服器和負載平衡器。

重寫或重新導向 URL

若要重寫或重新導向 URL，請使用 ASP.NET Core 中的 URL 重寫中間件。

在瀏覽器中開啟 SSH 工作階段

若要透過容器直接開啟 SSH 工作階段，您的應用程式應在執行中。

在瀏覽器中貼入下列 URL，並以您的應用程式名稱取代 <app-name>：

https://<app-name>.scm.azurewebsites.net/webssh/host

如果您尚未經過驗證，必須向您的 Azure 訂用帳戶進行驗證才能連線。驗證之後，您會看到瀏覽器中的殼層，您可以在其中執行您容器內的命令。

SSH 連線

注意

您在 /home 目錄以外進行的任何變更都會儲存在容器中，在應用程式重新啟動之後便不會保存。

若要從本機電腦開啟遠端 SSH 工作階段，請參閱從遠端殼層開啟 SSH 工作階段。

記錄中的 robots933456

您可能會在容器記錄中看到下列訊息：

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

您可以放心忽略這個訊息。 /robots933456.txt 是一個虛擬 URL 路徑，App Service 會使用該路徑來檢查容器是否可以處理要求。 404 回應只是指出路徑不存在，但其可讓 App Service 知道容器狀況良好，並已準備好回應要求。

下一步

教學課程：搭配 SQL 資料庫一起使用 ASP.NET Core 應用程式

App Service Linux 常見問題集

或者，參閱其他資源：

環境變數與應用程式設定參考

共用方式為