Overzicht van .NET.NET Aspire inner-loop-netwerken

Artikel
12/12/2024

Een van de voordelen van het ontwikkelen met .NET.NET Aspire is dat u hiermee lokaal cloudeigen apps kunt ontwikkelen, testen en fouten kunt opsporen. Interne lusnetwerken zijn een belangrijk aspect van .NET.NET Aspire waarmee uw apps met elkaar kunnen communiceren in uw ontwikkelomgeving. In dit artikel leert u hoe .NET.NET Aspire verschillende netwerkscenario's verwerkt met proxy's, eindpunten, eindpuntconfiguraties en startprofielen.

Netwerken binnen de inner loop

De binnenste lus is het proces van het lokaal ontwikkelen en testen van uw app voordat deze in een doelomgeving wordt geïmplementeerd. .NET .NET Aspire biedt verschillende hulpprogramma's en functies om de netwerkervaring in de binnenste lus te vereenvoudigen en te verbeteren, zoals:

Profielen starten: Startprofielen zijn configuratiebestanden die aangeven hoe uw app lokaal moet worden uitgevoerd. U kunt startprofielen (zoals het launchSettings.json-bestand) gebruiken om de eindpunten, omgevingsvariabelen en startinstellingen voor uw app te definiëren.
Kestrel-configuratie: met de Kestrel-configuratie kunt u de eindpunten opgeven waarop de Kestrel-webserver luistert. U kunt Kestrel-eindpunten configureren in uw app-instellingen en .NET.NET Aspire deze instellingen automatisch gebruikt om eindpunten te maken.
eindpunten/eindpuntconfiguraties: Eindpunten zijn de verbindingen tussen uw app en de services waarvoor deze afhankelijk is, zoals databases, berichtenwachtrijen of API's. Eindpunten bieden informatie zoals de servicenaam, hostpoort, schema en omgevingsvariabele. U kunt eindpunten aan uw app impliciet toevoegen (via startprofielen) of expliciet door WithEndpointaan te roepen.
proxies: .NET.NET Aspire start automatisch een proxy voor elke servicebinding die u aan uw app toevoegt en wijst een poort toe waarvoor de proxy luistert. De proxy stuurt de aanvragen vervolgens door naar de poort waarop uw app luistert. Dit kan afwijken van de proxypoort. Op deze manier kunt u poortconflicten voorkomen en toegang krijgen tot uw app en services met behulp van consistente en voorspelbare URL's.

Hoe eindpunten werken

Een servicebinding in .NET.NET Aspire omvat twee integraties: een service die een externe resource vertegenwoordigt die uw app nodig heeft (bijvoorbeeld een database, berichtenwachtrij of API) en een binding waarmee een verbinding tussen uw app en de service tot stand wordt gebracht en de benodigde informatie wordt verstrekt.

.NET .NET Aspire ondersteunt twee servicebindingstypen: impliciete, automatisch gemaakt op basis van opgegeven startprofielen die app-gedrag definiëren in verschillende omgevingen, en expliciete, handmatig gemaakt met behulp van WithEndpoint.

Bij het maken van een binding, hetzij impliciet of expliciet, starten .NET.NET Aspire een lichtgewicht omgekeerde proxy op een opgegeven poort, die de routering en taakverdeling voor aanvragen van uw app naar de service afhandelt. De proxy is een .NET.NET Aspire implementatiedetail waarvoor geen configuratie of beheer nodig is.

Als u wilt visualiseren hoe eindpunten werken, kunt u het .NET.NET Aspire starterssjablonen binnenloopnetwerkdiagram overwegen:

Profielen lanceren

Wanneer u AddProjectaanroept, zoekt de app-host naar Eigenschappen/launchSettings.json om de standaardset eindpunten te bepalen. De app-host selecteert een specifiek startprofiel met behulp van de volgende regels:

