Starts in:
2 DAYS
11 HRS
45 MIN
56 SEC
Starts in:
2 D
11 H
45 M
56 S

There are multiple versions of this document. Pick the options that suit you best.

UI
Database

Web Application Development Tutorial - Part 10: Book to Author Relation

About This Tutorial

In this tutorial series, you will build an ABP based web application named Acme.BookStore. This application is used to manage a list of books and their authors. It is developed using the following technologies:

  • Entity Framework Core as the database provider.
  • MAUI / Blazor Hybrid as the UI Framework.

This tutorial is organized as the following parts;

Download the Source Code

This tutorial has multiple versions based on your UI and Database preferences. We've prepared two combinations of the source code to be downloaded:

If you encounter the "filename too long" or "unzip" error on Windows, please see this guide.

Introduction

We have created Book and Author functionalities for the book store application. However, currently there is no relation between these entities.

In this tutorial, we will establish a 1 to N relation between the Author and the Book entities.

Add Relation to The Book Entity

Open the Books/Book.cs in the Acme.BookStore.Domain project and add the following property to the Book entity:

public Guid AuthorId { get; set; }

In this tutorial, we preferred to not add a navigation property to the Author entity from the Book class (like public Author Author { get; set; }). This is due to follow the DDD best practices (rule: refer to other aggregates only by id). However, you can add such a navigation property and configure it for the EF Core. In this way, you don't need to write join queries while getting books with their authors (like we will be doing below) which makes your application code simpler.

Database & Data Migration

Added a new, required AuthorId property to the Book entity. But, what about the existing books on the database? They currently don't have AuthorIds and this will be a problem when we try to run the application.

This is a typical migration problem and the decision depends on your case;

  • If you haven't published your application to the production yet, you can just delete existing books in the database, or you can even delete the entire database in your development environment.
  • You can update the existing data programmatically on data migration or seed phase.
  • You can manually handle it on the database.

We prefer to delete the database (you can run the Drop-Database in the Package Manager Console) since this is just an example project and data loss is not important. Since this topic is not related to the ABP Framework, we don't go deeper for all the scenarios.

Update the EF Core Mapping

Open the BookStoreDbContextModelCreatingExtensions class under the EntityFrameworkCore folder of the Acme.BookStore.EntityFrameworkCore project and change the builder.Entity<Book> part as shown below:

builder.Entity<Book>(b =>
{
    b.ToTable(BookStoreConsts.DbTablePrefix + "Books", BookStoreConsts.DbSchema);
    b.ConfigureByConvention(); //auto configure for the base class props
    b.Property(x => x.Name).IsRequired().HasMaxLength(128);
    
    // ADD THE MAPPING FOR THE RELATION
    b.HasOne<Author>().WithMany().HasForeignKey(x => x.AuthorId).IsRequired();
});

Add New EF Core Migration

The startup solution is configured to use Entity Framework Core Code First Migrations. Since we've changed the database mapping configuration, we should create a new migration and apply changes to the database.

Open a command-line terminal in the directory of the Acme.BookStore.EntityFrameworkCore project and type the following command:

dotnet ef migrations add Added_AuthorId_To_Book

This should create a new migration class with the following code in its Up method:

migrationBuilder.AddColumn<Guid>(
    name: "AuthorId",
    table: "AppBooks",
    type: "uniqueidentifier",
    nullable: false,
    defaultValue: new Guid("00000000-0000-0000-0000-000000000000"));

migrationBuilder.CreateIndex(
    name: "IX_AppBooks_AuthorId",
    table: "AppBooks",
    column: "AuthorId");

migrationBuilder.AddForeignKey(
    name: "FK_AppBooks_AppAuthors_AuthorId",
    table: "AppBooks",
    column: "AuthorId",
    principalTable: "AppAuthors",
    principalColumn: "Id",
    onDelete: ReferentialAction.Cascade);
  • Adds an AuthorId field to the AppBooks table.
  • Creates an index on the AuthorId field.
  • Declares the foreign key to the AppAuthors table.

If you are using Visual Studio, you may want to use Add-Migration Added_AuthorId_To_Book -c BookStoreMigrationsDbContext and Update-Database -c BookStoreMigrationsDbContext commands in the Package Manager Console (PMC). In this case, ensure that is the startup project and Acme.BookStore.EntityFrameworkCore.DbMigrations is the Default Project in PMC.

Change the Data Seeder

