Using the Generator SDK

After reading this document you will know how-to download, install and use the CodeSmith Generator SDK in your applications. This document will also demonstrate the most common uses of the CodeSmith Generator API:

  • Compiling a template
  • Retrieving compile errors
  • Creating a new template instance
  • Filling in template metadata
  • Rendering a template

Download

After logging into your account, visit the following downloads section to download the latest version of CodeSmith Generator.

It is recommended that you download the Zipped Version of CodeSmith Generator as it includes all of the assemblies that you will need to reference in your SDK application.  

Installing the license

A license key file will be emailed to you after you purchase the SDK license from the online store. This license file needs to meet one of the following criteria:

  • Embed the license file into your application as an embedded resource in the assembly that calls the CodeSmith.Engine.
  • Place the license file into the same directory as your application.
  • Specify a license key via the Generator:License environment variable or in code via the CodeSmithLicense.SetLicenseKey(key) method. We only recommend this for build/web servers as this will overwrite any locally defined licenses.

Creating a new project

In order to use the CodeSmith Generator SDK you will need to create a new .Net 4.6.2 or newer project. In the example below, we will be creating a new console application.

A C# and VB.Net sample SDK project exists in your extracted samples under the following directory (Documents\CodeSmith Generator\Samples\<VERSION>\Projects\CSharp\APISample). You may need to do some minor changes like changing the Connection String.
A project using an SDK license must be Strong-Named.

Adding project references

Next, you are required to reference the following NuGet packages:

In the example below we will also need to reference the NuGet packages:

Writing the Code

Now it's time to dive in and write some generation code!  We will add the following code to our console application: 

public static void Main() {
    string path = System.IO.Path.Combine(AppDomain.CurrentDomain.BaseDirectory, @"..\..\StoredProcedures.cst");
    var engine = new TemplateEngine(new DefaultEngineHost(System.IO.Path.GetDirectoryName(path)));

    CompileTemplateResult result = engine.Compile(path);
    if (result.Errors.Count == 0) {
        var database = new DatabaseSchema(new SqlSchemaProvider(), @"Server=.;Database=PetShop;Integrated Security=True;");
        TableSchema table = database.Tables["Inventory"];

        CodeTemplate template = result.CreateTemplateInstance();
        template.SetProperty("SourceTable", table);
        template.SetProperty("IncludeDrop", false);
        template.SetProperty("InsertPrefix", "Insert");
        template.Render(Console.Out);
    } else {
        foreach (var error in result.Errors)
            Console.Error.WriteLine(error.ToString());
    }
    
    Console.WriteLine("\r\nPress any key to continue.");
    Console.ReadKey();
}
TemplateEngine also features Async methods to compile templates Asynchronously.

The above code will compile and run but requires the Stored Procedures template that can be found in the APISample project that was mentioned above. If you have any SDK API questions feel free to contact support.

In addition to the methods shown in this sample, you may also find the CodeTemplate.RenderToFile() and CodeTemplate.RenderToString() methods useful; they let you direct the output of your templates directly to a file or to a string variable.