Entity Framework Core Scaffolding with Handlebars

Scaffold EF Core models using Handlebars templates.

• Uses Handlebars.NET to compile Handlebars templates when generating models with the Entity Framework Core scaffolding tools.

EF Core Community Standup

View the EF Core Community Standup episode featuring this framework for scaffolding entities with Handlebars templates. The demos for the episode can be found on this GitHub repo.

Contributing

Before creating a pull request, please refer to the Contributing Guidelines.

Prerequisites

• Visual Studio 2022 or greater, JetBrains Rider 2024.3 or greater.
• .NET 9.0 SDK or greater.
• EF Core CLI 9.0 or greater.
  • Install global dotnet-ef tool.

    dotnet tool install --global dotnet-ef
    

  • Or update global dotnet-ef tool.

    dotnet tool update --global dotnet-ef
    

Windows Intel Setup

• Use SQL Server Management Studio to connect to SQL Server
• The easiest is to use LocalDb, which is installed with Visual Studio.
• Connect to: (localdb)\MsSqlLocalDb.
• Create a new database named NorthwindSlim.
• Download the NorthwindSlim.sql file from https://github.com/TrackableEntities/northwind-slim.
• Unzip NorthwindSlim.sql and run the script to create tables and populate them with data.

MacOS arm64 Setup (M Series)

• Install Docker Desktop
• Run Docker SQL Server instance for arm64

docker run -e "ACCEPT_EULA=1" -e "MSSQL_SA_PASSWORD=MyPass@word" -e "MSSQL_PID=Developer" -e "MSSQL_USER=SA" -p 1433:1433 -d --name=sql mcr.microsoft.com/azure-sql-edge

• Add VS Code Extension for SQL Server
  • Connect with username sa and password MyPass@word
  • Enable trust server certificate when prompted
  • See here for help connecting and writing commands and queries
• Create a new database named NorthwindSlim.
• Download the NorthwindSlim.sql file from https://github.com/TrackableEntities/northwind-slim.
• Unzip NorthwindSlim.sql and run the script to create tables and populate them with data.

Upgrading

1. Upgrade TargetFramework in .csproj file to net8.0 or net9.0.
   • Optional: Set ImplicitUsings to enable.
   • Optional: Set Nullable to enable.
2. Update the following NuGet packages to 9.0.0 or later:
   • Microsoft.EntityFrameworkCore.Design
   • Microsoft.EntityFrameworkCore.SqlServer
   • EntityFrameworkCore.Scaffolding.Handlebars
3. Remove the EnableNullableReferenceTypes option from services.AddHandlebarsScaffolding in ScaffoldingDesignTimeServices.ConfigureDesignTimeServices.
   • Version 6 or greater relies on support for nullable reference types in EF Core 6.
4. Run dotnet ef dbcontext scaffold command to regenerate entities.
   • You may retain your customized Handlebars templates.
   • Many-to-many relationships will be materialized without the need for an intermediate entity.

Usage

1. Create a new .NET 8 or .NET 9 class library.

2. Add EF Core SQL Server and Tools NuGet packages.

   • Microsoft.EntityFrameworkCore.SqlServer
   • Microsoft.EntityFrameworkCore.Design

   dotnet add package Microsoft.EntityFrameworkCore.SqlServer
   dotnet add package Microsoft.EntityFrameworkCore.Design
   

3. Add the EntityFrameworkCore.Scaffolding.Handlebars NuGet package:

   • EntityFrameworkCore.Scaffolding.Handlebars

   dotnet add package EntityFrameworkCore.Scaffolding.Handlebars
   

4. Remove Class1.cs and add a ScaffoldingDesignTimeServices class.

   • Implement IDesignTimeServices by adding a ConfigureDesignTimeServices method that calls services.AddHandlebarsScaffolding.
   • You can optionally pass a ReverseEngineerOptions enum to indicate if you wish to generate only entity types, only a DbContext class, or both (which is the default).

   public class ScaffoldingDesignTimeServices : IDesignTimeServices
   {
       public void ConfigureDesignTimeServices(IServiceCollection services)
       {
           services.AddHandlebarsScaffolding();
       }
   }
   