Since the AuthorId is a required property of the Book entity, current data seeder code can not work. Open the BookStoreDataSeederContributor in the Acme.BookStore.Domain project and change as the following:

using System;
using System.Threading.Tasks;
using Acme.BookStore.Authors;
using Acme.BookStore.Books;
using Volo.Abp.Data;
using Volo.Abp.DependencyInjection;
using Volo.Abp.Domain.Repositories;

namespace Acme.BookStore;

public class BookStoreDataSeederContributor
    : IDataSeedContributor, ITransientDependency
{
    private readonly IRepository<Book, Guid> _bookRepository;
    private readonly IAuthorRepository _authorRepository;
    private readonly AuthorManager _authorManager;

    public BookStoreDataSeederContributor(
        IRepository<Book, Guid> bookRepository,
        IAuthorRepository authorRepository,
        AuthorManager authorManager)
    {
        _bookRepository = bookRepository;
        _authorRepository = authorRepository;
        _authorManager = authorManager;
    }

    public async Task SeedAsync(DataSeedContext context)
    {
        if (await _bookRepository.GetCountAsync() > 0)
        {
            return;
        }

        var orwell = await _authorRepository.InsertAsync(
            await _authorManager.CreateAsync(
                "George Orwell",
                new DateTime(1903, 06, 25),
                "Orwell produced literary criticism and poetry, fiction and polemical journalism; and is best known for the allegorical novella Animal Farm (1945) and the dystopian novel Nineteen Eighty-Four (1949)."
            )
        );

        var douglas = await _authorRepository.InsertAsync(
            await _authorManager.CreateAsync(
                "Douglas Adams",
                new DateTime(1952, 03, 11),
                "Douglas Adams was an English author, screenwriter, essayist, humorist, satirist and dramatist. Adams was an advocate for environmentalism and conservation, a lover of fast cars, technological innovation and the Apple Macintosh, and a self-proclaimed 'radical atheist'."
            )
        );

        await _bookRepository.InsertAsync(
            new Book
            {
                AuthorId = orwell.Id, // SET THE AUTHOR
                Name = "1984",
                Type = BookType.Dystopia,
                PublishDate = new DateTime(1949, 6, 8),
                Price = 19.84f
            },
            autoSave: true
        );

        await _bookRepository.InsertAsync(
            new Book
            {
                AuthorId = douglas.Id, // SET THE AUTHOR
                Name = "The Hitchhiker's Guide to the Galaxy",
                Type = BookType.ScienceFiction,
                PublishDate = new DateTime(1995, 9, 27),
                Price = 42.0f
            },
            autoSave: true
        );
    }
}

The only change is that we set the AuthorId properties of the Book entities.

Delete existing books or delete the database before executing the DbMigrator. See the Database & Data Migration section above for more info.

You can now run the .DbMigrator console application to migrate the database schema and seed the initial data.

Application Layer

We will change the BookAppService to support the Author relation.

Data Transfer Objects

Let's begin from the DTOs.

BookDto

Open the BookDto class in the Books folder of the Acme.BookStore.Application.Contracts project and add the following properties:

public Guid AuthorId { get; set; }
public string AuthorName { get; set; }

The final BookDto class should be following:

using System;
using Volo.Abp.Application.Dtos;

namespace Acme.BookStore.Books;

public class BookDto : AuditedEntityDto<Guid>
{
    public Guid AuthorId { get; set; }

    public string AuthorName { get; set; } = string.Empty;

    public string Name { get; set; } = string.Empty;

    public BookType Type { get; set; }

    public DateTime PublishDate { get; set; }

    public float Price { get; set; }
}

CreateUpdateBookDto

Open the CreateUpdateBookDto class in the Books folder of the Acme.BookStore.Application.Contracts project and add an AuthorId property as shown:

public Guid AuthorId { get; set; }

AuthorLookupDto

Create a new class, AuthorLookupDto, inside the Books folder of the Acme.BookStore.Application.Contracts project:

using System;
using Volo.Abp.Application.Dtos;

namespace Acme.BookStore.Books;

public class AuthorLookupDto : EntityDto<Guid>
{
    public string Name { get; set; } = string.Empty;
}

This will be used in a new method that will be added to the IBookAppService.

IBookAppService

Open the IBookAppService interface in the Books folder of the Acme.BookStore.Application.Contracts project and add a new method, named GetAuthorLookupAsync, as shown below:

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Application.Services;

namespace Acme.BookStore.Books;

