Allow resources to specify custom icons to use when displayed in the dashboard (#10760)

Co-authored-by: maddymontaquila <[email protected]>
Co-authored-by: adamint <[email protected]>
Co-authored-by: DamianEdwards <[email protected]>
Co-authored-by: JamesNK <[email protected]>
Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: James Newton-King <[email protected]>

Author: 5 people

playground/Stress/Stress.AppHost/Program.cs

@@ -38,7 +38,8 @@
 // TODO: OTEL env var can be removed when OTEL libraries are updated to 1.9.0
 // See https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/RELEASENOTES.md#1100
 var serviceBuilder = builder.AddProject<Projects.Stress_ApiService>("stress-apiservice", launchProfileName: null)
-    .WithEnvironment("OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE", "true");
+    .WithEnvironment("OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE", "true")
+    .WithIconName("Server");
 serviceBuilder
     .WithEnvironment("HOST", $"{serviceBuilder.GetEndpoint("http").Property(EndpointProperty.Host)}")
     .WithEnvironment("PORT", $"{serviceBuilder.GetEndpoint("http").Property(EndpointProperty.Port)}")
@@ -135,7 +136,8 @@
 
 for (var i = 0; i < 3; i++)
 {
-    var resourceBuilder = builder.AddProject<Projects.Stress_Empty>($"empty-{i:0000}");
+    var resourceBuilder = builder.AddProject<Projects.Stress_Empty>($"empty-{i:0000}")
+                                .WithIconName("Document");
     if (previousResourceBuilder != null)
     {
         resourceBuilder.WaitFor(previousResourceBuilder);

src/Aspire.Dashboard/Model/ResourceIconHelpers.cs

@@ -10,10 +10,21 @@ namespace Aspire.Dashboard.Model;
 internal static class ResourceIconHelpers
 {
     /// <summary>
-    /// Maps a resource to a default icon.
+    /// Maps a resource to an icon, checking for custom icons first, then falling back to default icons.
     /// </summary>
     public static Icon GetIconForResource(ResourceViewModel resource, IconSize desiredSize, IconVariant desiredVariant = IconVariant.Filled)
     {
+        // Check if the resource has a custom icon specified
+        if (!string.IsNullOrWhiteSpace(resource.IconName))
+        {
+            var customIcon = IconResolver.ResolveIconName(resource.IconName, desiredSize, resource.IconVariant ?? IconVariant.Filled);
+            if (customIcon != null)
+            {
+                return customIcon;
+            }
+        }
+
+        // Fall back to default icons based on resource type
         var icon = resource.ResourceType switch
         {
             KnownResourceTypes.Executable => IconResolver.ResolveIconName("Apps", desiredSize, desiredVariant),

src/Aspire.Dashboard/Model/ResourceViewModel.cs

@@ -43,6 +43,8 @@ public sealed class ResourceViewModel
     public HealthStatus? HealthStatus { get; private set; }
     public bool IsHidden { private get; init; }
     public bool SupportsDetailedTelemetry { get; init; }
+    public string? IconName { get; init; }
+    public IconVariant? IconVariant { get; init; }
 
     /// <summary>
     /// Gets the cached addresses for this resource that can be used for peer matching.

src/Aspire.Dashboard/ServiceClient/Partials.cs

@@ -40,7 +40,9 @@ public ResourceViewModel ToViewModel(IKnownPropertyLookup knownPropertyLookup, I
                 Commands = GetCommands(),
                 HealthReports = HealthReports.Select(ToHealthReportViewModel).OrderBy(vm => vm.Name).ToImmutableArray(),
                 IsHidden = IsHidden,
-                SupportsDetailedTelemetry = SupportsDetailedTelemetry
+                SupportsDetailedTelemetry = SupportsDetailedTelemetry,
+                IconName = HasIconName ? IconName : null,
+                IconVariant = HasIconVariant ? MapResourceIconVariant(IconVariant) : null
             };
         }
         catch (Exception ex)
@@ -131,6 +133,16 @@ static FluentUIIconVariant MapIconVariant(IconVariant iconVariant)
                 };
             }
         }
+
+        static FluentUIIconVariant MapResourceIconVariant(IconVariant iconVariant)
+        {
+            return iconVariant switch
+            {
+                IconVariant.Regular => FluentUIIconVariant.Regular,
+                IconVariant.Filled => FluentUIIconVariant.Filled,
+                _ => throw new InvalidOperationException("Unknown icon variant: " + iconVariant),
+            };
+        }
     }
 
     private ImmutableDictionary<string, ResourcePropertyViewModel> CreatePropertyViewModels(RepeatedField<ResourceProperty> properties, IKnownPropertyLookup knownPropertyLookup, ILogger logger)

src/Aspire.Hosting/ApplicationModel/CustomResourceSnapshot.cs

@@ -133,6 +133,17 @@ internal init
     /// </summary>
     internal bool SupportsDetailedTelemetry { get; init; }
 
+    /// <summary>
+    /// The custom icon name for the resource. This should be a valid FluentUI icon name.
+    /// If not specified, the dashboard will use default icons based on the resource type.
+    /// </summary>
+    public string? IconName { get; init; }
+
+    /// <summary>
+    /// The custom icon variant for the resource.
+    /// </summary>
+    public IconVariant? IconVariant { get; init; }
+
     internal static HealthStatus? ComputeHealthStatus(ImmutableArray<HealthReportSnapshot> healthReports, string? state)
     {
         if (state != KnownResourceStates.Running)

src/Aspire.Hosting/ApplicationModel/ResourceIconAnnotation.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+
+namespace Aspire.Hosting.ApplicationModel;
+
+/// <summary>
+/// Specifies the icon to use when displaying a resource in the dashboard.
+/// </summary>
+/// <param name="iconName">The name of the FluentUI icon to use.</param>
+/// <param name="iconVariant">The variant of the icon (Regular or Filled).</param>
+[DebuggerDisplay("Type = {GetType().Name,nq}, IconName = {IconName}, IconVariant = {IconVariant}")]
+public sealed class ResourceIconAnnotation(string iconName, IconVariant iconVariant = IconVariant.Filled) : IResourceAnnotation
+{
+    /// <summary>
+    /// Gets the name of the FluentUI icon to use for the resource.
+    /// </summary>
+    /// <remarks>
+    /// The icon name should be a valid FluentUI icon name. 
+    /// See https://aka.ms/fluentui-system-icons for available icons.
+    /// </remarks>
+    public string IconName { get; } = iconName ?? throw new ArgumentNullException(nameof(iconName));
+
+    /// <summary>
+    /// Gets the variant of the icon (Regular or Filled).
+    /// </summary>
+    public IconVariant IconVariant { get; } = iconVariant;
+}

src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

@@ -574,6 +574,8 @@ public Task PublishUpdateAsync(IResource resource, string resourceId, Func<Custo
 
             newState = UpdateCommands(resource, newState);
 
+            newState = UpdateIcons(resource, newState);
+
             notificationState.LastSnapshot = newState;
 
             OnResourceUpdated?.Invoke(new ResourceEvent(resource, resourceId, newState));
@@ -716,6 +718,36 @@ static ResourceCommandSnapshot CreateCommandFromAnnotation(ResourceCommandAnnota
         }
     }
 
+    /// <summary>
+    /// Use icon annotations to update resource snapshot.
+    /// </summary>
+    private static CustomResourceSnapshot UpdateIcons(IResource resource, CustomResourceSnapshot previousState)
+    {
+        var iconAnnotation = resource.Annotations.OfType<ResourceIconAnnotation>().FirstOrDefault();
+        
+        if (iconAnnotation == null)
+        {
+            // No icon annotation, keep existing icon information
+            return previousState;
+        }
+
+        // Only update icon information if not already set
+        var newIconName = string.IsNullOrEmpty(previousState.IconName) ? iconAnnotation.IconName : previousState.IconName;
+        var newIconVariant = previousState.IconVariant ?? iconAnnotation.IconVariant;
+
+        // Only create new snapshot if there are changes
+        if (previousState.IconName == newIconName && previousState.IconVariant == newIconVariant)
+        {
+            return previousState;
+        }
+
+        return previousState with 
+        { 
+            IconName = newIconName,
+            IconVariant = newIconVariant
+        };
+    }
+
     /// <summary>
     /// Updates the snapshot of the <see cref="CustomResourceSnapshot"/> for a resource.
     /// </summary>

src/Aspire.Hosting/Dashboard/DashboardServiceData.cs

@@ -57,7 +57,9 @@ static GenericResourceSnapshot CreateResourceSnapshot(IResource resource, string
                     HealthReports = snapshot.HealthReports,
                     Commands = snapshot.Commands,
                     IsHidden = snapshot.IsHidden,
-                    SupportsDetailedTelemetry = snapshot.SupportsDetailedTelemetry
+                    SupportsDetailedTelemetry = snapshot.SupportsDetailedTelemetry,
+                    IconName = snapshot.IconName,
+                    IconVariant = snapshot.IconVariant
                 };
             }
 

src/Aspire.Hosting/Dashboard/ResourceSnapshot.cs

@@ -30,6 +30,8 @@ internal abstract class ResourceSnapshot
     public required ImmutableArray<ResourceCommandSnapshot> Commands { get; init; }
     public required bool IsHidden { get; init; }
     public required bool SupportsDetailedTelemetry { get; init; }
+    public required string? IconName { get; init; }
+    public required IconVariant? IconVariant { get; init; }
 
     protected abstract IEnumerable<(string Key, Value Value, bool IsSensitive)> GetProperties();
 

src/Aspire.Hosting/Dashboard/proto/Partials.cs

@@ -22,6 +22,16 @@ public static Resource FromSnapshot(ResourceSnapshot snapshot)
             SupportsDetailedTelemetry = snapshot.SupportsDetailedTelemetry
         };
 
+        if (snapshot.IconName is not null)
+        {
+            resource.IconName = snapshot.IconName;
+        }
+
+        if (snapshot.IconVariant is not null)
+        {
+            resource.IconVariant = MapIconVariant(snapshot.IconVariant);
+        }
+
         if (snapshot.CreationTimeStamp.HasValue)
         {
             resource.CreatedAt = Timestamp.FromDateTime(snapshot.CreationTimeStamp.Value.ToUniversalTime());