Library Template Parameters

Complete reference guide for all parameters available in the ConnectSoft Library Template.

Parameter Overview

The template supports optional parameters that control the generated solution structure, optional feature folders, and CI badge placeholders. This page is the canonical CLI and Visual Studio reference for ConnectSoft.LibraryTemplate (dotnet new connectsoft-library).

Template parameters vs Azure Pipelines variables

• Template parameters (dotnet new ...) are defined in .template.config/template.json in the ConnectSoft.LibraryTemplate repository. They control what files exist in the scaffold (for example Options/, Metrics/, Diagnostics/, tracing sample).
• Pipeline variables (for example useLocalSqlDb, codeCoverageThreshold) live in azure-pipelines.yml in the generated repo. They are not dotnet new switches. Set them in Azure DevOps UI, YAML variables:, or variable groups when you run CI—not when you scaffold.

Framework vs multi-targeting

The generated library project always multi-targets net8.0;net9.0;net10.0. The Framework template parameter (default net10.0) is a primary moniker for tooling and documentation; it does not change TargetFrameworks in the .csproj. This avoids invalid TFM strings that would occur if a single replaces token were applied across the whole project file.

Why tracing defaults to off

UseActivitySource defaults to false so minimal libraries stay small and do not carry ActivitySource types unless you opt in. When true, the template includes Diagnostics/, unit tests under Diagnostics/, and Samples/TracingDemo.cs.

Complete Parameter Reference

Standard Template Parameters

These parameters are provided by the .NET template engine:

