Skip to content

Library Template

The ConnectSoft Library Template provides a ready-to-use solution for creating .NET Core libraries that adhere to best practices for reusable components and packages. The template ensures consistency, maintainability, and ease of publishing for library projects.

Introduction

Purpose

The library template is designed for developers who want to create high-quality, reusable .NET libraries with minimal setup. It includes a structured solution, pre-configured settings, integrated tools, and pipelines for seamless development, testing, and publishing.

The template provides a production-ready foundation for building .NET libraries that can be shared across projects, published as NuGet packages, and integrated into larger solutions. It follows Microsoft's .NET library design guidelines and incorporates best practices for maintainability, testability, and observability.

When to Use This Template

  • Creating reusable utility libraries for cross-project use
  • Building domain model libraries for shared business logic
  • Developing API client libraries for external service integration
  • Creating infrastructure libraries with cross-cutting concerns (DI, logging, configuration)
  • Building libraries that need to support multiple .NET versions (net8.0 and net9.0)
  • Publishing libraries as NuGet packages with CI/CD automation

Prerequisites

  • .NET SDK 8.0 or later (required)
  • .NET SDK 9.0 (recommended for multi-targeting support)
  • Visual Studio 2022 (v17.14+ for .slnx support) or JetBrains Rider
  • Azure DevOps account (for CI/CD pipeline integration, optional)
  • Python 3.x with pip (for MkDocs documentation, optional)

Template Scope

Generated Solution Structure

The template generates a complete solution with the following structure:

YourLibraryName/
├── src/
│   └── YourLibraryName/
│       ├── YourLibraryName.csproj
│       ├── Options/              (if UseOptions=true)
│       ├── Metrics/                (if UseMetrics=true)
│       ├── Diagnostics/            (if UseActivitySource=true)
│       └── Samples/                (if UseActivitySource=true)
├── tests/
│   └── YourLibraryName.UnitTests/
│       ├── YourLibraryName.UnitTests.csproj
│       └── Metrics/                (if UseMetrics=true)
├── docs/                           (MkDocs documentation structure)
├── YourLibraryName.slnx           (Modern solution format)
├── YourLibraryName.sln            (Legacy solution format, fallback)
├── Directory.Build.props           (Shared build properties)
├── Directory.Packages.props        (Central Package Management)
├── azure-pipelines.yml            (CI/CD pipeline)
├── README.md                       (Templated documentation)
├── .gitignore                      (Git ignore rules)
└── nuget.config                    (NuGet feed configuration)

Generated Projects

  1. Library Project: Main project containing your library code

    • Multi-targeting: net8.0 and net9.0
    • XML documentation generation enabled
    • Static code analyzers configured
    • Conditional feature folders based on template parameters

  2. Unit Test Project: MSTest-based test project

    • Code coverage collection configured
    • Conditional test projects for optional features
    • Project reference to library project

Key Features

Well-Structured Solution

  • Project Setup:
    • Includes a primary library project and a separate unit test project using MSTest.
  • Templated README.md:
    • Provides a ready-to-edit documentation file for the library.
  • Modern Solution Format:
    • Uses .slnx (XML-based) format for improved performance (48% faster builds)
    • Includes legacy .sln format as fallback for older tooling

Integrated CI/CD Pipeline

  • Pre-Built CI Pipeline:
    • Automatically builds, tests (with code coverage), and publishes NuGet packages to an artifact repository for reuse in the ConnectSoft Framework.
  • Git Integration:
    • Includes .gitignore and code analysis settings.
  • Artifacts Management:
    • Ensures all outputs, including NuGet packages, are available for framework reuse.

Best Practices

  • Preconfigured Settings:
    • Adheres to .NET library design and coding guidelines.
  • NuSpec Integration:
    • Simplifies NuGet packaging with proper metadata for library distribution.

Cross-Cutting Features Support

  • Optional Dependency Injection (DI):
    • Built-in support for IServiceCollection and Microsoft.Extensions.DependencyInjection
    • Enables service registration patterns and extension methods
    • Default: true (enabled)
  • Optional Structured Logging:
    • Built-in support for ILogger<T> and Microsoft.Extensions.Logging
    • Structured logging patterns and correlation support
    • Default: true (enabled)
  • Optional Options Pattern:
    • Built-in support for IOptions<T> with configuration binding
    • DataAnnotations validation and source-generated validators
    • Default: true (enabled)
  • Optional Metrics Support:
    • Built-in support for OpenTelemetry-compatible metrics
    • Custom metrics implementation with IMeterFactory
    • Default: true (enabled)
  • Optional ActivitySource Tracing:
    • Built-in support for distributed tracing with ActivitySource
    • OpenTelemetry integration and log correlation
    • Default: false (disabled)

Multi-Targeting Support

The template is pre-configured to support both .NET 8 (LTS) and .NET 9 via the TargetFrameworks property in .csproj:

<TargetFrameworks>net8.0;net9.0</TargetFrameworks>

Multi-Environment Support

  • CLI and Visual Studio:
    • Supports command-line interface (CLI) and Visual Studio IDE for template instantiation and usage.

Template Usage

Command-Line Interface (CLI)

The template is accessible through the .NET CLI, allowing developers to quickly scaffold a new library solution.

Help Output

