將終結(jié)點(diǎn)圖添加到你的ASP.NET Core應(yīng)用程序中

在本文中，我將展示如何使用DfaGraphWriter服務(wù)在ASP.NET Core 3.0應(yīng)用程序中可視化你的終結(jié)點(diǎn)路由。上面文章我向您演示了如何生成一個(gè)有向圖（如我上篇文章[譯]使用DOT語言和GraphvizOnline來可視化你的ASP.NETCore3.0終結(jié)點(diǎn)01中所示），可以使用GraphVizOnline將其可視化。最后，我描述了應(yīng)用程序生命周期中可以檢索圖形數(shù)據(jù)的點(diǎn)。

作者：依樂祝

原文地址：https://www.cnblogs.com/yilezhu/p/13335749.html

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

在本文中，我僅展示如何創(chuàng)建圖形的“默認(rèn)”樣式。在我的下一批那文章中，我再創(chuàng)建一個(gè)自定義的writer來生成自定義的圖如上篇文章所示。

使用DfaGraphWriter可視化您的終結(jié)點(diǎn)

ASP.NET Core附帶了一個(gè)方便的類DfaGraphWriter可用于可視化ASP.NET Core 3.x應(yīng)用程序中的終結(jié)點(diǎn)路由：

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

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

現(xiàn)在，我們將創(chuàng)建一個(gè)中間件，該中間件使用DfaGraphWriter將該圖編寫為HTTP響應(yīng)。您可以使用DI 將DfaGraphWriter和EndpointDataSource注入到構(gòu)造函數(shù)中：

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);
        }
    }
}

這個(gè)中間件非常簡單-我們使用依賴注入將必要的服務(wù)注入到中間件中。將圖形寫入響應(yīng)有點(diǎn)復(fù)雜：您必須在內(nèi)存中將響應(yīng)寫到一個(gè)?StringWriter，再將其轉(zhuǎn)換為?string，然后將其寫到圖形。

這一切都是必要的，因?yàn)?code style="margin: 1px 5px;line-height: 1.8;vertical-align: middle;display: inline-block;overflow-x: auto;padding-right: 5px !important;padding-left: 5px !important;font-family: "Courier New", sans-serif !important;font-size: 12px !important;background-color: rgb(245, 245, 245) !important;border-width: 1px !important;border-style: solid !important;border-color: rgb(204, 204, 204) !important;border-radius: 3px !important;">DfaGraphWriter寫入TextWriter使用同步?Stream?API調(diào)用，如Write，而不是WriteAsync。如果有異步方法，理想情況下，我們將能夠執(zhí)行以下操作：

// 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。不幸的是，它是同步的，出于性能原因您不應(yīng)該使用同步調(diào)用直接寫入Response.Body。如果您嘗試使用上面的模式，則可能會(huì)得到如下所示內(nèi)容的InvalidOperationException異常，具體取決于所寫圖形的大?。?/p>

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

如果圖形很小，則可能不會(huì)出現(xiàn)此異常，但是如果您嘗試映射中等規(guī)模的應(yīng)用程序（例如帶有Identity的默認(rèn)Razor Pages應(yīng)用程序），則可以看到此異常。

讓我們回到正軌上-我們現(xiàn)在有了一個(gè)圖形生成中間件，所以讓我們把它添加到管道中。這里有兩個(gè)選擇：

• 使用終結(jié)點(diǎn)路由將其添加為終結(jié)點(diǎn)。

• 從中間件管道中將其添加為簡單的“分支”。

通常建議使用前一種方法，將終結(jié)點(diǎn)添加到ASP.NET Core 3.0應(yīng)用程序，因此從這里開始。

將圖形可視化器添加為終結(jié)點(diǎn)

為了簡化終結(jié)點(diǎn)注冊(cè)代碼，我將創(chuàng)建一個(gè)簡單的擴(kuò)展方法以將GraphEndpointMiddleware作為終結(jié)點(diǎn)添加：

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

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

然后，我們可以在Startup.Configure()中的UseEndpoints()方法中調(diào)用MapGraphVisualisation("/graph")將圖形終結(jié)點(diǎn)添加到我們的ASP.NET Core應(yīng)用程序中：

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已經(jīng)在DI中可用，因此不需要額外的配置。導(dǎo)航至http://localhost:5000/graph將以純文本形式生成我們的終結(jié)點(diǎn)圖：

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進(jìn)行可視化顯示如下：

