Merge pull request #3502 from dotnet/main

✅ Merge `main` into `live`

Author: dotnet-policy-service[bot]

docs/database/seed-database-data.md

@@ -1,127 +1,97 @@
 ---
 title: Seed data in a database using .NET Aspire
 description: Learn about how to seed database data in .NET Aspire
-ms.date: 08/12/2024
+ms.date: 05/14/2025
 ms.topic: how-to
 ---
 
 # Seed data in a database using .NET Aspire
 
-In this article, you learn how to configure .NET Aspire projects to seed data in a database during app startup. .NET Aspire enables you to seed data using database scripts or Entity Framework Core for common platforms such as SQL Server, PostgreSQL and MySQL.
+In this article, you learn how to configure .NET Aspire projects to seed data in a database during app startup. .NET Aspire enables you to seed data using database scripts or Entity Framework Core (EF Core) for common platforms such as SQL Server, PostgreSQL, and MySQL.
 
 ## When to seed data
 
-Seeding data pre-populates database tables with rows of data so they're ready for testing via your app. You may want to seed data for the following scenarios:
+Seeding data pre-populates database tables with rows of data so they're ready for testing your app. You may want to seed data for the following scenarios:
 
-- Manually develop and test different features of your app against a meaningful set of data, such as a product catalog or list of customers.
-- Run test suites to verify that features behave a specific way with a given set of data.
+- You want to develop and test different features of your app manually against a meaningful set of data, such as a product catalog or a list of customers.
+- You want to run test suites to verify that features behave correctly with a given set of data.
 
-Manually seeding data is tedious and time consuming, so you should automate the process when possible. Use volumes to run database scripts for .NET Aspire projects during startup. You can also seed your database using tools like Entity Framework Core, which handles many underlying concerns for you.
+Manually seeding data is tedious and time consuming, so you should automate the process whenever possible. You can seed your database either by running database scripts for .NET Aspire projects during startup or by using tools like EF Core, which handles many underlying concerns for you.
 
 ## Understand containerized databases
 
 By default, .NET Aspire database integrations rely on containerized databases, which create the following challenges when trying to seed data:
 
-- .NET Aspire destroys and recreates containers every time the app restarts, which means by default you have to re-seed your database every time the app restarts.
+- By default, .NET Aspire destroys and recreates containers every time the app restarts, which means you have to re-seed your database on each run.
 - Depending on your selected database technology, the new container instance may or may not create a default database, which means you might also have to create the database itself.
-- Even if a default database exists, it most likely will not have the desired name or schema for your specific app.
+- Even if a default database exists, it most likely won't have the desired name or schema for your specific app.
 
-.NET Aspire enables you to resolve these challenges using volumes and a few configurations to seed data effectively.
+.NET Aspire enables you to resolve these challenges using volumes, bind mounts, and a few configurations to seed data effectively.
 
-## Seed data using volumes and SQL scripts
+> [!TIP]
+> Container hosts like Docker and Podman support volumes and bind mounts, both of which provide locations for data that persist when a container restarts. Volumes are the recommended solution, because they offer better performance, portability, and security. The container host creates and remains in control of volumes. Each volume can store data for multiple containers. Bind mounts have relatively limited functionality in comparison but enable you to access the data from the host machine.
 
-Volumes are the recommended way to automatically seed containerized databases when using SQL scripts. Volumes can store data for 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.WithBindMount%2A?displayProperty=nameWithType> method, which accepts three parameters:
-
-- **Source**: The source path of the volume mount, which is the physical location on your host.
-- **Target**: The target path in the container of the data you want to persist.
-
-Consider the following volume configuration code from a _:::no-loc text="Program.cs":::_ file in a sample **AppHost** project:
-
-```csharp
-var todosDbName = "Todos";
-var todosDb = builder.AddPostgres("postgres")
-    .WithEnvironment("POSTGRES_DB", todosDbName)
-    .WithBindMount(
-        "../DatabaseContainers.ApiService/data/postgres",
-        "/docker-entrypoint-initdb.d")
-    .AddDatabase(todosDbName);
-```
-
-In this example, the `.WithBindMount` method parameters configure the following:
-
-- `../DatabaseContainers.ApiService/data/postgres` sets a path to the SQL script in your local project that you want to run in the container to seed data.
-- `/docker-entrypoint-initdb.d` sets the path to an entry point in the container so your script will be run during container startup.
-
-The referenced SQL script located at `../DatabaseContainers.ApiService/data/postgres` creates and seeds a `Todos` table:
-
-```sql
--- Postgres init script
+> [!NOTE]
+> Visit the [Database Container Sample App](https://github.com/dotnet/aspire-samples/blob/main/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs) to view the full project and file structure for each database option.
 
--- Create the Todos table
-CREATE TABLE IF NOT EXISTS Todos
-(
-    Id SERIAL PRIMARY KEY,
-    Title text UNIQUE NOT NULL,
-    IsComplete boolean NOT NULL DEFAULT false
-);
+## Seed data using SQL scripts
 
--- Insert some sample data into the Todos table
-INSERT INTO Todos (Title, IsComplete)
-VALUES
-    ('Give the dog a bath', false),
-    ('Wash the dishes', false),
-    ('Do the groceries', false)
-ON CONFLICT DO NOTHING;
-```
+In .NET Aspire 9.2, the recommended method for executing database seeding scripts depends on the database server you use:
 
-The script runs during startup every time a new container instance is created.
+### [SQL Server](#tab/sql-server)
 
