快速入門:使用 Azure 應用程式設定建立 ASP.NET Core 應用程式Quickstart: Create an ASP.NET Core app with Azure App Configuration

在本快速入門中,您將使用 Azure 應用程式組態,集中儲存和管理 ASP.NET Core 應用程式的應用程式設定。In this quickstart, you'll use Azure App Configuration to centralize storage and management of application settings for an ASP.NET Core app. ASP.NET Core 會使用應用程式所指定一或多個資料來源中的設定,來建置一個以索引鍵/值為基礎的組態物件。ASP.NET Core builds a single, key-value-based configuration object using settings from one or more data sources specified by an app. 這些資料來源稱為「設定提供者」 。These data sources are known as configuration providers. 因為應用程式組態的 .NET Core 用戶端會實作為組態提供者,服務看來就像其他資料來源。Because App Configuration's .NET Core client is implemented as a configuration provider, the service appears like another data source.

PrerequisitesPrerequisites

提示

Azure Cloud Shell 是免費的互動式 Shell,可讓您用來執行本文中的命令列指令。The Azure Cloud Shell is a free, interactive shell that you can use to run the command line instructions in this article. 其中已預先安裝常用的 Azure 工具,包括 .NET Core SDK。It has common Azure tools preinstalled, including the .NET Core SDK. 如果您已登入 Azure 訂用帳戶,請從 shell.azure.com 啟動您的 Azure Cloud ShellIf you're logged in to your Azure subscription, launch your Azure Cloud Shell from shell.azure.com. 您可以閱讀我們的文件,以深入了解 Azure Cloud ShellYou can learn more about Azure Cloud Shell by reading our documentation

建立應用程式組態存放區Create an App Configuration store

  1. 若要建立新的應用程式組態存放區,請登入 Azure 入口網站To create a new App Configuration store, sign in to the Azure portal. 在首頁的左上角,選取 [建立資源] 。In the upper-left corner of the home page, select Create a resource. 在 [搜尋 Marketplace] 方塊中輸入應用程式組態,然後選取 Enter 鍵。In the Search the Marketplace box, enter App Configuration and select Enter.

    搜尋應用程式設定

  2. 從搜尋結果中選取 [應用程式設定] ,然後選取 [建立] 。Select App Configuration from the search results, and then select Create.

    選取 [建立]

  3. 在 [建立應用程式組態] 窗格上,輸入下列設定:On the Create App Configuration pane, enter the following settings:

    設定Setting 建議的值Suggested value 描述Description
    訂用帳戶Subscription 您的訂用帳戶Your subscription 選取您要用來測試應用程式設定的 Azure 訂用帳戶。Select the Azure subscription that you want to use to test App Configuration. 如果您的帳戶僅有一個訂用帳戶,則會自動加以選取,而且不會顯示 [訂用帳戶]**** 清單。If your account has only one subscription, it's automatically selected and the Subscription list isn't displayed.
    資源群組Resource group AppConfigTestResourcesAppConfigTestResources 為應用程式組態存放區資源選取或建立資源群組。Select or create a resource group for your App Configuration store resource. 此群組可用於組織多個資源,以便能夠藉由刪除資源群組來同時刪除多個資源。This group is useful for organizing multiple resources that you might want to delete at the same time by deleting the resource group. 如需詳細資訊,請參閱使用資源群組管理您的 Azure 資源For more information, see Use resource groups to manage your Azure resources.
    資源名稱Resource name 全域唯一的名稱Globally unique name 輸入要對應用程式組態存放區資源使用的唯一資源名稱。Enter a unique resource name to use for the App Configuration store resource. 名稱必須是介於 5 到 50 個字元的字串,且只能包含數字、字母和 - 字元。The name must be a string between 5 and 50 characters and contain only numbers, letters, and the - character. 名稱的開頭或結尾不可以是 - 字元。The name can't start or end with the - character.
    位置Location 美國中部Central US 使用 [位置] 來指定裝載應用程式設定存放區所在的地理位置。Use Location to specify the geographic location in which your app configuration store is hosted. 為了獲得最佳效能,請將資源建立在與應用程式其他元件相同的區域內。For the best performance, create the resource in the same region as other components of your application.
    定價層Pricing tier 免費Free 選取所需的定價層。Select the desired pricing tier. 如需詳細資訊,請參閱應用程式組態定價頁面For more information, see the App Configuration pricing page.
  4. 選取 [檢閱 + 建立] 以驗證您的設定。Select Review + create to validate your settings.

  5. 選取 [建立] 。Select Create. 部署可能需要幾分鐘的時間。The deployment might take a few minutes.

  6. 部署完成之後,瀏覽至應用程式組態資源。After the deployment finishes, navigate to the App Configuration resource. 選取 [設定] > [存取金鑰]。Select Settings > Access keys. 請記下連接字串的主要唯讀索引鍵。Make a note of the primary read-only key connection string. 稍後,您會使用此連接字串來設定您的應用程式,使其與您建立的應用程式組態存放區進行通訊。You'll use this connection string later to configure your application to communicate with the App Configuration store that you created.

  1. 選取 [作業] > [組態總管] > [建立] > [索引鍵/值] 以新增下列索引鍵/值組:Select Operations > Configuration explorer > Create > Key-value to add the following key-value pairs:

    KeyKey Value
    TestApp:Settings:BackgroundColor #FFF#FFF
    TestApp:Settings:FontColor #000#000
    TestApp:Settings:FontSize 2424
    TestApp:Settings:Message Azure 應用程式設定的值Data from Azure App Configuration

    目前先讓 [標籤] 和 [內容類型] 保持空白。Leave Label and Content type empty for now. 選取 [套用] 。Select Apply.