ConnectSoft Library Template (C#)
Author: Dmitry Khaymov
Description: A solution and projects for creating and publishing a library project.

Usage:
  dotnet new connectsoft-library [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output
                          directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result 
                          in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <solution>       Specifies the template type to instantiate.

Template options:
  -b, --buildDefinitionNumber <buildDefinitionNumber>  Overrides the build definition number
                                                       Type: string
                                                       Default: "" (empty)
  --useDI                    Include and use Dependency Injection support
                             Type: bool
                             Default: true
  --useLogging               Include and use Microsoft.Extensions.Logging support
                             Type: bool
                             Default: true
  --useOptions               Include and use Options binding and validation
                             Type: bool
                             Default: true
  --useMetrics               Include and use Metrics support for custom metrics
                             Type: bool
                             Default: true
  --useTracing               Include and use ActivitySource integration for tracing
                             Type: bool
                             Default: false

Examples

dotnet new connectsoft-library --name ConnectSoft.Extensions.OpenTelemetry --buildDefinitionNumber 46
dotnet new connectsoft-library --name ConnectSoft.Extensions.DomainModel.RulesEngine --buildDefinitionNumber 46
dotnet new connectsoft-library --name ConnectSoft.Extensions.LoggingSupport --useDI --useLogging --useOptions --useTracing

Visual Studio

The template is available in Visual Studio, providing an intuitive IDE-based workflow for creating new libraries. Follow these steps to create a new library using the ConnectSoft Library Template:

How to Create a New Library in Visual Studio

  1. Open Visual Studio:
    • Launch Visual Studio and select Create a new project from the home screen.

ConnectSoft Library Template
Hold "Alt" / "Option" to enable pan & zoom

  1. Find the ConnectSoft Library Template:
    • In the Create a new project dialog:
      • Use the search bar to find the ConnectSoft Library Template.
      • Filter by C# and Solution Templates if needed.

ConnectSoft Library Template
Hold "Alt" / "Option" to enable pan & zoom

  1. Select the Library Template:

    • Click on the ConnectSoft Library Template from the results.
    • Click Next to proceed.

  2. Provide Parameters:

    • In the Configure your new project dialog:
      • Enter the project name (e.g., ConnectSoft.Extensions.MyLibrary).
      • Specify the location where the solution should be created.
      • Provide any additional parameters, such as the build definition number if applicable.

ConnectSoft Library Template
Hold "Alt" / "Option" to enable pan & zoom

  1. Start Development:
    • Click Create to generate the solution.
    • The solution will include:
      • A library project.
      • A unit test project (MSTest).
      • A pre-configured README.md.
      • CI/CD pipeline scripts for Azure Pipelines.

ConnectSoft Library Template
Hold "Alt" / "Option" to enable pan & zoom

Features of the Generated Solution

  • Library Project:
    • Preconfigured for creating reusable components.
  • Test Project:
    • Includes MSTest setup for unit testing.
  • Documentation:
    • Templated README.md for library documentation.
  • CI/CD Integration:
    • Ready-to-use YAML templates for build, test, and NuGet publishing.

Artifacts Publishing

  • Ensures the NuGet package and associated artifacts are pushed to a central repository for reusability within the ConnectSoft Framework and other projects.

Quick Start

Step 1: Install the Template

The template is available from Azure DevOps Artifacts. Ensure your NuGet feed is configured in nuget.config.

Step 2: Create a New Library

dotnet new connectsoft-library --name ConnectSoft.Extensions.MyLibrary

Step 3: Customize Parameters (Optional)

# With all optional features enabled
dotnet new connectsoft-library --name MyLibrary --useDI --useLogging --useOptions --useMetrics --useTracing

# Minimal library without optional features
dotnet new connectsoft-library --name MyLibrary --useDI false --useLogging false --useOptions false --useMetrics false

Step 4: Build and Test

cd MyLibrary
dotnet build
dotnet test

Step 5: Review Generated Code

  • Check src/YourLibraryName/ for the main library project
  • Review tests/YourLibraryName.UnitTests/ for test examples
  • Customize README.md with your library description

Architecture Overview

Design Principles

  • Clean Architecture: Separation of concerns with clear boundaries
  • Domain-Driven Design: Focus on domain logic and business rules
  • Dependency Injection: Loose coupling and testability
  • Configuration Pattern: Strongly-typed configuration with validation
  • Observability First: Built-in support for logging, metrics, and tracing

Project Organization

  • Source Code: Organized in src/ folder with feature-based folders
  • Tests: Separate test project in tests/ folder
  • Documentation: MkDocs-based documentation in docs/ folder
  • CI/CD: Azure Pipelines YAML in root directory

Namespace Conventions

  • Main namespace matches the library name (e.g., ConnectSoft.Extensions.MyLibrary)
  • Feature folders map to namespace segments (e.g., Options/ → *.Options namespace)
  • Test namespaces mirror source namespaces with .UnitTests suffix

For detailed architecture information, see the Architecture Guide.

Complete Parameter Reference

Parameter Type Default CLI Flag Description
buildDefinitionNumber string "" -b, --buildDefinitionNumber Azure DevOps build definition number for CI/CD integration
Framework choice net8.0 -f, --framework Target framework: net8.0 or net9.0
UseDI bool true --useDI Enable Dependency Injection support
UseLogging bool true --useLogging Enable structured logging support
UseOptions bool true --useOptions Enable Options pattern with validation
UseMetrics bool true --useMetrics Enable metrics support
UseActivitySource bool false --useTracing Enable ActivitySource tracing support

For detailed parameter documentation, see the Parameters Guide.

Integration with ConnectSoft Framework

The library template seamlessly integrates into the ConnectSoft Framework, allowing developers to:

  • Reuse the NuGet packages generated by the template across multiple projects.
  • Leverage the pre-configured pipelines to maintain a consistent build, test, and publish process.
  • Follow consistent patterns and conventions across all ConnectSoft libraries.

Next Steps

References