將終結點圖添加到你的ASP.NET Core應用程序中

在本文中，我將展現如何使用DfaGraphWriter服務在ASP.NET Core 3.0應用程序中可視化你的終結點路由。上面文章我向您演示瞭如何生成一個有向圖（如我上篇文章中所示），可使用GraphVizOnline將其可視化。最後，我描述了應用程序生命週期中能夠檢索圖形數據的點。

做者：依樂祝

原文地址：http://www.javashuo.com/article/p-omdvvxoe-nb.html

譯文地址：https://andrewlock.net/adding-an-endpoint-graph-to-your-aspnetcore-application/

在本文中，我僅展現如何建立圖形的「默認」樣式。在個人下一批那文章中，我再建立一個自定義的writer來生成自定義的圖如上篇文章所示。

使用DfaGraphWriter可視化您的終結點

ASP.NET Core附帶了一個方便的類DfaGraphWriter可用於可視化ASP.NET Core 3.x應用程序中的終結點路由：

public class DfaGraphWriter
{
    public void Write(EndpointDataSource dataSource, TextWriter writer);
}

此類只有一個方法Write。EndpointDataSource包含描述您的應用程序的Endpoint集合，TextWriter用於編寫DOT語言圖（如您在前一篇文章中所見）。

如今，咱們將建立一箇中間件，該中間件使用DfaGraphWriter將該圖編寫爲HTTP響應。您可使用DI 將DfaGraphWriter和EndpointDataSource注入到構造函數中：

public class GraphEndpointMiddleware
{
    // inject required services using DI
    private readonly DfaGraphWriter _graphWriter;
    private readonly EndpointDataSource _endpointData;

    public GraphEndpointMiddleware(
        RequestDelegate next, 
        DfaGraphWriter graphWriter, 
        EndpointDataSource endpointData)
    {
        _graphWriter = graphWriter;
        _endpointData = endpointData;
    }

    public async Task Invoke(HttpContext context)
    {
        // set the response
        context.Response.StatusCode = 200;
        context.Response.ContentType = "text/plain";

        // Write the response into memory
        await using (var sw = new StringWriter())
        {
            // Write the graph
            _graphWriter.Write(_endpointData, sw);
            var graph = sw.ToString();

            // Write the graph to the response
            await context.Response.WriteAsync(graph);
        }
    }
}

這個中間件很是簡單-咱們使用依賴注入將必要的服務注入到中間件中。將圖形寫入響應有點複雜：您必須在內存中將響應寫到一個 StringWriter，再將其轉換爲 string，而後將其寫到圖形。

這一切都是必要的，由於DfaGraphWriter寫入TextWriter使用同步 Stream API調用，如Write，而不是WriteAsync。若是有異步方法，理想狀況下，咱們將可以執行如下操做：

// Create a stream writer that wraps the body
await using (var sw = new StreamWriter(context.Response.Body))
{
    // write asynchronously to the stream
    await _graphWriter.WriteAsync(_endpointData, sw);
}

若是DfaGraphWriter使用了異步API，則能夠如上所述直接寫入Response.Body，而避免使用in-memory string。不幸的是，它是同步的，出於性能緣由您不該該使用同步調用直接寫入Response.Body。若是您嘗試使用上面的模式，則可能會獲得以下所示內容的InvalidOperationException異常，具體取決於所寫圖形的大小：

System.InvalidOperationException: Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.

若是圖形很小，則可能不會出現此異常，可是若是您嘗試映射中等規模的應用程序（例如帶有Identity的默認Razor Pages應用程序），則能夠看到此異常。

讓咱們回到正軌上-咱們如今有了一個圖形生成中間件，因此讓咱們把它添加到管道中。這裏有兩個選擇：

• 使用終結點路由將其添加爲終結點。
• 從中間件管道中將其添加爲簡單的「分支」。

一般建議使用前一種方法，將終結點添加到ASP.NET Core 3.0應用程序，所以從這裏開始。

將圖形可視化器添加爲終結點

爲了簡化終結點註冊代碼，我將建立一個簡單的擴展方法以將GraphEndpointMiddleware做爲終結點添加：

public static class GraphEndpointMiddlewareExtensions
{
    public static IEndpointConventionBuilder MapGraphVisualisation(
        this IEndpointRouteBuilder endpoints, string pattern)
    {
        var pipeline = endpoints
            .CreateApplicationBuilder()
            .UseMiddleware<GraphEndpointMiddleware>()
            .Build();

        return endpoints.Map(pattern, pipeline).WithDisplayName("Endpoint Graph");
    }
}

