Plinth.Scaffold 1.0.21

Plinth Scaffold

Overview

Plinth Scaffold is a productivity tool that is used to quickly generate boilerplate code for CRUD operations around a project's business entities. It is primarily meant to be used with the Plinth Common Libraries as well as the Plinth API Starter project, but can also be extended to more specific use-cases if desired. It accepts a JSON file as an input, which defines all business entities of the project, including specific fields and any special behaviors. The output contains generated code at every level of a .NET Core API project, including: SQL table definitions, SQL stored procedures, C# common models, data access classes, logic classes, controller classes, C# API models, and a C# API client. Optionally, this tool can also generate iOS Swift API models and client, Java Retrofit API models and client, as well as Typescript models.

Running Scaffold

Scaffold is installed and ran as a Nuget tool, which can be installed via dotnet.exe. The general syntax for running the Scaffold tool via command-line is the following:

dotnet scaffold [input_file_path] [arguments]

The following example will create the dotnet tool manifest in your project, update Scaffold to the latest available version on nuget.org, and run the tool using a local scaffold.json file as input, and the current folder as output.

@ECHO OFF

IF NOT EXIST .config/dotnet-tools.json (
  ECHO Creating dotnet tool manifest...
  dotnet new tool-manifest
)

dotnet tool update Plinth.Scaffold
dotnet scaffold scaffold.json -o "."
PAUSE

Command-line Arguments

Scaffold supports the following optional command-line arguments:

• --help - display help screen
• --version - display version information
• -o, --output - change where output files are written
• --disable-database - disable generation of database entities
• --disable-common - disable generation of common entities
• --disable-dataaccess - disable generation of data access entities
• --disable-logic - disable generation of business logic entities
• --disable-webapi - disable generation of web api entities
• --webapi-client - generate C# client for web api
• --web - generate clients for web
• --mobile-android - generate clients for Android mobile platform (Java)
• --mobile-ios - generate clients for iOS mobile platform (Swift)
• --schema - generate json schema for scaffold input file
• --ignore-cycle-errors - do not throw an error is a cycle is detected in foreign key definitions
• -q, --quiet - suppress all output
• -v, --verbose - output scaffolding info

Input File

Scaffold generates its code using a JSON file as an input, which outlines the entire project definition, settings, data model entities and their relationships. Below is a sample of the input file which demonstrates the main sections of the input. Subsequent sections of this document will go into more detail on all available settings and discuss different features supported by the tool.

{
    "name": "TestProject",
	"cSharpNamespace": "Test.Project",
    "database":
    {
        "generateIndividualEntityFiles": true
    },
    "enums": [
        {
            "name": "RoleType",
            "values": [
                "User",
                "Admin"
            ]
        }
    ],
    "entities": [
        {
            "name": "User",
            "pluralName": "Users",
            "fields": [
                {
                    "name": "UserID",
                    "type": "Long",
                    "isPrimaryKey": true
                },
                {
                    "name": "GUID",
                    "type": "Guid",
                    "isApplicationPrimaryKey": true
                },
                {
                    "name": "Username",
                    "type": "String",
                    "isUnique": true
                },
                {
                    "name": "Role",
                    "type": "Enum",
                    "enumName": "RoleType"
                },
                {
                    "name": "DateCreated",
                    "type": "DateTime",
                    "isCurrentDateTime": true
                }
            ]
        }
    ]
}

Root Settings

Database Settings

Enum Settings

Enum Indexed Value Settings

Entity Settings

Sort Field Settings

Entity Field Settings

Additional Foreign Key Field Settings

Entity Field Type Conversion

Row-Level Security

The row-level security code generated by the Scaffold tool relies on the definition of a security hierarchy, starting at the entity that represents the CallingUser and going down to dependent entities. In order to turn on row-level security code generation, the root setting useRowLevelSecurity must be set to true. You will also need to specify the systemCallingUserName to bypass security code checks for System calling users.

Every entity that needs security code generated for it will need to specify one of 3 settings:

• isSystemEntity - This entity can only be accessed by the System calling user.
• isCallingUserIdentity - This entity's GUID represents the identifier of the CallingUser of the current request context. Most typically this is the User entity, and functions as the top-level rowLevelSecurityParent.
• rowLevelSecurityParent - Name of the entity from which the current entity inherits its row-level security definition. This is what sets up the security hierarchy.