5. Open a command prompt at the project level and use the dotnet ef tool to reverse engineer a context and models from an existing database.

   • Get help on dotnet-ef-dbcontext-scaffold at the command line: dotnet ef dbcontext scaffold -h
   • Execute the following command to reverse engineer classes from the NorthwindSlim database:

   dotnet ef dbcontext scaffold "Data Source=(localdb)\MSSQLLocalDB; Initial Catalog=NorthwindSlim; Integrated Security=True" Microsoft.EntityFrameworkCore.SqlServer -o Models -c NorthwindSlimContext -f --context-dir Contexts
   

   • You should see context and/or entity classes appear in the Models folder of the project.
   • You will also see a CodeTemplates folder appear containing Handlebars templates for customizing generation of context and entity type classes.
   • Add -d to the command to use data annotations. You will need to add the System.ComponentModel.Annotations package to a .NET Standard library containing linked entity classes.

6. You may edit any of the template files which appear under the CodeTemplates folder.

   • For now you can just add some comments, but you may wish to customize the templates in other ways, for example, by inheriting entities from a base class or implementing specific interfaces.
   • When you run the dotnet-ef-dbcontext-scaffold command again, you will see your updated reflected in the generated classes.

Nullable Reference Types

Take advantage of C# nullable reference types by enabling them in your .csproj file. (This is by default in .NET 6 or greater.)

<PropertyGroup>
  <TargetFramework>net6.0</TargetFramework>
  <Nullable>enable</Nullable>
</PropertyGroup>

Non-nullable properties will include the null forgiving operator.

public partial class Product
{
    public string ProductName { get; set; } = null!;
    public decimal? UnitPrice { get; set; }
}

Excluded Tables

You can optionally exclude certain tables from code generation. These may also be qualified by schema name.

services.AddHandlebarsScaffolding(options =>
{
    // Exclude some tables
    options.ExcludedTables = new List<string> { "dbo.Territory" };
});

Custom Template Data

You may find it useful to add your own custom template data for use in your Handlebars templates. For example, the model namespace is not included by default in the DbContext class import statements. To compensate you may wish to add a models-namespace template to the DbImports.hbs template file.

using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata; // Comment
using {{models-namespace}};

Likewise you may wish to specify the name of a model base class in the same way.

public partial class {{class}} : {{base-class}}
{
    {{{> constructor}}}
    {{> properties}}
}

You can then set the value of these templates in the TemplateData property of HandlebarsScaffoldingOptions.

services.AddHandlebarsScaffolding(options =>
{
    // Add custom template data
    options.TemplateData = new Dictionary<string, object>
    {
        { "models-namespace", "ScaffoldingSample.Models" },
        { "base-class", "EntityBase" }
    };
});

Schema Folders

You can generate models in different folders by database schema.

services.AddHandlebarsScaffolding(options =>
{
    // Put Models into folders by DB Schema
    options.EnableSchemaFolders = true;
});

Embedded Templates

Handlebars templates may be embdedded in a separate .NET Standard project that can be shared among multiple .NET Core scaffolding projects. Simply copy the CodeTemplates folder to the .NET Standard project and edit the .csproj file to embed them as a resource in the assembly.

<ItemGroup>
  <EmbeddedResource Include="CodeTemplates\**\*.hbs" />
</ItemGroup>

Then reference the .NET Standard project from the .NET Core projects and specify the templates assembly when adding Handlebars scaffolding in the ScaffoldingDesignTimeServices class.

public class ScaffoldingDesignTimeServices : IDesignTimeServices
{
    public void ConfigureDesignTimeServices(IServiceCollection services)
    {
        // Get templates assembly
        var templatesAssembly = Assembly.Load("TemplatesAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null");

        // Add Handlebars scaffolding using embedded templates templates
        services.AddHandlebarsScaffolding(options => options.EmbeddedTemplatesAssembly = templatesAssembly);
    }
}

Handlebars Helpers and Transformers

You can register Handlebars helpers in the ScaffoldingDesignTimeServices where setup takes place.

• Create a named tuple as shown with myHelper below.
• The `cont