vue d’ensemble de la mise en réseau en boucle interne .NET.NET Aspire

L’un des avantages du développement avec .NET.NET Aspire est qu’il vous permet de développer, tester et déboguer des applications natives cloud localement. La mise en réseau en boucle interne est un aspect clé de .NET.NET Aspire qui permet à vos applications de communiquer entre elles dans votre environnement de développement. Dans cet article, vous allez découvrir comment .NET.NET Aspire gère différents scénarios de mise en réseau avec des proxys, des points de terminaison, des configurations de point de terminaison et des profils de lancement.

Mise en réseau dans la boucle interne

La boucle interne est le processus de développement et de test de votre application localement avant de la déployer dans un environnement cible. .NET .NET Aspire fournit plusieurs outils et fonctionnalités pour simplifier et améliorer l’expérience réseau dans la boucle interne, par exemple :

• Profils de lancement: les profils de lancement sont des fichiers de configuration qui spécifient comment exécuter votre application localement. Vous pouvez utiliser des profils de lancement (tels que les launchSettings.json fichier) pour définir les points de terminaison, les variables d’environnement et les paramètres de lancement de votre application.
• Configuration Kestrel: la configuration Kestrel vous permet de spécifier les points de terminaison que le serveur web Kestrel server écoute. Vous pouvez configurer des points de terminaison Kestrel dans les paramètres de votre application, et .NET.NET Aspire utilise automatiquement ces paramètres pour créer des points de terminaison.
• configurations de points de terminaison/points de terminaison: les points de terminaison sont les connexions entre votre application et les services dont elle dépend, telles que les bases de données, les files d’attente de messages ou les API. Les points de terminaison fournissent des informations telles que le nom de service, le port hôte, le schéma et la variable d’environnement. Vous pouvez ajouter des points de terminaison à votre application implicitement (via des profils de lancement) ou explicitement en appelant WithEndpoint.
• proxies: .NET.NET Aspire met automatiquement en marche un proxy pour chaque liaison de service que vous ajoutez à votre application et affecte un port afin que le proxy écoute. Le proxy transfère ensuite les demandes au port sur lequel votre application écoute, ce qui peut être différent du port proxy. De cette façon, vous pouvez éviter les conflits de ports et accéder à vos applications et services à l’aide d’URL cohérentes et prévisibles.

Fonctionnement des points de terminaison

Une liaison de service dans .NET.NET Aspire implique deux intégrations : un service représentant une ressource externe dont votre application a besoin (par exemple, une base de données, une file d’attente de messages ou une API) et une liaison qui établit une connexion entre votre application et le service et fournit les informations nécessaires.

.NET .NET Aspire prend en charge deux types de liaison de service : implicite, créé automatiquement en fonction des profils de lancement spécifiés définissant le comportement de l’application dans différents environnements et explicite, créé manuellement à l’aide de WithEndpoint.

Lors de la création d’une liaison, qu’elle soit implicite ou explicite, .NET.NET Aspire lance un proxy inverse léger sur un port spécifié, gère le routage et l’équilibrage de charge des requêtes de votre application vers le service. Le proxy est un détail d’implémentation .NET.NET Aspire, ne nécessitant aucune configuration ni gestion.

Pour mieux comprendre le fonctionnement des points de terminaison, considérez le schéma de mise en réseau en boucle interne des modèles de base .NET.NET Aspire :

Profils de lancement

Lorsque vous appelez AddProject, l’hôte de l’application recherche dans Propriétés/launchSettings.json pour déterminer l’ensemble par défaut des points de terminaison. L’hôte de l’application sélectionne un profil de lancement spécifique à l’aide des règles suivantes :

1. Argument launchProfileName explicite passé lors de l’appel de AddProject.
2. Variable d’environnement DOTNET_LAUNCH_PROFILE. Pour plus d’informations, consultez .NET variables d’environnement.
3. Premier profil de lancement défini dans launchSettings.json.

Tenez compte des launchSettings suivants : fichierjson.

{
  "$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"
      }
    }
  }
}

Pour le reste de cet article, imaginez que vous avez créé une IDistributedApplicationBuilder affectée à une variable nommée builder avec l’API CreateBuilder() :

var builder = DistributedApplication.CreateBuilder(args);

Pour spécifier les profils de lancement http et https , configurez les valeurs de applicationUrl pour les deux dans le fichier launchSettings json. Ces URL sont utilisées pour créer des points de terminaison pour ce projet. Il s’agit de l’équivalent de :

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