而後，咱們能夠在Startup.Configure()中的UseEndpoints()方法中調用MapGraphVisualisation("/graph")將圖形終結點添加到咱們的ASP.NET Core應用程序中：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz");
        endpoints.MapControllers();
        // Add the graph endpoint
        endpoints.MapGraphVisualisation("/graph");
    });
}

這就是咱們要作的。該DfaGraphWriter已經在DI中可用，所以不須要額外的配置。導航至http://localhost:5000/graph將以純文本形式生成咱們的終結點圖：

digraph DFA {
    0 [label="/graph/"]
    1 [label="/healthz/"]
    2 [label="/api/Values/{...}/ HTTP: GET"]
    3 [label="/api/Values/{...}/ HTTP: PUT"]
    4 [label="/api/Values/{...}/ HTTP: DELETE"]
    5 [label="/api/Values/{...}/ HTTP: *"]
    6 -> 2 [label="HTTP: GET"]
    6 -> 3 [label="HTTP: PUT"]
    6 -> 4 [label="HTTP: DELETE"]
    6 -> 5 [label="HTTP: *"]
    6 [label="/api/Values/{...}/"]
    7 [label="/api/Values/ HTTP: GET"]
    8 [label="/api/Values/ HTTP: POST"]
    9 [label="/api/Values/ HTTP: *"]
    10 -> 6 [label="/*"]
    10 -> 7 [label="HTTP: GET"]
    10 -> 8 [label="HTTP: POST"]
    10 -> 9 [label="HTTP: *"]
    10 [label="/api/Values/"]
    11 -> 10 [label="/Values"]
    11 [label="/api/"]
    12 -> 0 [label="/graph"]
    12 -> 1 [label="/healthz"]
    12 -> 11 [label="/api"]
    12 [label="/"]
}

咱們可使用GraphVizOnline進行可視化顯示以下：

在終結點路由系統中將圖形公開爲終結點具備以下優勢和缺點：

• 您能夠輕鬆地向終結點添加受權。您可能不但願任何人都能查看此數據！
• 圖形終結點顯示爲系統中的終結點。這顯然是正確的，但可能會很煩人。

若是最後一點對您來講很重要，那麼您能夠使用傳統的方法來建立終結點，即便用分支中間件。

將圖形可視化工具添加爲中間件分支

在您進行終結點路由以前，將分支添加到中間件管道是建立「終結點」的最簡單方法之一。它在ASP.NET Core 3.0中仍然可用，它比終結點路由系統要更爲，但不能輕鬆添加受權或高級路由。

要建立中間件分支，請使用Map()命令。例如，您可使用如下命令添加分支：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // add the graph endpoint as a branch of the pipeline
    app.Map("/graph", branch => 
        branch.UseMiddleware<GraphEndpointMiddleware>());

    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz");
        endpoints.MapControllers();
    });
}

使用此方法的優缺點在本質上與終結點路由版本相反：圖形中沒有/graph終結點，您沒法輕鬆地將受權應用於此終結點！

對我來講，像這樣公開應用程序的圖形是沒有意義的。在下一節中，我將展現如何經過小型集成測試來生成圖形。

從集成測試生成終結點圖

ASP.NET Core對於運行內存集成測試有很好的設計，它能夠在不須要進行網絡調用的狀況下運行完整的中間件管道和API控制器/Razor頁面。

除了能夠用來確認應用程序總體正確運行的傳統「端到端」集成測試以外，我有時還喜歡編寫「健全性檢查」測試，以確認應用程序配置正確。您可使用，在Microsoft.AspNetCore.Mvc.Testing中暴露的底層DI容器中的WebApplicationFactory<>設施實現。這樣，您就能夠在應用程序的DI上下文中運行代碼，而無需經過單元測試。

如今，讓咱們來試下吧

• 使用VS或dotnet new xunit來運行一個新的xUnit項目（我選擇的測試框架）
• 經過運行dotnet add package Microsoft.AspNetCore.Mvc.Testing安裝Microsoft.AspNetCore.Mvc.Testing
• 將測試項目的<Project>元素更新爲<Project Sdk="Microsoft.NET.Sdk.Web">
• 從測試項目中引用您的ASP.NET Core項目

如今，咱們能夠建立一個簡單的測試來生成終結點圖，並將其寫入測試輸出。在下面的示例中，我將默認值WebApplicationFactory<>做爲類基礎設施；若是您須要自定義工廠，請參閱文檔以獲取詳細信息。

除了WebApplicationFactory<>，我還注入了ITestOutputHelper。您須要使用此類來記錄xUnit的測試輸出。直接寫Console不會起做用。。

