Dotnet.DefaultFiles

This repository provides a template for initializing .NET projects with default files and a setup script. It is designed to help developers quickly scaffold a new solution following Clean Architecture principles, including recommended folder structure, configuration, and build scripts.

📚 Table of Contents

🚀 Overview

Dotnet.DefaultFiles serves as a starting point for .NET development. It includes:

Standard files for solution and project setup
PowerShell script for creating a new Clean Architecture project
Quality criteria for artifacts and code
Copilot agents, instructions and prompts for generating artifacts, code and documentation.

🎯 Solution Goals

Provide a consistent starting point for .NET projects
Encourage best practices in project structure and configuration
Facilitate quick setup of Clean Architecture solutions
Include tools and resources for maintaining code quality and documentation
Support both Blazor and Web API project types with Clean Architecture principles
Offer flexibility through script arguments for different project needs

Setup & Usage

Initializing a New Project

Create a folder with the name of your new solution. (e.g., mkdir MyNewSolution)
Go to the new folder. (e.g., cd MyNewSolution)

Windows PowerShell

Download and run the setup script to scaffold your solution. The script uses a YAML configuration file (solution-structure.config.yaml) to define the directory and file structure, which is loaded by import-yaml-config.ps1:
- Scaffold a new solution with Clean Architecture principles:
  Invoke-WebRequest -Uri "https://raw.githubusercontent.com/TirsvadCLI/Dotnet.DefaultFiles/refs/heads/main/settings.yaml" -OutFile "settings.yaml"
  
  Invoke-WebRequest -Uri "https://raw.githubusercontent.com/TirsvadCLI/Dotnet.DefaultFiles/refs/heads/main/import-yaml-config.ps1" -OutFile "import-yaml-config.ps1"
  
  Invoke-WebRequest -Uri "https://raw.githubusercontent.com/TirsvadCLI/Dotnet.DefaultFiles/refs/heads/main/setupSolutionCleanArchentectureCSharp.ps1" -OutFile "setupSolutionCleanArchentectureCSharp.ps1"
  
  .\setupSolutionCleanArchentectureCSharp.ps1
- Scaffold a new Blazor project with Clean Architecture principles and WebApi:
  Invoke-WebRequest -Uri "https://raw.githubusercontent.com/TirsvadCLI/Dotnet.DefaultFiles/refs/heads/main/setupSolutionCleanArchentectureCSharp.ps1" -OutFile "setupSolutionCleanArchentectureCSharp.ps1"
  
  .\setupSolutionCleanArchentectureCSharp.ps1 -Blazor -WebApi

This will create the recommended folder structure, add default files, and configure the solution for Clean Architecture, all based on the YAML configuration.

The folder structure will be created as follows:

🛠️ Script Arguments and Usage

The setupSolutionCleanArchentectureCSharp.ps1 script supports several arguments to customize the solution setup:

Arguments:

Switch	Description
`-Files`	Only create directories, hardlink, and copy default files.
`-Arch`	Only set up Clean Architecture solution and projects (Domain, Application, Infrastructure).
`-Blazor`	Set up Clean Architecture and add Blazor WebAssembly and server projects (frontend/backend)
`-WebApi`	Set up Clean Architecture and add a Web API project
`-Help`	Show usage instructions and exit.
`-DefaultFilesRoot <path>`	Optional path to a custom source for default files.
`-SolutionFile <file>`	Optional custom solution file name.
`-Framework <version>`	Optional .NET target framework (default: net10.0).

Examples:

# Default setup: directories, files, and Clean Architecture projects
./setupSolutionCleanArchentectureCSharp.ps1
 
# Only create directories and copy default files
./setupSolutionCleanArchentectureCSharp.ps1 -Files
 
# Only set up Clean Architecture projects (no file copying)
./setupSolutionCleanArchentectureCSharp.ps1 -Arch
 
# Set up Clean Architecture and add Blazor frontend/backend
./setupSolutionCleanArchentectureCSharp.ps1 -Blazor
 
# Set up Clean Architecture and add Web API backend
./setupSolutionCleanArchentectureCSharp.ps1 -WebApi
 
# Show help
./setupSolutionCleanArchentectureCSharp.ps1 -Help
 
# Use a custom default files source and solution file name
./setupSolutionCleanArchentectureCSharp.ps1 -DefaultFilesRoot "../MyDefaults" -SolutionFile "MySolution.slnx"

MyBlazorApp/
├── src/
│   ├── Domain/                                     # Business logic and entities
│   │   ├── Entities/                               # Domain entities
│   │   ├── Interfaces/                             # Domain interfaces
│   │   └── ValueObjects/                           # Domain value objects
│   ├── Application/                                # Application services and use cases
│   │   ├── Services/                               # Application services
│   │   ├── Helpers/                                # Application helpers
│   │   ├── Managers/                               # Application managers
│   │   ├── Mappers/                                # Application mappers
│   │   ├── DTOs/                                   # Data transfer objects
│   │   └── Interfaces/                             # Application interfaces
│   ├── Infrastructure/                             # Data access, external services
│   │   ├── Persistence/                            # Database context and repositories
│   │   │   └── Configuration/                      # Database configuration files 
│   │   └── Repositories/                           # Repository implementations
│   ├── Web/                                        # Web UI projects (if selected)
│   │   ├── MyBlazorApp.Web/                        # Blazor project
│   │   └── MyBlazorApp.Web.Client/                 # Blazor WebAssembly project
│   └── WebApi                                      # Web API project (if selected)
├── docs/                                           # Documentation and design files
├── tests/                                          # Test projects
└── .github                                         # GitHub configuration files

