BlazorDockerSample

This repository is a small Blazor Server sample wired to a SQL Server container for local development. This README documents how to start the Docker services, run EF Core migrations, and use the Tools/CheckDb helper to verify the database.

Prerequisites

• .NET SDK (8.0+) installed (used for building tools and app)
• Docker Desktop (for running the SQL Server and the app)
• dotnet-ef CLI tools installed (optional; used for running EF commands):

---

Docker Desktop (what and how to install)

Docker Desktop is an easy way to run containerized services (Docker Engine, Compose, and a GUI) on macOS and Windows. It also works on Linux via the Docker Engine package. For this project you only need Docker Engine and Docker Compose.

• Install on macOS / Windows: https://www.docker.com/get-started
• Install on Linux: follow your distribution's Docker Engine instructions (https://docs.docker.com/engine/install/)

After installing, make sure Docker Desktop is running before starting the app. Verify with:

docker --version
docker compose version
docker info

If Docker is not running, start the Docker Desktop app (macOS/Windows) or start the Docker service on Linux (e.g., sudo systemctl start docker).

dotnet tool install --global dotnet-ef

Start Docker services

From the repo root:

docker compose up -d

This starts two services:

• blazorapp - the Blazor Server app (exposes port 5050 on the host)
• sqlserver - SQL Server 2022 container (exposes port 1433 on the host)

Check status:

docker compose ps
docker ps

Check SQL Server logs to ensure it's ready:

docker logs blazordockersample-sqlserver-1 --tail 200

Look for SQL Server is now ready for client connections.

Connection string

Default connection string in appsettings.json:

"ConnectionStrings": {
  "DefaultConnection": "Server=sqlserver;Database=ClientDb;User Id=sa;Password=YourStrong!Passw0rd;"
}

From the host (for dotnet ef or other host tools) use 127.0.0.1 and include TrustServerCertificate=True to avoid TLS pre-login handshake issues:

Server=127.0.0.1,1433;Database=ClientDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;

EF Core migrations

Create a migration (if needed):

# from repo root
dotnet ef migrations add InitialCreate

Apply migrations to the database:

# If you need to override the connection string to use host port and trust certificate:
ConnectionStrings__DefaultConnection='Server=127.0.0.1,1433;Database=ClientDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;' dotnet ef database update

If EF tooling reports TLS pre-login errors when connecting to sqlserver by name, use the host override above.

Tools/CheckDb helper

A small console helper is included at Tools/CheckDb. It connects to the configured DB and lists tables (useful if sqlcmd isn't available or cross-arch images cause problems).

Build and run it from the project folder:

cd Tools/CheckDb
dotnet run --project .

Or pass a connection string explicitly:

dotnet run --project . "Server=127.0.0.1,1433;Database=ClientDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"

Example output when tables are present:

dbo.__EFMigrationsHistory
dbo.Clients

Troubleshooting

• TLS pre-login handshake error when running dotnet ef from the host:

  • Use TrustServerCertificate=True in the connection string or run EF commands from inside the Docker network.

• sqlcmd login/connect issues from the host:

  • The mcr.microsoft.com/mssql-tools image may be amd64 while your Docker host is arm64. Running tools from inside Docker on the same compose network (or using dotnet tooling) avoids cross-arch client issues.

• Package/version warnings when building:

  • This repo pins EF Core runtime packages at 7.0.14 and the SQL client at 6.0.0. If you change the target framework or packages, make sure tool/runtime packages align (e.g., Microsoft.EntityFrameworkCore.Tools should match runtime EF Core version).

Next steps

• Upgrade target framework to match your environment or move to net8.0 if desired.
• Add more migrations or seed data as needed.

If you'd like, I can add commands to the repository to automate the common workflows (Makefile or scripts), or add a small README under Tools/CheckDb describing the helper in more detail.

Scripts

Convenience scripts are provided in the scripts/ folder to simplify common workflows. Make them executable and run from the repository root.

Start services:

./scripts/start.sh

Stop services:

./scripts/stop.sh

Apply migrations / list migrations (uses host connection override and trusts certificate):

./scripts/migrate.sh        # applies migrations using host override
./scripts/migrate.sh list   # lists migrations

Check DB tables (uses Tools/CheckDb):

./scripts/check-db.sh
# or pass a custom connection string to the tool after --:
./scripts/check-db.sh -- "Server=127.0.0.1,1433;Database=ClientDb;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"

Build the project:

./scripts/build.sh

These scripts are minimal wrappers around docker compose, dotnet ef, and the small helper in Tools/CheckDb. If you want I can add a Makefile or example task targets for VS Code to further streamline the workflow.

How to run the app (quick start)

1. Ensure prerequisites are installed (see above).
2. Start Docker services (builds images if needed):

./scripts/start.sh
# or
docker compose up -d --build

3. Seed the database (inserts sample clients):

./scripts/check-db.sh -- --seed
# or run the helper directly:
dotnet run --project Tools/CheckDb -- --seed

4. Open your browser at http://localhost:5050/clients to view the clients grid.