Move resource name validation to AddResource/Build with SuppressNameValidationAnnotation

Resource names have a 64-character limit enforced by ModelName.ValidateName.
Internal resources like ProjectRebuilderResource, JavaScriptInstallerResource,
PythonInstallerResource, and PythonVenvCreatorResource append suffixes to
user-provided resource names, which can push them over the limit.

Previously, validation happened in the Resource constructor, requiring internal
skip-validation constructors that couldn't be accessed from external assemblies.

This change moves validation from the Resource constructor to
DistributedApplicationBuilder.AddResource() and Build(), and introduces a
public SuppressNameValidationAnnotation that any resource can use to opt out
of name validation before being added to the app model.

Author: JamesNK

src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs

@@ -1134,6 +1134,7 @@ private static void AddInstaller<TResource>(IResourceBuilder<TResource> resource
             }
 
             var installer = new JavaScriptInstallerResource(installerName, resource.Resource.WorkingDirectory);
+            installer.Annotations.Add(new SuppressNameValidationAnnotation());
             var installerBuilder = resource.ApplicationBuilder.AddResource(installer)
                 .WithParentRelationship(resource.Resource)
                 .ExcludeFromManifest()

src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs

@@ -1320,6 +1320,7 @@ private static void AddInstaller<T>(IResourceBuilder<T> builder, bool install) w
             }
 
             var installer = new PythonInstallerResource(installerName, builder.Resource);
+            installer.Annotations.Add(new SuppressNameValidationAnnotation());
             var installerBuilder = builder.ApplicationBuilder.AddResource(installer)
                 .WithParentRelationship(builder.Resource)
                 .ExcludeFromManifest()
@@ -1393,6 +1394,7 @@ private static void CreateVenvCreatorIfNeeded<T>(IResourceBuilder<T> builder) wh
 
         // Create new venv creator resource
         var venvCreator = new PythonVenvCreatorResource(venvCreatorName, builder.Resource, venvPath);
+        venvCreator.Annotations.Add(new SuppressNameValidationAnnotation());
 
         // Determine which Python command to use
         string pythonCommand;

src/Aspire.Hosting/ApplicationModel/Resource.cs

@@ -27,7 +27,7 @@ public abstract class Resource : IResource
     /// <param name="name">The name of the resource.</param>
     protected Resource(string name)
     {
-        ModelName.ValidateName(nameof(Resource), name);
+        ArgumentNullException.ThrowIfNull(name);
 
         Name = name;
     }

src/Aspire.Hosting/ApplicationModel/SuppressNameValidationAnnotation.cs

@@ -0,0 +1,19 @@
+// 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>
+/// Represents an annotation that indicates the resource name should not be validated against naming rules when
+/// the resource is added to the application model.
+/// </summary>
+/// <remarks>
+/// This is useful for internal resources (such as installers or rebuilders) that append suffixes to user-provided
+/// resource names and may exceed the 64-character name limit, but are never deployed.
+/// </remarks>
+[DebuggerDisplay("Type = {GetType().Name,nq}")]
+public sealed class SuppressNameValidationAnnotation : IResourceAnnotation
+{
+}

src/Aspire.Hosting/DistributedApplicationBuilder.cs

@@ -735,6 +735,15 @@ public DistributedApplication Build()
                 throw new DistributedApplicationException($"Multiple resources with the name '{duplicateResourceName}'. Resource names are case-insensitive.");
             }
 
+            // Validate resource names. Resources added directly to the collection bypass AddResource validation.
+            foreach (var resource in Resources)
+            {
+                if (!resource.HasAnnotationOfType<SuppressNameValidationAnnotation>())
+                {
+                    ModelName.ValidateName(nameof(Resource), resource.Name);
+                }
+            }
+
             var application = new DistributedApplication(_innerBuilder.Build());
 
             _executionContextOptions.ServiceProvider = application.Services.GetRequiredService<IServiceProvider>();
