Skip to content

Latest commit

 

History

History
157 lines (100 loc) · 8.24 KB

README.md

File metadata and controls

157 lines (100 loc) · 8.24 KB
Raw

Beef.CodeGen.Core

This tooling console application assembly contains the Beef code generation capabilities.

Code generation is proposed as a means to greatly accelerate application development where standard coding patterns can be determined and the opportunity to automate exists.

Code generation is intended to bring the following benefits:

  • Acceleration of development;
  • Consistency of approach;
  • Simplification of implementation;
  • Reusability of layering and framework;
  • Evolution of approach over time;
  • Richness of capabilities with limited effort.

There are generally two types of code generation:

  • Gen-many - the ability to consistently generate a code artefact multiple times over its lifetime without unintended breaking side-effects. Considered non-maintainable by the likes of developers as contents may change at any time; however, can offer extensible hooks to enable custom code injection where applicable.
  • Gen-once - the ability to generate a code artefact once to effectively start the development process. Considered maintainable, and should not be re-generated as this would override custom coded changes.

Beef primarily leverages Gen-many as this offers the greatest long-term benefits.


Code-gen data source

The code-gen is driven by a data source, in this case XML. This acts as a type of DSL (Domain Specific Language) to define the key characteristics / attributes that will be used to generate the required artefacts.


Code-gen templates

Once the code-gen data source(s) have been defined, one or more templates will be required to drive the artefact output. These templates are defined using XML - these have some basic language / logic capabilities to enable rich code generation output.

The Beef standard templates can be found here.


Scripts and loaders

To orchestrate the code generation, in terms of the templates to be used, an XML-based script file is used. The Beef standard scripts can be found here.

Additionally, the script can define the loader Type which is a class that implements ICodeGenConfigLoader. The purpose of a loader is to manipulate (update) the configuration XML before processing via the templates. The Beef standard loaders can be found here.


Supported code-gen

The following code generation is supported:

CodeGen


Entity-driven code-gen

The entity-driven gen-many code generation is enabled by an Entity.xml file that is responsible for defining the characteristics for an Entity, its Properties, Constants and Operations (and underlying Parameters). The entity definitions are wrapped by a root CodeGeneration element.

The hierarcy is as follows:

└── CodeGeneration
  └── Entity(s)
    └── Property(s)
    └── Const(s)
    └── Operation(s)
      └── Parameter(s)

The Entity.xml is defined by a schema codegen.entity.xsd. This schema should be used within the likes of Visual Studio when editing to enable real-time validation and basic intellisense capabilities.


Database table-driven code-gen

The database table-driven code generation is enabled by a Table.xml file that is responsible for defining the characteristics for the generation of stored procedures. A Table has StoredProcedures (and underlying Parameters, Where and OrderBy clauses, and Execute statements). The tablle definitions are wrapped by a root CodeGeneration element.

Standard stored procedures can be generated from a Table schema, as well as the definition of a custom defined Stored Procedure.

The hierarcy is as follows:

└── CodeGeneration
  └── Table(s)
    └── StoredProcedure(s)
      └── Parameter(s)
      └── Where(s)
      └── OrderBy(s)
      └── Execute(s)

The Table.xml is defined by a schema codegen.table.xsd. This schema should be used within the likes of Visual Studio when editing to enable real-time validation and basic intellisense capabilities.

This is not intended as an all purpose database schema generation capability. It is expected that the Tables and/or Views pre-exist within the database. This database schema/catalog information is queried from the database directly to aid the generation configuration to minimise the need to replicate column configurations within the Table.xml.


Console application

The Beef.CodeGen.Core can be executed as a console application directly; however, the experience has been optimised so that a new console application can reference and inherit the capabilities.


Commands

The following commands are automatically enabled for the console application (where set up):

  • Entity - performs code generation using the Company.AppName.xml configuration and EntityWebApiCoreAgent.xml script.
  • RefData - performs code generation using the Company.RefData.xml configuration and RefDataCoreCrud.xml script.
  • Database - performs code generation using the Company.AppName.Database.xml configuration and Database.xml script.
  • DataModel - performs code generation using the Company.AppName.DataModel.xml configuration and DataModelOnly.xml script.
  • All - performs all of the above (where each is supported as per set up).

There are a number of properties that support changes to these templates above where they need to be overridden.


Program.cs

The Program.cs for the new console application should be updated similar to the following. The Company and AppName values are specified, as well as optionally indicating whether the Entity, RefData, Database and/or DataModel commands are supported.

public class Program
{
    static int Main(string[] args)
    {
        return CodeGenConsoleWrapper.Create("Company", "AppName").Supports(entity: true, refData: true).Run(args);
    }
}

To run the console application, simply specify the required command; e.g:

dotnet run entity      -- Default filename: Company.AppName.xml
dotnet run refdata     -- Default filename: Company.RefData.xml
dotnet run datamodel   -- Default filename: Company.AppName.DataModel.xml
dotnet run all         -- All of the above

-- Override the configuration filename from the default.
dotnet run entity -x configfilename.xml

Personalization and/or overridding

As described above Beef has a set of defined (out-of-the-box) templates and scripts - these do not have to be used, or could be maintained, to achieve an alternate outcome as required.

To avoid the need to clone the solution, and update, add the Templates and Scripts folders into this console application and embed the required resources. The underlying Beef.CodeGen.Core will probe the embedded resources and use the overridden version where provided, falling back on the Beef version where not found.


What about T4?

There are multiple capabilities to perform code generation, such as the likes of T4 (arguably, it is a more fully featured code generation capability).

The Beef code generation largely pre-dates T4, is highly-flexible achieving the desired code generation outcomes, and as such there has been no compelling reason to replatform to date - a high-cost, with a limited return.