public interface IBookAppService :
    ICrudAppService< //Defines CRUD methods
        BookDto, //Used to show books
        Guid, //Primary key of the book entity
        PagedAndSortedResultRequestDto, //Used for paging/sorting
        CreateUpdateBookDto> //Used to create/update a book
{
    // ADD the NEW METHOD
    Task<ListResultDto<AuthorLookupDto>> GetAuthorLookupAsync();
}

This new method will be used from the UI to get a list of authors and fill a dropdown list to select the author of a book.

BookAppService

Open the BookAppService interface in the Books folder of the Acme.BookStore.Application project and replace the file content with the following code:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Linq.Dynamic.Core;
using System.Threading.Tasks;
using Acme.BookStore.Authors;
using Acme.BookStore.Permissions;
using Microsoft.AspNetCore.Authorization;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Application.Services;
using Volo.Abp.Domain.Entities;
using Volo.Abp.Domain.Repositories;

namespace Acme.BookStore.Books;

[Authorize(BookStorePermissions.Books.Default)]
public class BookAppService :
    CrudAppService<
        Book, //The Book entity
        BookDto, //Used to show books
        Guid, //Primary key of the book entity
        PagedAndSortedResultRequestDto, //Used for paging/sorting
        CreateUpdateBookDto>, //Used to create/update a book
    IBookAppService //implement the IBookAppService
{
    private readonly IAuthorRepository _authorRepository;

    public BookAppService(
        IRepository<Book, Guid> repository,
        IAuthorRepository authorRepository)
        : base(repository)
    {
        _authorRepository = authorRepository;
        GetPolicyName = BookStorePermissions.Books.Default;
        GetListPolicyName = BookStorePermissions.Books.Default;
        CreatePolicyName = BookStorePermissions.Books.Create;
        UpdatePolicyName = BookStorePermissions.Books.Edit;
        DeletePolicyName = BookStorePermissions.Books.Create;
    }

    public override async Task<BookDto> GetAsync(Guid id)
    {
        //Get the IQueryable<Book> from the repository
        var queryable = await Repository.GetQueryableAsync();

        //Prepare a query to join books and authors
        var query = from book in queryable
                    join author in await _authorRepository.GetQueryableAsync() on book.AuthorId equals author.Id
                    where book.Id == id
                    select new { book, author };

        //Execute the query and get the book with author
        var queryResult = await AsyncExecuter.FirstOrDefaultAsync(query);
        if (queryResult == null)
        {
            throw new EntityNotFoundException(typeof(Book), id);
        }

        var bookDto = ObjectMapper.Map<Book, BookDto>(queryResult.book);
        bookDto.AuthorName = queryResult.author.Name;
        return bookDto;
    }

    public override async Task<PagedResultDto<BookDto>>
        GetListAsync(PagedAndSortedResultRequestDto input)
    {
        //Get the IQueryable<Book> from the repository
        var queryable = await Repository.GetQueryableAsync();

        //Prepare a query to join books and authors
        var query = from book in queryable
                    join author in await _authorRepository.GetQueryableAsync() on book.AuthorId equals author.Id
                    select new { book, author };

        query = query
            .OrderBy(NormalizeSorting(input.Sorting))
            .Skip(input.SkipCount)
            .Take(input.MaxResultCount);

        //Execute the query and get a list
        var queryResult = await AsyncExecuter.ToListAsync(query);

        //Convert the query result to a list of BookDto objects
        var bookDtos = queryResult.Select(x =>
        {
            var bookDto = ObjectMapper.Map<Book, BookDto>(x.book);
            bookDto.AuthorName = x.author.Name;
            return bookDto;
        }).ToList();

        //Get the total count with another query
        var totalCount = await Repository.GetCountAsync();

        return new PagedResultDto<BookDto>(
            totalCount,
            bookDtos
        );
    }

    public async Task<ListResultDto<AuthorLookupDto>> GetAuthorLookupAsync()
    {
        var authors = await _authorRepository.GetListAsync();

        return new ListResultDto<AuthorLookupDto>(
            ObjectMapper.Map<List<Author>, List<AuthorLookupDto>>(authors)
        );
    }

    private static string NormalizeSorting(string sorting)
    {
        if (sorting.IsNullOrEmpty())
        {
            return $"book.{nameof(Book.Name)}";
        }

        if (sorting.Contains("authorName", StringComparison.OrdinalIgnoreCase))
        {
            return sorting.Replace(
                "authorName",
                "author.Name",
                StringComparison.OrdinalIgnoreCase
            );
        }

        return $"book.{sorting}";
    }
}

