Kemenkeu.Utility.Templates 1.9.2

Kemenkeu.Utility.Templates

A NuGet package containing multiple .NET templates for building enterprise applications with Kemenkeu standards.

📦 Package Information

• Package ID: Kemenkeu.Utility.Templates
• Installation: dotnet new install Kemenkeu.Utility.Templates
• Package Type: Template Package

🎯 Available Templates

1. Kemenkeu Web API (Clean Architecture) - Project Template

• Short Name: kemenkeu-webapi
• Type: Project template
• Description: Production-ready service template built with Clean Architecture, targeting .NET 10.0
• Usage: dotnet new kemenkeu-webapi -n MyCompany.MyService -o ~/MyService

2. Kemenkeu Feature (CQRS + DDD) - Item Template

• Short Name: kemenkeu-feature
• Type: Item template (code scaffolding)
• Description: Generates a complete CQRS feature across all layers (Controller, Commands, Queries, Handlers, DTOs, Entity, Repository, DbContext)
• Usage: dotnet new kemenkeu-feature -n Tag --plural Tags --rootNamespace MyCompany.MyService --storage sqlserver
• Storage options: sqlserver, postgresql, mongodb

See individual template READMEs for detailed documentation.

🏗️ Repository Structure

Kemenkeu.Utility.Templates/
├── working/
│   └── content/
│       ├── ProjectWebApiDomainDrivenDesign10/    # Project template (kemenkeu-webapi)
│       │   ├── .template.config/
│       │   │   └── template.json
│       │   ├── src/
│       │   ├── tests/
│       │   └── README.md
│       ├── FeatureTemplate/                       # Item template (kemenkeu-feature)
│       │   ├── .template.config/
│       │   │   └── template.json
│       │   └── src/                              # Template source files with conditionals
│       └── [FutureTemplate]/                     # Add new templates here
├── Kemenkeu.Utility.Templates.csproj            # Packaging project
└── README.md                                      # This file

➕ Adding a New Template

Follow these steps to add a new template to the package:

Step 1: Create Template Directory

Create a new directory under working/content/ for your template:

mkdir -p working/content/YourNewTemplate
cd working/content/YourNewTemplate

Step 2: Create Template Structure

Your template directory should follow this structure:

YourNewTemplate/
├── .template.config/
│   └── template.json              # REQUIRED: Template configuration
├── src/                            # Source files (project structure)
├── tests/                          # Test files (optional)
├── README.md                       # Template documentation (recommended)
└── [other files]                   # Additional template files

Step 3: Create template.json

Create .template.config/template.json with the following structure:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Your Name or Team",
  "classifications": [
    "Web",
    "API"
  ],
  "identity": "kemenkeu.yourtemplate.template",
  "name": "Your Template Name",
  "shortName": "your-template-shortname",
  "sourceName": "Kemenkeu.Service",  // This will be replaced when template is used
  "preferNameDirectory": true,
  "tags": {
    "language": "C#",
    "type": "project"
  },
  "symbols": {
    "projectName": {
      "type": "parameter",
      "datatype": "text",
      "replaces": "Kemenkeu.Service",
      "defaultValue": "Kemenkeu.Service",
      "description": "The name of your project"
    }
    // Add more symbols/parameters as needed
  }
}

Important Fields:

• identity: Must be unique across all templates
• name: Display name shown when listing templates
• shortName: Command used to invoke template (e.g., dotnet new your-template-shortname)
• sourceName: Placeholder that gets replaced with user's project name

Step 4: Add Template Files

1. Create your template files in the directory structure
2. Use Kemenkeu.Service as placeholder for project names (or whatever you set in sourceName)
3. Files will be automatically processed by the template engine

Example file replacements:

• Kemenkeu.Service → User's project name
• Kemenkeu.Service.Api → {projectName}.Api
• Namespace references will be automatically replaced

Step 5: Test Your Template Locally

Before packaging, test your template locally:

# From your template directory
cd working/content/YourNewTemplate

# Install the template locally
dotnet new install . --force

# Test creating a project
dotnet new your-template-shortname -n Test.Project -o ~/test-output

# Verify the generated project
cd ~/test-output
dotnet restore
dotnet build

# Uninstall when done testing
dotnet new uninstall working/content/YourNewTemplate

Step 6: Build and Test the Package

Build the NuGet package (all templates will be included):

# From repository root
cd /path/to/Kemenkeu.Utility.Templates

# Build the package
dotnet pack Kemenkeu.Utility.Templates.csproj -c Release

# The package will be created at:
# bin/Release/Kemenkeu.Utility.Templates.{version}.nupkg

Step 7: Test the Package Locally

Test the package before publishing:

# Install from local package
dotnet new install bin/Release/Kemenkeu.Utility.Templates.1.0.0.nupkg

# Verify your template is listed
dotnet new list | grep kemenkeu

# Test creating a project with your template
dotnet new your-template-shortname -n Test.Project -o ~/test-output

# Uninstall when done
dotnet new uninstall Kemenkeu.Utility.Templates

Step 8: Update Version and Publish

1. Update Version in Kemenkeu.Utility.Templates.csproj:

   <Version>1.1.0</Version>
   <PackageVersion>1.1.0</PackageVersion>
   

2. Rebuild Package:

   dotnet pack Kemenkeu.Utility.Templates.csproj -c Release
   

3. Push to NuGet:

   dotnet nuget push bin/Release/Kemenkeu.Utility.Templates.1.1.0.nupkg \
     --api-key YOUR_API_KEY \
     --source https://api.nuget.org/v3/index.json
   

📋 Template Checklist

When adding a new template, ensure:

• Template directory created under working/content/
• .template.config/template.json created with unique identity
• shortName is clear and follows naming convention (kebab-case)
• All placeholder names use the sourceName value
• README.md created for template documentation
• Template tested locally before packaging
• Template works with dotnet new install and dotnet new {shortname}
• Generated project builds successfully
• Version bumped in .csproj before publishing

🔍 Template Naming Conventions

• shortName: Use kebab-case (e.g., kemenkeu-webapi, kemenkeu-worker)
• identity: Use reverse domain notation (e.g., kemenkeu.yourtemplate.template)
• name: Use descriptive name with parentheses for clarification (e.g., "Kemenkeu Web API (Clean Architecture)")

📦 Packaging Details

The Kemenkeu.Utility.Templates.csproj automatically includes all templates from working/content/:

<Content Include="working\content\**\*" 
         Exclude="working\content\**\bin\**;working\content\**\obj\**">
  <Pack>true</Pack>
  <PackagePath>content\</PackagePath>
</Content>

This means:

• ✅ Any new template folder added will be automatically included
• ✅ Build artifacts (bin/, obj/) are automatically excluded
• ✅ No need to modify .csproj when adding templates

🚀 Publishing Workflow

1. Develop your template in working/content/YourTemplate/
2. Test locally using dotnet new install
3. Document in the template's README.md
4. Update version in .csproj
5. Build package: dotnet pack
6. Test package installation locally
7. Publish to NuGet: dotnet nuget push

📚 Resources

• .NET Template Authoring
• Template JSON Schema
• NuGet Package Creation

🤝 Contributing

When adding a new template:

1. Follow the structure and conventions outlined above
2. Ensure your template follows Kemenkeu coding standards
3. Include comprehensive documentation in the template's README.md
4. Test thoroughly before requesting package publication
5. Update this README.md with the new template information

📝 Notes

• The package includes all templates from working/content/ - users get everything when they install
• Each template must have a unique identity and shortName
• Version numbers should follow Semantic Versioning
• Always test locally before publishing to NuGet