Persistent container lifetimes docs should cross-reference WithDataVolume() and clarify data durability

[maddymontaquila]

Bug Description

The Persistent container lifetimes docs page explains WithLifetime(ContainerLifetime.Persistent) for keeping containers alive between AppHost runs, but never mentions WithDataVolume(). Conversely, the What is the AppHost? page shows PostgreSQL examples with .WithDataVolume() but never shows or explains ContainerLifetime.Persistent.

This gap creates a real risk: a developer who reads only the persistent container lifetimes page may think ContainerLifetime.Persistent is sufficient for durable data. But persistent container ≠ persistent data. If Docker recreates the container (config change detected by Aspire, docker system prune, image update), data in the container filesystem is lost unless WithDataVolume() is also used.

Current Behavior

• The persistent-container-lifetimes page:

  • Explains ContainerLifetime.Persistent and ContainerLifetime.Session
  • Shows how to keep containers alive between runs
  • Never mentions WithDataVolume(), data volumes, or data durability
  • Does not warn that persistent container ≠ persistent data

• The app-host-overview page:

  • Shows PostgreSQL examples with .WithDataVolume()
  • Never shows or explains ContainerLifetime.Persistent
  • Doesn't explain the relationship between the two concepts

Expected Behavior

The docs should:

1. Add a cross-reference from the persistent-container-lifetimes page to WithDataVolume() — e.g., an "Important" or "Tip" callout box explaining that ContainerLifetime.Persistent keeps the container alive but does NOT guarantee data durability across container recreation events.

2. Clarify the distinction between container lifetime and data durability:

   • ContainerLifetime.Persistent = container stays running between AppHost restarts (avoids slow container startup)
   • WithDataVolume() = data persists even if the container is destroyed and recreated (volume outlives the container)

3. Show the canonical pattern for databases — both APIs together with an explanation of what each does:

   var postgres = builder.AddPostgres("postgres")
       .WithLifetime(ContainerLifetime.Persistent) // Keep container alive between AppHost runs
       .WithDataVolume()                           // Persist data even if container is recreated
       .AddDatabase("mydb");

4. Explain when you'd use one without the other:

   • WithDataVolume() without Persistent — ephemeral container that resets on each AppHost run but preserves volume data across container recreations
   • Persistent without WithDataVolume() — fast iteration (no container restart) but data lives only in the container filesystem (acceptable for caches, not for databases)

Page URL

• https://learn.microsoft.com/dotnet/aspire/fundamentals/persist-container-lifetimes
• https://learn.microsoft.com/dotnet/aspire/fundamentals/app-host-overview

Additional Context

Our experience: We were building a project with PostgreSQL via Aspire (AddPostgres + AddDatabase). We added WithLifetime(ContainerLifetime.Persistent) based on the persistent container lifetimes docs page. Because the docs didn't mention volumes at all, we didn't add WithDataVolume() and didn't realize our database data could be lost if the container was ever recreated.

Our AppHost configuration that exposed this gap:

var postgres = builder.AddPostgres("postgres")
    .WithLifetime(ContainerLifetime.Persistent)  // ← We thought this was enough
    // .WithDataVolume()                          // ← Missing — docs didn't mention it
    .AddDatabase("hotelhairdb");

Environment:

• .NET SDK 10.0.102
• Aspire SDK 13.2.0-preview.1
• Aspire.Hosting.PostgreSQL 13.2.0-preview.1
• Windows 10

This is a docs improvement request, not a code bug. The APIs work correctly — the gap is in the documentation not connecting these two related concepts.