Important

S’il n’y a pas de launchSettings.json (ou le profil de lancement), il n’existe aucune liaison par défaut.

Pour plus d’informations, consultez .NET.NET Aspire et lancez les profils.

Points de terminaison configurés par Kestrel

.NET .NET Aspire prend en charge le paramétrage du point de terminaison Kestrel. Par exemple, considérons un fichier appsettings.json pour un projet qui définit un point de terminaison Kestrel avec le schéma HTTPS et le port 5271 :

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

La configuration précédente spécifie un point de terminaison Https. La propriété Url est définie sur https://*:5271, ce qui signifie que le point de terminaison écoute toutes les interfaces sur le port 5271. Pour plus d’informations, consultez Configurer des points de terminaison pour le web Kestrel ASP.NET Coreserver.

Avec le point de terminaison Kestrel configuré, le projet doit supprimer toutes les applicationUrl configurées du launchSettings. fichierjson.

Note

Si le applicationUrl est présent dans le fichier launchSettings,json et que le point de terminaison Kestrel est configuré, l’hôte de l’application lève une exception.

Lorsque vous ajoutez une ressource de projet, il existe une surcharge qui vous permet de spécifier que le point de terminaison Kestrel doit être utilisé au lieu du launchSettings. fichierjson :

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

Pour plus d’informations, consultez AddProject.

Ports et proxys

Lors de la définition d’une liaison de service, le port hôte est toujours donné au proxy qui se trouve devant le service. Cela permet aux répliques uniques ou multiples d'un service de se comporter de manière similaire. En outre, toutes les dépendances de ressources qui utilisent l’API WithReference s’appuient sur le point de terminaison proxy à partir de la variable d’environnement.

Considérez la chaîne de méthode suivante qui appelle AddProject, WithHttpEndpoint, puis WithReplicas:

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

Le code précédent génère le diagramme de mise en réseau suivant :

Le diagramme précédent illustre les éléments suivants :

• Un navigateur web en tant que point d’entrée vers l’application.
• Port hôte 5066.
• Proxy frontal assis entre le navigateur web et les réplicas du service frontal, à l’écoute sur le port 5066.
• Réplique du service frontal frontend_0 écoute sur le port 65001 attribué de manière aléatoire.
• Le réplica du service frontend frontend_1 écoute sur le port attribué aléatoirement 65002.

Sans l’appel à WithReplicas, il n’existe qu’un seul service front-end. Le proxy écoute toujours sur le port 5066, mais le service frontal écoute sur un port aléatoire :

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

Il existe deux ports définis :

• Port hôte de 5066.
• Port proxy aléatoire auquel le service sous-jacent sera lié.

Le diagramme précédent illustre les éléments suivants :

• Un navigateur web en tant que point d’entrée vers l’application.
• Port hôte de 5066.
• Le proxy frontal qui se situe entre le navigateur web et le service frontal, et qui écoute sur le port 5066.
• Service front-end à l’écoute sur le port aléatoire de 65001.

Le service sous-jacent est alimenté via le port ASPNETCORE_URLS pour les ressources du projet. D’autres ressources accèdent à ce port en spécifiant une variable d’environnement sur la liaison de service :

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

Le code précédent rend le port aléatoire disponible dans la variable d’environnement PORT. L’application utilise ce port pour écouter les connexions entrantes à partir du proxy. Considérez le diagramme suivant :

Le diagramme précédent illustre les éléments suivants :

• Un navigateur web en tant que point d’entrée vers l’application.
• Port hôte de 5067.
• Le proxy frontal, qui se situe entre le navigateur web et le service frontal, écoute sur le port 5067.
• Service frontal à l’écoute sur un environnement 65001.

Pourboire

Pour éviter qu’un point de terminaison soit proxié, définissez la propriété IsProxied sur false lors de l’appel de la méthode d’extension WithEndpoint. Pour plus d’informations, consultez extensions de point de terminaison : considérations supplémentaires.

Omettre le port hôte

Lorsque vous omettez le port hôte, .NET.NET Aspire génère un port aléatoire pour l’hôte et le port de service. Cela est utile lorsque vous souhaitez éviter les conflits de ports et ne vous soucier pas de l’hôte ou du port de service. Considérez le code suivant :

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

Dans ce scénario, les ports hôte et de service sont aléatoires, comme illustré dans le diagramme suivant :