@@ -753,6 +762,11 @@ public IResourceBuilder<T> AddResource<T>(T resource) where T : IResource
     {
         ArgumentNullException.ThrowIfNull(resource);
 
+        if (!resource.HasAnnotationOfType<SuppressNameValidationAnnotation>())
+        {
+            ModelName.ValidateName(nameof(Resource), resource.Name);
+        }
+
         if (Resources.FirstOrDefault(r => string.Equals(r.Name, resource.Name, StringComparisons.ResourceName)) is { } existingResource)
         {
             throw new DistributedApplicationException($"Cannot add resource of type '{resource.GetType()}' with name '{resource.Name}' because resource of type '{existingResource.GetType()}' with that name already exists. Resource names are case-insensitive.");

src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs

@@ -921,6 +921,7 @@ private static void AddRebuilderResource<TProjectResource>(IResourceBuilder<TPro
 
         var rebuilderName = $"{projectResource.Name}-rebuilder";
         var rebuilder = new ProjectRebuilderResource(rebuilderName, projectResource, projectMetadata.ProjectPath);
+        rebuilder.Annotations.Add(new SuppressNameValidationAnnotation());
         var rebuilderBuilder = builder.ApplicationBuilder.AddResource(rebuilder);
 
         rebuilderBuilder

tests/Aspire.Hosting.JavaScript.Tests/PackageInstallationTests.cs

@@ -561,6 +561,21 @@ public void WithBun_DefaultsArgsInPublishMode()
         Assert.Equal(["install", "--frozen-lockfile"], installCommand.Args);
     }
 
+    [Fact]
+    public void InstallerResourceHasSuppressNameValidationAnnotation()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        builder.AddJavaScriptApp("nodeApp", "./test-app")
+            .WithNpm(install: true);
+
+        using var app = builder.Build();
+
+        var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
+        var installerResource = Assert.Single(appModel.Resources.OfType<JavaScriptInstallerResource>());
+        Assert.True(installerResource.TryGetLastAnnotation<SuppressNameValidationAnnotation>(out _));
+    }
+
     [UnsafeAccessor(UnsafeAccessorKind.Method, Name = "ExecuteBeforeStartHooksAsync")]
     private static extern Task ExecuteBeforeStartHooksAsync(DistributedApplication app, CancellationToken cancellationToken);
 }

tests/Aspire.Hosting.Python.Tests/AddPythonAppTests.cs

@@ -2390,6 +2390,49 @@ public async Task WithUv_InstallFalse_CreatesInstallerWithExplicitStart()
         Assert.Empty(waitAnnotations);
     }
 
+    [Fact]
+    public void InstallerResourceHasSuppressNameValidationAnnotation()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create().WithTestAndResourceLogging(outputHelper);
+        using var tempDir = new TestTempDirectory();
+
+        var scriptName = "main.py";
+
+        builder.AddPythonApp("pythonProject", tempDir.Path, scriptName)
+            .WithPip();
+
+        var app = builder.Build();
+        var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
+
+        var installerResource = appModel.Resources.OfType<PythonInstallerResource>().Single();
+        Assert.True(installerResource.HasAnnotationOfType<SuppressNameValidationAnnotation>());
+    }
+
+    [Fact]
+    public void VenvCreatorResourceHasSuppressNameValidationAnnotation()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create().WithTestAndResourceLogging(outputHelper);
+        using var tempDir = new TestTempDirectory();
+        using var tempVenvDir = new TestTempDirectory();
+
+        var scriptName = "main.py";
+        var scriptPath = Path.Combine(tempDir.Path, scriptName);
+        File.WriteAllText(scriptPath, "print('Hello')");
+
+        var requirementsPath = Path.Combine(tempDir.Path, "requirements.txt");
+        File.WriteAllText(requirementsPath, "requests");
+
+        builder.AddPythonApp("pythonProject", tempDir.Path, scriptName)
+            .WithVirtualEnvironment(tempVenvDir.Path, createIfNotExists: true);
+
+        var app = builder.Build();
+        var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
+
+        var venvCreatorResource = appModel.Resources.OfType<PythonVenvCreatorResource>().SingleOrDefault();
+        Assert.NotNull(venvCreatorResource);
+        Assert.True(venvCreatorResource.HasAnnotationOfType<SuppressNameValidationAnnotation>());
+    }
+
     /// <summary>
     /// Helper method to manually trigger BeforeStartEvent for tests.
     /// This is needed because BeforeStartEvent is normally triggered during StartAsync(),