Een expliciet launchProfileName argument dat is doorgegeven bij het aanroepen van AddProject.
De omgevingsvariabele DOTNET_LAUNCH_PROFILE. Zie .NET omgevingsvariabelenvoor meer informatie.
Het eerste startprofiel dat is gedefinieerd in launchSettings.json.

Houd rekening met het volgende launchSettings.json bestand:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "applicationUrl": "https://localhost:7239;http://localhost:5066",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Stel dat u voor de rest van dit artikel een IDistributedApplicationBuilder hebt gemaakt die is toegewezen aan een variabele met de naam builder met de CreateBuilder()-API:

var builder = DistributedApplication.CreateBuilder(args);

Als u de http- en https startprofielen wilt opgeven, configureert u de applicationUrl waarden voor beide in het launchSettings.json-bestand. Deze URL's worden gebruikt om eindpunten voor dit project te maken. Dit is het equivalent van:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithHttpsEndpoint(port: 7239);

Belangrijk

Als er geen launchSettings.json (of startprofiel) is, zijn er standaard geen bindingen.

Zie .NET.NET Aspire en startprofielenvoor meer informatie.

Geconfigureerde eindpunten voor Kestrel

.NET .NET Aspire ondersteunt de configuratie van Kestrel-eindpunten. Denk bijvoorbeeld aan een appsettings.json-bestand voor een project dat een Kestrel-eindpunt definieert met het HTTPS-schema en poort 5271:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5271"
      }
    }
  }
}

In de voorgaande configuratie wordt een Https-eindpunt opgegeven. De eigenschap Url is ingesteld op https://*:5271, wat betekent dat het eindpunt luistert op alle interfaces op poort 5271. Zie Eindpunten configureren voor de ASP.NET Core Kestrel-webservervoor meer informatie.

Met het Kestrel-eindpunt geconfigureerd, behoort het project de geconfigureerde applicationUrl uit het launchSettings.json-bestand te verwijderen.

Notitie

Als de applicationUrl aanwezig is in het launchSettings.json-bestand en het Kestrel-eindpunt is geconfigureerd, genereert de app-host een uitzondering.

Wanneer u een projectresource toevoegt, is er een overloadfunctie waarmee u kunt opgeven dat het Kestrel-eindpunt moet worden gebruikt in plaats van het launchSettings.json file:

builder.AddProject<Projects.Networking_ApiService>(
    name: "apiservice",
    configure: static project =>
    {
        project.ExcludeLaunchProfile = true;
        project.ExcludeKestrelEndpoints = false;
    })
    .WithHttpsEndpoint();

Zie AddProjectvoor meer informatie.

Poorten en proxies

Bij het definiëren van een servicebinding wordt de hostpoort altijd altijd gegeven aan de proxy die zich voor de service bevindt. Hierdoor kunnen enkele of meerdere replica's van een service zich op dezelfde manier gedragen. Daarnaast zijn alle resourceafhankelijkheden die gebruikmaken van de WithReference-API afhankelijk van het proxy-eindpunt uit de omgevingsvariabele.

Houd rekening met de volgende methodeketen die AddProject, WithHttpEndpointaanroept en vervolgens WithReplicas:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithReplicas(2);

De voorgaande code resulteert in het volgende netwerkdiagram:

In het voorgaande diagram ziet u het volgende:

Een webbrowser als toegangspunt voor de app.
Een hostpoort van 5066.
De front-endproxy die tussen de webbrowser en de front-endservicereplica's zit en luistert op poort 5066.
De frontend_0 frontendservicereplica die luistert op poort 65001, welke willekeurig is toegewezen.
Het frontend_1 frontendservice replica luistert naar de willekeurig toegewezen poort 65002.

Zonder de aanroep van WithReplicasis er slechts één frontendservice. De proxy luistert nog steeds op poort 5066, maar de front-endservice luistert op een willekeurige poort:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066);

Er zijn twee poorten gedefinieerd:

Een hostpoort van 5066.
Een willekeurige proxypoort waaraan de onderliggende service is gebonden.

In het voorgaande diagram ziet u het volgende:

