Merge branch 'master' into dependabot/github_actions/docker/setup-buildx-action-3.12.0

Author: nanotaboada

.github/copilot-instructions.md

@@ -294,11 +294,26 @@ dotnet ef database update --project src/Dotnet.Samples.AspNetCore.WebApi
 ./scripts/run-migrations-and-copy-database.sh
 ```
 
-**Important**: The `run-migrations-and-copy-database.sh` script:
-- Resets the placeholder database file
-- Runs all migrations
-- Copies the generated database from `bin/Debug/net8.0/Data/` to `Data/`
-- Requires `dotnet ef` CLI tool installed globally
+**Database Workflow Explained:**
+
+The project maintains a **pre-seeded database** at `storage/players-sqlite3.db` to support three use cases:
+1. **Clone & Run** - Developers can clone the repo and run immediately without manual DB setup
+2. **Recreate from Scratch** - Use the script to rebuild the database with all migrations
+3. **Docker** - Container gets a copy of the pre-seeded database on first startup
+
+**How `run-migrations-and-copy-database.sh` works:**
+1. **Creates empty file** at `storage/players-sqlite3.db` (version-controlled source location)
+2. **Runs migrations** via `dotnet ef database update`
+   - EF Core uses `AppContext.BaseDirectory/storage/players-sqlite3.db`
+   - During migration, `AppContext.BaseDirectory` = `bin/Debug/net8.0/`
+   - EF Core creates/updates database at `bin/Debug/net8.0/storage/players-sqlite3.db`
+   - Applies all migrations: creates schema, seeds 26 players (11 starting + 15 substitutes)
+3. **Copies migration-applied database** from `bin/Debug/net8.0/storage/` back to `storage/`
+   - Updates the version-controlled database with latest schema + seed data
+   - This file is included in git and copied to build output via `.csproj` configuration
+
+**Requirements:**
+- `dotnet ef` CLI tool installed globally (`dotnet tool install --global dotnet-ef`)
 
 ### Docker Operations
 ```bash
@@ -325,9 +340,9 @@ docker compose down -v
 ## 🚨 Common Issues & Workarounds
 
 ### Database Path Issues
-- **SQLite database location**: `storage/players-sqlite3.db` relative to binary output
-- **Container storage**: `/storage/players-sqlite3.db` (mounted volume)
-- **Environment variable**: `STORAGE_PATH` can override the default path in containers
+- **Development**: `storage/players-sqlite3.db` (source, copied to `bin/Debug/net8.0/storage/` during build)
+- **Container**: Pre-seeded database copied from image `/app/hold/` to volume `/storage/` on first run
+- **Runtime**: Application uses `AppContext.BaseDirectory/storage/players-sqlite3.db`
 
 ### Validation Patterns
 - **FluentValidation** runs in the validator class for input format/structure

README.md

@@ -75,7 +75,7 @@ src/Dotnet.Samples.AspNetCore.WebApi/
 │   ├── Player.cs
 │   ├── PlayerRequestModel.cs
 │   └── PlayerResponseModel.cs
-├── Data/                       # EF Core DbContext
+├── Data/                       # EF Core DbContext and migrations
 │   └── PlayerDbContext.cs
 ├── Mappings/                   # AutoMapper profiles
 │   └── PlayerMappingProfile.cs

scripts/run-migrations-and-copy-database.sh

@@ -5,16 +5,19 @@ DATA_FILE="players-sqlite3.db"
 PROJECT_ROOT_PATH="src/Dotnet.Samples.AspNetCore.WebApi"
 PROJECT_BASE_PATH="$PROJECT_ROOT_PATH/bin/Debug/net8.0"
 
-SOURCE_FILE_PATH="$PROJECT_BASE_PATH/Data/$DATA_FILE"
-TARGET_FILE_PATH="$PROJECT_ROOT_PATH/Data/$DATA_FILE"
+SOURCE_FILE_PATH="$PROJECT_BASE_PATH/storage/$DATA_FILE"
+TARGET_FILE_PATH="$PROJECT_ROOT_PATH/storage/$DATA_FILE"
 
+# log prints a formatted log message prefixed by an emoji and timestamp, followed by the log level and message.
+# Parameters: emoji — emoji or symbol to prefix the entry; level — severity or level label; message — the log text.
 log() {
     local emoji=$1
     local level=$2
     local message=$3
     local timestamp
     timestamp=$(date +"%Y-%m-%d %H:%M:%S")
     echo "$emoji [$timestamp] [$level] $message"
+    return 0
 }
 
 # Check if the EF Core CLI tool is installed