在終結(jié)點(diǎn)路由系統(tǒng)中將圖形公開為終結(jié)點(diǎn)具有如下優(yōu)點(diǎn)和缺點(diǎn)：

• 您可以輕松地向終結(jié)點(diǎn)添加授權(quán)。您可能不希望任何人都能查看此數(shù)據(jù)！

• 圖形終結(jié)點(diǎn)顯示為系統(tǒng)中的終結(jié)點(diǎn)。這顯然是正確的，但可能會(huì)很煩人。

如果最后一點(diǎn)對(duì)您來說很重要，那么您可以使用傳統(tǒng)的方法來創(chuàng)建終結(jié)點(diǎn)，即使用分支中間件。

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

在您進(jìn)行終結(jié)點(diǎn)路由之前，將分支添加到中間件管道是創(chuàng)建“終結(jié)點(diǎn)”的最簡單方法之一。它在ASP.NET Core 3.0中仍然可用，它比終結(jié)點(diǎn)路由系統(tǒng)要更為簡單，但不能輕松添加授權(quán)或高級(jí)路由。

要?jiǎng)?chuàng)建中間件分支，請(qǐng)使用Map()命令。例如，您可以使用以下命令添加分支：

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

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

使用此方法的優(yōu)缺點(diǎn)在本質(zhì)上與終結(jié)點(diǎn)路由版本相反：圖形中沒有/graph終結(jié)點(diǎn)，您無法輕松地將授權(quán)應(yīng)用于此終結(jié)點(diǎn)！

對(duì)我來說，像這樣公開應(yīng)用程序的圖形是沒有意義的。在下一節(jié)中，我將展示如何通過小型集成測試來生成圖形。

從集成測試生成終結(jié)點(diǎn)圖

ASP.NET Core對(duì)于運(yùn)行內(nèi)存集成測試有很好的設(shè)計(jì)，它可以在不需要進(jìn)行網(wǎng)絡(luò)調(diào)用的情況下運(yùn)行完整的中間件管道和API控制器/Razor頁面。

除了可以用來確認(rèn)應(yīng)用程序整體正確運(yùn)行的傳統(tǒng)“端到端”集成測試之外，我有時(shí)還喜歡編寫“健全性檢查”測試，以確認(rèn)應(yīng)用程序配置正確。您可以使用，在Microsoft.AspNetCore.Mvc.Testing中暴露的底層DI容器中的WebApplicationFactory<>設(shè)施實(shí)現(xiàn)。這樣，您就可以在應(yīng)用程序的DI上下文中運(yùn)行代碼，而無需通過單元測試。

現(xiàn)在，讓我們來試下吧

• 使用VS或dotnet new xunit來運(yùn)行一個(gè)新的xUnit項(xiàng)目（我選擇的測試框架）

• 通過運(yùn)行dotnet add package Microsoft.AspNetCore.Mvc.Testing安裝Microsoft.AspNetCore.Mvc.Testing

• 將測試項(xiàng)目的元素更新為

• 從測試項(xiàng)目中引用您的ASP.NET Core項(xiàng)目

現(xiàn)在，我們可以創(chuàng)建一個(gè)簡單的測試來生成終結(jié)點(diǎn)圖，并將其寫入測試輸出。在下面的示例中，我將默認(rèn)值WebApplicationFactory<>作為類基礎(chǔ)設(shè)施；如果您需要自定義工廠，請(qǐng)參閱文檔以獲取詳細(xì)信息。

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

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

    // Inject the factory and the output helper
    private readonly WebApplicationFactory _factory;
    private readonly ITestOutputHelper _output;

    public GenerateGraphTest(
        WebApplicationFactory 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();
        var endpointData = _factory.Services.GetRequiredService();

        // 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);
        }
    }
}

測試的大部分內(nèi)容與中間件相同，但是我們沒有編寫響應(yīng)，而是編寫了xUnit的ITestOutputHelper以將記錄測試的結(jié)果輸出。在Visual Studio中，您可以通過以下方式查看此輸出：打開“測試資源管理器”，導(dǎo)航到GenerateGraph測試，然后單擊“為此結(jié)果打開其他輸出”，這將以選項(xiàng)卡的形式打開結(jié)果：

我發(fā)現(xiàn)像這樣的簡單測試通常足以滿足我的目的。在我看來有如下這些優(yōu)點(diǎn)：

• 它不會(huì)將此數(shù)據(jù)公開為終結(jié)點(diǎn)

• 對(duì)您的應(yīng)用沒有影響