建立 ASP.NET Core Web 應用程式Create an ASP.NET Core web app

使用 .NET Core 命令列介面 (CLI) 建立新的 ASP.NET Core MVC 專案。Use the .NET Core command-line interface (CLI) to create a new ASP.NET Core MVC project. Azure Cloud Shell 會為您提供這些工具。The Azure Cloud Shell provides these tools for you. 也可以跨 Windows、macOS 及 Linux 平台使用這些工具。They're also available across the Windows, macOS, and Linux platforms.

執行下列命令,在新的 TestAppConfig 資料夾中建立 ASP.NET Core MVC Web 專案:Run the following command to create an ASP.NET Core MVC project in a new TestAppConfig folder:

dotnet new mvc --no-https --output TestAppConfig

新增祕密管理員Add Secret Manager

名為祕密管理員的工具能儲存專案樹狀結構外開發工作的敏感性資料。A tool called Secret Manager stores sensitive data for development work outside of your project tree. 此作法能協助避免於原始程式碼內意外共用應用程式祕密。This approach helps prevent the accidental sharing of app secrets within source code. 請完成下列步驟,以啟用在 ASP.NET Core 專案中使用秘密管理員:Complete the following steps to enable the use of Secret Manager in the ASP.NET Core project:

瀏覽至專案的根目錄,然後執行下列命令以啟用專案中的秘密儲存體:Navigate to the project's root directory, and run the following command to enable secrets storage in the project:

dotnet user-secrets init

包含 GUID 的 UserSecretsId 元素會新增至 .csproj 檔案:A UserSecretsId element containing a GUID is added to the .csproj file:

<Project Sdk="Microsoft.NET.Sdk.Web">
    
    <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
        <UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
    </PropertyGroup>

</Project>

提示

若要深入了解秘密管理員,請參閱在 ASP.NET Core 中的開發中安全儲存應用程式秘密To learn more about Secret Manager, see Safe storage of app secrets in development in ASP.NET Core.