Een webbrowser als toegangspunt voor de app.
Een hostpoort van 5066.
De front-endproxy die zich tussen de webbrowser en de front-endservice bevindt en luistert op poort 5066.
De front-endservice luistert op willekeurige poort van 65001.

De onderliggende service wordt van deze poort voorzien via ASPNETCORE_URLS voor projectmiddelen. Andere resources krijgen toegang tot deze poort door een omgevingsvariabele op te geven voor de servicebinding.

builder.AddNpmApp("frontend", "../NodeFrontend", "watch")
       .WithHttpEndpoint(port: 5067, env: "PORT");

De vorige code maakt de willekeurige poort beschikbaar in de omgevingsvariabele PORT. De app gebruikt deze poort om te luisteren naar binnenkomende verbindingen vanuit de proxy. Bekijk het volgende diagram:

In het voorgaande diagram ziet u het volgende:

Een webbrowser als toegangspunt voor de app.
Een hostpoort van 5067.
De frontendproxy, die tussen de webbrowser en de frontendservice zit, luistert op poort 5067.
De front-endservice luistert op een omgeving 65001.

Tip

Als u wilt voorkomen dat een eindpunt wordt geproxied, stelt u de eigenschap IsProxied in op false bij het aanroepen van de WithEndpoint-extensiemethode. Zie voor meer informatie: Endpoint-extensies, aanvullende overwegingen.

Laat de hostpoort weg

Wanneer u de hostpoort weglaat, genereert .NET.NET Aspire een willekeurige poort voor zowel host- als servicepoort. Dit is handig als u poortconflicten wilt voorkomen en u zich geen zorgen hoeft te maken over de host- of servicepoort. Houd rekening met de volgende code:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint();

In dit scenario zijn zowel de host- als servicepoorten willekeurig, zoals wordt weergegeven in het volgende diagram:

In het voorgaande diagram ziet u het volgende:

Een webbrowser als toegangspunt voor de app.
Een willekeurige hostpoort van 65000.
De frontend-proxy die zich bevindt tussen de webbrowser en de frontendservice, luistert op poort 65000.
De front-endservice luistert op een willekeurige poort van 65001.

Containerpoorten

Wanneer u een containerresource toevoegt, wijst .NET.NET Aspire automatisch een willekeurige poort toe aan de container. Als u een containerpoort wilt opgeven, configureert u de containerresource met de gewenste poort:

builder.AddContainer("frontend", "mcr.microsoft.com/dotnet/samples", "aspnetapp")
       .WithHttpEndpoint(port: 8000, targetPort: 8080);

De voorgaande code:

Maakt een containerresource met de naam frontend, van de image mcr.microsoft.com/dotnet/samples:aspnetapp.
Dit stelt een http-eindpunt voor door de host aan poort 8000 te binden en deze toe te wijzen aan poort 8080 van de container.

Bekijk het volgende diagram:

.NET.NET Aspire netwerkdiagram voor front-end-apps met een docker-host.

Methoden voor eindpuntextensie

Elke resource die de IResourceWithEndpoints-interface implementeert, kan gebruikmaken van de WithEndpoint-extensiemethoden. Er zijn verschillende overload-methoden van deze extensie, zodat u het schema, de containerpoort, de hostpoort, de naam van de omgevingsvariabele kunt opgeven en of het eindpunt via een proxy loopt.

Er is ook een overbelasting waarmee u een gemachtigde kunt opgeven om het eindpunt te configureren. Dit is handig wanneer u het eindpunt moet configureren op basis van de omgeving of andere factoren. Houd rekening met de volgende code:

builder.AddProject<Projects.Networking_ApiService>("apiService")
       .WithEndpoint(
            endpointName: "admin",
            callback: static endpoint =>
       {
           endpoint.Port = 17003;
           endpoint.UriScheme = "http";
           endpoint.Transport = "http";
       });