• 容易產(chǎn)生

不過，也許您想從應(yīng)用程序中生成此圖，但是您不想使用到目前為止顯示的任何一種中間件方法將其包括在內(nèi)。如果是這樣，請(qǐng)務(wù)必小心在哪里進(jìn)行。

您無法在IHostedService中生成圖形

一般而言，您可以在應(yīng)用程序中任何使用依賴項(xiàng)注入或有權(quán)訪問實(shí)例的任何位置通過IServiceProvider訪問DfaGraphWriter和EndpointDataSource服務(wù)。這意味著在請(qǐng)求的上下文中（例如從MVC控制器或Razor Page生成）圖很容易，并且與您到目前為止所看到的方法相同。

如果您要嘗試在應(yīng)用程序生命周期的早期生成圖形，則必須小心。尤其是IHostedService。

在ASP.NET Core 3.0中，Web基礎(chǔ)結(jié)構(gòu)是在通用主機(jī)的基礎(chǔ)上重建的，這意味著您的服務(wù)器（Kestrel）作為一個(gè)IHostedService在你的應(yīng)用程序中運(yùn)行的。在大多數(shù)情況下，這不會(huì)產(chǎn)生太大影響，但是與ASP.NET Core 2.x相比，它改變了應(yīng)用程序的生成順序。

在ASP.NET Core 2.x中，將發(fā)生以下情況：

• 中間件管道已建立。

• 服務(wù)器（Kestrel）開始偵聽請(qǐng)求。

• 在IHostedService實(shí)現(xiàn)啟動(dòng)。

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

• IHostedService實(shí)現(xiàn)啟動(dòng)。

• 
  

GenericWebHostService

啟動(dòng)：

• 中間件管道已建立

• 服務(wù)器（Kestrel）開始偵聽請(qǐng)求。

需要注意的重要一點(diǎn)是，直到您的IHostedServices的執(zhí)行后中間件管道才會(huì)建立。由于UseEndpoints()尚未被調(diào)用，EndpointDataSource將不包含任何數(shù)據(jù)！

如果您嘗試從一個(gè)IHostedService中的DfaGraphWriter生成圖表,該EndpointDataSource是空的。

如果嘗試使用其他標(biāo)準(zhǔn)機(jī)制來注入早期行為，情況也是如此，如IStartupFilter-?Startup.Configure()執(zhí)行之前?調(diào)用 ，因此EndpointDataSource將為空。

同樣，您不能只是在Program.Main調(diào)用IHostBuilder.Build()來構(gòu)建一個(gè)Host，然后使用IHost.Services：來訪問服務(wù)，直到您調(diào)用IHost.Run，并且服務(wù)器已啟動(dòng)，否則您的終結(jié)點(diǎn)列表將為空！

這些限制可能不是問題，具體取決于您要實(shí)現(xiàn)的目標(biāo)。對(duì)我來說，單元測試方法可以解決我的大多數(shù)問題。

無論使用哪種方法，都只能生成本文中顯示的“默認(rèn)”終結(jié)點(diǎn)圖。這隱藏了很多真正有用的信息，例如哪些節(jié)點(diǎn)生成了終結(jié)點(diǎn)。在下一篇文章中，我將展示如何創(chuàng)建自定義圖形編寫器，以便您可以生成自己的圖形。

總結(jié)

在這篇文章中，我展示了如何使用DfaGraphWriter和EndpointDataSource創(chuàng)建應(yīng)用程序中所有終結(jié)點(diǎn)的圖形。我展示了如何創(chuàng)建中間件終結(jié)點(diǎn)來公開此數(shù)據(jù)，以及如何將這種中間件與分支中間件策略一起用作終結(jié)點(diǎn)路由。

我還展示了如何使用簡單的集成測試來生成圖形數(shù)據(jù)而無需運(yùn)行您的應(yīng)用程序。這避免了公開（可能敏感）的終結(jié)點(diǎn)圖，同時(shí)仍然允許輕松訪問數(shù)據(jù)。

最后，我討論了何時(shí)可以在應(yīng)用程序的生命周期中生成圖形。該EndpointDataSource未填充，直到后Server（Kestrel）已經(jīng)開始，所以你主要限于在請(qǐng)求上下文訪問數(shù)據(jù)。IHostedService和IStartupFilter執(zhí)行得太早以至于無法訪問數(shù)據(jù)，IHostBuilder.Build()只是構(gòu)建DI容器，而沒有構(gòu)建中間件管道。