前言：

本系列文章主要參考了《Ultimate ASP.NET Core 3 Web API》一書，對原文進行了翻譯，同時適當刪減、修改了一部分內容。

對于某些概念和原理，原書和本文中都沒有進行詳細描述，如果一一詳細介紹，內容就顯得臃腫且混亂，我個人是先對原書進行了通讀，理解主要內容，然后再具體搜索了解其中不明白或者感興趣的概念和知識點。

由于我的技術水平和英文水平都有限，且主要是為了方便以后自己查看回顧，所以有錯誤之處，還請各位批評指正。

 項目配置

本篇內容簡介： Configuration 在開發(fā)過程中至關重要，我們首先需要了解如何配置我們的應用程序。在之前的 .NET Framework 項目中，我們一般是通過 web.config 文件來完成對應用程序的配置，而在 .NET Core 中，我們不再使用該文件，而是使用 .NET Core 內置的 Configuration 框架。本文將介紹 Startup 類中的配置方法以及如何通過這些方法來設置應用程序。除此之外，還將介紹如何注冊服務以及如何通過擴展方法來實現(xiàn)注冊。

1. 創(chuàng)建新項目

打開 Visual Studio 2019，點擊 Create a new project ，然后選擇 ASP.NET Core Web API ：

填寫項目名稱并選擇項目路徑：

然后選擇目標框架，并點擊 Create ：

2. launchSettings.json 文件

項目創(chuàng)建成功后，在解決方案的 Properties 節(jié)點下可以看到 launchSettings.json 文件：

這個文件決定了 ASP.NET Core 應用程序的啟動行為，可以看到，它包含了 IIS 和自托管應用（ self-hosted ） Kestrel 的啟動設置的相關配置。

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59126",
      "sslPort": 44389
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "weatherforecast",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "CompanyEmployees": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "weatherforecast",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

由于我們開發(fā)的是 Web API 項目，因此我們并不需要使用瀏覽器像查看 Web 項目一樣來查看 API，我們之后會通過 Postman （以后會介紹）來調用并查看 API 的輸出。而為了阻止應用程序啟動時自動打開瀏覽器，需要將 launchBrowser 屬性值設置為 false ：

"launchBrowser": false


在創(chuàng)建項目時，如果勾選了 Configure for HTTPS 的復選框，那么在 applicationUrl 節(jié)點中就會有兩個 URL，一個用于 HTTP，另一個用于 HTTPS。

注意：此 HTTPS 配置項盡在本地環(huán)境中有效，當應用程序正式部署后，必需配置真實有效的證書。

在本地開發(fā)應用程序時，還有一個很重要的屬性： launchUrl ，該屬性定義了應用程序啟動時默認導航到的 URL。如果要讓該屬性生效，就需要將 launchBrowser 屬性值設置為 true 。

3. Program.cs 和 Startup.cs

ASP.NET Core 應用程序本質是一個控制臺應用程序，它通過創(chuàng)建 web 服務器來托管應用程序并監(jiān)聽傳入的HTTP請求，然后返回響應，所以程序的入口還是 Program 類的 Main() 方法，ASP.NET Core Web API 應用程序中的 Program 如下：

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

關于 Host 的啟動過程，可以參考：以后補充。

CreateDefaultBuilder(args) 方法設置項目的默認配置文件和變量，以及日志提供程序。在應用啟動過程的早期配置好日志提供程序意味著可以使用日志記錄發(fā)生在啟動過程中的問題。

之后，調用 webBuilder.UseStartup<Startup>() 方法來初始化 Startup 類， Startup 類在 ASP.NET Core Web API 項目中是強制要求的類，需要在該類中配置應用程序需要的嵌入式或者自定義的服務，代碼如下：

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

其中，正如方法名字所示， ConfigureServices() 方法用于配置應用程序使用的服務，而服務就是為應用程序添加功能的一些可重用的代碼。在 Configure() 方法中將會向應用程序的請求管道添加不同的中間件。

