前言：

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

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

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

 項目配置

本篇內(nèi)容簡介： Configuration 在開發(fā)過程中至關(guān)重要，我們首先需要了解如何配置我們的應(yīng)用程序。在之前的 .NET Framework 項目中，我們一般是通過 web.config 文件來完成對應(yīng)用程序的配置，而在 .NET Core 中，我們不再使用該文件，而是使用 .NET Core 內(nèi)置的 Configuration 框架。本文將介紹 Startup 類中的配置方法以及如何通過這些方法來設(shè)置應(yīng)用程序。除此之外，還將介紹如何注冊服務(wù)以及如何通過擴展方法來實現(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 應(yīng)用程序的啟動行為，可以看到，它包含了 IIS 和自托管應(yīng)用（ self-hosted ） Kestrel 的啟動設(shè)置的相關(guān)配置。

{
  "$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 （以后會介紹）來調(diào)用并查看 API 的輸出。而為了阻止應(yīng)用程序啟動時自動打開瀏覽器，需要將 launchBrowser 屬性值設(shè)置為 false ：

"launchBrowser": false


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

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

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

3. Program.cs 和 Startup.cs

ASP.NET Core 應(yīng)用程序本質(zhì)是一個控制臺應(yīng)用程序，它通過創(chuàng)建 web 服務(wù)器來托管應(yīng)用程序并監(jiān)聽傳入的HTTP請求，然后返回響應(yīng)，所以程序的入口還是 Program 類的 Main() 方法，ASP.NET Core Web API 應(yīng)用程序中的 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>();
            });
}

關(guān)于 Host 的啟動過程，可以參考：以后補充。

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

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

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() 方法用于配置應(yīng)用程序使用的服務(wù)，而服務(wù)就是為應(yīng)用程序添加功能的一些可重用的代碼。在 Configure() 方法中將會向應(yīng)用程序的請求管道添加不同的中間件。

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

4. 擴展方法和 CORS 配置

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

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

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

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

public static class ServiceExtensions
{

}

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

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

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

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

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

5. IIS 配置

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

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

    });

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

至此，我們已經(jīng)編寫了用于支持 CORS 和 IIS 集成的擴展方法，接下來就在 Startup 類中進行調(diào)用，注意引用命名空間 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() 方法中添加一系列代碼來說，使用擴展方法后可以使代碼更簡潔，可讀性更高。另外擴展方法的命名要盡可能準確、明了。

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

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

6. Startup 類中的其它代碼

ConfigureServices() 方法中，

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

Configure() 方法：

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

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

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

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

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

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

為了設(shè)置應(yīng)用程序運行時的環(huán)境，我們需要設(shè)置 ASPNETCORE_ENVIRONMENT 環(huán)境變量。例如，如果想讓應(yīng)用程序運行在生產(chǎ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 應(yīng)用程序通過上述環(huán)境變量的值來決定使用哪個 appsettings.json 文件，例如在生產(chǎn)環(huán)境中，將會使用 appsettings.Production.json 文件。默認情況下 ASPNETCORE_ENVIRONMENT 變量的值是 Development ，打開 launchSettings.json 文件可以看到：

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

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

最新評論