Library Template Parameters

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

Parameter Overview

The template supports both required and optional parameters that control the generated solution structure, included features, and CI/CD integration.

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 Flag	Short Flag	Description
buildDefinitionNumber	string	""	--buildDefinitionNumber	-b, --bdn	Azure DevOps build definition number for CI/CD integration. Leave empty to use default.
Framework	choice	net8.0	--framework	-f	Target framework: net8.0 or net9.0.
UseDI	bool	true	--useDI	--di	Include support for Dependency Injection (Microsoft.Extensions.DependencyInjection).
UseLogging	bool	true	--useLogging	--logging	Include support for structured logging (Microsoft.Extensions.Logging).
UseOptions	bool	true	--useOptions	--options	Enable binding and validation of configuration sections via IOptions.
UseMetrics	bool	true	--useMetrics	--metrics	Enable built-in metrics support for custom metrics.
UseActivitySource	bool	false	--useTracing	--traces	Enable ActivitySource support for OpenTelemetry tracing.

Parameter Details

buildDefinitionNumber

Type: string
Default: "" (empty string)
CLI Flags: -b, --buildDefinitionNumber, --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 --buildDefinitionNumber 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
Default: net8.0
CLI Flag: -f, --framework
Required: No

The target framework for the library project. The template supports multi-targeting (both frameworks), but this parameter controls the primary framework used in template replacements.

Example:

# Target .NET 8 (default)
dotnet new connectsoft-library --name MyLibrary

# Target .NET 9
dotnet new connectsoft-library --name MyLibrary --framework net9.0

Note: The generated project always targets both net8.0 and net9.0 regardless of this parameter. This parameter only affects template replacements.

UseDI

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

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

What Gets Generated:

• Package references: Microsoft.Extensions.DependencyInjection.Abstractions, Microsoft.Extensions.DependencyInjection
• Enables service registration extension methods
• Allows IServiceCollection usage in library code

Example:

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

# Disable DI
dotnet new connectsoft-library --name MyLibrary --useDI 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: --useLogging, --logging
Required: No

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

What Gets Generated:

• Package references: Microsoft.Extensions.Logging.Abstractions, Microsoft.Extensions.Logging, Microsoft.Extensions.Logging.Debug, Microsoft.Extensions.Logging.Console
• Enables ILogger<T> usage in library code
• Supports structured logging patterns

Example:

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

# Disable logging
dotnet new connectsoft-library --name MyLibrary --useLogging 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: --useOptions, --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 --useOptions

# Disable options
dotnet new connectsoft-library --name MyLibrary --useOptions 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: --useMetrics, --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 --useMetrics

# Disable metrics
dotnet new connectsoft-library --name MyLibrary --useMetrics 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: --useTracing, --traces
Required: No

Enables ActivitySource support for distributed tracing with OpenTelemetry integration.

What Gets Generated:

• Diagnostics/ folder with ActivitySource implementation
• Samples/ folder with tracing demo
• Log correlation with trace IDs
• OpenTelemetry-compatible tracing

Example:

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

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

When to Use:

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

Note: When disabled, the Diagnostics/ and Samples/ folders are not generated.

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 \
  --useDI --useLogging --useOptions --useMetrics --useTracing

Minimal Utility Library:

dotnet new connectsoft-library --name MyLibrary \
  --useDI false --useLogging false --useOptions false --useMetrics false

Configuration Library:

dotnet new connectsoft-library --name MyLibrary \
  --useDI --useLogging --useOptions --useMetrics false --useTracing false

Observability Library:

dotnet new connectsoft-library --name MyLibrary \
  --useDI --useLogging --useOptions false --useMetrics --useTracing

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 \
  --buildDefinitionNumber 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 \
  --useDI false \
  --useLogging false \
  --useOptions false \
  --useMetrics false

Full-Featured Library

# Create library with all features enabled
dotnet new connectsoft-library \
  --name MyLibrary \
  --useDI \
  --useLogging \
  --useOptions \
  --useMetrics \
  --useTracing

Framework Selection

# Target .NET 9
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:
   • 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 or net9.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 net8.0 (LTS) for maximum compatibility

Overriding Defaults

You can override defaults in several ways:

1. CLI Flags: Explicitly set parameters

   dotnet new connectsoft-library --name MyLibrary --useDI 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

• Ensure you're using the correct CLI flag format
• Check that the template is installed: dotnet new list
• Verify template version supports the parameter

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 for current defaults

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