| File: ResourceTraitBuilderExtensions.cs | Web Access |
| Project: src\src\Aspire.Hosting\Aspire.Hosting.csproj (Aspire.Hosting) |
// Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. using Aspire.Dashboard.Model; using Aspire.Hosting.ApplicationModel; namespace Aspire.Hosting; /// <summary>Provides methods for adding resource metadata and dashboard defaults.</summary> public static class ResourceTraitBuilderExtensions { /// <summary>Adds immutable, non-sensitive metadata to a resource. Repeated names add multiple values.</summary> /// <typeparam name="T">The resource type.</typeparam> /// <param name="builder">The resource builder.</param> /// <param name="name">The case-sensitive trait name.</param> /// <param name="value">The trait value. Do not include secrets.</param> /// <returns>The resource builder.</returns> [AspireExport] public static IResourceBuilder<T> WithTrait<T>(this IResourceBuilder<T> builder, string name, string value) where T : IResource { ArgumentNullException.ThrowIfNull(builder); var annotation = new TraitAnnotation(name, value); // WithTags adds its tags through here, and a reserved tag added directly is still a tag. if (name == KnownResourceTraits.Tag && (value.Length > 50 || value != string.Join(' ', value.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries)))) { throw new ArgumentException("Tags must be at most 50 characters and use single spaces between words, without leading or trailing whitespace.", nameof(value)); } return builder.WithAnnotation(annotation); } /// <summary>Adds AppHost-defined dashboard tags that users cannot remove. Repeated calls add tags.</summary> /// <typeparam name="T">The resource type.</typeparam> /// <param name="builder">The resource builder.</param> /// <param name="tags">The tags, each up to 50 characters with single spaces between words.</param> /// <returns>The resource builder.</returns> [AspireExportIgnore(Reason = "ReadOnlySpan is not supported by ATS; use the withTags array adapter for polyglot SDKs.")] public static IResourceBuilder<T> WithTags<T>(this IResourceBuilder<T> builder, params ReadOnlySpan<string> tags) where T : IResource { ArgumentNullException.ThrowIfNull(builder); foreach (var tag in tags) { builder.WithTrait(KnownResourceTraits.Tag, tag); } return builder; } /// <summary>Adds AppHost-defined dashboard tags that users cannot remove. Repeated calls add tags.</summary> /// <param name="builder">The resource builder.</param> /// <param name="tags">The tags, each up to 50 characters with single spaces between words.</param> /// <returns>The resource builder.</returns> [AspireExport("withTags")] internal static IResourceBuilder<T> WithTagsForPolyglot<T>(this IResourceBuilder<T> builder, string[] tags) where T : IResource { ArgumentNullException.ThrowIfNull(tags); return builder.WithTags(tags.AsSpan()); } /// <summary> /// Sets the default display order of the resource in lists of resources, such as the dashboard's. A saved ordering /// takes precedence. Repeated calls replace the order. /// </summary> /// <typeparam name="T">The resource type.</typeparam> /// <param name="builder">The resource builder.</param> /// <param name="order"> /// A relative sort key. Higher values appear first, consistent with <see cref="ResourceUrlAnnotation.DisplayOrder"/>. /// Resources without a display order are treated as having an order of 0, so a negative value moves a resource after them. /// </param> /// <returns>The resource builder.</returns> [AspireExport] public static IResourceBuilder<T> WithDisplayOrder<T>(this IResourceBuilder<T> builder, int order) where T : IResource => builder.WithAnnotation(new DisplayOrderAnnotation(order), ResourceAnnotationMutationBehavior.Replace); }