Let's see the changes we've done:

  • Added [Authorize(BookStorePermissions.Books.Default)] to authorize the methods we've newly added/overrode (remember, authorize attribute is valid for all the methods of the class when it is declared for a class).
  • Injected IAuthorRepository to query from the authors.
  • Overrode the GetAsync method of the base CrudAppService, which returns a single BookDto object with the given id.
    • Used a simple LINQ expression to join books and authors and query them together for the given book id.
    • Used AsyncExecuter.FirstOrDefaultAsync(...) to execute the query and get a result. It is a way to use asynchronous LINQ extensions without depending on the database provider API. Check the repository documentation to understand why we've used it.
    • Throws an EntityNotFoundException which results an HTTP 404 (not found) result if requested book was not present in the database.
    • Finally, created a BookDto object using the ObjectMapper, then assigning the AuthorName manually.
  • Overrode the GetListAsync method of the base CrudAppService, which returns a list of books. The logic is similar to the previous method, so you can easily understand the code.
  • Created a new method: GetAuthorLookupAsync. This simple gets all the authors. The UI uses this method to fill a dropdown list and select and author while creating/editing books.

Object to Object Mapping Configuration

Introduced the AuthorLookupDto class and used object mapping inside the GetAuthorLookupAsync method. So, we need to add a new mapping definition inside the BookStoreApplicationAutoMapperProfile.cs file of the Acme.BookStore.Application project:

CreateMap<Author, AuthorLookupDto>();

Unit Tests

Some of the unit tests will fail since we made some changed on the BookAppService. Open the BookAppService_Tests in the Books folder of the Acme.BookStore.Application.Tests project and change the content as the following:

using System;
using System.Linq;
using System.Threading.Tasks;
using Acme.BookStore.Authors;
using Shouldly;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Modularity;
using Volo.Abp.Validation;
using Xunit;

namespace Acme.BookStore.Books;

public abstract class BookAppService_Tests<TStartupModule> : BookStoreApplicationTestBase<TStartupModule>
    where TStartupModule : IAbpModule
{
    private readonly IBookAppService _bookAppService;
    private readonly IAuthorAppService _authorAppService;

    protected BookAppService_Tests()
    {
        _bookAppService = GetRequiredService<IBookAppService>();
        _authorAppService = GetRequiredService<IAuthorAppService>();
    }

    [Fact]
    public async Task Should_Get_List_Of_Books()
    {
        //Act
        var result = await _bookAppService.GetListAsync(
            new PagedAndSortedResultRequestDto()
        );

        //Assert
        result.TotalCount.ShouldBeGreaterThan(0);
        result.Items.ShouldContain(b => b.Name == "1984" &&
                                   b.AuthorName == "George Orwell");
    }

    [Fact]
    public async Task Should_Create_A_Valid_Book()
    {
        var authors = await _authorAppService.GetListAsync(new GetAuthorListDto());
        var firstAuthor = authors.Items.First();

        //Act
        var result = await _bookAppService.CreateAsync(
            new CreateUpdateBookDto
            {
                AuthorId = firstAuthor.Id,
                Name = "New test book 42",
                Price = 10,
                PublishDate = System.DateTime.Now,
                Type = BookType.ScienceFiction
            }
        );

        //Assert
        result.Id.ShouldNotBe(Guid.Empty);
        result.Name.ShouldBe("New test book 42");
    }

    [Fact]
    public async Task Should_Not_Create_A_Book_Without_Name()
    {
        var exception = await Assert.ThrowsAsync<AbpValidationException>(async () =>
        {
            await _bookAppService.CreateAsync(
                new CreateUpdateBookDto
                {
                    Name = "",
                    Price = 10,
                    PublishDate = DateTime.Now,
                    Type = BookType.ScienceFiction
                }
            );
        });

        exception.ValidationErrors
            .ShouldContain(err => err.MemberNames.Any(m => m == "Name"));
    }
}
  • Changed the assertion condition in the Should_Get_List_Of_Books from b => b.Name == "1984" to b => b.Name == "1984" && b.AuthorName == "George Orwell" to check if the author name was filled.
  • Changed the Should_Create_A_Valid_Book method to set the AuthorId while creating a new book, since it is required anymore.

The User Interface

The Book List

It is very easy to show the Author Name in the book list. Open the /Pages/Books.razor file in the Acme.BookStore.MauiBlazor project and add the following DataGridColumn definition just after the Name (book name) column:

<DataGridColumn TItem="BookDto"
                Field="@nameof(BookDto.AuthorName)"
                Caption="@L["Author"]"></DataGridColumn>

When you run the application, you can see the Author column on the table:

blazor-bookstore-book-list-with-authors

Create Book Modal

Add the following field to the Books.razor.cs file:

IReadOnlyList<AuthorLookupDto> authorList = Array.Empty<AuthorLookupDto>();

Override the OnInitializedAsync method and add the following code to the end of the method:

protected override async Task OnInitializedAsync()
{
    await base.OnInitializedAsync();
    authorList = (await AppService.GetAuthorLookupAsync()).Items;
}

* It is essential to call the base.OnInitializedAsync() since AbpCrudPageBase has some initialization code to be executed.

Override the OpenCreateModalAsync method and add the following code to the end of the method:

protected override async Task OpenCreateModalAsync()
{
    if (!authorList.Any())
    {
        throw new UserFriendlyException(message: L["AnAuthorIsRequiredForCreatingBook"]);
    }
        
    await base.OpenCreateModalAsync();
    NewEntity.AuthorId = authorList.First().Id;
}

The final Books.razor.cs should be the following:

using Blazorise;
using System.Threading.Tasks;
using Volo.Abp.AspNetCore.Components.Web.Theming.PageToolbars;
using Acme.BookStore.Permissions;
using Acme.BookStore.Books;
using System.Collections.Generic;
using System;


namespace Acme.BookStore.MauiBlazor.Pages; 

public partial class Books
{
    IReadOnlyList<AuthorLookupDto> authorList = Array.Empty<AuthorLookupDto>();

    protected PageToolbar Toolbar { get; } = new();

    public Books()
    {
        CreatePolicyName = BookStorePermissions.Books.Create;
        UpdatePolicyName = BookStorePermissions.Books.Edit;
        DeletePolicyName = BookStorePermissions.Books.Delete;
    }

    protected override async Task OnInitializedAsync()
    {
        await base.OnInitializedAsync();
        authorList = (await AppService.GetAuthorLookupAsync()).Items;
    }

    protected override async Task OpenCreateModalAsync()
     {
         if (!authorList.Any())
         {
             throw new UserFriendlyException(message: L["AnAuthorIsRequiredForCreatingBook"]);
         }

         await base.OpenCreateModalAsync();
         NewEntity.AuthorId = authorList.First().Id;
     }

    protected override ValueTask SetToolbarItemsAsync()
    {
        Toolbar.AddButton(L["NewBook"],
            OpenCreateModalAsync,
            IconName.Add,
            requiredPolicyName: CreatePolicyName);

        return base.SetToolbarItemsAsync();
    }
}

Finally, add the following Field definition into the ModalBody of the Create modal, as the first item, before the Name field:

<Field>
    <FieldLabel>@L["Author"]</FieldLabel>
    <Select TValue="Guid" @bind-SelectedValue="@NewEntity.AuthorId">
        @foreach (var author in authorList)
        {
            <SelectItem TValue="Guid" Value="@author.Id">
                @author.Name
            </SelectItem>
        }
        </Select>
</Field>

This requires to add a new localization key to the en.json file:

"AnAuthorIsRequiredForCreatingBook": "An author is required to create a book"

You can run the application to see the Author Selection while creating a new book:

book-create-modal-with-author

Edit Book Modal

Add the following Field definition into the ModalBody of the Edit modal, as the first item, before the Name field:

<Field>
    <FieldLabel>@L["Author"]</FieldLabel>
    <Select TValue="Guid" @bind-SelectedValue="@EditingEntity.AuthorId">
        @foreach (var author in authorList)
        {
            <SelectItem TValue="Guid" Value="@author.Id">
                @author.Name
            </SelectItem>
        }
    </Select>
</Field>

That's all. We are reusing the authorList defined for the Create modal.

Previous
Authors: User Interface

Was this page helpful?

Please make a selection.

To help us improve, please share your reason for the negative feedback in the field below.

Please enter a note.

Thank you for your valuable feedback!

Please note that although we cannot respond to feedback, our team will use your comments to improve the experience.

In this document
Community Talks

What’s New with .NET 9 & ABP 9?

21 Nov, 17:00
Online
Watch the Event
Mastering ABP Framework Book
Mastering ABP Framework

This book will help you gain a complete understanding of the framework and modern web application development techniques.

Learn More