SAIF.Platform.Templates¶

This project pushes templates to a nuget feed that can be used to create new projects using the dotnet new cli.

How to add templates¶

This project contains two branches main and develop, they each push to a different nuget package. SAIF.Platform.Templates and SAIF.Platform.Templates.Development, respectively.

Microsoft Documentation

How to Update Template Configuration¶

The template configuration is managed through the template-config.yaml file in the root directory. This file defines the available templates, their symbols (parameters), and validation rules.

Configuration Structure¶

The configuration file has two main sections:

Templates: Define individual template configurations
Symbols: Define reusable symbols with their properties and choices

Adding a New Template¶

To add a new template to the configuration:

Add template entry under the templates section:

- name: "your-template-name"
  symbols:
    - name: symbol_name
      choices:
        - value1
        - value2
    - name: another_symbol
  scripts:
    - setup.cmd  # Optional post-generation script

Create the template folder in the templates/ directory with the same name
Update tests to include your new template

Adding or Modifying Symbols¶

Symbols are reusable parameters that can be shared across templates. To add a new symbol:

symbols:
  - name: your_symbol_name
    description: "Human readable description"
    required: true  # Optional, defaults to false
    choices:
      - name: choice1
        description: "Description for choice1"
        short: ch1  # Optional short name
      - name: choice2
        description: "Description for choice2"
    additional_symbols:  # Optional derived symbols
      - name: derived_symbol
        description: "Derived from main symbol"
        flag: your_symbol_name != ''

Symbol Properties¶

name: Unique identifier for the symbol
description: Human-readable description shown in help
required: Whether the symbol must be provided (default: false)
choices: Predefined values for the symbol
additional_symbols: Derived symbols that are calculated based on other symbols
flag: Boolean expression to set derived symbol values
cases: Conditional value assignment based on other symbols

Advanced Symbol Features¶

Conditional Requirements¶

- name: oracle_instance
  description: "Oracle Instance"
  required: database_type == 'oracle'  # Only required when database_type is oracle

Derived Flags¶

- name: has_database
  description: "Has Database"
  flag: database_type != 'none'  # Boolean flag based on condition

Conditional Values¶

- name: deploy_tenant
  description: "Deploy Tenant"
  cases:
    - value: "corp"
      condition: is_external_app == false
    - value: "ext"
      condition: is_external_app == true

After Making Changes¶

Validate configuration by running the templates locally
Update tests to reflect new symbols or templates
Test template generation with various symbol combinations
Update documentation if new public symbols are added

Best Practices¶

Use descriptive names for symbols and templates
Provide clear descriptions for all choices
Group related symbols logically
Use conditional requirements to avoid invalid combinations
Test all symbol combinations that should be valid

How to Setup for Development on Windows¶

Prerequisites

Install .Net SDK (which includes dotnet CLI)
Install Docker Desktop
Install Visual Studio
Install Make

How to Build Templates and Use Locally¶

Build

In this folder, compile the templates:
make install-templates

EG: To create an Experience API app with a Cosmos DB using the templates

Create a folder somewhere for your new app, and generate code for an Experience API:
cd MyNewApp
dotnet new saif-api-exp --name MyNewApp --businessdomain pol --owner Architecture --frontendtype None --is_external_app false --skip_setup true --database_type cosmos --cosmos_api_type nosql
Run the generated app:
Open the generated solution in Visual Studio
F5 - This will start a browser that shows your servers running in docker containers: One for your web API, one for Cosmos etc.
Click the API server for HTTP mode and you should see the "Hello, world!" JSON

How to Validate Changes Locally¶

Validate template changes by installing from source and generating output:

Install the modified template: dotnet new install src/templates/<template-name> --force
Generate into a scratch directory and inspect the output
Run the template configuration tests:
dotnet test src/dotnet/tests/SAIF.Platform.CLI.UnitTests --filter FullyQualifiedName~Templates

How to use templates¶

Verify SAIFCorporation source is setup¶

dotnet nuget list source

If it does not exist you can add the nuget feed

dotnet nuget add source https://pkgs.dev.azure.com/SAIFCorporation/_packaging/SAIFCorporation/nuget/v3/index.json -n SAIFCorporation

Install¶

You can't have both installed at the same time

Install Production Templates¶

dotnet new install SAIF.Platform.Templates

Install Development Templates¶

dotnet new install SAIF.Platform.Templates.Development

How to use Console App¶

dotnet new saif-console --name ExampleApp --team ExampleTeam --oracle --database-user EXAMPLE_USER dotnet new saif-console --name ExampleApp --team ExampleTeam

Uninstall¶

Uninstall Production Templates¶

dotnet new uninstall SAIF.Platform.Templates

Uninstall Development Templates¶

dotnet new uninstall SAIF.Platform.Templates.Development

How to test locally¶

Use make to build and install the templates make install-templates If you've added your own commands for the templates in Makefile, you can run them using make <target>.

View source on GitHub