由于較大的應用程序可能包含許多不同的服務，因此在 ConfigureServices() 方法中可能會出現(xiàn)大量的代碼，這樣會導致代碼看起來混亂臃腫、可讀性差。為了提高代碼可讀性，我們可以將添加服務的代碼分離成一個個的擴展方法。

4. 擴展方法和 CORS 配置

擴展方法本質上是一種靜態(tài)方法。它與其他靜態(tài)方法的不同之處在于，它接受 this 作為第一個參數(shù)， this 表示使用該擴展方法的對象的數(shù)據(jù)類型。

擴展方法必需定義在靜態(tài)類中，它擴展了.NET 中類型的行為。一旦定義了擴展方法，就可以在同一類型的對象上多次鏈式調用它。

接下來開始寫代碼，首先在項目中創(chuàng)建一個新的文件夾： Extensions

然后在該文件夾中創(chuàng)建一個類： ServiceExtensions ，并將這個類改為靜態(tài)類，代碼如下：

public static class ServiceExtensions
{

}

接下來就開始實現(xiàn)一個具體的功能，這樣就能看到應該如何使用靜態(tài)類。我們要做的第一件事就是在應用程序中配置 CORS。CORS ( Cross-Origin Resource Sharing，跨資源共享 ) 是一種向來自不同域的應用程序授予或者限制訪問權限的機制。

如果我們想從不同的域向應用程序發(fā)送請求，那就必須配置 CORS。所以接下來就在 ServiceExtensions 類中添加一個擴展方法來允許將來自所有域的所有請求發(fā)送到我們的 API：

public static void ConfigureCors(this IServiceCollection services) =>
    services.AddCors(options =>
    {
        options.AddPolicy("CorsPolicy", builder =>
        {
            builder.AllowAnyOrigin()
            .AllowAnyMethod()
            .AllowAnyHeader();
        });
    });

我們這里暫時使用基本的 CORS 策略設置，因為目前來說允許所有來源 ( origin )、所有類型的方法、所有 header 是可以接受的。但是如果是生產環(huán)境，那我們應該盡可能的將策略設置的更嚴格。

當有需要的時候，我們可以使用 WithOrigins("https://example.com") 方法來限制請求只能來自某個具體源，而不是使用 AllowAnyOrigin() 方法允許來自所有源的請求。同樣，可以使用 WithMethods("POST","GET") 方法來限制請求只能是特定的 HTTP 方法，而不是使用 AllowAnyMethods() 方法允許所有類型的 HTTP 方法。另外，可以使用 WithHeaders("accept","content-type") 方法來限制請求包含特定的 headers。

5. IIS 配置

ASP.NET Core 應用默認是自托管（self hosted），當然我們也可以通過配置 IIS 集成來幫助我們將應用使用 IIS 托管，可以通過添加以下擴展方法來實現(xiàn)：

public static void ConfigureIISIntegration(this IServiceCollection services) =>
    services.Configure<IISOptions>(options =>
    {

    });

目前我們使用默認配置就可以，所以在上述代碼中沒有初始化 options 的任何屬性。如果想修改某些配置，可以參考 官方文檔 ：

至此，我們已經編寫了用于支持 CORS 和 IIS 集成的擴展方法，接下來就在 Startup 類中進行調用，注意引用命名空間 using CompanyEmployees.Extensions ， ConfigureService() 代碼如下：

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    //custom extension methods
    services.ConfigureCors();
    services.ConfigureIISIntegration();
    
    services.AddControllers();
}

對于直接在 ConfigureServices() 方法中添加一系列代碼來說，使用擴展方法后可以使代碼更簡潔，可讀性更高。另外擴展方法的命名要盡可能準確、明了。

我們已經成功的將 CORS 和 IIS 配置添加到應用程序的服務容器中，但是還沒有真正用到這些服務，所以還需要在 Configure() 方法中添加一些使用服務的代碼：

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    //custom pipeline start
    app.UseStaticFiles();

    app.UseCors("CorsPolicy");

    app.UseForwardedHeaders(new ForwardedHeadersOptions
    {
        ForwardedHeaders = ForwardedHeaders.All
    });
    //custom pipeline end

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

其中，

