Add WithHttpHealthCheck remarks and Debug.Assert for external services (#10524)

src/Aspire.Hosting/ExternalServiceBuilderExtensions.cs

@@ -203,6 +203,16 @@ static ImmutableArray<UrlSnapshot> AddUrlIfNotPresent(ImmutableArray<UrlSnapshot
     /// A path for the health check request can be specified. The expected status code is set to <c>200</c> by default but a
     /// different one can be specified.
     /// </para>
+    /// <para>
+    /// When the external service URL is a static <see cref="ExternalServiceResource.Uri"/>, the health check is registered
+    /// with <c>AddUrlGroup</c> at configuration time and the HTTP or HTTPS scheme is validated when this method is called.
+    /// </para>
+    /// <para>
+    /// When the URL comes from a <see cref="ExternalServiceResource.UrlParameter"/>, the final address is not known at
+    /// configuration time. A <see cref="ParameterUriHealthCheck"/> is registered instead; it resolves the parameter with
+    /// <see cref="ParameterResource.GetValueAsync(CancellationToken)"/> on each probe, validates the URL, and then performs
+    /// the HTTP request.
+    /// </para>
     /// </remarks>
     [AspireExportIgnore(Reason = "Polyglot app hosts use the internal withHttpHealthCheck export wrapper.")]
     public static IResourceBuilder<ExternalServiceResource> WithHttpHealthCheck(this IResourceBuilder<ExternalServiceResource> builder, string? path = null, int? statusCode = null)
@@ -224,6 +234,8 @@ public static IResourceBuilder<ExternalServiceResource> WithHttpHealthCheck(this
             }
         }
 
+        Debug.Assert(builder.Resource.Uri is not null || builder.Resource.UrlParameter is not null, "Either Uri or UrlParameter must be provided.");
+
         statusCode ??= 200;
 
         var pathKey = path is not null ? $"_{path}" : string.Empty;