連線至應用程式組態存放區Connect to the App Configuration store

  1. 執行下列命令,以新增 Microsoft.Azure.AppConfiguration.AspNetCore NuGet 套件參考:Run the following command to add a Microsoft.Azure.AppConfiguration.AspNetCore NuGet package reference:

    dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
    
  2. 在與 .csproj 檔案相同的目錄中執行下列命令。Run the following command in the same directory as the .csproj file. 此命令會使用秘密管理員來儲存名為 ConnectionStrings:AppConfig 的密碼,其中儲存應用程式組態存放區的連接字串。The command uses Secret Manager to store a secret named ConnectionStrings:AppConfig, which stores the connection string for your App Configuration store. <your_connection_string> 預留位置取代為應用程式組態存放區的連接字串。Replace the <your_connection_string> placeholder with your App Configuration store's connection string. 您可以在 Azure 入口網站中的 [存取金鑰] 下找到連接字串。You can find the connection string under Access Keys in the Azure portal.

    dotnet user-secrets set ConnectionStrings:AppConfig "<your_connection_string>"
    

    重要

    除非以引號括住連接字串,否則某些殼層會截斷連接字串。Some shells will truncate the connection string unless it's enclosed in quotes. 請確定 dotnet user-secrets 命令的輸出會顯示整個連接字串。Ensure that the output of the dotnet user-secrets command shows the entire connection string. 如果不是,請重新執行命令,並以引號括住連接字串。If it doesn't, rerun the command, enclosing the connection string in quotes.

    祕密管理員僅可用於在本機測試 Web 應用程式。Secret Manager is used only to test the web app locally. 當應用程式部署至 Azure App Service 時,請使用 App Service 中的連接字串應用程式設定 (而不是秘密管理員) 來儲存連接字串。When the app is deployed to Azure App Service, use the Connection Strings application setting in App Service instead of Secret Manager to store the connection string.

    使用 .NET Core 組態 API 來存取此秘密。Access this secret using the .NET Core Configuration API. 在所有支援的平台上,組態 API 的組態名稱中都適用冒號 (:)。A colon (:) works in the configuration name with the Configuration API on all supported platforms. 如需詳細資訊,請參閱組態金鑰和值For more information, see Configuration keys and values.

  3. 在 Program.cs 中,將參考新增至 .NET Core 組態 API 命名空間:In Program.cs, add a reference to the .NET Core Configuration API namespace:

    using Microsoft.Extensions.Configuration;
    
  4. 藉由呼叫 AddAzureAppConfiguration 方法將 CreateWebHostBuilder 方法更新為使用應用程式設定。Update the CreateWebHostBuilder method to use App Configuration by calling the AddAzureAppConfiguration method.

    重要

    CreateHostBuilder 會取代 .NET Core 3.x 中的 CreateWebHostBuilderCreateHostBuilder replaces CreateWebHostBuilder in .NET Core 3.x. 根據您的環境選取正確的語法。Select the correct syntax based on your environment.

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
                webBuilder.ConfigureAppConfiguration(config =>
                {
                    var settings = config.Build();
                    var connection = settings.GetConnectionString("AppConfig");
                    config.AddAzureAppConfiguration(connection);
                }).UseStartup<Startup>());
    

    透過先前的變更,應用程式組態的組態提供者已向 .NET Core 組態 API 註冊。With the preceding change, the configuration provider for App Configuration has been registered with the .NET Core Configuration API.

從應用程式組態存放區讀取Read from the App Configuration store

請完成下列步驟,以讀取和顯示在應用程式組態存放區中儲存的值。Complete the following steps to read and display values stored in the App Configuration store. .NET Core 組態 API 將用來存取存放區。The .NET Core Configuration API will be used to access the store. Razor 語法將用來顯示金鑰的值。Razor syntax will be used to display the keys' values.

開啟 <app root>/Views/Home/Index.cshtml,並將其內容取代為下列程式碼:Open <app root>/Views/Home/Index.cshtml, and replace its content with the following code:

@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<style>
    body {
        background-color: @Configuration["TestApp:Settings:BackgroundColor"]
    }
    h1 {
        color: @Configuration["TestApp:Settings:FontColor"];
        font-size: @Configuration["TestApp:Settings:FontSize"]px;
    }
</style>

<h1>@Configuration["TestApp:Settings:Message"]</h1>

