CodegenCS is a Toolkit for doing Code Generation using plain C#.

Before anything else, don't forget to read the Main Project Page to learn the basics (basic idea, basic features, and major components).

This page is only about CodegenCS Command-line Tool (dotnet-codegencs):

• If you are writing a template (code generator) and want to learn more about CodegenCS features (and internals) then check out the CodegenCS Main Project documentation.
• If you want to compile and run templates or reverse-engineer a database schema this is the right place.
• If you want to browse the sample templates (POCO Generators, DAL generators, etc) check out https://github.com/CodegenCS/Templates/
• If you just want to download the Visual Studio Extension check out the Visual Studio Extension

dotnet-codegencs is a .NET Command-line Tool that contains utilities to download, build and run templates.
It can also be used to extract models (reverse engineer) from existing sources, so that those models can be used with the templates.

• Pre-requisite: .NET If you don't have .NET installed you can install it from https://dotnet.microsoft.com/en-us/download
• Install running this command: dotnet tool install -g dotnet-codegencs
  If your environment is configured to use private Nuget feeds (in addition to nuget.org) you may need --ignore-failed-sources option to ignore not-found errors.

When you run dotnet-codegencs template run:

• It will search for an entrypoint method called Main() (in any class in the cs file)
• It will automatically create an instance of that class and invoke that Main() method.
• Both the class constructor and the Main() method may get automatically injected into them some important types: ICodegenContext (if you want to write to multiple files), ICodegenTextWriter (if you want to write to a single file), CliArgs (if your template needs to read custom command-line arguments), etc.
• Both the class constructor and the Main() method may also get automatically injected into them the Input Models: any class that implements IJsonInputModel. Any class that implements that interface will be automatically deserialized from a JSON file (so it must be provided in the command-line, after the template name) and injected as necessary.
• Main() return type can be void - use this if you're manually writing to ICodegenContext or ICodegenTextWriter. Outputs are automatically saved.
• Main() return type can also be int - it's exactly like void but the templates can return a nonzero result to indicate an error (and outputs wouldn't be saved).
• Main() return type can also be FormattableString or string - it's a more "functional" approach - in this case that return is automatically written to the default output file (ICodegenTextWriter) - no need to call writer.WriteLine()
• If multiple files were written (into a ICodegenContext) then they are all saved under current folder
  Different folder can be specified using option --OutputFolder [OutputFolder]
• If a single file was written (into a ICodegenTextWriter) then it's saved under current folder as <TemplateName>.g.cs
  Different file can be specified using option --File [DefaultOutputFile]
• Using statements are automatically added to the script (if not there) to let templates be as simple as possible

In the templates repository you'll find templates using the legacy syntax which requires templates to implements one of the legacy templating interfaces (ICodegenTemplate<TModel>, ICodegenMultifileTemplate<TModel>, ICodegenStringTemplate<TModel>). That's legacy since now it's possible (and easier) to just use a Main() method and inject whatever object you need.

The purpose of this document is only to show the basic commands, it does NOT describe all different options - but you can see all available commands and options using --help:

• dotnet-codegencs --help (shows all available commands)
• dotnet-codegencs template --help (shows template subcommands)
• dotnet-codegencs template clone --help (shows template clone usage/options)
• dotnet-codegencs template build --help (shows template build usage/options)
• dotnet-codegencs template run --help (shows template run usage/options)
• dotnet-codegencs model dbschema extract --help (shows how to extract a dbschema model)
• Etc.

As shown in the Quickstart, template clone is the first step and is used to get a local copy of a template (like git clone, but for downloading a single .cs file - so it's more like wget).

You can download templates from any 3rd-party origin by providing the full url: dotnet-codegencs template clone <template-url>
We're not responsible for 3rd-party templates - use them at your own risk (ensure that you trust the source and review any scripts before running it).
Downloading from third-party sources will show a warning (but you can skip it with option --allow-untrusted-origin).

If you're downloading from our own Templates repository (https://github.com/CodegenCS/Templates) you can use this shortcut:
dotnet-codegencs template clone <templateName>
(equivalent to: dotnet-codegencs template clone https://github.com/CodegenCS/Templates/<templateName>/<templateName>.cs).

template clone will automatically build the source into a dll after the download (equivalent to running template build).

Templates can be executed from the .cs source (they will be compiled on-the-fly into a dll file) or they can be executed from the .dll file (which is generated using template build).
If you need to invoke the template multiple times in a row then running from the .dll might be the preferred method (faster), but for most cases running from the .cs should be fine.

When templates are downloaded (using template clone) they are automatically compiled into a DLL (no need to run template build), so immediately after cloning you can run using the .dll instead of .cs (and if you don't provide an extension template run will first try to find with the dll extension before trying .cs).

template run also accepts some options like --OutputFolder <outputFolder> (base folder for all output files), or --File <defaultOutputFile> (name of the default output file, useful for templates that write to a single file)

This compiles the template (e.g. template.cs) into a DLL (e.g. template.dll).
As mentioned earlier, template build is totally optional since template run can use the .cs source file.
If you're running templates directly from .dll and you have modified the .cs source then you can rebuild the dll using dotnet-codegencs template build <template.cs>.

Templates may define their own options and arguments using .NET System.CommandLine. Template-specific arguments and options should be passed after the model:
dotnet-codegencs template run <template> <model> [template-args]

SimplePocos template is a good example of how to use custom arguments and options:

• It defines 1 mandatory argument which is the namespace for the generated POCOs
• It defines a -p:SingleFile option which when used will generate all POCOs under a single filename (default output file)

dotnet-codegencs template run SimplePocos.cs --File MyPOCOS.cs AdventureWorks.json MyProject.POCOs -p:SingleFile

In the command above, --File is an option of template run and defines the default output file, while -p:SingleFile is a template-specific option (SimplePocos option) and defines that all POCOs should be generated into that single file.
If we don't specify -p:SingleFile then SimplePocos will generate each file on it's own <TableName>.generated.poco.
If we specify -p:SingleFile but don't specify a --File then the default output file would be SimplePocos.g.cs (since we're running dotnet-codegencs template run SimplePocos ...).
(P.S. we suggest this -p: as an alternative prefix to avoid conflicting options with the main tool, but it's also possible to use standard formats like --youroption or /youroption)

For any template that define their own arguments/options using ConfigureCommand() and .NET System.CommandLine syntax we can also get help (see template usage and options):

dotnet-codegencs template run SimplePocos.cs --help

Currently dotnet-codegencs will automatically add some libraries including Generics, System.Net.Http, System.IO, and Newtonsoft JSON. In the future dotnet-codegencs should allow dynamic nuget references, for for now if you want to use other libraries please use CodegenCS Core Library directly.

MIT License