Generated Structure

Complete documentation of what the ConnectSoft Library Template generates, including file structure, conditional generation, and template replacements.

Solution Structure Overview

The template generates a complete .NET solution with the following top-level structure:

YourLibraryName/
├── src/                                    # Source code folder
│   └── YourLibraryName/                   # Main library project
├── tests/                                  # Test projects folder
│   └── YourLibraryName.UnitTests/         # Unit test project
├── docs/                                   # Documentation folder (MkDocs)
├── YourLibraryName.slnx                   # Modern solution file (XML)
├── YourLibraryName.sln                    # Legacy solution file (fallback)
├── Directory.Build.props                   # Shared build properties
├── Directory.Packages.props                # Central Package Management
├── azure-pipelines.yml                    # CI/CD pipeline
├── azure-pipelines-documentation.yml      # Documentation pipeline
├── README.md                              # Project README
├── .gitignore                             # Git ignore rules
├── nuget.config                           # NuGet feed configuration
├── ConnectSoft.LibraryTemplate.nuspec     # NuGet package spec (authoring mode)
└── ConnectSoft.LibraryTemplate.runsettings # Test run settings

Root-Level Files

Solution Files

YourLibraryName.slnx

Type: Modern solution file (XML format)
Purpose: Primary solution file with improved performance (48% faster builds)
Requirements: Visual Studio 2022 v17.14+ or .NET SDK 9.0.200+

<Solution>
  <Folder Name="/src/">
    <Project Path="src/YourLibraryName/YourLibraryName.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/YourLibraryName.UnitTests/YourLibraryName.UnitTests.csproj" />
  </Folder>
  <!-- Additional folders for organization -->
</Solution>

YourLibraryName.sln

Type: Legacy solution file (text format)
Purpose: Fallback for older tooling that doesn't support .slnx
Generated: Always

Build Configuration Files

Directory.Build.props

Purpose: Shared build properties for all projects in the solution
Contains:

• NuGet audit settings
• Implicit usings configuration
• Static code analyzer references
• Authoring mode constants (if applicable)

Key Properties:

<PropertyGroup>
  <NuGetAudit>true</NuGetAudit>
  <NuGetAuditMode>direct</NuGetAuditMode>
  <NuGetAuditLevel>moderate</NuGetAuditLevel>
  <ImplicitUsings>disable</ImplicitUsings>
  <Authors>ConnectSoft</Authors>
  <Company>ConnectSoft</Company>
</PropertyGroup>

Directory.Packages.props

Purpose: Central Package Management (CPM) for versioning
Contains:

• Package versions for all NuGet packages
• Conditional package references based on template parameters
• Testing libraries
• Static code analyzers
• Feature-specific packages (DI, Logging, Options, Metrics)

Package Categories:

• Testing Libraries (MSTest, coverlet)
• Static Code Analyzers (StyleCop, SonarAnalyzer, etc.)
• Logging Libraries (if UseLogging=true)
• Options Libraries (if UseOptions=true)
• DI Libraries (if UseDI=true)
• Metrics Libraries (if UseMetrics=true)

CI/CD Files

azure-pipelines.yml

Purpose: Main CI/CD pipeline for build, test, and publish
Features:

• Multi-targeting build (.NET 8 and .NET 9)
• Code coverage collection
• NuGet package creation
• Artifact publishing
• Build quality checks

Variables:

• buildDefinitionNumber: Replaced from template parameter
• codeCoverageThreshold: Configurable coverage threshold
• useLocalSqlDb: Optional SQL LocalDB support

azure-pipelines-documentation.yml

Purpose: Documentation build and deployment pipeline
Features:

• MkDocs build
• Static site generation
• Azure Static Web Apps deployment

Configuration Files

.gitignore

Purpose: Git ignore rules for .NET projects
Includes:

• Build outputs (bin/, obj/)
• Test results (TestResults/)
• IDE files (.vs/, .idea/)
• User-specific files
• Package restore files

nuget.config

Purpose: NuGet feed configuration
Contains:

• Azure DevOps Artifacts feed settings
• Package source credentials
• Feed authentication

ConnectSoft.LibraryTemplate.runsettings

Purpose: Test run settings for MSTest
Contains:

• Code coverage settings
• Test adapter paths
• Data collection settings

Documentation Files

README.md

Purpose: Project documentation template
Contains:

• Project description (TODO placeholders)
• Installation instructions
• Usage examples
• Configuration examples
• Metrics documentation
• Development setup
• Build badges (with buildDefinitionNumber replacement)

Source Project Structure

src/YourLibraryName/

src/YourLibraryName/
├── YourLibraryName.csproj                 # Main project file
├── YourLibraryName.xml                     # XML documentation file
├── GlobalSuppressions.cs                   # Code analyzer suppressions
├── Options/                                # (Conditional: UseOptions=true)
│   ├── LibraryTemplateOptions.cs
│   └── ValidateLibraryTemplateOptions.cs
├── Metrics/                                # (Conditional: UseMetrics=true)
│   └── LibraryTemplateMetrics.cs
├── Diagnostics/                            # (Conditional: UseActivitySource=true)
│   └── LibraryTemplateDiagnostics.cs
└── Samples/                                # (Conditional: UseActivitySource=true)
    └── TracingDemo.cs

YourLibraryName.csproj

Key Properties:

<PropertyGroup>
  <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
  <ImplicitUsings>disable</ImplicitUsings>
  <Nullable>enable</Nullable>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>

Package References (conditional):

• Options libraries (if UseOptions=true)
• Logging libraries (if UseLogging=true)
• DI libraries (if UseDI=true)
• Metrics libraries (if UseMetrics=true)

InternalsVisibleTo:

• YourLibraryName.UnitTests (for unit testing internal members)

Options/ Folder

Condition: UseOptions=true
Generated: Only when UseOptions parameter is true

Files:

• LibraryTemplateOptions.cs: Options class with DataAnnotations
• ValidateLibraryTemplateOptions.cs: Source-generated validator

Purpose: Demonstrates Options pattern with configuration binding and validation

Metrics/ Folder

Condition: UseMetrics=true
Generated: Only when UseMetrics parameter is true

Files:

• LibraryTemplateMetrics.cs: Custom metrics implementation

Purpose: Demonstrates OpenTelemetry-compatible metrics with counters and histograms

Diagnostics/ Folder

Condition: UseActivitySource=true
Generated: Only when UseActivitySource parameter is true

Files:

• LibraryTemplateDiagnostics.cs: ActivitySource implementation

Purpose: Provides distributed tracing support with ActivitySource

Samples/ Folder

Condition: UseActivitySource=true
Generated: Only when UseActivitySource parameter is true

Files:

• TracingDemo.cs: Sample tracing usage

Purpose: Demonstrates how to use ActivitySource for distributed tracing

Test Project Structure

tests/YourLibraryName.UnitTests/

tests/YourLibraryName.UnitTests/
├── YourLibraryName.UnitTests.csproj       # Test project file
├── YourLibraryName.UnitTests.xml          # XML documentation
├── GlobalSuppressions.cs                   # Code analyzer suppressions
├── Properties/
│   └── AssemblyInfo.cs                    # Assembly metadata
├── Metrics/                                # (Conditional: UseMetrics=true)
│   └── LibraryTemplateMetricsUnitTests.cs
└── Diagnostics/                           # (Conditional: UseActivitySource=true)
    └── LibraryTemplateDiagnosticsTests.cs

YourLibraryName.UnitTests.csproj

Key Properties:

<PropertyGroup>
  <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
  <IsPackable>false</IsPackable>
  <IsTestProject>true</IsTestProject>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Package References:

• Microsoft.NET.Test.Sdk
• MSTest.TestAdapter
• MSTest.TestFramework
• coverlet.collector (for code coverage)
• Conditional packages matching source project features

Project Reference:

• Main library project (src/YourLibraryName/YourLibraryName.csproj)

Documentation Structure

docs/ Folder

docs/
├── index.md                                # Documentation home page
├── Overview.md                            # Template overview
├── Features.md                            # Feature documentation
├── GettingStarted.md                      # Getting started guide
├── UseCases.md                            # Use case examples
├── Runbook.md                             # Operations runbook
├── assets/                                 # Documentation assets
│   ├── favicon.ico
│   └── logo.png
└── (Additional documentation files)