在上述程式碼中,會使用應用程式組態存放區的金鑰,如下所示:In the preceding code, the App Configuration store's keys are used as follows:

  • TestApp:Settings:BackgroundColor 金鑰的值會指派給 CSS background-color 屬性。The TestApp:Settings:BackgroundColor key's value is assigned to the CSS background-color property.
  • TestApp:Settings:FontColor 金鑰的值會指派給 CSS color 屬性。The TestApp:Settings:FontColor key's value is assigned to the CSS color property.
  • TestApp:Settings:FontSize 金鑰的值會指派給 CSS font-size 屬性。The TestApp:Settings:FontSize key's value is assigned to the CSS font-size property.
  • TestApp:Settings:Message 金鑰的值會顯示為標題。The TestApp:Settings:Message key's value is displayed as a heading.

於本機建置並執行應用程式Build and run the app locally

  1. 若要使用 .NET Core CLI 來建置應用程式,請瀏覽至專案的根目錄。To build the app using the .NET Core CLI, navigate to the root directory of your project. 在命令殼層中執行下列命令:Run the following command in the command shell:

    dotnet build
    
  2. 成功完成建置後,請執行下列命令以在本機執行 Web 應用程式:After the build completes successfully, run the following command to run the web app locally:

    dotnet run
    
  3. 如果您是在本機電腦上工作,請使用瀏覽器瀏覽至 http://localhost:5000If you're working on your local machine, use a browser to navigate to http://localhost:5000. 此位址是本機裝載 Web 應用程式的預設 URL。This address is the default URL for the locally hosted web app. 如果您在 Azure Cloud Shell 中工作,請選取 [Web 預覽] 按鈕,然後選取 [設定] 。If you're working in the Azure Cloud Shell, select the Web Preview button followed by Configure.

    尋找 Web 預覽按鈕

    系統提示您設定預覽的連接埠時,請輸入 5000,並選取 [開啟並瀏覽]。When prompted to configure the port for preview, enter 5000 and select Open and browse. 網頁會顯示「Azure 應用程式組態中的值」。The web page will read "Data from Azure App Configuration."

清除資源Clean up resources

如果您不想繼續使用本文中建立的資源,請刪除在此處建立的資源群組,以避免產生費用。If you do not want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

重要

刪除資源群組是無法回復的動作。Deleting a resource group is irreversible. 資源群組和其中的所有資源都將被永久刪除。The resource group and all the resources in it are permanently deleted. 請確定您不會誤刪錯誤的資源群組或資源。Make sure that you don't accidentally delete the wrong resource group or resources. 如果您是在包含需保留其他資源的資源群組內部,建立本文的資源,則可以從每個資源各自的窗格中個別刪除每個資源,而不必刪除整個資源群組。If you created the resources for this article inside a resource group that contains other resources you want to keep, delete each resource individually from its respective pane instead of deleting the resource group.

  1. 登入 Azure 入口網站,然後選取 [資源群組]。Sign in to the Azure portal, and select Resource groups.
  2. 在 [依名稱篩選]**** 方塊中,輸入您資源群組的名稱。In the Filter by name box, enter the name of your resource group.
  3. 在結果清單中,選取資源群組名稱以查看概觀。In the result list, select the resource group name to see an overview.
  4. 選取 [刪除資源群組]。Select Delete resource group.
  5. 系統將會要求您確認是否刪除資源群組。You're asked to confirm the deletion of the resource group. 輸入您資源群組的名稱以進行確認,然後選取 [刪除] 。Enter the name of your resource group to confirm, and select Delete.

不久後,系統便會刪除該資源群組及其所有的資源。After a few moments, the resource group and all its resources are deleted.

後續步驟Next steps

在本快速入門中,您已:In this quickstart, you:

  • 已佈建新的應用程式組態存放區。Provisioned a new App Configuration store.
  • 已註冊應用程式組態存放區的 .NET Core 組態提供者。Registered the App Configuration store's .NET Core configuration provider.
  • 已使用組態提供者讀取應用程式組態存放區的金鑰。Read the App Configuration store's keys with the configuration provider.
  • 使用 Razor 語法顯示應用程式組態存放區的金鑰值。Displayed the App Configuration store's key values using Razor syntax.

若要了解如何將 ASP.NET Core 應用程式設定為以動態方式重新整理組態設定,請繼續進行下一個教學課程。To learn how to configure your ASP.NET Core app to dynamically refresh configuration settings, continue to the next tutorial.