Merge pull request #327 from alexwolfmsft/persist-data-volume-mount

volume mount

Author: alexwolfmsft

docs/fundamentals/persist-data-volumes.md

@@ -0,0 +1,73 @@
+---
+title: Persist data with .NET Aspire using volume mounts
+description: Learn about .NET Aspire volume configurations.
+ms.date: 12/08/2023
+ms.topic: how-to
+---
+
+# Persist .NET Aspire app data using volumes
+
+In this article, you learn how to configure .NET Aspire apps to persist data across app launches using volumes. A continuous set of data during local development is useful in many scenarios. Various .NET Aspire resource container types are able to leverage volume storage, such as PostreSQL, Redis and Azure Storage.
+
+## When to use volumes
+
+By default, every time you start and stop a .NET Aspire app, the app also creates and destroys the app resource containers. This setup creates problems when you want to persist data in a database or storage services between app launches for testing or debugging. For example, you may want to handle the following scenarios:
+
+- Work with a continuous set of data in a database during an extended development session.
+- Test or debug a changing set of files in an Azure Blob Storage emulator.
+- Maintain cached data or messages in a Redis instance across app launches.
+
+These goals can all be accomplished using volumes. With volumes, you decide which services retain data between launches of your .NET Aspire app.
+
+## Understand volumes
+
+Volumes are the recommended way to persist data generated by containers and supported on both Windows and Linux. Volumes can store data from multiple containers at a time, offer high performance and are easy to back up or migrate. With .NET Aspire, you configure a volume for each resource container using the <xref:Aspire.Hosting.ContainerResourceBuilderExtensions.WithVolumeMount%2A?displayProperty=nameWithType> method, which accepts three parameters:
+
+- **Source**: The source path of the volume, which is the physical location on the host.
+- **Target**: The target path in the container of the data you want to persist.
+- **VolumeMountType**: There are two types of volume mounts available:
+  - **Named mounts**: Storage managed by docker that your containers can use to persist data.
+  - **Bind mounts**: Files mounted from your host machine onto your container.
+
+Consider the following volume configuration code from a _Program.cs_ file in a sample AppHost project:
+
+```csharp
+var sql = builder.AddSqlServerContainer("sql", sqlpassword)
+    .WithVolumeMount("VolumeMount.sqlserver.data", "/var/opt/mssql", VolumeMountType.Named)
+    .AddDatabase("sqldb");
+```
+
+In this example:
+
+- `VolumeMount.sqlserver.data` sets where the volume will be stored on the host.
+- `/var/opt/mssql` sets the path to the database files in the container.
+- <xref:Aspire.Hosting.ApplicationModel.VolumeMountType.Named?displayProperty=nameWithType> sets a named volume that will persist across container life cycles.
+
+## Create a persistent password
+
+Named volumes require a consistent password between app launches. Run the following command in your project directory to set a local password in your .NET user secrets:
+
+```dotnetcli
+dotnet user-secrets set samplepassword <password>
+```
+
+Retrieve this password in your app using the following code:
+
+```csharp
+// Retrieve the password you created from user secrets
+var password = builder.Configuration["samplepassword"];
+```
+
+## Configure volumes using the AppHost
+
+Volumes are configured in the _Program.cs_ file in the **.AppHost** project of your .NET Aspire apps. The following code demonstrates how to configure a volume for various .NET Aspire resources:
+
+:::code source="~/aspire-samples/samples/VolumeMount/VolumeMount.AppHost/Program.cs":::
+
+## Next steps
+
+You can apply the volume concepts in the preceding code to a variety of services, including seeding a database with data that will persist across app launches. Try combining these techniques with the resource implementations demonstrated in the following tutorials:
+
+- [Tutorial: Connect an ASP.NET Core app to .NET Aspire storage components](../storage/azure-storage-components.md)
+- [Tutorial: Connect an ASP.NET Core app to SQL Server using .NET Aspire and Entity Framework Core](../database/sql-server-components.md)
+- [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md)

docs/toc.yml

@@ -40,6 +40,8 @@ items:
         href: service-discovery/overview.md
       - name: Service defaults
         href: fundamentals/service-defaults.md
+      - name: Persist data using volumes
+        href: fundamentals/persist-data-volumes.md
       - name: Health checks
         href: fundamentals/health-checks.md
       - name: Telemetry