De voorgaande code biedt een callback-gemachtigde voor het configureren van het eindpunt. Het eindpunt heeft de naam admin en is geconfigureerd voor het gebruik van het http schema en transport, evenals de hostpoort 17003. De consument verwijst naar dit eindpunt op naam en overweeg de volgende AddHttpClient aanroep:

builder.Services.AddHttpClient<WeatherApiClient>(
    client => client.BaseAddress = new Uri("http://_admin.apiservice"));

De Uri wordt samengesteld met behulp van de admin eindpuntnaam voorafgegaan door de _ sentinel. Dit is een conventie om aan te geven dat het admin segment de eindpuntnaam is die hoort bij de apiservice-service. Zie .NET.NET Aspire servicedetectievoor meer informatie.

Aanvullende overwegingen

Bij het aanroepen van de WithEndpoint-extensiemethode maakt de callback overbelasting de onbewerkte EndpointAnnotationbeschikbaar, waardoor de consument veel aspecten van het eindpunt kan aanpassen.

Met de eigenschap AllocatedEndpoint kunt u het eindpunt voor een service ophalen of instellen. De eigenschappen IsExternal en IsProxied bepalen hoe het eindpunt wordt beheerd en weergegeven: IsExternal bepaalt of het openbaar toegankelijk moet zijn, terwijl IsProxied ervoor zorgt dat DCP het beheert, waardoor interne poortverschillen en replicatie mogelijk zijn.

Tip

Als u een extern uitvoerbaar bestand host dat een eigen proxy uitvoert en poortbindingsproblemen ondervindt vanwege DCP die de poort al heeft gebonden, probeert u de eigenschap IsProxied in te stellen op false. Hierdoor voorkomt u dat DCP de proxy beheert, zodat het uitvoerbare bestand de poort kan binden.

De eigenschap Name identificeert de service, terwijl de eigenschappen Port en TargetPort respectievelijk de gewenste en luisterende poorten opgeven.

Voor netwerkcommunicatie ondersteunt de eigenschap ProtocolTCP- en UDP-, met potentieel voor meer in de toekomst, en de eigenschap Transport geeft het transportprotocol (HTTP-, HTTP2-, HTTP3-). Als de service tot slot URI-adresseerbaar is, biedt de eigenschap UriScheme het URI-schema voor het maken van de service-URI.

Zie de beschikbare eigenschappen van de EndpointAnnotation-eigenschappenvoor meer informatie.

Eindpuntfiltering

Alle .NET.NET Aspire projectresource-eindpunten volgen een set standaard-heuristieken. Sommige eindpunten zijn opgenomen in ASPNETCORE_URLS tijdens de uitvoeringstijd, sommige worden gepubliceerd als HTTP/HTTPS_PORTS, en sommige configuraties worden opgelost vanuit de Kestrel-configuratie. Ongeacht het standaardgedrag kunt u de eindpunten filteren die zijn opgenomen in omgevingsvariabelen met behulp van de WithEndpointsInEnvironment-extensiemethode:

builder.AddProject<Projects.Networking_ApiService>("apiservice")
    .WithHttpsEndpoint() // Adds a default "https" endpoint
    .WithHttpsEndpoint(port: 19227, name: "admin")
    .WithEndpointsInEnvironment(
        filter: static endpoint =>
        {
            return endpoint.Name is not "admin";
        });

Met de voorgaande code wordt een standaard-HTTPS-eindpunt en een admin-eindpunt toegevoegd op poort 19227. Het admin-eindpunt wordt echter uitgesloten van de omgevingsvariabelen. Dit is handig als u alleen een eindpunt beschikbaar wilt maken voor intern gebruik.

Delen via

Overzicht van .NET.NET Aspire inner-loop-netwerken

Netwerken binnen de inner loop

Hoe eindpunten werken

Profielen lanceren

Geconfigureerde eindpunten voor Kestrel

Poorten en proxies

Laat de hostpoort weg

Containerpoorten

Methoden voor eindpuntextensie

Aanvullende overwegingen

Eindpuntfiltering

Aanvullende resources