@@ -31,18 +34,18 @@ touch "$TARGET_FILE_PATH"
 # Run the database migration
 log "✅" "INFO" "Running EF Core database migration for project at '$PROJECT_ROOT_PATH'..."
 dotnet ef database update --project "$PROJECT_ROOT_PATH"
-if [ $? -ne 0 ]; then
+if [[ $? -ne 0 ]]; then
     log "❌" "ERROR" "Migration failed. See error above."
     exit 1
 fi
 
 # Check and copy database
-if [ -f "$SOURCE_FILE_PATH" ]; then
+if [[ -f "$SOURCE_FILE_PATH" ]]; then
     log "✅" "INFO" "Found database at '$SOURCE_FILE_PATH'"
     log "✅" "INFO" "Copying to '$TARGET_FILE_PATH'..."
     cp -f "$SOURCE_FILE_PATH" "$TARGET_FILE_PATH"
 
-    if [ $? -eq 0 ]; then
+    if [[ $? -eq 0 ]]; then
         log "✅" "INFO" "Database successfully copied to '$TARGET_FILE_PATH'"
     else
         log "❌" "ERROR" "Failed to copy the database file."
@@ -55,7 +58,7 @@ else
 fi
 
 # Confirm destination file exists
-if [ -f "$TARGET_FILE_PATH" ]; then
+if [[ -f "$TARGET_FILE_PATH" ]]; then
     log "✅" "INFO" "Done. The database is now available at '$TARGET_FILE_PATH'"
 else
     log "⚠️" "WARNING" "Something went wrong. The destination file was not found."

src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs

@@ -177,7 +177,7 @@ [FromBody] PlayerRequestModel player
                 .ToArray();
 
             logger.LogWarning(
-                "PUT /players/{squadNumber} validation failed: {@Errors}",
+                "PUT /players/{SquadNumber} validation failed: {@Errors}",
                 squadNumber,
                 errors
             );

src/Dotnet.Samples.AspNetCore.WebApi/Migrations/20251221220614_SeedSubstitutes.Designer.cs

@@ -0,0 +1,62 @@
+using Dotnet.Samples.AspNetCore.WebApi.Utilities;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Dotnet.Samples.AspNetCore.WebApi.Migrations
+{
+    /// <inheritdoc />
+    public partial class SeedSubstitutes : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            var substitutes = PlayerData.GetSubstitutesWithId();
+
+            foreach (var player in substitutes)
+            {
+                migrationBuilder.InsertData(
+                    table: "Players",
+                    columns:
+                    [
+                        "Id",
+                        "FirstName",
+                        "MiddleName",
+                        "LastName",
+                        "DateOfBirth",
+                        "SquadNumber",
+                        "Position",
+                        "AbbrPosition",
+                        "Team",
+                        "League",
+                        "Starting11"
+                    ],
+                    values: new object[]
+                    {
+                        player.Id,
+                        player.FirstName,
+                        player.MiddleName,
+                        player.LastName,
+                        player.DateOfBirth,
+                        player.SquadNumber,
+                        player.Position,
+                        player.AbbrPosition,
+                        player.Team,
+                        player.League,
+                        player.Starting11
+                    }
+                );
+            }
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            var substitutes = PlayerData.GetSubstitutesWithId();
+            foreach (var player in substitutes)
+            {
+                migrationBuilder.DeleteData(table: "Players", keyColumn: "Id", keyValue: player.Id);
+            }
+        }
+    }
+}

src/Dotnet.Samples.AspNetCore.WebApi/Migrations/20251221220614_SeedSubstitutes.cs

@@ -15,7 +15,7 @@ partial class PlayerDbContextModelSnapshot : ModelSnapshot
         protected override void BuildModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618
-            modelBuilder.HasAnnotation("ProductVersion", "9.0.4");
+            modelBuilder.HasAnnotation("ProductVersion", "9.0.11");
 
             modelBuilder.Entity("Dotnet.Samples.AspNetCore.WebApi.Models.Player", b =>
                 {

src/Dotnet.Samples.AspNetCore.WebApi/Migrations/PlayerDbContextModelSnapshot.cs

@@ -20,7 +20,7 @@ public class PlayerRequestModel
 
     public DateTime? DateOfBirth { get; set; }
 
-    public int SquadNumber { get; set; }
+    public required int SquadNumber { get; set; }
 
     public string? AbbrPosition { get; set; }