Make it yours
Sooner or later you’ll want to evict Deep Space Gardeners and move your own domain in. The tempting move is to delete Movies, Authors and Reviews first. Don’t. Half the tests stop compiling, and the shared plumbing (paging, validation, logging, the serializer and telemetry) suddenly has nothing to exercise it, so coverage falls through the floor.
Go the other way round. Build your first slice beside the sample domain, prove it works end to end, then take the movies out. This guide adds cinemas, with a GetCinemas function to list and search them and a CreateCinema function to add one, each with an API Gateway twin at GET /cinemas and POST /cinemas, and finishes with a solution that has no movies left in it. We ran every step on a fresh solution: it ends with 75 passing tests and 99.7% line coverage.
The code below assumes you named the solution WorksOnMyMachine.Movies. Swap in your own name wherever you see it.
Build the new slice
Section titled “Build the new slice”-
Add the entity and use cases to
src/Application(add-a-use-case).The entity, the repository interface, one query and one command, each with a validator. Handlers and validators are
public, like the samples, so Mediator’s source generator and the tests can see them.Directorysrc/Application/Cinemas/
- Entities/Cinema.cs
- ICinemasRepository.cs
DirectoryQueries/GetCinemas/
- GetCinemasQuery.cs
- GetCinemasHandler.cs
- GetCinemasValidator.cs
DirectoryCommands/CreateCinema/
- CreateCinemaCommand.cs
- CreateCinemaHandler.cs
- CreateCinemaValidator.cs
src/Application/Cinemas/Entities/Cinema.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Entities;/// <summary>/// A cinema that shows movies./// </summary>/// <param name="Id">The unique identifier of the cinema.</param>/// <param name="Name">The name of the cinema.</param>public record Cinema(Guid Id, string Name);src/Application/Cinemas/ICinemasRepository.cs namespace WorksOnMyMachine.Movies.Application.Cinemas;using Common.Paging;using Entities;public interface ICinemasRepository{public Task<Page<Cinema>> GetCinemas(string? query,PageRequest page,CancellationToken cancellationToken);public Task<Cinema> CreateCinema(string name, CancellationToken cancellationToken);}The query reuses the shared paging and search rules, so
Common/Pagingstays covered once the sample queries are gone.src/Application/Cinemas/Queries/GetCinemas/GetCinemasQuery.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Queries.GetCinemas;using Common.Paging;using Entities;using Mediator;/// <summary>/// Lists cinemas one page at a time, optionally only those whose name contains a search term./// </summary>public class GetCinemasQuery : IRequest<Page<Cinema>>{/// <summary>The words to look for in the name, ignoring case. Leave empty to list every cinema.</summary>public string? Query { get; init; }/// <summary>The number of results to skip, 0 for the first page.</summary>public int Offset { get; init; }/// <summary>The largest number of results to return, from 1 to 50.</summary>public int Limit { get; init; } = Paging.DefaultLimit;}src/Application/Cinemas/Queries/GetCinemas/GetCinemasHandler.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Queries.GetCinemas;using Common.Paging;using Entities;using Mediator;public class GetCinemasHandler(ICinemasRepository repository) : IRequestHandler<GetCinemasQuery, Page<Cinema>>{public async ValueTask<Page<Cinema>> Handle(GetCinemasQuery request, CancellationToken cancellationToken){return await repository.GetCinemas(request.Query, new PageRequest(request.Offset, request.Limit), cancellationToken);}}src/Application/Cinemas/Queries/GetCinemas/GetCinemasValidator.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Queries.GetCinemas;using Common.Paging;using FluentValidation;public class GetCinemasValidator : AbstractValidator<GetCinemasQuery>{public GetCinemasValidator(){_ = this.RuleFor(r => r.Query).ValidSearchTerm();_ = this.RuleFor(r => r.Offset).ValidOffset();_ = this.RuleFor(r => r.Limit).ValidLimit();}}src/Application/Cinemas/Commands/CreateCinema/CreateCinemaCommand.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Commands.CreateCinema;using Entities;using Mediator;public class CreateCinemaCommand : IRequest<Cinema>{public string Name { get; init; } = string.Empty;}src/Application/Cinemas/Commands/CreateCinema/CreateCinemaHandler.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Commands.CreateCinema;using Entities;using Mediator;public class CreateCinemaHandler(ICinemasRepository repository) : IRequestHandler<CreateCinemaCommand, Cinema>{public async ValueTask<Cinema> Handle(CreateCinemaCommand request, CancellationToken cancellationToken){return await repository.CreateCinema(request.Name, cancellationToken);}}src/Application/Cinemas/Commands/CreateCinema/CreateCinemaValidator.cs namespace WorksOnMyMachine.Movies.Application.Cinemas.Commands.CreateCinema;using FluentValidation;public class CreateCinemaValidator : AbstractValidator<CreateCinemaCommand>{public CreateCinemaValidator(){_ = this.RuleFor(r => r.Name).NotEmpty().WithMessage("A cinema needs a name.");_ = this.RuleFor(r => r.Name).MaximumLength(100).WithMessage("A cinema name can't be longer than 100 characters.");}} -
Store and map it in
src/Infrastructure(data-access-ef-coreandmapping-with-mapperly).Add the database model and its configuration beside the sample ones. Every model inherits
Entity, which brings the id and the created and modified dates, and every configuration inheritsEntityConfiguration<T>, which sets them up.src/Infrastructure/Databases/MovieReviews/Models/Cinema.cs namespace WorksOnMyMachine.Movies.Infrastructure.Databases.MovieReviews.Models;using System.Diagnostics.CodeAnalysis;[ExcludeFromCodeCoverage]internal record Cinema : Entity{public required string Name { get; init; }}src/Infrastructure/Databases/MovieReviews/Configuration/CinemaConfiguration.cs namespace WorksOnMyMachine.Movies.Infrastructure.Databases.MovieReviews.Configuration;using Microsoft.EntityFrameworkCore;using Microsoft.EntityFrameworkCore.Metadata.Builders;using Models;internal class CinemaConfiguration : EntityConfiguration<Cinema>{public override void Configure(EntityTypeBuilder<Cinema> builder){base.Configure(builder);_ = builder.Property(c => c.Name).HasMaxLength(100).UseCollation(Collations.NoCase);_ = builder.HasIndex(c => c.Name);}}Then wire it in:
-
MovieReviewsDbContext.cs: addpublic DbSet<Cinema> Cinemas => this.Set<Cinema>();beside the other sets. -
Mapping/MovieReviewsMapper.cs: addusing AppCinema = Application.Cinemas.Entities.Cinema;andusing InfraCinema = Models.Cinema;with the other aliases, and this method:[MapperIgnoreSource(nameof(InfraCinema.DateCreated))][MapperIgnoreSource(nameof(InfraCinema.DateModified))]public partial AppCinema ToDomain(InfraCinema cinema); -
EntityFrameworkMovieReviewsRepository.cs: addusing Application.Cinemas;andusing ApplicationCinema = Application.Cinemas.Entities.Cinema;, addICinemasRepositoryto the interfaces the class implements, and add aCinemasregion. The search reuses the repository’s ownContainsPatternandEscapeCharacter, so a%or_in a search term matches itself, the same as for movies.#region Cinemaspublic async Task<Page<ApplicationCinema>> GetCinemas(string? query,PageRequest page,CancellationToken cancellationToken){var cinemas = this.context.Cinemas.AsQueryable();if (!string.IsNullOrWhiteSpace(query)){var pattern = ContainsPattern(query);cinemas = cinemas.Where(c => EF.Functions.Like(c.Name, pattern, EscapeCharacter));}var totalCount = await cinemas.CountAsync(cancellationToken);var result = await cinemas.OrderBy(c => c.Name).ThenBy(c => c.Id).Skip(page.Offset).Take(page.Limit).ToListAsync(cancellationToken);return new([.. result.Select(this.mapper.ToDomain)], page.Offset, page.Limit, totalCount);}public async Task<ApplicationCinema> CreateCinema(string name, CancellationToken cancellationToken){var now = this.timeProvider.GetUtcNow().UtcDateTime;var cinema = new Cinema{Name = name,DateCreated = now,DateModified = now};_ = this.context.Add(cinema);_ = await this.context.SaveChangesAsync(cancellationToken);return this.mapper.ToDomain(cinema);}#endregion Cinemas -
src/Infrastructure/DependencyInjection.cs: addusing Application.Cinemas;and register the interface against the same repository, like the others:_ = services.AddScoped<ICinemasRepository>(x =>x.GetRequiredService<EntityFrameworkMovieReviewsRepository>()); -
Extensions/MovieReviewsDbContextExtensions.cs(sample-data): givelocalanddockersome cinemas to look at. Add this toAddDatabeforeSaveChanges:var cinemas = new Faker<Cinema>().UseSeed(Seed).RuleFor(c => c.Id, f => f.Random.Guid()).RuleFor(c => c.Name, f => $"{f.Address.City()} Picture House").RuleFor(c => c.DateCreated, f => f.Date.Past(refDate: ReferenceDate)).RuleFor(c => c.DateModified, f => f.Date.Past(refDate: ReferenceDate)).Generate(5);context.AddRange(cinemas);
-
-
Add a migration (
database-migrations).Terminal window dotnet tool install --global dotnet-efdotnet ef migrations add AddCinemas \--project ./src/Infrastructure \--output-dir Databases/MovieReviews/Migrations \--namespace WorksOnMyMachine.Movies.Infrastructure.Databases.MovieReviews.Migrationssed -i '1s/^\xEF\xBB\xBF//' src/Infrastructure/Databases/MovieReviews/Migrations/*.csWithout
--namespacethe migration lands in a namespace of its own. Thesedstrips the byte order mark the tool adds. On macOS, usesed -i ''. Then make// <auto-generated />the first line of the new<timestamp>_AddCinemas.cs, as it is in the other migrations, so the analysers leave generated code alone.
Expose and test it
Section titled “Expose and test it”-
Put it on functions in
src/Presentation(expose-a-use-case,api-conventionsandjson-serialization).Every use case goes out twice, like the samples: a function you invoke directly with a request record, and an HTTP API function that API Gateway calls with the request in the path, query or body. Both share one private method, so the use case is only sent from one place.
The function returns its own models, not the Application entities, so what goes over the wire is decided here.
src/Presentation/LambdaFunction/Models/Cinema.cs namespace WorksOnMyMachine.Movies.Presentation.LambdaFunction.Models;/// <summary>/// A cinema that shows movies./// </summary>/// <param name="Id">The unique identifier of the cinema.</param>/// <param name="Name">The name of the cinema.</param>public record Cinema(Guid Id, string Name);src/Presentation/LambdaFunction/Models/CreateCinemaRequest.cs namespace WorksOnMyMachine.Movies.Presentation.LambdaFunction.Models;/// <summary>/// Creates a cinema./// </summary>public record CreateCinemaRequest{/// <summary>The name of the cinema, up to 100 characters.</summary>public string Name { get; init; } = string.Empty;}Then in
src/Presentation/LambdaFunction/:-
Mapping/LambdaFunctionMapper.cs: addusing AppCinema = Application.Cinemas.Entities.Cinema;andusing PresentationCinema = Models.Cinema;with the other aliases, andpublic partial PresentationCinema ToPresentation(AppCinema cinema);. -
Serialization/LambdaFunctionJsonSerializerContext.cs: add[JsonSerializable(typeof(CreateCinemaRequest))],[JsonSerializable(typeof(Cinema))]and[JsonSerializable(typeof(Page<Cinema>))]. Native AOT can’t reflect, so a type that isn’t listed here can’t be read or written. -
LambdaFunction.cs: addusing Application.Cinemas.Commands.CreateCinema;andusing Application.Cinemas.Queries.GetCinemas;, then the two functions and the methods they share:/// <summary>/// Lists cinemas ordered by name, one page at a time, optionally only those whose name contains a search term./// </summary>/// <param name="request">The search term, offset and limit.</param>/// <param name="context">The Lambda invocation context.</param>/// <returns>One page of cinemas.</returns>[LambdaFunction(ResourceName = "GetCinemas", PackageType = LambdaPackageType.Image, MemorySize = 256, Timeout = 30)]public async Task<Page<Cinema>> GetCinemas(ListRequest request, ILambdaContext context){return await this.Invoke(request, context, () => this.ListCinemas(request, context));}/// <summary>/// Creates a cinema and returns it with its new id./// </summary>/// <param name="request">The name of the cinema.</param>/// <param name="context">The Lambda invocation context.</param>/// <returns>The cinema that was created.</returns>[LambdaFunction(ResourceName = "CreateCinema", PackageType = LambdaPackageType.Image, MemorySize = 256, Timeout = 30)]public async Task<Cinema> CreateCinema(CreateCinemaRequest request, ILambdaContext context){return await this.Invoke(request, context, () => this.AddCinema(request, context));}private async Task<Page<Cinema>> ListCinemas(ListRequest request, ILambdaContext context){var page = await this.Send(new GetCinemasQuery{Query = request.Query,Offset = request.Offset,Limit = request.Limit}, context);return ToPage(page, this.mapper.ToPresentation);}private async Task<Cinema> AddCinema(CreateCinemaRequest request, ILambdaContext context){return this.mapper.ToPresentation(await this.Send(new CreateCinemaCommand { Name = request.Name }, context));}And their HTTP API twins, beside the sample ones:
/// <summary>/// The same list as <see cref="GetCinemas"/>, for API Gateway: <c>GET /cinemas?query=&offset=&limit=</c>./// </summary>/// <param name="query">The words to look for in the name, ignoring case. Leave empty to list every cinema.</param>/// <param name="offset">The number of cinemas to skip.</param>/// <param name="limit">The most cinemas to return, from 1 to 50.</param>/// <param name="context">The Lambda invocation context.</param>/// <returns><c>200</c> with one page of cinemas, or <c>400</c> with problem details when the request is invalid.</returns>[LambdaFunction(ResourceName = "HttpGetCinemas", PackageType = LambdaPackageType.Image, MemorySize = 256, Timeout = 30)][HttpApi(LambdaHttpMethod.Get, "/cinemas")]public async Task<IHttpResult> HttpGetCinemas([FromQuery] string query,[FromQuery] int? offset,[FromQuery] int? limit,ILambdaContext context){var request = new ListRequest{Query = EmptyAsNull(query),Offset = offset ?? 0,Limit = limit ?? AppPaging.Paging.DefaultLimit};return await this.Invoke(request, context, () => Http(() => this.ListCinemas(request, context)));}/// <summary>/// The same as <see cref="CreateCinema"/>, for API Gateway: <c>POST /cinemas</c> with the name in the body./// </summary>/// <param name="request">The name of the cinema.</param>/// <param name="context">The Lambda invocation context.</param>/// <returns><c>201</c> with the cinema, or <c>400</c> with problem details when the request is invalid.</returns>[LambdaFunction(ResourceName = "HttpCreateCinema", PackageType = LambdaPackageType.Image, MemorySize = 256, Timeout = 30)][HttpApi(LambdaHttpMethod.Post, "/cinemas")]public async Task<IHttpResult> HttpCreateCinema([FromBody] CreateCinemaRequest request, ILambdaContext context){return await this.Invoke(request, context, () => Http(() => this.AddCinema(request, context), HttpResults.Created));}A create should answer
201 Created, and theHttphelper only knew200 OK. Give it an optionalsuccessthat turns the result into a response, soHttpResults.Createdcan take over, and update its summary to say so:private static async Task<IHttpResult> Http<T>(Func<Task<T>> function, Func<string?, object?, IHttpResult>? success = null){try{var result = await function();return success is null ? HttpResults.Ok(result) : success(null, result);}catch (ValidationException exception)...
The build regenerates
src/Presentation/serverless.templatefrom the attributes, so the four new functions show up there. Commit it with the code. -
-
Test the new slice (
test-design,unit-tests,integration-testsandpresentation-integration-tests).Each new test has a sample test that already does the same job for movies or reviews. Copy it and rename it, and you have the shape, the names and the house style without having to think about them.
tests/Application.Tests.Unit/Cinemas/Queries/GetCinemas/GetCinemasHandlerTests.cs, copied fromMovies/Queries/GetMovies/GetMoviesHandlerTests.cs.tests/Application.Tests.Unit/Cinemas/Queries/GetCinemas/GetCinemasValidatorTests.cs, copied fromMovies/Queries/GetMovies/GetMoviesValidatorTests.cs.tests/Application.Tests.Unit/Cinemas/Commands/CreateCinema/CreateCinemaHandlerTests.cs, copied fromReviews/Commands/CreateReview/CreateReviewHandlerTests.cs.tests/Application.Tests.Unit/Cinemas/Commands/CreateCinema/CreateCinemaValidatorTests.cs, copied fromReviews/Commands/CreateReview/CreateReviewValidatorTests.cs.- A
Cinemasregion intests/Infrastructure.Tests.Integration/Databases/MovieReviews/EntityFrameworkMovieReviewsRepositoryTests.cs, copied from theMoviesregion: search, paging and create. GetCinemas_ShouldReturn_FirstPage,CreateCinema_ShouldReturn_CinemaandCreateCinema_ShouldThrow_WhenNameIsEmptyintests/Presentation.Tests.Integration/HandlerTests.cs, copied from theGetMoviestests in the same file.HttpGetCinemas_ShouldReturn_Ok,HttpCreateCinema_ShouldReturn_CreatedandHttpCreateCinema_ShouldReturn_BadRequest_WhenNameIsEmptyintests/Presentation.Tests.Integration/HttpApiTests.cs, copied from theHttpGetMoviestests in the same file.
The repository tests need some cinemas. Add three to
AddTestDataintests/Infrastructure.Tests.Integration/Databases/MovieReviews/Extensions/MovieReviewsCollectionData.cs, named the same way as the sample rows:List<Cinema> cinemas =[new() { Id = Guid.NewGuid(), Name = "One" },new() { Id = Guid.NewGuid(), Name = "Two" },new() { Id = Guid.NewGuid(), Name = "Three" }];context.Cinemas.AddRange(cinemas);Terminal window dotnet builddotnet testdotnet format --verify-no-changesBoth domains now run side by side. Stop here if you’re keeping the sample for reference, which is a perfectly respectable choice.
Take out the sample
Section titled “Take out the sample”-
Take out the sample movies, authors and reviews (
sample-dataanddatabase-migrations).This step is mostly deleting, but the template’s own tests use the sample as their test subject, so a few of them change instead of going. Work through it layer by layer and build as you go. The compiler finds what’s left faster than any list.
-
Application: delete
src/Application/Authors/,Movies/andReviews/. InCommon/Enums/EntityType.cs, replaceAuthor,MovieandReviewwithCinema.NotFoundExceptionuses it, and you’ll want it the day you addGetCinemaById. -
Infrastructure: delete
Author.cs,Movie.csandReview.csfromModels/, and the matching*Configuration.csfiles. Then remove from:MovieReviewsDbContext.cs: their threeDbSetproperties.MovieReviewsMapper.cs: their aliases and mapping methods.EntityFrameworkMovieReviewsRepository.cs: theAuthors,Movies,ReviewsandHelpersregions, theirusinglines and aliases, and their three interfaces.DependencyInjection.cs: their three registrations andusinglines.MovieReviewsDbContextExtensions.cs: the titles, the review texts and the author, movie and review fakers. Change the guard at the top ofAddDatatocontext.Cinemas.Any().
-
Presentation: delete
Author.cs,Movie.cs,Review.csandListReviewsRequest.csfromLambdaFunction/Models/. Then remove from:LambdaFunction.cs:GetMovies,GetAuthorsandGetReviews, theirHttptwins, the private methods behind them,ParseId, which only the review functions used, and theirusinglines. Move the “This is the function the image runs by default.” line toGetCinemas, and make the class summary’s exampleHandler_GetCinemas_Generated.LambdaFunctionMapper.cs: their aliases and mapping methods.LambdaFunctionJsonSerializerContext.cs: their[JsonSerializable]lines.Models/ListRequest.cs: the summary, which says it lists movies and authors. Make it “Lists cinemas one page at a time”.
-
Dockerfile: the image runsGetMoviesby default, which is gone. Point theCMDatPresentation::WorksOnMyMachine.Movies.Presentation.LambdaFunction.Handler_GetCinemas_Generated::GetCinemas. -
docs/RUN.mdand thelambda-emulatorskill: their examples invoke the sample functions. Swap inGetCinemasandHttpGetCinemas. -
Migrations: replace the history with one migration for your schema. With the old snapshot gone, the tool files the new one under a folder named after the namespace, so move it back beside the migration. Then add
// <auto-generated />to the first line of<timestamp>_InitialCreate.cs, as in step 3.Terminal window rm src/Infrastructure/Databases/MovieReviews/Migrations/*.csdotnet ef migrations add InitialCreate \--project ./src/Infrastructure \--output-dir Databases/MovieReviews/Migrations \--namespace WorksOnMyMachine.Movies.Infrastructure.Databases.MovieReviews.Migrationsmv src/Infrastructure/WorksOnMyMachine/Movies/Infrastructure/Databases/MovieReviews/Migrations/MovieReviewsDbContextModelSnapshot.cs \src/Infrastructure/Databases/MovieReviews/Migrations/rm -r src/Infrastructure/WorksOnMyMachinesed -i '1s/^\xEF\xBB\xBF//' src/Infrastructure/Databases/MovieReviews/Migrations/*.cs -
Tests to delete:
tests/Application.Tests.Unit/: theAuthors/,Movies/andReviews/folders.EntityFrameworkMovieReviewsRepositoryTests.cs: theAuthors,MoviesandReviewsregions.MovieReviewsCollectionData.cs: the author, movie and review rows.
-
Tests to change: these test the template’s plumbing, and they used the sample as their subject. Point them at cinemas.
Common/Behaviours/LoggingBehaviourTests.csandValidationBehaviourTests.cs: UseCreateCinemaCommand,CreateCinemaValidatorandCinemain place ofGetAuthorByIdQuery, its validator andAuthor. The invalid case is an emptyName, so the expected property isName. The logged message namesCreateCinemaCommand.Common/Exceptions/NotFoundExceptionTests.cs: UseEntityType.Cinemaand aCinema. The message becomes “The Cinema with the supplied id was not found.”MovieReviewsConfigurationTests.cs: Check a cinema loads, ignoring case: look up"one"and expect"One".DependencyInjectionTests.cs: ExpectICinemasRepository, 5 seeded cinemas and none when seeding is off. UseGetCinemasfor the concurrency and same-sample-data checks.HandlerTests.cs: Run the generated handlers and the validation checks againstGetCinemas, which returns 5 cinemas.HttpApiTests.cs: Keep the cinema tests, and point the generated handler test atHttpGetCinemas.TelemetryTests.cs: UseGetCinemasfor the function name, the ARN and the call, and expect aGetCinemasQueryspan. The HTTP test callsHttpGetCinemasand expects one use case span, because a list has no rejection before the use case runs.Serialization/LambdaFunctionJsonSerializerTests.cs: Drop the review test, and write a page of cinemas:{"items":[{"id":"…","name":"Lorem Ipsum"}],"totalCount":1}.
-
-
Check it the way CI will (
coverage).Terminal window dotnet builddotnet format --verify-no-changesdotnet test -m:1 \-p:CollectCoverage=true -p:CoverletOutput=../results/ -p:MergeWith="../results/coverage.json" \-p:CoverletOutputFormat=opencover%2cjson \-p:ExcludeByFile="**/Program.cs%2c**/Migrations/*.cs%2c**/obj/**/*.cs" \-p:ExcludeByAttribute="GeneratedCodeAttribute"The last table it prints is the merged total. Ours came out at 99.7%. If yours is under 95%,
coveragesays what to do about it, and it isn’t “lower the number”.
What’s still called “movie reviews”
Section titled “What’s still called “movie reviews””The database plumbing keeps its sample name: the Databases/MovieReviews folder, MovieReviewsDbContext, EntityFrameworkMovieReviewsRepository, the MovieReviews connection string and the movie-reviews.db file. They all work as they are. Everything in src/Infrastructure apart from DependencyInjection is internal, so renaming them later is a refactor that never reaches Application or Presentation. Do it when the name starts to bother you, and change the connection string’s name and DefaultConnectionString in LambdaFunction/Startup.cs at the same time.