Row-level security checks will be generated directly within the stored procedures in order to ensure that any custom business logic that uses the generated data access code will benefit from the automated security checks. The types of checks performed depends on the type of the stored procedure:

• INSERT - If the entity that is being inserted contains a foreign key to the specified rowLevelSecurityParent, a security check will be generated to make sure the CallingUser has access to the parent entity record. If the entity being inserted contains foreign keys to other entities that have this entity specified as their rowLevelSecurityParent, a security check will also be generated to make sure the CallingUser has access to those entity records as well.
• UPDATE - A security check will be generated to make sure the CallingUser has access to the entity record being updated. If the entity being updated contains foreign keys to other entities that have this entity specified as their rowLevelSecurityParent, and if the foreign key entity id is provided as a parameter, a security check will also be generated to make sure the CallingUser has access to those entity records as well.
• DELETE - A security check will be generated to make sure the CallingUser has access to the entity record being deleted.
• SELECT - A security check will be added to the WHERE clause to make sure the CallingUser has access to each of the returned entity records.

To add more SQL conditions for selecting or modifying an entity and its security children, use rowLevelSecuritySelectSqlCondition and rowLevelSecurityModifySqlCondition.

In order to make an entity that is protected by row-level security code allow public reads, disableRowLevelSecuritySelectSqlGeneration can be set to true.

Extending Generated Code

When the root setting useBaseFolderStructure is set to true, generated code will be placed in a Base folder on every level (database, data access, logic, etc) and configured for extension and overrides. This allows the Scaffold tool to be re-runnable by cleaning the Base folders on each run and re-generating all code. All custom extensions will be preserved since they are done in separate files and folders.

Placing generated code in separate folders also has the advantage of being able to easily distinguish custom code from the generated boilerplate code. For example, the following git command can be used to exclude generated files from the list of changed files, to more easily see the actual business logic that was modified:

git status ':!**/Base/*' ':!**/ContainerBootstrapBase.cs' ':!**/SampleData_Template.sql' ':!**/dbo/*' ':!*.dacpac'

Extending Database Code

When the starter project's DeployDatabase.ps1 script creates a new database, it runs SQL code in Base folders first before executing the code outside of the Base folders on each level. This means that extension .sql files can be created on the same level as the Base folder to modify the base SQL entities. In cases of table definition, the custom SQL file may add new columns, foreign keys, or constraints.

Extending stored procedures is a bit less convenient, since a stored procedure has to be specified in its entirety upon creation or modification. This is why each stored procedure is created using CREATE OR ALTER PROCEDURE command to allow DeployDatabase.ps1 to overwrite existing stored procedures. For any stored procedure that needs to be extended, the base stored procedure .sql file would be copied outside of the Procedures\Base folder, and modifications applied directly to the copied file.

Remember that if any future modifications to scaffold.json input file result in a modification the the base stored procedure, these updates will need to be propagated to the copied file as well. Because of this, it is best practice to put an -- Extended comment next to each modification in the copied stored procedure file, to easily identify which parts came from the generated version.

Extending C# Code

Every generated C# class is marked as partial in order to allow extending models and classes with additional properties and methods. Every generated method is also marked as virtual in order to allow overrides. To support overriding methods from custom partial classes, the structure of the generated C# code is such that a partial class extends a base class that contains the actual implementation, which allows overrides of the base class's methods from custom partial extensions.

In cases when a layer requires custom implementation such that extending and/or overriding the base generated code will not suffice, the generation of code at the desired layer can be turned off per entity using various disableGeneration settings.

Try It Out

The easiest way to try out the Scaffold tool is to start with the Plinth API Starter project, which provides the project structure as well as a sample scaffold.json definition.

Clone the repository and follow the instructions in the API starter project to create a new project.

Then, run build-scaffold.bat for the first time to generate code using the sample configuration provided in scaffold.json file.

Make the desired changes to scaffold.json and re-run build-scaffold.bat to update generated code.

Support

While efforts are being made to maintain full support of every combination of the settings mentioned above, the reality is such that settings that are used in the more recent projects are the ones that get the most attention. For example, while PGSQL is a supported option for database code generation, row-level security and bulk insert stored procedures are only currently available in the MSSQL version of the database code, since there are no known current projects that use PGSQL.

If you find a bug or a gap in the settings that are needed for your project, please contact the Scaffold tool's administrators to report a bug, submit a feature request, or ask for assistance.

Alternatively, feel free to fork and modify the code to your liking, and submit a pull request for bug fixes or non-project-specific functionality.