Parameter	Type	Required	CLI Flag	Description
name	string	No	-n, --name	The name for the output being created. If not specified, the directory name is used.
output	string	No	-o, --output	Location to place the generated output.
language	string	No	-lang, --language	Template language (C# is the only option).
type	string	No	--type	Template type (solution is the only option).

Template-Specific Parameters

These parameters are specific to the ConnectSoft Library Template:

Parameter	Type	Default	CLI (preferred)	Short	Description
buildDefinitionNumber	string	""	--build-definition-number	-b, --bdn	Azure DevOps build definition ID for README/pipeline placeholders.
Framework	choice	net10.0	--framework	-f	Primary framework moniker (documentation/tooling). Library still multi-targets net8, net9, net10.
UseDI	bool	true	--use-di	--di	Dependency Injection (Microsoft.Extensions.DependencyInjection).
UseLogging	bool	true	--use-logging	--logging	Structured logging (Microsoft.Extensions.Logging).
UseOptions	bool	true	--use-options	--options	IOptions<T> binding and validation.
UseMetrics	bool	true	--use-metrics	--metrics	Custom metrics (Microsoft.Extensions.Diagnostics).
UseActivitySource	bool	false	--use-tracing	--traces	ActivitySource, Diagnostics/ sample, tracing demo, diagnostics tests.

Host mapping is defined in ConnectSoft.LibraryTemplate .template.config/dotnetcli.host.json. Some alternate spellings may be accepted by the template engine; prefer the kebab-case flags above.

Parameter Details

buildDefinitionNumber

Type: string
Default: "" (empty string)
CLI Flags: --build-definition-number, -b, --bdn
Required: No

Custom Azure DevOps build definition number used in CI/CD pipelines. This value replaces the placeholder in azure-pipelines.yml and README.md badges.

Example:

dotnet new connectsoft-library --name MyLibrary --build-definition-number 46

When to Use:

• When you have a specific Azure DevOps build definition number
• When you want to customize CI/CD pipeline references
• When generating multiple libraries with different build definitions

Note: If left empty, the template will use a placeholder that you can manually update later.

Framework

Type: choice
Choices: net8.0, net9.0, net10.0
Default: net10.0
CLI Flag: -f, --framework
Required: No

Selects the primary framework moniker (default .NET 10). The scaffolded .csproj always lists net8.0;net9.0;net10.0 so one package can run on all three; changing --framework does not remove TFMs from the project file.

Example:

# Default primary moniker net10.0 (multi-TFM unchanged)
dotnet new connectsoft-library --name MyLibrary

dotnet new connectsoft-library --name MyLibrary --framework net8.0
dotnet new connectsoft-library --name MyLibrary --framework net9.0

UseDI

Type: bool
Default: true
CLI Flags: --use-di, --di
Required: No

Enables Dependency Injection support by including Microsoft.Extensions.DependencyInjection packages and abstractions.

What Gets Generated:

• Package references (library project): Microsoft.Extensions.DependencyInjection.Abstractions (full DI package versions are centralized in Directory.Packages.props for optional use)
• Enables IServiceCollection / extension-method patterns in library code

Example:

# Enable DI (default)
dotnet new connectsoft-library --name MyLibrary --use-di

# Disable DI
dotnet new connectsoft-library --name MyLibrary --use-di false

When to Use:

• Enable (default): When your library needs to register services or use DI patterns
• Disable: For simple utility libraries that don't need DI

UseLogging

Type: bool
Default: true
CLI Flags: --use-logging, --logging
Required: No

Enables structured logging support by including Microsoft.Extensions.Logging packages.

What Gets Generated:

• Package references (library project): Microsoft.Extensions.Logging.Abstractions (versions for additional logging packages may be listed in Directory.Packages.props for you to reference if needed)
• Enables ILogger<T> usage in library code

Example:

# Enable logging (default)
dotnet new connectsoft-library --name MyLibrary --use-logging

# Disable logging
dotnet new connectsoft-library --name MyLibrary --use-logging false

When to Use:

• Enable (default): When your library needs logging capabilities
• Disable: For libraries that don't require logging

UseOptions

Type: bool
Default: true
CLI Flags: --use-options, --options
Required: No

Enables the Options pattern with configuration binding and validation.

What Gets Generated:

• Package references: Microsoft.Extensions.Options, Microsoft.Extensions.Options.DataAnnotations
• Options/ folder with sample options class
• Source-generated options validator
• Configuration binding examples

Example:

# Enable options (default)
dotnet new connectsoft-library --name MyLibrary --use-options

# Disable options
dotnet new connectsoft-library --name MyLibrary --use-options false

When to Use:

• Enable (default): When your library needs configuration options
• Disable: For libraries that don't require configuration

Note: When disabled, the Options/ folder is not generated.

UseMetrics

Type: bool
Default: true
CLI Flags: --use-metrics, --metrics
Required: No

Enables built-in metrics support for custom OpenTelemetry-compatible metrics.

What Gets Generated:

• Package references: Microsoft.Extensions.Diagnostics
• Metrics/ folder with sample metrics class
• IMeterFactory integration
• Example counter and histogram metrics

Example:

# Enable metrics (default)
dotnet new connectsoft-library --name MyLibrary --use-metrics

# Disable metrics
dotnet new connectsoft-library --name MyLibrary --use-metrics false

When to Use:

• Enable (default): When your library needs observability metrics
• Disable: For libraries that don't require metrics

Note: When disabled, the Metrics/ folder is not generated.

UseActivitySource

Type: bool
Default: false
CLI Flags: --use-tracing, --traces
Required: No

Enables ActivitySource support for distributed tracing with OpenTelemetry integration.

What Gets Generated:

• Diagnostics/ with LibraryTemplateDiagnostics (ActivitySource)
• tests/.../UnitTests/Diagnostics/ with sample tests
• Samples/TracingDemo.cs (only file under Samples/ in the template)

Example:

# Enable tracing
dotnet new connectsoft-library --name MyLibrary --use-tracing

# Disable tracing (default)
dotnet new connectsoft-library --name MyLibrary --use-tracing false

When to Use:

• Enable: When your library participates in distributed tracing
• Disable (default): For libraries that do not emit activities

Note: When disabled, Diagnostics/, UnitTests/Diagnostics/, and Samples/TracingDemo.cs are omitted from the scaffold.

Parameter Interactions

Dependency Relationships

Some parameters have implicit dependencies:

• UseOptions may benefit from UseDI for service registration
• UseMetrics works independently but integrates well with UseLogging
• UseActivitySource integrates with UseLogging for log correlation

Recommended Combinations

Full-Featured Library:

dotnet new connectsoft-library --name MyLibrary \
  --use-di --use-logging --use-options --use-metrics --use-tracing

Minimal Utility Library:

dotnet new connectsoft-library --name MyLibrary \
  --use-di false --use-logging false --use-options false --use-metrics false

Configuration Library:

dotnet new connectsoft-library --name MyLibrary \
  --use-di --use-logging --use-options --use-metrics false --use-tracing false

Observability Library:

dotnet new connectsoft-library --name MyLibrary \
  --use-di --use-logging --use-options false --use-metrics --use-tracing

CLI Usage Examples

Basic Usage

# Create library with default settings
dotnet new connectsoft-library --name ConnectSoft.Extensions.MyLibrary

With Build Definition

# Specify build definition number
dotnet new connectsoft-library \
  --name MyLibrary \
  --build-definition-number 46

Custom Output Location

# Generate in specific directory
dotnet new connectsoft-library \
  --name MyLibrary \
  --output ./Libraries/MyLibrary

Minimal Library

# Create library without optional features
dotnet new connectsoft-library \
  --name MyLibrary \
  --use-di false \
  --use-logging false \
  --use-options false \
  --use-metrics false

Full-Featured Library

# Create library with all features enabled
dotnet new connectsoft-library \
  --name MyLibrary \
  --use-di \
  --use-logging \
  --use-options \
  --use-metrics \
  --use-tracing

Framework Selection

# Primary moniker net9.0 (library still multi-targets net8, net9, net10)
dotnet new connectsoft-library \
  --name MyLibrary \
  --framework net9.0

Visual Studio Parameter Configuration

When using Visual Studio, parameters are configured in the project creation dialog:

1. Project Name: Maps to --name parameter
2. Location: Maps to --output parameter
3. Additional Parameters: Configured in advanced options:
   • Primary framework moniker (Framework)
   • Build Definition Number
   • Enable Dependency Injection
   • Enable Logging
   • Enable Options
   • Enable Metrics
   • Enable Tracing

Parameter Validation

The template validates parameters as follows:

• buildDefinitionNumber: Accepts any string (empty string is valid)
• Framework: Must be net8.0, net9.0, or net10.0
• Boolean parameters: Accept true, false, 1, 0, yes, no

Default Values Strategy

Default values are chosen to provide a good starting point for most libraries:

• UseDI, UseLogging, UseOptions, UseMetrics: Default to true because most libraries benefit from these features
• UseActivitySource: Defaults to false because tracing is typically needed only for libraries that participate in distributed systems
• Framework: Defaults to net10.0 as the primary moniker; the library still compiles for net8 and net9 via multi-targeting

Overriding Defaults

You can override defaults in several ways:

1. CLI Flags: Explicitly set parameters

   dotnet new connectsoft-library --name MyLibrary --use-di false
   

2. Visual Studio: Uncheck options in the project creation dialog

3. Post-Generation: Manually remove generated folders and package references (not recommended)

Best Practices

1. Start with Defaults: Use default values unless you have a specific reason to change them
2. Enable What You Need: Enable only the features you'll actually use
3. Consider Dependencies: Think about how features interact (e.g., Options + DI)
4. Document Choices: Document why you chose specific parameter values in your library's README

Troubleshooting

Parameter Not Recognized

• Prefer kebab-case flags (--use-tracing, not --UseTracing). Run dotnet new connectsoft-library -h to see the names your SDK reports.
• Install or update the template: dotnet new install <path-or-package-to-ConnectSoft.LibraryTemplate>
• Run dotnet new list and confirm ConnectSoft Library Template / short name connectsoft-library appears.

“Framework does not change TargetFrameworks”

• This is expected: the scaffold always emits net8.0;net9.0;net10.0. Use Framework as a documentation / primary moniker only. To drop a TFM, edit the generated .csproj after scaffold.

Unexpected Behavior

• Check parameter interactions (some features depend on others)
• Review generated files to understand what was created
• Consult the Generated Structure guide

Default Values Not Applied

• Explicitly set parameters if defaults aren't working
• Check template version for default value changes
• Review template.json in ConnectSoft.LibraryTemplate for current defaults

Template installed but wrong version

• Uninstall then reinstall the template package, or install from a specific folder / NuGet version your team documents.

Related Documentation

• Overview - Template overview and quick start
• Generated Structure - What gets generated based on parameters
• Features - Detailed feature documentation
• Use Cases - Real-world parameter usage examples