Wolfgang.Template.Console.Subcommand 0.7.0

Wolfgang Console App Templates

A robust set of .NET templates for building console applications with modern development best practices, including dependency injection, configuration management, structured logging, and extensible command-line parsing.

Table of Contents

• Overview
• Templates in this Repository
• Features
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
• Usage
• Project Structure
• Customization
  • Commands and Subcommands
  • Configuration Files
  • Logging
• Contributing
• License

Overview

Wolfgang.Template.Console provides a solid foundation for .NET console applications. It leverages best practices such as structured logging (via Serilog), dependency injection, configuration via JSON files, and powerful command-line parsing (with McMaster.Extensions.CommandLineUtils).

The templates are designed for scalability, maintainability, and ease-of-use, whether for small scripts or complex automation tools.

Templates in this Repository

🎯 Supported Frameworks

The Wolfgang.Template.Console package installs three templates:

The template pack itself targets netstandard2.0 for dotnet new compatibility across all SDKs — this does not affect the generated project's target framework.

See the NuGet package page for the authoritative per-TFM compatibility matrix.

Features

• Command Line Parsing: Easily define commands, subcommands, and options.
• Structured Logging: Integrated Serilog with console and file sinks, plus support for enrichment.
• Dependency Injection: Built-in .NET DI with easy configuration.
• Flexible Configuration: Supports single or environment-specific JSON configuration files.
• Error Handling: Robust error catching and exit codes for integration in automation pipelines.
• Analyzer Enforcement: Generated projects ship with AsyncFixer, Meziantou, Roslynator, and Sonar analyzers enabled, with warnings treated as errors in Release builds.
• Optional companion projects: Generate with --unit-tests, --integration-tests, and/or --benchmarks to scaffold a matching xUnit unit-test project, an xUnit integration-test project, and a BenchmarkDotNet project — each referencing the app (with InternalsVisibleTo so internal types are reachable).
• Optional CLI-contract snapshot: Generate with --cli-contract to add a cli-surface subcommand that emits a deterministic JSON manifest of your published CLI arguments, plus a baseline-diff script and CI workflow that fail the build when a rename/removal breaks that contract.
• Optional OpenTelemetry: Generate with --otel to wire OpenTelemetry tracing + metrics (console exporter by default; set OpenTelemetry:OtlpEndpoint in AppSettings to export via OTLP to Jaeger, Grafana, Azure Monitor, etc.).
• Entry-point style: Defaults to the classic static Task<int> Main; pass --top-level to generate a top-level-statements Program.cs instead (no explicit Main). Functionality is identical either way.
• Native AOT variant: cwconsole-aot scaffolds a reflection-free console app (System.CommandLine + generic host + source-generated configuration binding) that publishes as a small, fast, self-contained native executable via dotnet publish -r <rid>.
• Extensible: Easily add new commands, services, or configuration sections.

Getting Started

Prerequisites

• .NET 8.0 SDK or later
• (Optional) Visual Studio or VS Code

Installation

Install the console application template from NuGet:

dotnet new install Wolfgang.Template.Console

Create a new project using the template:

dotnet new cwconsole -n MyConsoleApp
cd MyConsoleApp

To add more subcommands later, install the item templates as well:

dotnet new install Wolfgang.Template.Console.Subcommand
dotnet new install Wolfgang.Template.Console.ETL-SubCommand

Review Next Steps: After creating your project, be sure to review the Instructions.md file included in the root of your new project directory. This file provides detailed, project-specific setup steps and guidance for customizing your application.

If you create your project using Visual Studio, the Instructions.md file will open automatically to help guide you through initial configuration and customization.

Restore packages and build:

dotnet restore
dotnet build

Configuration

The template uses JSON files for application and environment configuration.

• AppSettings.json: Main config file, used by default for all environments
• AppSettings.Development.json, AppSettings.Production.json, etc.: Environment-specific files

By default the generated app loads the single AppSettings.json file. To use one file per environment instead, change the ConfigurationFileMethod.SingleFile argument in Program.cs to ConfigurationFileMethod.OneFilePerEnvironment; the file is then selected by the DOTNET_ENVIRONMENT variable.

To set the environment (example for Windows):

set DOTNET_ENVIRONMENT=Development

Or for Linux/macOS:

export DOTNET_ENVIRONMENT=Development

Usage

Run the application from the root directory:

dotnet run

You can also publish the app and run the executable:

dotnet publish -c Release
./bin/Release/net8.0/publish/MyConsoleApp.exe [options]

Command Line Options

The template supports a main command and subcommands. To view help:

dotnet run -- --help

Add new subcommands by creating classes and registering them in Program.cs — or generate one with dotnet new cwsubcmd.

Project Structure

A project generated from cwconsole looks like:

MyConsoleApp/
├── Program.cs
├── AppSettings.json
├── AppSettings.Development.json
├── AppSettings.Production.json
├── Command/
│   └── SampleCommand.cs
├── Framework/
│   └── (hosting, configuration, and console helpers)
├── Model/
│   └── SampleConfiguration.cs
├── Instructions.md
└── ...

• Program.cs: Entry point with main logic and configuration.
• AppSettings.json*: Application configuration files.
• Command/: Subcommand classes; add new commands here.
• Framework/: Hosting and configuration extension helpers.
• Model/: Configuration binding models.
• Instructions.md: In-depth development and customization notes.

Customization

Commands and Subcommands

• Define your main command in Program.cs using attributes.
• Add subcommands by creating new classes and registering them with [Subcommand(typeof(MyCommand))].

Example:

[Subcommand(typeof(MyNewCommand))]

Configuration Files

• Single File: Use AppSettings.json for all environments (the default).
• Per Environment: Use AppSettings.{Environment}.json files by switching to ConfigurationFileMethod.OneFilePerEnvironment.

See Instructions.md for detailed setup.

Logging

• Logging is configured via the Serilog section in your AppSettings*.json.
• Add or remove log sinks and adjust minimum levels as needed.
• Default logs to both console and file (see AppSettings.json).

Security posture

This repo runs OpenSSF Scorecard (weekly + on push to main) to grade its security posture — branch protection, pinned dependencies, token permissions, dangerous-workflow patterns, and more. Results upload as SARIF to Security → Code scanning, alongside the other scanners (gitleaks, CodeQL, DevSkim, InspectCode, and zizmor for workflow security).

• Target score floor: ≥ 7.0 / 10. Investigate and address any check that drops the aggregate below that; the per-check breakdown is in Code Scanning.

• Public badge / dashboard: off by default (the score stays private in Code Scanning). To publish to the public OpenSSF dashboard and enable the badge below, set publish_results: true in .github/workflows/scorecard.yml (and add id-token: write to that job) — a deliberate "make our posture public" decision. Once enabled, add:

  [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Chris-Wolfgang/console-app-template/badge)](https://scorecard.dev/viewer/?uri=github.com/Chris-Wolfgang/console-app-template)
  

See the Threat Model for the STRIDE analysis behind these controls, and SECURITY.md for how to report a vulnerability.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the full workflow, coding standards, and PR checklist.

License

This project is licensed under the MIT License. See the LICENSE file for details.

References & Further Reading

• CHANGELOG · Migration Guide (breaking template changes)
• Serilog Documentation
• McMaster.Extensions.CommandLineUtils
• Microsoft.Extensions.Hosting
• .NET Generic Host
• Custom templates for dotnet new

Support

For questions, please open an issue on GitHub.

For more in-depth developer notes and template usage, see src/ConsoleAppTemplate/Content/Instructions.md.