Partager via

Définir des URL de ressource personnalisées

Dans .NET.NET Aspire, les ressources qui exposent les points de terminaison configurent uniquement l’hôte et le port, qui ne sont pas connus jusqu’au moment de l’exécution. Si vous devez accéder à un chemin spécifique sur l’un de ces points de terminaison, en particulier à partir du tableau de bord, vous pouvez définir des URL de ressources personnalisées. Vous pouvez également ajouter des URL personnalisées qui ne sont pas liées à un point de terminaison. Toutes les URL personnalisées sont uniquement disponibles en mode « Exécuter », car elles sont destinées à une utilisation du tableau de bord. Cet article montre comment définir des URL personnalisées.

Comportement du point de terminaison par défaut

Par défaut, .NET.NET Aspire les ressources de projet s’appuient sur des configurations existantes telles que Kestrel ou des profils de lancement pour déterminer l’hôte et le port d’une ressource pour un point de terminaison configuré, et les points de terminaison sont toujours affichés sur le tableau de bord.

De même, vous pouvez exposer explicitement des points de terminaison à l’aide de l’API WithEndpoint . Cette API vous permet de spécifier l’hôte et le port d’une ressource, qui est ensuite utilisé pour créer l’URL par défaut de cette ressource. L’URL par défaut est généralement au format <scheme>://<host>:<port>. Pour omettre le port hôte, utilisez l’une des méthodes suivantes :

Pour plus d’informations, consultez les méthodes d’extension de point de terminaison.

Types de ressources pris en charge

Les URL de ressource personnalisées sont prises en charge pour les types de ressources suivants :

Personnaliser les URL de ressource

Utilisez la surcharge appropriée WithUrl, WithUrls, ou les API WithUrlForEndpoint sur n’importe quel générateur de ressources pris en charge pour définir des URL personnalisées pour une ressource. L’exemple suivant montre comment définir une URL personnalisée pour une ressource de projet :

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.AspireApp_Api>("api");

api.WithUrl("/admin", "Admin Portal");

builder.Build().Run();

Conseil / Astuce

Il existe une fonction surchargée qui accepte une string, vous permettant de passer n'importe quelle URL. Cela est utile pour définir des URL personnalisées qui ne sont pas directement liées au point de terminaison de la ressource.

Le code précédent affecte une référence de projet à la api variable, qui est ensuite utilisée pour créer une URL personnalisée pour l’itinéraire Admin Portal . La méthode WithUrl prend un ReferenceExpression et un nom à afficher en tant que paramètres. L’URL résultante est disponible dans le tableau de bord, comme illustré dans la capture d’écran suivante :

.NET.NET Aspire URL personnalisée du portail d’administration du tableau de bord.

Personnaliser l’URL du point de terminaison

Scalar et Swagger sont des services d’API courants qui améliorent la facilité d’utilisation des points de terminaison. Ces services sont accessibles via des URL liées aux points de terminaison déclarés.

Pour personnaliser l’URL du premier point de terminaison de ressource associé, utilisez la WithUrlForEndpoint méthode.

Si vous souhaitez ajouter une URL distincte (même pour le même point de terminaison), vous devez appeler la surcharge WithUrl qui prend une chaîne ReferenceExpression ou une chaîne interpolée, ou appeler WithUrls et ajouter l’URL à la liste Urls dans le contexte.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.AspireApp_Api>("api")
    .WithUrlForEndpoint("https", url =>
    {
        url.DisplayText = "Scalar (HTTPS)";
        url.Url = "/scalar";
    });

builder.Build().Run();

L’exemple précédent suppose que la ressource de api projet a un https point de terminaison configuré. La méthode WithUrlForEndpoint met à jour l'élément ResourceUrlAnnotation associé au point de terminaison. Dans ce cas, il affecte le texte d’affichage à Scalar (HTTPS) et le chemin relatif /scalar à l’URL.

Lorsque la ressource est démarrée, l’URL est disponible dans le tableau de bord, comme illustré dans la capture d’écran suivante :

.NET.NET Aspire tableau de bord avec une URL Scalaire personnalisée.

Vous pouvez également utiliser la surcharge qui accepte une Func<EndpointReference, ResourceUrlAnnotation> fonction de rappel. Cela vous permet de spécifier des liens approfondis sur les instances cibles EndpointReference .

Personnaliser plusieurs URL de ressource

Pour personnaliser plusieurs URL pour une ressource, utilisez la WithUrls méthode. Cette méthode vous permet de spécifier plusieurs URL pour une ressource, chacune avec son propre texte d’affichage. L’exemple suivant montre comment définir plusieurs URL pour une ressource de projet :

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.AspireApp_Api>("api")
    .WithUrls(context =>
    {
        foreach (var url in context.Urls)
        {
            if (string.IsNullOrEmpty(url.DisplayText))
            {
                url.DisplayText = $"API ({url.Endpoint?.Scheme?.ToUpper()})";
            }
        }
    });

builder.Build().Run();

Le code précédent parcourt les URL définies pour la ressource de api projet et attribue un texte d'affichage selon un schéma. Les URL obtenues sont disponibles dans le tableau de bord, comme illustré dans la capture d’écran suivante :

.NET.NET Aspire tableau de bord personnalisé avec URL nommées et commandées sur mesure.

Conseil / Astuce

Le ResourceUrlsCallbackContext expose une méthode d'extension qui vous permet d'accéder facilement aux points de terminaison nommés de la ressource sous-jacente. Appelez l’API GetEndpoint sur une instance de contexte pour y parvenir.

Cycle de vie de personnalisation d’URL

Les rappels de personnalisation d’URL s’exécutent pendant le cycle de vie du modèle d’application, notamment lors du traitement des événements BeforeResourceStartedEvent. Les URL associées aux points de terminaison deviennent actives et apparaissent dans le tableau de bord une fois que le point de terminaison lui-même devient actif. Les URL non associées aux points de terminaison deviennent actives uniquement lorsque la ressource entre dans l’état « En cours d’exécution ». Cela garantit que toutes les URL personnalisées sont correctement représentées et disponibles lorsque les ressources de l’application sont entièrement opérationnelles.

Voir aussi