Le diagramme précédent illustre les éléments suivants :

• Un navigateur web en tant que point d’entrée vers l’application.
• Port hôte aléatoire de 65 000.
• Le proxy frontal situé entre le navigateur web et le service frontal, écoutant sur le port 65000.
• Le service frontal est à l'écoute d'un port aléatoire, par exemple 65001.

Ports de conteneur

Lorsque vous ajoutez une ressource de conteneur, .NET.NET Aspire attribue automatiquement un port aléatoire au conteneur. Pour spécifier un port de conteneur, configurez la ressource de conteneur avec le port souhaité :

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

Code précédent :

• Crée une ressource conteneur nommée frontend, à partir de l’image mcr.microsoft.com/dotnet/samples:aspnetapp.
• Expose un point de terminaison http en liant l’hôte au port 8000 et en le mappant au port 8080 du conteneur.

Considérez le diagramme suivant :

Méthodes d’extension de point de terminaison

Toute ressource qui implémente l’interface IResourceWithEndpoints peut utiliser les méthodes d’extension WithEndpoint. Il existe plusieurs surcharges de cette extension, ce qui vous permet de spécifier le schéma, le port de conteneur, le port hôte, le nom de variable d’environnement et si le point de terminaison est proxié.

Il existe également une surcharge qui vous permet de spécifier un délégué pour configurer le point d'accès. Cela est utile lorsque vous devez configurer le point de terminaison en fonction de l’environnement ou d’autres facteurs. Considérez le code suivant :

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

Le code précédent fournit un délégué de rappel pour configurer le point de terminaison. Le point de terminaison est nommé admin et configuré pour utiliser le schéma et le transport http, ainsi que le port hôte 17003. Le consommateur fait référence à ce point de terminaison par son nom, considérez l'appel suivant AddHttpClient.

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

Le Uri est construit à l’aide du nom du point de terminaison admin précédé de la sentinelle _. Il s’agit d’une convention pour indiquer que le segment admin est le nom du point de terminaison appartenant au service apiservice. Pour plus d’informations, consultez la découverte de service .NET.NET Aspire.

Considérations supplémentaires

Lorsqu'on appelle la méthode d'extension WithEndpoint, la surcharge callback expose la EndpointAnnotationbrute, ce qui permet au consommateur de personnaliser de nombreux aspects du point de terminaison.

La propriété AllocatedEndpoint vous permet d’obtenir ou de définir le point de terminaison d’un service. Les propriétés IsExternal et IsProxied déterminent la façon dont le point de terminaison est géré et exposé : IsExternal décide s’il doit être accessible publiquement, tandis que IsProxied garantit que DCP la gère, ce qui permet des différences de port internes et la réplication.

Pourboire

Si vous hébergez un exécutable externe qui exécute son propre proxy et rencontre des problèmes de liaison de port en raison de l'occupation du port par DCP, essayez de définir la propriété IsProxied à false. Cela empêche DCP de gérer le proxy, ce qui permet à votre exécutable de lier le port avec succès.

La propriété Name identifie le service, tandis que les propriétés Port et TargetPort spécifient respectivement les ports souhaités et d’écoute.

Pour la communication réseau, la propriété Protocol prend en charge TCP et UDP, avec un potentiel plus important à l’avenir, et la propriété Transport indique le protocole de transport (HTTP, HTTP2, HTTP3). Enfin, si le service est adressable à l’URI, la propriété UriScheme fournit le schéma d’URI pour construire l’URI du service.

Pour plus d’informations, consultez les propriétés disponibles des propriétés EndpointAnnotation.

Filtrage des points de terminaison

Tous les points de terminaison de ressources de projet .NET.NET Aspire suivent un ensemble d’heuristiques par défaut. Certains points de terminaison sont inclus dans ASPNETCORE_URLS au moment de l’exécution, certains sont publiés en tant que HTTP/HTTPS_PORTSet certaines configurations sont résolues à partir de la configuration Kestrel. Quel que soit le comportement par défaut, vous pouvez filtrer les points de terminaison inclus dans les variables d’environnement à l’aide de la méthode d’extension WithEndpointsInEnvironment :

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

Le code précédent ajoute un point de terminaison HTTPS par défaut, ainsi qu’un point de terminaison admin sur le port 19227. Toutefois, le point de terminaison admin est exclu des variables d’environnement. Cela est utile lorsque vous souhaitez exposer un point de terminaison pour une utilisation interne uniquement.