-## Database seeding examples
+In .NET Aspire 9.2 and later versions, you can use the <xref:Aspire.Hosting.SqlServerBuilderExtensions.WithCreationScript*> method to ensure a T-SQL script is run when the database is created. Add SQL code to this script that creates and populates the database, the necessary tables, and other database objects.
 
-The following examples demonstrate how to seed data using SQL scripts and configurations applied using the `.WithBindMount` method for different database technologies:
+The following code is an example T-SQL script that creates and populates an address book database:
 
-> [!NOTE]
-> Visit the [Database Container Sample App](https://github.com/dotnet/aspire-samples/blob/main/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs) to view the full project and file structure for each database option.
+:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.ApiService/data/sqlserver/init.sql" :::
 
-### [SQL Server](#tab/sql-server)
+You must ensure that this script is copied to the app host's output directory, so that .NET Aspire can execute it. Add the following XML to your *.csproj* file:
 
-The configuration code in the **.AppHost** _:::no-loc text="Program.cs":::_ file mounts the required database files and folders and configures an entrypoint so that they run during startup.
+:::code language="xml" source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/DatabaseContainers.AppHost.csproj" range="13-17" :::
 
-:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs" range="37-49" :::
+Adjust the `Include` parameter to match the path to your SQL script in the project.
 
-The _entrypoint.sh_ script lives in the mounted `./sqlserverconfig` project folder and runs when the container starts. The script launches SQL Server and checks that it's running.
+Next, in the app host's *Program.cs* file, create the database and run the creation script:
 
-:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/sqlserverconfig/entrypoint.sh" :::
+:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs" range="40-49" :::
 
-The _init.sql_ SQL script that lives in the mounted `../DatabaseContainers.ApiService/data/sqlserver` project folder creates the database and tables.
+This code:
 
-:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.ApiService/data/sqlserver/init.sql" :::
+- Create a SQL Server container by calling `builder.AddSqlServer()`.
+- Ensures that data is persisted across debugging sessions by calling `WithDataVolume()` and `WithLifetime(ContainerLifetime.Persistent)`.
+- Obtains the path to the T-SQL script in the output folder.
+- Calls `WithCreationScript()` to create and seed the database.
 
 ### [PostgreSQL](#tab/postgresql)
 
-Configuration code in the **.AppHost** project:
+In .NET Aspire 9.2, the `WithCreationScript()` method isn't supported for the PostgreSQL integration. Instead, you must use a bind mount and deploy the setup SQL script to it, so that the data is seeded when the container initializes the database.
 
-:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs" range="3-15" :::
-
-Corresponding SQL script included in the app:
+The following code is an example PostgreSQL script that creates and populates a to do list database:
 
 :::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.ApiService/data/postgres/init.sql" :::
 
-### [MySQL](#tab/mysql)
+In the app host's *Program.cs* file, create the database and mount the folder that contains the SQL script as a bind mount:
+
+:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs" range="3-19" :::
 
-Configuration code in the **.AppHost** project:
+### [MySQL](#tab/mysql)
 
-:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs" range="20-32" :::
+In .NET Aspire 9.2, the `WithCreationScript()` method isn't supported for the MySQL integration. Instead, you must use a bind mount and deploy the setup SQL script to it, so that the data is seeded when the container initializes the database.
 
-Corresponding SQL script included in the app:
+The following code is an example MySQL script that creates and populates a product catalog database:
 
 :::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.ApiService/data/mysql/init.sql" :::
 
+In the app host's *Program.cs* file, create the database and mount the folder that contains the SQL script as a bind mount:
+
+:::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs" range="21-36" :::
+
 ---
 
-## Seed data using Entity Framework Core
+## Seed data using EF Core
 
-You can also seed data in .NET Aspire projects using Entity Framework Core by explicitly running migrations during startup. Entity Framework Core handles underlying database connections and schema creation for you, which eliminates the need to use volumes or run SQL scripts during container startup.
+You can also seed data in .NET Aspire projects using EF Core by explicitly running migrations during startup. EF Core handles underlying database connections and schema creation for you, which eliminates the need to use volumes or run SQL scripts during container startup.
 
 > [!IMPORTANT]
 > These types of configurations should only be done during development, so make sure to add a conditional that checks your current environment context.
@@ -197,6 +167,7 @@ if (app.Environment.IsDevelopment())
 
 Database seeding is useful in a variety of app development scenarios. Try combining these techniques with the resource implementations demonstrated in the following tutorials:
 
-- [Tutorial: Connect an ASP.NET Core app to SQL Server using .NET Aspire and Entity Framework Core](../database/sql-server-integrations.md)
+- [Tutorial: Connect an ASP.NET Core app to SQL Server using .NET Aspire and Entity Framework Core](sql-server-integrations.md)
+- [Tutorial: Apply Entity Framework Core migrations in .NET Aspire](ef-core-migrations.md)
 - [Tutorial: Connect an ASP.NET Core app to .NET Aspire storage integrations](../storage/azure-storage-integrations.md)
 - [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md)

docs/fundamentals/dashboard/standalone-for-python.md

@@ -168,7 +168,7 @@ To use the .NET Aspire dashboard with your Python app, you need to install the O
     from otlp_tracing import configure_otel_otlp
 
     logging.basicConfig(level=logging.INFO)
-    tracer = configure_otel_otlp()
+    tracer = configure_oltp_grpc_tracing()
     logger = logging.getLogger(__name__)
     ```