Scaffold EF Core models using Handlebars templates.
- Uses Handlebars.NET to compile Handlebars templates when generating models with the Entity Framework Core scaffolding tools.
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.
Before creating a pull request, please refer to the Contributing Guidelines.
- Visual Studio 2022 or greater, JetBrains Rider 2022.2 or greater.
- .NET 8.0 SDK or greater.
- EF Core CLI 8.0 or greater.
- Install global
dotnet-eftool.dotnet tool install --global dotnet-ef - Or update global
dotnet-eftool.dotnet tool update --global dotnet-ef
- Install global
- 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.sqlfile from https://github.com/TrackableEntities/northwind-slim. - Unzip NorthwindSlim.sql and run the script to create tables and populate them with data.
- 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
saand passwordMyPass@word - Enable trust server certificate when prompted
- See here for help connecting and writing commands and queries
- Connect with username
- Create a new database named NorthwindSlim.
- Download the
NorthwindSlim.sqlfile from https://github.com/TrackableEntities/northwind-slim. - Unzip NorthwindSlim.sql and run the script to create tables and populate them with data.
- Upgrade
TargetFrameworkin .csproj file tonet8.0.- Optional: Set
ImplicitUsingstoenable. - Optional: Set
Nullabletoenable.
- Optional: Set
- Update the following NuGet packages to
8.0.0or later:- Microsoft.EntityFrameworkCore.Design
- Microsoft.EntityFrameworkCore.SqlServer
- EntityFrameworkCore.Scaffolding.Handlebars
- Remove the
EnableNullableReferenceTypesoption fromservices.AddHandlebarsScaffoldinginScaffoldingDesignTimeServices.ConfigureDesignTimeServices.- Version 6 or greater relies on support for nullable reference types in EF Core 6.
- Run
dotnet ef dbcontext scaffoldcommand to regenerate entities.- You may retain your customized Handlebars templates.
- Many-to-many relationships will be materialized without the need for an intermediate entity.
-
Create a new .NET 8 class library.
-
Add EF Core SQL Server and Tools NuGet packages.
Microsoft.EntityFrameworkCore.SqlServerMicrosoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer dotnet add package Microsoft.EntityFrameworkCore.Design -
Add the EntityFrameworkCore.Scaffolding.Handlebars NuGet package:
EntityFrameworkCore.Scaffolding.Handlebars
dotnet add package EntityFrameworkCore.Scaffolding.Handlebars -
Remove Class1.cs and add a ScaffoldingDesignTimeServices class.
- Implement
IDesignTimeServicesby adding aConfigureDesignTimeServicesmethod that callsservices.AddHandlebarsScaffolding. - You can optionally pass a
ReverseEngineerOptionsenum 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(); } }
- Implement
-
Open a command prompt at the project level and use the
dotnet eftool 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
-dto 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.
- Get help on dotnet-ef-dbcontext-scaffold at the command line:
-
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.
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; }
}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" };
});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.
Likewise you may wish to specify the name of a model base class in the same way.
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" }
};
});You can generate models in different folders by database schema.
services.AddHandlebarsScaffolding(options =>
{
// Put Models into folders by DB Schema
options.EnableSchemaFolders = true;
});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);
}
}You can register Handlebars helpers in the ScaffoldingDesignTimeServices where setup takes place.
- Create a named tuple as shown with
myHelperbelow. - The
contextparameter of the helper method provides model data injected by the Handlebars scaffolding extension. - Pass the tuple to the
AddHandlebarsHelpersextension method. - To use Handlebars helper defined above, add the following to any of the .hbs files within the CodeTemplates folder:
{{my-helper}} - You may register as many helpers as you wish.
You can pass transform functions to AddHandlebarsTransformers in order to customize generation of entity type definitions, including class names, constructors and properties.
public class ScaffoldingDesignTimeServices : IDesignTimeServices
{
public void ConfigureDesignTimeServices(IServiceCollection services)
{
// Add Handlebars scaffolding templates
services.AddHandlebarsScaffolding(options =>
{
// Generate both context and entities
options.ReverseEngineerOptions = ReverseEngineerOptions.DbContextAndEntities;
// Enable Nullable reference types
options.EnableNullableReferenceTypes = true;
// Put Models into folders by DB Schema
//options.EnableSchemaFolders = true;
// Exclude some tables
options.ExcludedTables = new List<string> { "Territory", "EmployeeTerritories" };
// Add custom template data
options.TemplateData = new Dictionary<string, object>
{
{ "models-namespace", "ScaffoldingSample.Models" },
{ "base-class", "EntityBase" }
};
});
// Register Handlebars helper
var myHelper = (helperName: "my-helper", helperFunction: (Action<TextWriter, Dictionary<string, object>, object[]>) MyHbsHelper);
// Add optional Handlebars helpers
services.AddHandlebarsHelpers(myHelper);
// Add Handlebars transformer for Country property
services.AddHandlebarsTransformers(
propertyTransformer: p =>
p.PropertyName == "Country"
? new EntityPropertyInfo("Country?", p.PropertyName, false)
: new EntityPropertyInfo(p.PropertyType, p.PropertyName, p.PropertyIsNullable));
// Add Handlebars transformer for Id property
//services.AddHandlebarsTransformers2(
// propertyTransformer: (e, p) =>
// $"{e.Name}Id" == p.PropertyName
// ? new EntityPropertyInfo(p.PropertyType, "Id", false)
// : new EntityPropertyInfo(p.PropertyType, p.PropertyName, p.PropertyIsNullable));
// Add optional Handlebars transformers
//services.AddHandlebarsTransformers2(
// entityTypeNameTransformer: n => n + "Foo",
// entityFileNameTransformer: n => n + "Foo",
// constructorTransformer: (e, p) => new EntityPropertyInfo(p.PropertyType + "Foo", p.PropertyName + "Foo"),
// propertyTransformer: (e, p) => new EntityPropertyInfo(p.PropertyType, p.PropertyName + "Foo"),
// navPropertyTransformer: (e, p) => new EntityPropertyInfo(p.PropertyType + "Foo", p.PropertyName + "Foo"));
}
// Sample Handlebars helper
void MyHbsHelper(TextWriter writer, Dictionary<string, object> context, object[] parameters)
{
writer.Write("// My Handlebars Helper");
}
}There are times when you might like to modify generated code, for example, by adding a HasConversion method to an entity property in the OnModelCreating method of the generated class that extends DbContext. However, doing so may prove futile because added code would be overwritten the next time you run the dotnet ef dbcontext scaffold command.
- Rather than modifying generated code, a better idea would be to extend it by using partial classes and methods. To enable this scenario, the generated
DbContextclass is already defined using thepartialkeyword, and it contains a partialOnModelCreatingPartialmethod that is invoked at the end of theOnModelCreatingmethod. - To implement the partial method, simply add a new class to your project with the same name as the generated
DbContextclass, and define it aspartial. Then add aOnModelCreatingPartialmethod with the same signature as the partial method defined in the generatedDbContextclass.
// Place in separate class file (NorthwindSlimContextPartial.cs)
public partial class NorthwindSlimContext
{
partial void OnModelCreatingPartial(ModelBuilder modelBuilder)
{
modelBuilder.Entity<Employee>()
.Property(e => e.Country)
.HasConversion(
v => v.ToString(),
v => (Country)Enum.Parse(typeof(Country), v));
modelBuilder.Entity<Customer>()
.Property(e => e.Country)
.HasConversion(
v => v.ToString(),
v => (Country)Enum.Parse(typeof(Country), v));
}
}To generate TypeScript entities simply pass LanguageOptions.TypeScript to AddHandlebarsScaffolding. Since generating a DbContext class is strictly a server-side concern, you should also pass ReverseEngineerOptions.EntitiesOnly to AddHandlebarsScaffolding.
public class ScaffoldingDesignTimeServices : IDesignTimeServices
{
public void ConfigureDesignTimeServices(IServiceCollection services)
{
// Generate entities only
var options = ReverseEngineerOptions.EntitiesOnly;
// Generate TypeScript files
var language = LanguageOptions.TypeScript;
// Add Handlebars scaffolding templates
services.AddHandlebarsScaffolding(options, language);
}
}For an example of this approach, see
MyHbsCSharpEntityTypeGeneratorin the ef-core-community-handlebars repo.
To take full control of context and entity generation, you can extend HbsCSharpDbContextGenerator and HbsCSharpEntityTypeGenerator, overriding select virtual methods. Then register your custom generators in ScaffoldingDesignTimeServices.ConfigureDesignTimeServices.
For example, you may want to add property-isprimarykey to the template data in order to insert some code or a comment.
- Add a
MyHbsCSharpEntityTypeGeneratorto the .Tooling project.- Extend
HbsCSharpEntityTypeGenerator. - Override
GenerateProperties. - Copy code from the base
GeneratePropertiesmethod. - Add code that inserts
property-isprimarykeyinto the template data.
protected override void GenerateProperties(IEntityType entityType) { var properties = new List<Dictionary<string, object>>(); foreach (var property in entityType.GetProperties().OrderBy(p => p.GetColumnOrdinal())) { // Code elided for clarity properties.Add(new Dictionary<string, object> { { "property-type", propertyType }, { "property-name", property.Name }, { "property-annotations", PropertyAnnotationsData }, { "property-comment", property.GetComment() }, { "property-isnullable", property.IsNullable }, { "nullable-reference-types", _options?.Value?.EnableNullableReferenceTypes == true }, // Add new item to template data { "property-isprimarykey", property.IsPrimaryKey() } }); } var transformedProperties = EntityTypeTransformationService.TransformProperties(properties); // Add to transformed properties for (int i = 0; i < transformedProperties.Count ; i++) { transformedProperties[i].Add("property-isprimarykey", properties[i]["property-isprimarykey"]); } TemplateData.Add("properties", transformedProperties); }
- Extend
- Register
MyHbsCSharpEntityTypeGeneratorinScaffoldingDesignTimeServices.ConfigureDesignTimeServices.services.AddSingleton<ICSharpEntityTypeGenerator, MyHbsCSharpEntityTypeGenerator>();
- Update CSharpEntityType/Partials/Properties.hbs to add
property-isprimarykey. - Run the
dotnet ef dbcontext scaffoldcommand from above.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent