ASP.NET Core中配置監聽URLs的五種方式

LamondLu發表於2020-04-18
ASP.NET

原文： 5 ways to set the URLs for an ASP.NET Core app
作者： Andrew Lock
譯者： Lamond Lu

預設情況下，ASP. NET Core應用會監聽一下2個Url:

在本篇博文中，我將展示如何使用五種不同的方式改變應用監聽的URLs。

在ASP.NET Core專案啟動時，有多種配置監聽Url的方式，在我之前的一篇部落格中，已經展示了在ASP.NET Core 1.0中如何應用不同的方式配置，在ASP.NET Core 3.x中，大部分方式還是一樣的。

  • UseUrls() - 在Program.cs配置程式監聽的URLs
  • 環境變數 - 使用DOTNET_URLS或者ASPNETCORE_URLS配置URLs
  • 命令列引數 - 當使用命令列啟動應用時，使用--urls引數指定URLs
  • 使用launchSettings.json - 使用applicationUrl屬性來配置URLs
  • KestrelServerOptions.Listen() - 使用Listen()方法手動配置Kestral伺服器監聽的地址

下面我來詳細說明一下每個一種方式。

哪些Url可以使用？

在本篇我描述是你可以繫結的"URLs", 但是你不能使用所有的URLs. 這裡有三種你可以繫結的URLs

  • IPV4和IPV6的主機名(例如http://localhost:5000). 這種URL的格式是{scheme}://{loopbackAddress}:{port}
  • 在你機器上可用的指定IP地址(例如http://192.168.8.31:5005), 這種URL的格式是{scheme}://{IPAddress}:{port}
  • 針對給定埠，使用"任何"IP地址（例如http://*:6264）, 這種URL的格式是{scheme}://*:{port}

在以上說明的幾種格式中，埠號也可以是選填的， 如果你忽略它，系統會使用預設埠(http使用80埠，https使用443埠)。

使用哪一種格式的URLs取決於你的部署方式。例如，如果你你將多個應用託管在同一臺“裸機”中，你可能需要顯示指定IP地址。但是如果你使用了容器託管，那麼你可以使用localhost作為地址。

注意，針對"任何"IP地址的格式 - 你不一定必須使用*，你可以使用任何字元，只要不是IP地址或者localhost, 這意味著你可以使用http://*, http://+, http://mydomain, http://example.org. 以上所有字串都具有相同的行為，可以監聽任何IP地址。如果你想僅處理來自單一主機名的請求，你需要額外配置主機過濾。

現在你已經瞭解了你需要監聽的URLs型別，接下來你就需要告訴你的應用如何使用它們。我這裡我將展示五種可能使用到方式。

UseUrls()

首先，最簡單的方式，當配置IWebHostBuilder時，你可以使用UseUrls()方法硬編碼繫結的URLs。

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>();
                webBuilder.UseUrls("http://localhost:5003", "https://localhost:5004");
            });
}

硬編碼一個URLs從來都不是一個乾淨可擴充套件解決方案的選擇，所以這種方式通常只會用來做Demo.

幸運的是，你也可以從外部配置檔案、環境變數或者命令列引數中載入URLs配置。

環境變數

.NET Core中允許使用兩種配置方式

  • 應用程式級配置是你通常在應用程式中使用的配置，它是用appSettings.json配置檔案和環境變數中載入的。
  • 主機配置用於配置應用程式的基礎配置，例如主機環境和主機URLs

當我們在考慮如何配置應用URLs時，主機配置是讓我們感興趣的一種。預設主機配置的值來自三個不同的地方。

  • 以DOTNET_開頭的環境變數。
  • 命令列引數
  • 以ASPNETCORE_開頭的環境變數。這種方式僅限ASP.NET Core應用，基於通用主機的worker service是不適用的。

如果你沒有手動複寫過UseUrls()方法，ASP.NET Core會使用系統配置的中URLS鍵的值。基於描述，你可以使用一下兩種方式配置URLs

  • DOTNET_URLS
  • ASPNETCORE_URLS

如果你同時使用2種環境變數，系統會優先使用ASPNETCORE_URLS中定義的引數

你可以根據你的開發環境使用一些通用方式配置環境變數。例如，使用命令列

setx ASPNETCORE_URLS "http://localhost:5001"

使用powershell

$Env: ASPNETCORE_URLS = "http://localhost:5001"

或者使用bash命令

export ASPNETCORE_URLS="http://localhost:5001;https://localhost:5002"

從以上例子中不難發現，如果想要配置多個地址，只需要用分號間隔即可。