• UseForwardedHeaders() ：將轉發(fā)的 header 應用于當前請求上的匹配的字段。按照約定， HTTP 代理以眾所周知的 HTTP header 從客戶端轉發(fā)消息。該中間件讀取這些 header 并填充 HttpContext 上的相關字段。
• UseStaticFiles() ：對當前請求的路徑啟用靜態(tài)文件服務，意思就是可以通過路徑訪問當前目錄的文件。如果沒有設置靜態(tài)文件目錄的路徑，則默認使用 wwwroot 目錄。
• UseCors() ：將 CORS 中間件添加到應用程序的請求管道中以允許跨域請求。

6. Startup 類中的其它代碼

ConfigureServices() 方法中，

AddControllers() ：將控制器的服務添加到服務集合中。 AddMvc() 方法也可以將控制器添加到服務集合中，但它除了控制器外，還會將視圖和頁面添加到服務集合中。我們的項目是 Web API 項目，所以只需要控制器就可以。

Configure() 方法：

• UseRouting() ：將路由中間件添加到請求管道中。
• UseAuthorization() ：將授權中間件添加到請求管道中。
• UseEndpoints() ：為控制器的 Action 添加終結點并將終結點添加路由中。

7. 基于環(huán)境的設置

在開發(fā)應用程序時，我們使用 開發(fā) (development) 環(huán)境，當我們發(fā)布了應用程序之后就需要使用 生產 (production) 環(huán)境。開發(fā)環(huán)境和生產環(huán)境對應不同的 URLs、端口、連接字符串、密碼等其它敏感信息。所以我們需要根據(jù)環(huán)境來區(qū)分配置，這在 .NET Core 中是很容易實現(xiàn)的。

當我們創(chuàng)建一個項目后，可以在項目的根目錄中看到 appsettings.json 文件，這就我們主要的配置文件，點擊文件前面的箭頭可以看到一個 appsettings.Development.json 文件。如果在系統(tǒng)的文件資源管理器中打開項目目錄，可以看到這是兩個不同的文件，但是在 Visual Studio 中，這兩個配置文件被關聯(lián)在了一起。

appsettings.{EnvironmentSuffix}.json 是用于特定環(huán)境時的配置文件，可以覆蓋 appsettings.json 文件中的配置。如果 appsettings.{EnvironmentSuffix}.json 文件中存在與 appsettings.json 文件同名的鍵值對，則會覆蓋鍵值對的值。另外我們還可以自定義特定的環(huán)境，例如，對于生產環(huán)境，我們可以添加另一個文件： appsettings.Production.json ：

appsettings.Production.json 文件中應該包含用于生產環(huán)境的配置項。

為了設置應用程序運行時的環(huán)境，我們需要設置 ASPNETCORE_ENVIRONMENT 環(huán)境變量。例如，如果想讓應用程序運行在生產環(huán)境中，就需要在部署的機器上將上述環(huán)境變量的值修改為 Production 。在 Windows 環(huán)境中，可以通過輸入命令： set ASPNETCORE_ENVIRONMENT=Production 來實現(xiàn)。在 Linux 環(huán)境中，可以通過輸入命令： export ASPNET_CORE_ENVIRONMENT=Production 來實現(xiàn)。

ASP.NET Core 應用程序通過上述環(huán)境變量的值來決定使用哪個 appsettings.json 文件，例如在生產環(huán)境中，將會使用 appsettings.Production.json 文件。默認情況下 ASPNETCORE_ENVIRONMENT 變量的值是 Development ，打開 launchSettings.json 文件可以看到：

對于應用程序開發(fā)來說，日志記錄是非常重要的一項功能，無論是在開發(fā)中、還是部署后的使用中，日志都會幫助我們發(fā)現(xiàn)、記錄問題，我們可以根據(jù)日志來定位、復現(xiàn)并修復問題，所以盡可能的早的將日志服務添加到應用程序中是很有必要的，

到此這篇關于ASP.NET Core Web API 教程Project Configuration的文章就介紹到這了,更多相關ASP.NET Core Web API 教程內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論