Add comprehensive AppHost resource health checks documentation with enhanced overview (#4310)

* Initial plan

* Add AppHost resource health checks section to health checks fundamentals

Co-authored-by: DamianEdwards <[email protected]>

* Add reference to ASP.NET Core health checks documentation

Co-authored-by: DamianEdwards <[email protected]>

* Add screenshot reference for health check dashboard status

Co-authored-by: DamianEdwards <[email protected]>

* Add overview clarification that health checks run in AppHost and applications

Co-authored-by: davidfowl <[email protected]>

* Add health checks status on dashboard screenshot

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: DamianEdwards <[email protected]>
Co-authored-by: davidfowl <[email protected]>
Co-authored-by: Damian Edwards <[email protected]>

Author: 3 people

docs/fundamentals/health-checks.md

@@ -8,7 +8,14 @@ uid: dotnet/aspire/health-checks
 
 # Health checks in .NET Aspire
 
-Health checks provide availability and state information about an app. Health checks are often exposed as HTTP endpoints, but can also be used internally by the app to write logs or perform other tasks based on the current health. Health checks are typically used in combination with an external monitoring service or container orchestrator to check the status of an app. The data reported by health checks can be used for various scenarios:
+Health checks provide availability and state information about an app. Health checks are often exposed as HTTP endpoints, but can also be used internally by the app to write logs or perform other tasks based on the current health. Health checks are typically used in combination with an external monitoring service or container orchestrator to check the status of an app.
+
+In .NET Aspire, health checks operate in two main contexts:
+
+- **AppHost resource health checks** - Run in the AppHost project to determine resource readiness for orchestration and dependency management. These checks control when dependent resources start and are displayed in the Aspire dashboard.
+- **Application health check endpoints** - Run within individual applications and services to expose `/health` and `/alive` endpoints for monitoring and load balancing decisions.
+
+The data reported by health checks can be used for various scenarios:
 
 - Influence decisions made by container orchestrators, load balancers, API gateways, and other management services. For instance, if the health check for a containerized app fails, it might be skipped by a load balancer routing traffic.
 - Verify that underlying dependencies are available, such as a database or cache, and return an appropriate status message.
@@ -110,6 +117,76 @@ builder.AddNpgsqlDbContext<MyDbContext>(
     static settings => settings.DisableHealthChecks  = true);
 ```
 
+## AppHost resource health checks
+
+AppHost resource health checks are different from the health check endpoints described earlier. These health checks are configured in the AppHost project and determine the readiness of resources from the orchestrator's perspective. They're particularly important for controlling when dependent resources start via the [`WaitFor`](orchestrate-resources.md#waiting-for-resources) functionality and are displayed in the Aspire dashboard.
+
+### Resource readiness with health checks
+
+When a resource has health checks configured, the AppHost uses them to determine if the resource is ready before starting dependent resources. If no health checks are registered for a resource, the AppHost waits for the resource to be in the <xref:Aspire.Hosting.ApplicationModel.KnownResourceStates.Running> state.
+
+### HTTP health checks for resources
+
+For resources that expose HTTP endpoints, you can add health checks that poll specific paths:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var catalogApi = builder.AddContainer("catalog-api", "catalog-api")
+                        .WithHttpEndpoint(targetPort: 8080)
+                        .WithHttpHealthCheck("/health");
+
+builder.AddProject<Projects.WebApp>("webapp")
+       .WithReference(catalogApi)
+       .WaitFor(catalogApi); // Waits for /health to return HTTP 200
+```
+
+The `WithHttpHealthCheck` method can also be applied to project resources:
+
+```csharp
+var backend = builder.AddProject<Projects.Backend>("backend")
+                     .WithHttpHealthCheck("/health");
+                     
+builder.AddProject<Projects.Frontend>("frontend")
+       .WithReference(backend)
+       .WaitFor(backend);
+```
+
+### Custom resource health checks
+
+You can create custom health checks for more complex readiness scenarios. Start by defining the health check in the AppHost's service collection, then associate it with resources:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var startAfter = DateTime.Now.AddSeconds(30);
+
+builder.Services.AddHealthChecks().AddCheck("mycheck", () =>
+    {
+        return DateTime.Now > startAfter 
+            ? HealthCheckResult.Healthy() 
+            : HealthCheckResult.Unhealthy();
+    });
+
+var pg = builder.AddPostgres("pg")
+    .WithHealthCheck("mycheck");
+
+builder.AddProject<Projects.MyApp>("myapp")
+    .WithReference(pg)
+    .WaitFor(pg); // Waits for both the Postgres container to be running
+                  // AND the custom "mycheck" health check to be healthy
+```
+
+The <xref:Microsoft.Extensions.DependencyInjection.HealthChecksBuilderAddCheckExtensions.AddCheck*> method registers the health check, and <xref:Aspire.Hosting.ResourceBuilderExtensions.WithHealthCheck*> associates it with specific resources. For more details about creating and registering custom health checks, see [Create health checks](/aspnet/core/host-and-deploy/health-checks#create-health-checks).
+
+### Dashboard integration
+
+Resource health check status is displayed in the Aspire dashboard, providing real-time visibility into resource readiness. When resources are waiting for health checks to pass, the dashboard shows the current status and any failure details.
+
+:::image type="content" source="media/health-checks-dashboard-status.png" alt-text="Screenshot of the Aspire dashboard showing health check status for resources" lightbox="media/health-checks-dashboard-status.png":::
+
+For more information about using health checks with resource dependencies, see [Waiting for resources](orchestrate-resources.md#waiting-for-resources).
+
 ## See also
 
 - [.NET app health checks in C#](/dotnet/core/diagnostics/diagnostic-health-checks)