命令列引數

另外一種設定主機配置的方式是使用命令列引數。如果同時配置了環境變數和命令列引數，命令列引數的值會覆蓋環境變數配置的值。這裡我們可以使用--urls引數來配置URLS

dotnet run --urls "http://localhost:5100"

和之前的例子一樣，這裡你可以使用分號間隔配置多個URLs

dotnet run --urls "http://localhost:5100;https://localhost:5101"

在生產環境中，配置URLS的最常用方式是使用環境變數或者命令列引數，但是在本地開發環境中，可能就有點笨重了，這時候使用launchSetting.json來配置URLS可能更簡單一點。

launchSettings.json

大部分.NET Core專案模板中都包含了一個名為launchSetting.json的檔案, 這個檔案通常放在Properties資料夾中。這個檔案中包含了啟動ASP.NET Core專案的各種配置。一個典型的launchSetting.json檔案中包含了兩部分定義，一部分是命令列啟動專案時的配置，一部分是使用IIS Express啟動專案時的配置。具體使用哪一部分是由Visual Studio中的"Debug"下拉選單控制的：

在launchSettings.json檔案中，我們使用applicationUrl屬性就可以配置應用繫結的URLs - 在如下的例子中，你可以看到在iisSettings節點下有一個配置，在TestApp節點下有一個配置。

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:38327",
      "sslPort": 44310
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "TestApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

你不需要特別指定使用這個檔案 - dotnet run命令會自動載入它。

launchSettings.json檔案中也提供了額外的環境變數配置引數environmentVariables，在上面的例子中你就可以發現它們。

當你從命令列使用dotnet run命令啟動你的應用時，你的應用會從"Project"命令下的applicationUrl引數中載入配置https://localhost:5001;http://localhost:5000，當你使用IISExpress命令啟動專案的時候，你的應用會從iisSettings.iisExpress節點的applicationUrl引數中載入配置http://localhost:38327

當你做本地開發的時候，這個檔案是配置環境最簡單的方式。事實上，如果你不想使用launchSettings.json檔案，你需要特別配置。

dotnet run --no-launch-profile

以上命令會跳過launchSettings.json檔案的載入，並使用主機環境變數配置來決定繫結的URLs。

到目前為止，所有的實現方案都是間接為Kestrel伺服器配置URLs, 但是實際上你還可以直接配置。

KestrelServerOptions.Listen()

幾乎所有的ASP.NET Core應用預設都會使用Kestrel伺服器。如果你想的話，你可以手動配置Kestrel伺服器節點，或者使用IConfiguration配置KestrelServerOptions。

我從來沒有這樣做過，這裡有非常多的配置項，因此在大多數情況下，我建議參考文件。例如，你可以使用Listen()函式顯式配置KestrelServerOptions

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>();
                webBuilder.UseKestrel(opts =>
                {
                    // Bind directly to a socket handle or Unix socket
                    // opts.ListenHandle(123554);
                    // opts.ListenUnixSocket("/tmp/kestrel-test.sock");
                    opts.Listen(IPAddress.Loopback, port: 5002);
                    opts.ListenAnyIP(5003);
                    opts.ListenLocalhost(5004, opts => opts.UseHttps());
                    opts.ListenLocalhost(5005, opts => opts.UseHttps());
                });

            });
}

以上配置為Kestrel伺服器設定了多個監聽地址。在上面的例子中，使用了硬編碼，但是實際上可以改用IConfiguration繫結。當你使用以上方式為Kestrel伺服器配置URLs時，如果你還是用了其他方式對URLs進行了配置，那麼它覆蓋其他方式的配置。如果發生這種情況，你會在程式日誌中看到如下警告：

warn: Microsoft.AspNetCore.Server.Kestrel[0]
      Overriding address(es) 'http://localhost:5007'. Binding to endpoints defined in UseKestrel() instead.
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://127.0.0.1:5002 
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://[::]:5003

對我個人而言，我沒有遇到過使用這方式為Kestrel伺服器配置URLs的場景, 但是當你需要的時候，你就可以完全控制Kestrel伺服器配置。

總結

在本篇博文中，我展示了通過五種不同的方式，來設定應用程式的監聽URLs. UseUrls()是最簡單的，但是基本上不太適合在生產環境中使用。 通過命令列引數--urls以及ASPNETCORE_/DOTNET環境變數是生產環境的常用方式。在開發環境中，launchSetting.json檔案是最有用的配置方式。如果你需要細粒度的配置，你可以直接使用Kestrel伺服器自帶的配置選項。

相關文章