Run it locally
There are two ready-made environments. local is for dotnet run: sample data on, logs to the console. docker is for Docker Compose: sample data on, logs, traces and metrics to the Aspire dashboard, database on a volume. Both are for your machine. Neither is for production, which is why neither is the default.
Run it
Section titled “Run it”dotnet run --project ./src/PresentationlaunchSettings.json sets the environment to local and listens on https://localhost:7311, and on http://localhost:7310, which redirects to it. If your browser or curl doesn’t trust the .NET development certificate yet, run dotnet dev-certs https --trust once.
docker compose up -d --buildCompose builds the run stage, starts an OpenTelemetry Collector and the Aspire dashboard next to it, and publishes the API on http://localhost:7310. Shut it down with docker compose down, or docker compose down -v to drop the database too.
docker build . --target run --tag worksonmymachine-movies:localdocker run --rm -p 7310:7310 -e DOTNET_ENVIRONMENT=docker worksonmymachine-movies:localWithout Compose there’s no collector, so the logs stay on the console and nothing else is exported. Set OTEL_EXPORTER_OTLP_ENDPOINT to send them to a collector of your own.
Find your way around
Section titled “Find your way around”| Where | What |
|---|---|
/scalar |
The Scalar API reference, built from the OpenAPI document |
/openapi/v1.json |
The OpenAPI document itself |
/health/live |
Answers 200 while the process is up |
/health/ready |
Answers 200 when the database can be reached |
/api/version |
The version stamped into the build. Needs a token when authentication is on |
| http://localhost:7312 | The Aspire dashboard, with the logs, traces and metrics, when running with Docker Compose |
The health endpoints answer without a token even when authentication is on, so a load balancer never needs to log in.
See the telemetry
Section titled “See the telemetry”Docker Compose runs an OpenTelemetry Collector beside the API, and the collector forwards everything to the Aspire dashboard at http://localhost:7312. Open Traces to follow a request from the HTTP request to the use case, Structured for the logs, each linked to its trace, and Metrics for request durations, EF Core queries and the runtime. The dashboard keeps everything in memory, so it’s empty again after a restart. The dashboard has no login, and the collector accepts OTLP from anyone on ports 7313 and 7314. That’s on purpose, so there’s nothing to sign in to on your machine, and it’s why the compose file is for your machine only. Don’t run it anywhere other people can reach.
The API only ever talks OTLP to the collector, and otel-collector.yaml decides where things go. To send them to a real backend, add its exporter there; the API doesn’t change. To see a dotnet run in the dashboard, start the collector and point the API at it:
docker compose up -d otel-collectorOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7313 dotnet run --project ./src/PresentationTry the endpoints
Section titled “Try the endpoints”Open src/Presentation/Presentation.http in Visual Studio, Rider or VS Code to run a request for every endpoint in one click, or call them from the terminal. These use the dotnet run address; with Docker Compose, use http://localhost:7310 instead. The sample data uses a fixed seed, so these ids are the same on every machine. See the endpoint reference for every parameter and response.
# Search movies, two at a timecurl "https://localhost:7311/api/movies?query=space&limit=2"
# One movie, with its reviewscurl "https://localhost:7311/api/movies/cb188ef6-14e7-f85f-2f78-924c2ab26b28"
# Write a reviewcurl -X POST "https://localhost:7311/api/reviews" -H "Content-Type: application/json" \ -d '{"authorId":"01fa8b58-05d2-abd4-e55c-2633222dd0a5","movieId":"cb188ef6-14e7-f85f-2f78-924c2ab26b28","stars":5,"text":"Great film. I cried at the ending."}'Run the tests
Section titled “Run the tests”dotnet testThe tests build their own in-memory SQLite databases from the same migrations and seed, so nothing touches movie-reviews.db. Test your changes covers where a test goes, how the tests are written and how to check coverage before CI does.
Run just one part of the Dockerfile
Section titled “Run just one part of the Dockerfile”The Dockerfile has a stage for each job, so you can build only what you need.
| Stage | What it does |
|---|---|
build |
Restores and builds the solution |
test |
Runs every test with coverage, and saves the result instead of failing the build |
results |
Exports the test results, the coverage report and the exit code to your machine |
publish |
Publishes the Presentation project |
run |
The image you deploy |
docker build . --target results --output type=local,dest=outA failing test doesn’t fail the build, so the results still come out. Check out/exit-code: anything other than 0 means a test failed, and a pipeline built on these stages should fail on it.
Stamp a version
Section titled “Stamp a version”docker build . --target run --tag worksonmymachine-movies:latest \ --build-arg VERSION_PREFIX=1.2.3 --build-arg VERSION_SUFFIX=betaGET /api/version then reports 1.2.3-beta and the commit it was built from.