Customizing

Edit configuration files as needed (e.g., global.json, Directory.Build.props).
Add or update environment variables for your setup.

Default Files Included

global.json: .NET SDK version management
Directory.Build.props / Directory.Build.targets: Solution-wide build settings
.gitignore: Standard ignore rules
nuget.config: Custom NuGet feeds
Example scripts for setup and build

Why use <tt>ci-cd.ps1</tt>

The ci-cd.ps1 script automates essential CI/CD safety and consistency checks for your repository. It ensures:

You do not accidentally run deployments from the main branch.
There are no uncommitted changes before running CI/CD steps.
All git-tracked text files have consistent LF (Unix) line endings, preventing cross-platform issues.
Optionally, it can start required containers, run build and test stages, and commit line ending fixes automatically.

Using this script helps maintain a clean, reliable, and reproducible development and deployment workflow, especially in collaborative or cross-platform environments.

How to use <tt>ci-cd.ps1</tt>

Ensure all your work is committed and you are not on the main branch.
Open a PowerShell terminal in the repository root.
Run the script:
./ci-cd.ps1
The script will:
- Check your branch and uncommitted changes.
- Convert all git-tracked file line endings to LF.
- Optionally, start containers and run build/test stages (uncomment in the script as needed).
- Commit any line ending fixes if changes are detected.
- Push changes to the remote repository.

Note:

You can customize which stages are active by commenting/uncommenting lines in the script (e.g., to enable build or test stages).
The script requires Docker and Git to be installed and available in your PATH.

For more details, see the comments in ci-cd.ps1.

📂 The <tt>.github</tt> Folder

The .github directory contains configuration, automation, and documentation resources that support development workflows and code quality:

Copilot Instructions & Agents:
- .github/copilot-instructions.md defines repository-wide rules for Copilot agents, including Clean Architecture conventions, folder structure, and documentation standards.
- .github/instructions/ contains detailed instructions and prompts for Copilot agents, such as how to generate or validate domain models, documentation, and code artifacts.
- Agent prompt files (e.g., dm-artifact.agent.md) provide reusable templates for generating domain model documentation and other artifacts.
Workflow & Community Files:
- GitHub Actions workflows (if present) automate CI/CD, testing, and other tasks.
- Issue and pull request templates help standardize contributions.
- Configuration files for repository settings and community standards.

These resources ensure consistency, automate repetitive tasks, and provide guidance for both humans and AI agents working in the repository.

For more details, see the .github/ directory and referenced documentation.

Best Practices

Keep source code in src/, tests in tests/.
Use environment variables for sensitive data.
Update README.md with any new setup or usage instructions.

For more details, see the Microsoft documentation and Clean Architecture guides.

🔐 GitHub Actions Secrets Setup

To enable CI/CD with the provided workflow, you must configure the following repository secrets in your GitHub project:

Secret Name	Description	Example Value
`DB_HOST`	Database server host (PostgreSQL/MySQL/other)	`localhost` or `db.example`
`DB_PORT`	Database server port	`5432` (Postgres default)
`DB_NAME`	Database name	`mydatabase`
`DB_USER`	Database user	`dbuser`
`DB_PASSWORD`	Database user password	`supersecret`
`TOKENVALIDATIONPARAMETERS__ISSUERSIGNINGKEY`	JWT signing key for token validation	`your-signing-key`

How to add secrets:

Go to your repository on GitHub.
Click on Settings > Secrets and variables > Actions.
Click New repository secret for each secret above and enter the name and value.

These secrets are used by the workflow in .github/workflows/ci.yml to generate the .env file and configure your build and test environment.

🌐 GitHub Pages & Google Site Verification

If you use GitHub Pages to publish documentation or a project site, you can add a google*.html file (such as googleXXXX.html) for Google site verification. This file is used by Google Search Console or Analytics to collect statistics about your site.

How to add Google verification:

Download the HTML verification file from Google Search Console (it will be named like googleXXXXXXXXXXXX.html).
Place the file in the shared/github-pages/ folder.
Commit and push the file to your repository.
Google will then be able to verify your site and collect statistics.

This is useful for tracking site traffic, indexing, and using other Google webmaster tools with your GitHub Pages site.

🤖 Copilot Agents, Instructions and Prompts

The repository also includes Copilot agents, instructions and prompts to assist developers in generating artifacts, code and documentation. These resources can be found in the .github/ directory and are designed to enhance productivity and ensure consistency across projects.

Agent Examples:

Domain Model Agent

Generates, validates, and maintains domain model (DM) documentation in markdown, following strict content, structure, and naming conventions for clarity and consistency. It analyses business case, identifies domain entities and relationships, and produces DM artifacts that align with the project’s domain language and requirements. The agent ensures that DM files are correctly named, versioned, and structured according to the instructions, and it validates the content for completeness and clarity without evaluating quality criteria.

Example Usage:

#dm-artifact.agent.md

Create DM

📄 License

Distributed under the AGPL-3.0 License.

📬 Contact

Jens Tirsvad Nielsen - LinkedIn