# 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](https://learn.microsoft.com/en-us/dotnet/core/tools/custom-templates)

## 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:

1. **Templates**: Define individual template configurations
2. **Symbols**: Define reusable symbols with their properties and choices

### Adding a New Template

To add a new template to the configuration:

1. **Add template entry** under the `templates` section:

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

2. **Create the template folder** in the `templates/` directory with the same name
3. **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:

```yaml
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

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

#### Derived Flags

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

#### Conditional Values

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

### After Making Changes

1. **Validate configuration** by running the templates locally
2. **Update tests** to reflect new symbols or templates
3. **Test template generation** with various symbol combinations
4. **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](https://github.com/saif-corp/forge/blob/main/src/dotnet/SAIF.Platform.Templates/README.md)