Purpose: MkDocs-based documentation site
Build: mkdocs build
Serve: mkdocs serve (http://localhost:8000)

Template Replacements

The template performs the following replacements during generation:

Name Replacements

Template Value	Replaced With
ConnectSoft.LibraryTemplate	Your library name (from --name parameter)
ConnectSoft	Extracted from library name or default
LibraryTemplate	Extracted from library name

Build Definition Replacement

Template Value	Replaced With
buildDefinitionNumber	Value from --buildDefinitionNumber parameter (or empty string)

Framework Replacement

Template Value	Replaced With
net8.0	Value from --framework parameter (default: net8.0)

Conditional Generation

Files and folders are conditionally generated based on parameters:

Parameter	Generated Items
UseOptions=true	Options/ folder and related files
UseMetrics=true	Metrics/ folder and related files
UseActivitySource=true	Diagnostics/ and Samples/ folders

Conditional File Exclusion

The template excludes files based on conditions:

UseActivitySource Condition

• If UseActivitySource=false: Excludes Samples/TracingDemo.cs

UseOptions Condition

• If UseOptions=false: Excludes entire Options/ folder

UseMetrics Condition

• If UseMetrics=false: Excludes Metrics/ folder in both source and test projects

AuthoringMode Condition

• If AuthoringMode=false: Excludes scaffold test projects and nuspec file

File Naming Conventions

Projects

• Library project: {LibraryName}.csproj
• Test project: {LibraryName}.UnitTests.csproj

Solutions

• Modern: {LibraryName}.slnx
• Legacy: {LibraryName}.sln

Namespaces

• Main namespace: Matches library name (e.g., ConnectSoft.Extensions.MyLibrary)
• Feature namespaces: {MainNamespace}.{Feature} (e.g., ConnectSoft.Extensions.MyLibrary.Options)

Generated Code Structure

Options Pattern (UseOptions=true)

namespace YourLibraryName.Options
{
    public class LibraryTemplateOptions
    {
        public const string LibraryTemplateSectionName = "LibraryTemplate";
        [Required]
        required public string LibraryTemplateName { get; set; }
    }
}

Metrics Pattern (UseMetrics=true)

namespace YourLibraryName.Metrics
{
    public class LibraryTemplateMetrics
    {
        private readonly Counter<long> requestCounter;
        private readonly Histogram<double> requestDuration;
        // Implementation
    }
}

Diagnostics Pattern (UseActivitySource=true)

namespace YourLibraryName.Diagnostics
{
    public static class LibraryTemplateDiagnostics
    {
        public const string ActivitySourceName = "YourLibraryName";
        public static readonly ActivitySource ActivitySource = new(ActivitySourceName);
        // Implementation
    }
}

Build Output Structure

After building, the following structure is generated:

bin/
└── Debug/
    ├── net8.0/
    │   ├── YourLibraryName.dll
    │   ├── YourLibraryName.pdb
    │   ├── YourLibraryName.xml
    │   └── YourLibraryName.deps.json
    └── net9.0/
        ├── YourLibraryName.dll
        ├── YourLibraryName.pdb
        ├── YourLibraryName.xml
        └── YourLibraryName.deps.json

obj/
└── Debug/
    ├── net8.0/
    │   └── (Build artifacts)
    └── net9.0/
        └── (Build artifacts)

Package Output Structure

After packing, NuGet package structure:

YourLibraryName.{version}.nupkg
├── lib/
│   ├── net8.0/
│   │   └── YourLibraryName.dll
│   └── net9.0/
│       └── YourLibraryName.dll
├── YourLibraryName.nuspec
└── (Package metadata)

Understanding Conditional Generation

Feature Flags in .csproj

Conditional package references use MSBuild conditions:

<ItemGroup Label="Options Libraries" Condition="'$(UseOptions)' == 'true'">
  <PackageReference Include="Microsoft.Extensions.Options" />
</ItemGroup>

Template Conditions

Template conditions control file generation:

{
  "condition": "(!UseOptions)",
  "exclude": ["src/ConnectSoft.LibraryTemplate/Options/**/*"]
}

Customization After Generation

After generation, you can:

1. Add New Folders: Create additional feature folders as needed
2. Modify Project Files: Update .csproj files for additional packages
3. Extend Options: Add more options classes in Options/ folder
4. Add Metrics: Create additional metrics classes in Metrics/ folder
5. Customize Pipeline: Modify azure-pipelines.yml for specific needs

Related Documentation

• Parameters - Understanding template parameters
• Architecture - Design principles and patterns
• Features - Detailed feature documentation
• Development Guide - Local development workflow