Added triple slash XML comments for public-facing Aspire.Hosting APIs. (dotnet#622)

* Added triple slash XML comments for public-facing APIs.

Author: IEvangelist

src/Aspire.Hosting/ApplicationModel/AllocatedEndpointAnnotation.cs

@@ -6,9 +6,20 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents an endpoint allocated for a service instance.
+/// </summary>
 [DebuggerDisplay("Type = {GetType().Name,nq}, Name = {Name}, UriString = {UriString}, BindingNameQualifiedUriString = {BindingNameQualifiedUriString}")]
 public class AllocatedEndpointAnnotation : IResourceAnnotation
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AllocatedEndpointAnnotation"/> class.
+    /// </summary>
+    /// <param name="name">The name of the endpoint.</param>
+    /// <param name="protocol">The protocol used by the endpoint.</param>
+    /// <param name="address">The IP address of the endpoint.</param>
+    /// <param name="port">The port number of the endpoint.</param>
+    /// <param name="scheme">The URI scheme used by the endpoint.</param>
     public AllocatedEndpointAnnotation(string name, ProtocolType protocol, string address, int port, string scheme)
     {
         ArgumentNullException.ThrowIfNullOrEmpty(name);
@@ -48,6 +59,9 @@ public AllocatedEndpointAnnotation(string name, ProtocolType protocol, string ad
     /// </summary>
     public string UriScheme { get; private set; }
 
+    /// <summary>
+    /// Endpoint in string representation formatted as <c>"Address:Port"</c>.
+    /// </summary>
     public string EndPointString => $"{Address}:{Port}";
 
     /// <summary>
@@ -59,5 +73,10 @@ public AllocatedEndpointAnnotation(string name, ProtocolType protocol, string ad
     /// URI in string representation.
     /// </summary>
     public string UriString => $"{UriScheme}://{EndPointString}";
+
+    /// <summary>
+    /// Returns a string representation of the allocated endpoint URI.
+    /// </summary>
+    /// <returns>The URI string, <see cref="UriString"/>.</returns>
     public override string ToString() => UriString;
 }

src/Aspire.Hosting/ApplicationModel/ContainerImageAnnotation.cs

@@ -5,10 +5,24 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents an annotation for a container image.
+/// </summary>
 [DebuggerDisplay("Type = {GetType().Name,nq}, Image = {Image}, Tag = {Tag}")]
 public sealed class ContainerImageAnnotation : IResourceAnnotation
 {
+    /// <summary>
+    /// Gets or sets the registry for the container image.
+    /// </summary>
     public string? Registry { get; set; }
+
+    /// <summary>
+    /// Gets or sets the image for the container.
+    /// </summary>
     public required string Image { get; set; }
+
+    /// <summary>
+    /// Gets or sets the tag for the container image.
+    /// </summary>
     public required string Tag { get; set; }
 }

src/Aspire.Hosting/ApplicationModel/ContainerResource.cs

@@ -3,6 +3,10 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a container resource that implements <see cref="IResourceWithEnvironment"/> 
+/// and <see cref="IResourceWithBindings"/>.
+/// </summary>
 public class ContainerResource(string name) : Resource(name), IResourceWithEnvironment, IResourceWithBindings
 {
 }

src/Aspire.Hosting/ApplicationModel/DistributedApplicationModel.cs

@@ -5,10 +5,20 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a distributed application.
+/// </summary>
+/// <param name="resources">The resource collection used to initiate the model.</param>
 [DebuggerDisplay("Name = {Name}, Resources = {Resources.Count}")]
 public class DistributedApplicationModel(IResourceCollection resources)
 {
+    /// <summary>
+    /// Gets the collection of resources associated with the distributed application.
+    /// </summary>
     public IResourceCollection Resources { get; } = resources;
 
+    /// <summary>
+    /// Gets or sets the name of the distributed application.
+    /// </summary>
     public string? Name { get; set; }
 }

src/Aspire.Hosting/ApplicationModel/EndpointReference.cs

@@ -3,11 +3,26 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents an endpoint reference for a resource with bindings.
+/// </summary>
+/// <param name="owner">The resource with bindings that owns the endpoint reference.</param>
+/// <param name="bindingName">The name of the binding.</param>
 public sealed class EndpointReference(IResourceWithBindings owner, string bindingName)
 {
+    /// <summary>
+    /// Gets the owner of the endpoint reference.
+    /// </summary>
     public IResourceWithBindings Owner { get; } = owner;
+
+    /// <summary>
+    /// Gets the name of the binding associated with the endpoint reference.
+    /// </summary>
     public string BindingName { get; } = bindingName;
 
+    /// <summary>
+    /// Gets the URI string for the endpoint reference.
+    /// </summary>
     public string UriString
     {
         get

src/Aspire.Hosting/ApplicationModel/EnvironmentCallbackAnnotation.cs

@@ -3,22 +3,41 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents an annotation that provides a callback to modify the environment variables of an application.
+/// </summary>
 public class EnvironmentCallbackAnnotation : IResourceAnnotation
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EnvironmentCallbackAnnotation"/> class with the specified name and callback function.
+    /// </summary>
+    /// <param name="name">The name of the environment variable to set.</param>
+    /// <param name="callback">The callback function that returns the value to set the environment variable to.</param>
     public EnvironmentCallbackAnnotation(string name, Func<string> callback)
     {
         Callback = (c) => c.EnvironmentVariables[name] = callback();
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EnvironmentCallbackAnnotation"/> class with the specified callback action.
+    /// </summary>
+    /// <param name="callback">The callback action to be executed.</param>
     public EnvironmentCallbackAnnotation(Action<Dictionary<string, string>> callback)
     {
         Callback = (c) => callback(c.EnvironmentVariables);
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EnvironmentCallbackAnnotation"/> class with the specified callback.
+    /// </summary>
+    /// <param name="callback">The callback to be invoked.</param>
     public EnvironmentCallbackAnnotation(Action<EnvironmentCallbackContext> callback)
     {
         Callback = callback;
     }
 
+    /// <summary>
+    /// Gets or sets the callback action to be executed when the environment is being built.
+    /// </summary>
     public Action<EnvironmentCallbackContext> Callback { get; private set; }
 }

src/Aspire.Hosting/ApplicationModel/EnvironmentCallbackContext.cs

@@ -3,8 +3,20 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a callback context for environment variables associated with a publisher.
+/// </summary>
+/// <param name="publisherName">The name of the publisher.</param>
+/// <param name="environmentVariables">The environment variables associated with the publisher.</param>
 public class EnvironmentCallbackContext(string publisherName, Dictionary<string, string>? environmentVariables = null)
 {
+    /// <summary>
+    /// Gets the environment variables associated with the callback context.
+    /// </summary>
     public Dictionary<string, string> EnvironmentVariables { get; } = environmentVariables ?? new();
+
+    /// <summary>
+    /// Gets the name of the publisher associated with the callback context.
+    /// </summary>
     public string PublisherName { get; } = publisherName;
 }

src/Aspire.Hosting/ApplicationModel/ExecutableArgsCallbackAnnotation.cs

@@ -3,12 +3,14 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
-public class ExecutableArgsCallbackAnnotation : IResourceAnnotation
+/// <summary>
+/// Represents an annotation that provides a callback to be executed with a list of command-line arguments when an executable resource is started.
+/// </summary>
+/// <param name="callback">The callback action to be executed.</param>
+public class ExecutableArgsCallbackAnnotation(Action<IList<string>> callback) : IResourceAnnotation
 {
-    public ExecutableArgsCallbackAnnotation(Action<IList<string>> callback)
-    {
-        Callback = callback;
-    }
-
-    public Action<IList<string>> Callback { get; private set; }
+    /// <summary>
+    /// Gets the callback action to be executed when the executable arguments are parsed.
+    /// </summary>
+    public Action<IList<string>> Callback { get; } = callback;
 }

src/Aspire.Hosting/ApplicationModel/ExecutableResource.cs

@@ -3,9 +3,27 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a resource that can be executed as a standalone process.
+/// </summary>
+/// <param name="name">The name of the resource.</param>
+/// <param name="command">The command to execute.</param>
+/// <param name="workingDirectory">The working directory of the executable.</param>
+/// <param name="args">The arguments to pass to the executable.</param>
 public class ExecutableResource(string name, string command, string workingDirectory, string[]? args) : Resource(name), IResourceWithEnvironment, IResourceWithBindings
 {
+    /// <summary>
+    /// Gets the command associated with this executable resource.
+    /// </summary>
     public string Command { get; } = command;
+
+    /// <summary>
+    /// Gets the working directory for the executable resource.
+    /// </summary>
     public string WorkingDirectory { get; } = workingDirectory;
+    
+    /// <summary>
+    /// Gets the command line arguments passed to the executable resource.
+    /// </summary>
     public string[]? Args { get; } = args;
 }

src/Aspire.Hosting/ApplicationModel/IResource.cs

@@ -3,8 +3,18 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a resource that can be hosted by an application.
+/// </summary>
 public interface IResource
 {
+    /// <summary>
+    /// Gets the name of the resource.
+    /// </summary>
     string Name { get; }
+
+    /// <summary>
+    /// Gets the annotations associated with the resource.
+    /// </summary>
     ResourceMetadataCollection Annotations { get; }
 }

src/Aspire.Hosting/ApplicationModel/IResourceAnnotation.cs

@@ -3,6 +3,9 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents an annotation for a resource.
+/// </summary>
 public interface IResourceAnnotation
 {
 }

src/Aspire.Hosting/ApplicationModel/IResourceBuilder.cs

@@ -3,10 +3,34 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Defines a builder for creating resources of type <typeparamref name="T"/>.
+/// </summary>
+/// <typeparam name="T">The type of resource to build.</typeparam>
 public interface IResourceBuilder<out T> where T : IResource
 {
+    /// <summary>
+    /// Gets the distributed application builder associated with this resource builder.
+    /// </summary>
     IDistributedApplicationBuilder ApplicationBuilder { get; }
+
+    /// <summary>
+    /// Gets the resource of type <typeparamref name="T"/> that is being built.
+    /// </summary>
     T Resource { get; }
+
+    /// <summary>
+    /// Adds an annotation to the resource being built.
+    /// </summary>
+    /// <typeparam name="TAnnotation">The type of the annotation to add.</typeparam>
+    /// <returns>The resource builder instance.</returns>
     IResourceBuilder<T> WithAnnotation<TAnnotation>() where TAnnotation : IResourceAnnotation, new() => WithAnnotation(new TAnnotation());
+    
+    /// <summary>
+    /// Adds an annotation to the resource being built.
+    /// </summary>
+    /// <typeparam name="TAnnotation">The type of the annotation to add.</typeparam>
+    /// <param name="annotation">The annotation to add.</param>
+    /// <returns>The resource builder instance.</returns>
     IResourceBuilder<T> WithAnnotation<TAnnotation>(TAnnotation annotation) where TAnnotation : IResourceAnnotation;
 }

src/Aspire.Hosting/ApplicationModel/IResourceCollection.cs

@@ -3,6 +3,9 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a collection of resources.
+/// </summary>
 public interface IResourceCollection : IList<IResource>
 {
 }

src/Aspire.Hosting/ApplicationModel/IResourceWithBindings.cs

@@ -3,8 +3,17 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a resource that has bindings associated with it.
+/// </summary>
 public interface IResourceWithBindings : IResource
 {
+    /// <summary>
+    /// Gets an endpoint reference for the specified binding.
+    /// </summary>
+    /// <param name="bindingName">The name of the binding.</param>
+    /// <returns>An <see cref="EndpointReference"/> object representing the endpoint reference 
+    /// for the specified binding.</returns>
     public EndpointReference GetEndpoint(string bindingName)
     {
         return new EndpointReference(this, bindingName);

src/Aspire.Hosting/ApplicationModel/IResourceWithConnectionString.cs

@@ -3,7 +3,14 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a resource that has a connection string associated with it.
+/// </summary>
 public interface IResourceWithConnectionString : IResource
 {
+    /// <summary>
+    /// Gets the connection string associated with the resource.
+    /// </summary>
+    /// <returns>The connection string associated with the resource, when one is available.</returns>
     public string? GetConnectionString();
 }

src/Aspire.Hosting/ApplicationModel/IResourceWithEnvironment.cs

@@ -3,6 +3,9 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a resource that is associated with an environment.
+/// </summary>
 public interface IResourceWithEnvironment : IResource
 {
 }

src/Aspire.Hosting/ApplicationModel/IResourceWithParentOfT.cs

@@ -3,7 +3,14 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents a resource that has a parent resource of type <typeparamref name="T"/>.
+/// </summary>
+/// <typeparam name="T">The type of the parent resource.</typeparam>
 public interface IResourceWithParent<T> : IResource where T : IResource
 {
-    public T Parent { get; }
+    /// <summary>
+    /// Gets the parent resource of type <typeparamref name="T"/>.
+    /// </summary>
+    T Parent { get; }
 }

src/Aspire.Hosting/ApplicationModel/ManifestPublishingCallbackAnnotation.cs

@@ -5,8 +5,19 @@
 
 namespace Aspire.Hosting.ApplicationModel;
 
+/// <summary>
+/// Represents an annotation that provides a callback to be executed during manifest publishing.
+/// </summary>
 public class ManifestPublishingCallbackAnnotation(Action<Utf8JsonWriter>? callback) : IResourceAnnotation
 {
+    /// <summary>
+    /// Gets the callback action for publishing the manifest.
+    /// </summary>
     public Action<Utf8JsonWriter>? Callback { get; } = callback;
-    public static ManifestPublishingCallbackAnnotation Ignore { get; } = new ManifestPublishingCallbackAnnotation(null);
+    
+    /// <summary>
+    /// Represents a <see langword="null"/>-based callback annotation for manifest 
+    /// publishing used in scenarios where it's ignored.
+    /// </summary>
+    public static ManifestPublishingCallbackAnnotation Ignore { get; } = new(null);
 }