tests/Aspire.Hosting.Tests/DistributedApplicationBuilderTests.cs

@@ -347,10 +347,63 @@ public void LegacyShaUsesProjectNameShaInPublishMode()
         Assert.Equal(projectNameSha, legacySha);
     }
 
+    [Fact]
+    public void AddResource_InvalidName_Error()
+    {
+        var appBuilder = DistributedApplication.CreateBuilder();
+
+        var longName = new string('a', 65);
+        var resource = new ContainerResource(longName);
+
+        var ex = Assert.Throws<ArgumentException>(() => appBuilder.AddResource(resource));
+        Assert.Equal($"Resource name '{longName}' is invalid. Name must be between 1 and 64 characters long. (Parameter 'name')", ex.Message);
+    }
+
+    [Fact]
+    public void AddResource_InvalidNameWithExcludeAnnotation_Success()
+    {
+        var appBuilder = DistributedApplication.CreateBuilder();
+
+        var longName = new string('a', 65);
+        var resource = new ContainerResource(longName);
+        resource.Annotations.Add(new SuppressNameValidationAnnotation());
+
+        appBuilder.AddResource(resource);
+
+        Assert.Contains(appBuilder.Resources, r => r.Name == longName);
+    }
+
+    [Fact]
+    public void Build_InvalidName_Error()
+    {
+        var appBuilder = DistributedApplication.CreateBuilder();
+
+        var longName = new string('a', 65);
+        appBuilder.Resources.Add(new ContainerResource(longName));
+
+        var ex = Assert.Throws<ArgumentException>(appBuilder.Build);
+        Assert.Equal($"Resource name '{longName}' is invalid. Name must be between 1 and 64 characters long. (Parameter 'name')", ex.Message);
+    }
+
+    [Fact]
+    public void Build_InvalidNameWithExcludeAnnotation_Success()
+    {
+        var appBuilder = DistributedApplication.CreateBuilder();
+
+        var longName = new string('a', 65);
+        var resource = new ContainerResource(longName);
+        resource.Annotations.Add(new SuppressNameValidationAnnotation());
+        appBuilder.Resources.Add(resource);
+
+        var app = appBuilder.Build();
+
+        Assert.NotNull(app);
+    }
+
     private sealed class TestResource : IResource
     {
         public string Name => nameof(TestResource);
 
-        public ResourceAnnotationCollection Annotations => throw new NotImplementedException();
+        public ResourceAnnotationCollection Annotations { get; } = new();
     }
 }

tests/Aspire.Hosting.Tests/ProjectResourceTests.cs

@@ -932,6 +932,20 @@ public void AddCSharpAppAddsSupportsDebuggingAnnotationInRunMode()
         Assert.Equal("project", annotation.LaunchConfigurationType);
     }
 
+    [Fact]
+    public void AddProjectCreatesRebuilderWithSuppressNameValidationAnnotation()
+    {
+        using var builder = TestDistributedApplicationBuilder.Create(DistributedApplicationOperation.Run);
+        builder.AddProject<TestProject>("projectName", options => { options.ExcludeLaunchProfile = true; });
+
+        var app = builder.Build();
+        var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
+
+        var rebuilder = appModel.Resources.OfType<ProjectRebuilderResource>().SingleOrDefault();
+        Assert.NotNull(rebuilder);
+        Assert.True(rebuilder.HasAnnotationOfType<SuppressNameValidationAnnotation>());
+    }
+
     internal static IDistributedApplicationBuilder CreateBuilder(string[]? args = null, DistributedApplicationOperation operation = DistributedApplicationOperation.Publish)
     {
         var resolvedArgs = new List<string>();