public class GenerateGraphTest
    : IClassFixture<WebApplicationFactory<ApiRoutes.Startup>>
{

    // Inject the factory and the output helper
    private readonly WebApplicationFactory<ApiRoutes.Startup> _factory;
    private readonly ITestOutputHelper _output;

    public GenerateGraphTest(
        WebApplicationFactory<Startup> factory, ITestOutputHelper output)
    {
        _factory = factory;
        _output = output;
    }

    [Fact]
    public void GenerateGraph()
    {
        // fetch the required services from the root container of the app
        var graphWriter = _factory.Services.GetRequiredService<DfaGraphWriter>();
        var endpointData = _factory.Services.GetRequiredService<EndpointDataSource>();

        // build the graph as before
        using (var sw = new StringWriter())
        {
            graphWriter.Write(endpointData, sw);
            var graph = sw.ToString();

            // write the graph to the test output
            _output.WriteLine(graph);
        }
    }
}

測試的大部份內容與中間件相同，可是咱們沒有編寫響應，而是編寫了xUnit的ITestOutputHelper以將記錄測試的結果輸出。在Visual Studio中，您能夠經過如下方式查看此輸出：打開「測試資源管理器」，導航到GenerateGraph測試，而後單擊「爲此結果打開其餘輸出」，這將以選項卡的形式打開結果：

我發現像這樣的簡單測試一般足以知足個人目的。在我看來有以下這些優勢：

• 它不會將此數據公開爲終結點
• 對您的應用沒有影響
• 容易產生

不過，也許您想從應用程序中生成此圖，可是您不想使用到目前爲止顯示的任何一種中間件方法將其包括在內。若是是這樣，請務必當心在哪裏進行。

您沒法在IHostedService中生成圖形

通常而言，您能夠在應用程序中任何使用依賴項注入或有權訪問實例的任何位置經過IServiceProvider訪問DfaGraphWriter和EndpointDataSource服務。這意味着在請求的上下文中（例如從MVC控制器或Razor Page生成）圖很容易，而且與您到目前爲止所看到的方法相同。

若是您要嘗試在應用程序生命週期的早期生成圖形，則必須當心。尤爲是IHostedService。

在ASP.NET Core 3.0中，Web基礎結構是在通用主機的基礎上重建的，這意味着您的服務器（Kestrel）做爲一個IHostedService在你的應用程序中運行的。在大多數狀況下，這不會產生太大影響，可是與ASP.NET Core 2.x相比，它改變了應用程序的生成順序。

在ASP.NET Core 2.x中，將發生如下狀況：

• 中間件管道已創建。
• 服務器（Kestrel）開始偵聽請求。
• 在IHostedService實現啓動。

而是在ASP.NET Core 3.x上，以下所示：

• IHostedService實現啓動。

GenericWebHostService

啓動：

• 中間件管道已創建
• 服務器（Kestrel）開始偵聽請求。

須要注意的重要一點是，直到您的IHostedServices的執行後中間件管道纔會創建。因爲UseEndpoints()還沒有被調用，EndpointDataSource將不包含任何數據！

若是您嘗試從一個IHostedService中的DfaGraphWriter生成圖表,該EndpointDataSource是空的。

若是嘗試使用其餘標準機制來注入早期行爲，狀況也是如此，如IStartupFilter- Startup.Configure()執行以前 調用 ，所以EndpointDataSource將爲空。

一樣，您不能只是在Program.Main調用IHostBuilder.Build()來構建一個Host，而後使用IHost.Services：來訪問服務，直到您調用IHost.Run，而且服務器已啓動，不然您的終結點列表將爲空！

這些限制可能不是問題，具體取決於您要實現的目標。對我來講，單元測試方法能夠解決個人大多數問題。

不管使用哪一種方法，都只能生成本文中顯示的「默認」終結點圖。這隱藏了不少真正有用的信息，例如哪些節點生成了終結點。在下一篇文章中，我將展現如何建立自定義圖形編寫器，以便您能夠生成本身的圖形。

總結

在這篇文章中，我展現瞭如何使用DfaGraphWriter和EndpointDataSource建立應用程序中全部終結點的圖形。我展現瞭如何建立中間件終結點來公開此數據，以及如何將這種中間件與分支中間件策略一塊兒用做終結點路由。

我還展現瞭如何使用簡單的集成測試來生成圖形數據而無需運行您的應用程序。這避免了公開（可能敏感）的終結點圖，同時仍然容許輕鬆訪問數據。

最後，我討論了什麼時候能夠在應用程序的生命週期中生成圖形。該EndpointDataSource未填充，直到後Server（Kestrel）已經開始，因此你主要限於在請求上下文訪問數據。IHostedService和IStartupFilter執行得太早以致於沒法訪問數據，IHostBuilder.Build()只是構建DI容器，而沒有構建中間件管道。