Skip to content

README.md

Latest commit

 

History

History
168 lines (126 loc) · 7.27 KB

README.md

File metadata and controls

168 lines (126 loc) · 7.27 KB

Template DotNet Tool

GitHub forks GitHub stars GitHub contributors License Build Quality Gate Security NuGet

DEMA Consulting template project for DotNet Tools, demonstrating best practices for building command-line tools with .NET.

Features

This template demonstrates:

  • Standardized Command-Line Interface: Context class handling common arguments (--version, --help, --silent, --validate, --results, --depth, --log)
  • Self-Validation: Built-in validation tests with TRX/JUnit output
  • Multi-Platform Support: Builds and runs on Windows, Linux, and macOS
  • Multi-Runtime Support: Targets .NET 8, 9, and 10
  • Comprehensive CI/CD: GitHub Actions workflows with quality checks, builds, and integration tests
  • Linting Enforcement: markdownlint, cspell, and yamllint enforced on every CI run
  • Continuous Compliance: Compliance evidence generated automatically on every CI run, following the Continuous Compliance methodology
  • SonarCloud Integration: Quality gate and security analysis on every build
  • Documentation Generation: Automated build notes, user guide, code quality reports, requirements, justifications, and trace matrix
  • Requirements Traceability: Requirements linked to passing tests with auto-generated trace matrix

Installation

Install the tool globally using the .NET CLI:

dotnet tool install -g DemaConsulting.TemplateDotNetTool

Usage

# Default behavior (no arguments) — displays banner and copyright
templatetool

# Display version
templatetool --version

# Display help
templatetool --help

# Run self-validation
templatetool --validate

# Save validation results (--result is an accepted alias for --results)
templatetool --validate --results results.trx
templatetool --validate --result results.xml

# Set heading depth for embedded validation output
templatetool --validate --depth 2

# Silent mode with logging
templatetool --silent --log output.log

Command-Line Options

Option Description
-v, --version Display version information
-?, -h, --help Display help message
--silent Suppress console output
--validate Run self-validation
--results <file>, --result <file> Write results to .trx (TRX) or .xml (JUnit XML) file.
--depth <#> Set heading depth for markdown output (default: 1)
--log <file> Write output to log file

Error Handling

Unrecognized arguments cause the tool to print an error message to standard error and exit with a non-zero exit code. For example:

Error: Unsupported argument '--unknown'

This behavior enables CI/CD pipelines to detect and surface misconfiguration failures automatically.

Self Validation

Running self-validation produces a report containing the following information:

# DEMA Consulting Template DotNet Tool

| Information         | Value                                              |
| :------------------ | :------------------------------------------------- |
| Tool Version        | <version>                                          |
| Machine Name        | <machine-name>                                     |
| OS Version          | <os-version>                                       |
| DotNet Runtime      | <dotnet-runtime-version>                           |
| Time Stamp          | <timestamp> UTC                                    |

✓ TemplateTool_VersionDisplay - Passed
✓ TemplateTool_HelpDisplay - Passed

Total Tests: 2
Passed: 2
Failed: 0

Each test in the report proves:

  • TemplateTool_VersionDisplay - --version outputs a valid version string.
  • TemplateTool_HelpDisplay - --help outputs usage and options information.

Use --depth <#> to control the heading level of the validation output (default: 1). This is useful when embedding validation output into a larger markdown document:

# Embed validation at heading level 2
templatetool --validate --depth 2

See the User Guide for more details on the self-validation tests.

On validation failure the tool will exit with a non-zero exit code.

Documentation

Generated documentation includes:

  • Build Notes: Release information and changes
  • User Guide: Comprehensive usage documentation
  • Code Quality Report: CodeQL and SonarCloud analysis results
  • Requirements: Functional and non-functional requirements
  • Requirements Justifications: Detailed requirement rationale
  • Trace Matrix: Requirements to test traceability

License

Copyright (c) DEMA Consulting. Licensed under the MIT License. See LICENSE for details.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.