Skip to content

API Library Template Parameters

The ConnectSoft API Library Template offers a rich set of customizable parameters that allow developers to tailor the generated project to their specific needs. These parameters control various aspects of the library, including its name, target framework, authentication mechanism, and optional features like metrics.

This document provides a comprehensive reference for all available parameters, their types, default values, and how to use them via both the .NET Command-Line Interface (CLI) and Visual Studio.

Parameter Reference Table

The following table lists all parameters available in the connectsoft-api-library template:

Parameter Name CLI Flag(s) Type Default Value Required Description
name -n, --name string ConnectSoft.ApiLibrary1 No The name of the generated library project and solution. This name is used for the .csproj file, solution folder, and default namespace.
ApiServiceName --api-service-name, -api-srv-name string ExchangeRate Yes The service name used in code (e.g., ExchangeRate, GoogleAnalytics, StripeClient). This value replaces ExchangeRate throughout the generated code.
ApiServiceDescription --api-service-description, -api-srv-desc string Exchange rate Yes A short human-readable description of the API being wrapped. Used in XML documentation and comments.
AuthenticationType --authentication-type, -auth-type choice None No Select the authentication mechanism used by the API. Choices: None, Basic, OAuth, OpenIDConnect, ApiKey.
buildDefinitionNumber -b, --build-definition-number, -bdn string "" (empty string) No Custom Azure DevOps build definition number for CI/CD integration. Used in the azure-pipelines.yml for badge linking. If left empty, the badge will not link to a specific build definition.
UseMetrics --use-metrics, -metrics bool true No Enable built-in metrics support for custom application metrics using System.Diagnostics.Metrics (OpenTelemetry compatible). When true, includes metrics classes and unit tests.
Framework -f, --framework choice net8.0 No The target framework for the library. The template supports multi-targeting. Choices: net8.0, net9.0. The generated .csproj will include <TargetFrameworks>net8.0;net9.0</TargetFrameworks> by default, but this parameter allows you to specify a primary target.

Parameter Details

name Parameter

Type: string
Default: ConnectSoft.ApiLibrary1
Required: No
CLI Flags: -n, --name

The name of the generated library project and solution. This name is used for:

  • The solution file name (.slnx and .sln)
  • The project folder name
  • The default namespace
  • The .csproj file name

Example: 

dotnet new connectsoft-api-library --name ConnectSoft.GoogleAnalytics

This creates a solution named ConnectSoft.GoogleAnalytics.slnx with a project folder ConnectSoft.GoogleAnalytics.

ApiServiceName Parameter

Type: string
Default: ExchangeRate
Required: Yes
CLI Flags: --api-service-name, -api-srv-name

The service name used in code. This value replaces ExchangeRate throughout the generated code, including:

  • Interface names: I{ApiServiceName}Service
  • Implementation class names: {ApiServiceName}Service
  • Extension method names: Add{ApiServiceName}Service
  • Options class names: {ApiServiceName}ServiceOptions
  • Metrics class names: {ApiServiceName}ServiceMetrics
  • Exception class names: {ApiServiceName}ServiceException

Naming Guidelines:

  • Use PascalCase (e.g., GoogleAnalytics, StripeClient, PaymentGateway)
  • Avoid spaces or special characters
  • Use descriptive names that reflect the API being wrapped

Example: 

dotnet new connectsoft-api-library --api-service-name "GoogleAnalytics"

This generates IGoogleAnalyticsService, GoogleAnalyticsService, GoogleAnalyticsServiceOptions, etc.

ApiServiceDescription Parameter

Type: string
Default: Exchange rate
Required: Yes
CLI Flags: --api-service-description, -api-srv-desc

A short human-readable description of the API being wrapped. This description is used in:

  • XML documentation comments
  • README.md placeholders
  • Code comments

Example: 

dotnet new connectsoft-api-library --api-service-description "Google Analytics Measurement Protocol API"

AuthenticationType Parameter

Type: choice
Default: None
Required: No
CLI Flags: --authentication-type, -auth-type
Choices: None, Basic, OAuth, OpenIDConnect, ApiKey

Select the authentication mechanism used by the target API. This parameter determines which authentication options classes are generated and how the HTTP client is configured.

Authentication Type: None

  • Use Case: Public APIs that don't require authentication
  • Generated Files: No authentication options classes
  • Configuration: No authentication configuration needed

Authentication Type: Basic

  • Use Case: APIs using HTTP Basic Authentication (username/password)
  • Generated Files: BasicAuthenticationOptions.cs
  • Configuration: Requires Username and Password in configuration
  • Implementation: Base64-encoded credentials in Authorization header

Authentication Type: ApiKey

  • Use Case: APIs that use API keys in headers or query strings
  • Generated Files: ApiKeyAuthenticationOptions.cs
  • Configuration: Requires ApiKey and optional HeaderName (default: X-Api-Key)
  • Implementation: API key added to request headers

Authentication Type: OAuth

  • Use Case: APIs using OAuth 2.0 client credentials flow
  • Generated Files: Uses ConnectSoft.Extensions.Http.OAuth2 package
  • Configuration: Requires OAuth2 client options (client ID, client secret, token endpoint, scopes)
  • Implementation: Automatic token acquisition and refresh

Authentication Type: OpenIDConnect

  • Use Case: APIs using OpenID Connect with identity provider integration
  • Generated Files: Uses ConnectSoft.Extensions.Http.OAuth2 package with OpenID Connect validation
  • Configuration: Requires OAuth2 options plus OpenID Connect authority and validation settings
  • Implementation: Token acquisition with OpenID Connect token validation

Example: 

dotnet new connectsoft-api-library --authentication-type "ApiKey"

For detailed authentication documentation, see the Authentication Guide.

buildDefinitionNumber Parameter

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

Custom Azure DevOps build definition number for CI/CD integration. This value is used in the azure-pipelines.yml file to link the build status badge to a specific pipeline definition.

Example: 

dotnet new connectsoft-api-library --build-definition-number "12345"

This updates the README.md badge to link to build definition 12345.

Note: If left empty, the badge will still be generated but won't link to a specific build definition.

UseMetrics Parameter

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

Enable built-in metrics support for custom application metrics using System.Diagnostics.Metrics (OpenTelemetry compatible). When true:

  • Generates {ApiServiceName}ServiceMetrics.cs in the Metrics/ folder
  • Generates corresponding unit tests
  • Adds Microsoft.Extensions.Diagnostics package reference
  • Includes metrics instrumentation in the service implementation

When to Enable:

  • You want to track API call counts, durations, and failures
  • You're integrating with OpenTelemetry or Prometheus
  • You need observability for production monitoring

When to Disable:

  • Building a simple library without observability requirements
  • Reducing dependencies for minimal footprint

Example: 

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

# Disable metrics
dotnet new connectsoft-api-library --use-metrics false

For detailed metrics documentation, see the Features Guide.

Framework Parameter

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

The target framework for the library. The template supports multi-targeting, so the generated .csproj will include both net8.0 and net9.0 by default. This parameter allows you to specify a primary target framework.

Multi-Targeting: The template always generates multi-targeting support: 

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

This ensures the NuGet package supports both .NET 8 (LTS) and .NET 9, maximizing compatibility.

Example: 

dotnet new connectsoft-api-library --framework net9.0

Using Parameters with the .NET CLI

Basic Usage

To create a library with default settings (name will be derived from the output directory):

dotnet new connectsoft-api-library -o MyApiLibrary

Specifying Required Parameters

dotnet new connectsoft-api-library \
  --name ConnectSoft.GoogleAnalytics \
  --api-service-name "GoogleAnalytics" \
  --api-service-description "Google Analytics Measurement Protocol API"

Enabling/Disabling Optional Features

# Enable metrics (default)
dotnet new connectsoft-api-library \
  --api-service-name "StripeClient" \
  --api-service-description "Stripe Payment API" \
  --use-metrics

# Disable metrics
dotnet new connectsoft-api-library \
  --api-service-name "StripeClient" \
  --api-service-description "Stripe Payment API" \
  --use-metrics false

Setting Authentication Type

# API Key authentication
dotnet new connectsoft-api-library \
  --api-service-name "PaymentGateway" \
  --api-service-description "Payment Gateway API" \
  --authentication-type "ApiKey"

# OAuth2 authentication
dotnet new connectsoft-api-library \
  --api-service-name "MicrosoftGraph" \
  --api-service-description "Microsoft Graph API" \
  --authentication-type "OAuth"

Setting Build Definition Number

dotnet new connectsoft-api-library \
  --api-service-name "MyService" \
  --api-service-description "My Service API" \
  --build-definition-number "12345"

Combining Parameters

You can combine multiple parameters in a single command:

dotnet new connectsoft-api-library \
  --name ConnectSoft.FullFeaturedLibrary \
  --api-service-name "FullFeaturedService" \
  --api-service-description "A fully featured API service" \
  --authentication-type "OAuth" \
  --use-metrics \
  --build-definition-number "56789" \
  --framework net9.0

Using Parameters with Visual Studio

When creating a new project in Visual Studio using the ConnectSoft API Library Template, the parameters are presented in an intuitive graphical interface.

  1. Open Visual Studio and select Create a new project.
  2. Search for and select ConnectSoft Api Library Template. Click Next.
  3. In the Configure your new project screen:
    • Project name: Enter the desired name for your library (corresponds to --name).
    • Location: Choose where to save the project.
  4. Click Next.
  5. In the Additional information screen, you will see fields for the parameters:
    • The service name used in code (e.g., ExchangeRate): Text field (corresponds to --api-service-name, required).
    • A short human-readable description of the API being wrapped: Text field (corresponds to --api-service-description, required).
    • Choose the type of authentication this API uses: Dropdown (corresponds to --authentication-type).
    • Azure DevOps build definition number: Text field (corresponds to --build-definition-number).
    • Enable built-in metrics support for custom metrics: Checkbox (corresponds to --use-metrics).
    • Framework: Dropdown for selecting the target framework (corresponds to --framework).
  6. Select your desired options and click Create.

Parameter Interactions and Dependencies

Authentication Type Dependencies

  • Basic: Generates BasicAuthenticationOptions.cs and requires Username and Password in configuration.
  • ApiKey: Generates ApiKeyAuthenticationOptions.cs and requires ApiKey and optional HeaderName in configuration.
  • OAuth or OpenIDConnect: Adds ConnectSoft.Extensions.Http.OAuth2 package reference and requires OAuth2 configuration.

UseMetrics Dependencies

  • When UseMetrics is true:
    • Generates Metrics/{ApiServiceName}ServiceMetrics.cs
    • Generates Metrics/{ApiServiceName}ServiceMetricsUnitTests.cs
    • Adds Microsoft.Extensions.Diagnostics package reference
    • Includes metrics instrumentation in service implementation

Framework Selection

  • The template always generates multi-targeting (net8.0;net9.0), regardless of the Framework parameter value.
  • The Framework parameter is primarily for documentation and specifying a primary target.

Best Practices

Parameter Naming

  • ApiServiceName: Use PascalCase, descriptive names (e.g., GoogleAnalytics, StripeClient, PaymentGateway).
  • ApiServiceDescription: Use clear, concise descriptions that explain what the API does.

Authentication Type Selection

  • None: Use for public APIs or when authentication is handled externally.
  • Basic: Use for legacy APIs or simple username/password authentication.
  • ApiKey: Use for most modern APIs that use API keys.
  • OAuth: Use for APIs that support OAuth 2.0 client credentials flow.
  • OpenIDConnect: Use for APIs that require OpenID Connect token validation.

Metrics

  • Enable by default: Metrics provide valuable observability in production.
  • Disable only if: You have specific requirements to minimize dependencies.

Build Definition Number

  • Set when: You have an existing Azure DevOps pipeline and want badge linking.
  • Leave empty when: You're creating a new project and will set up the pipeline later.

Examples

Example 1: Simple API Key Library

dotnet new connectsoft-api-library \
  --name ConnectSoft.WeatherAPI \
  --api-service-name "WeatherService" \
  --api-service-description "Weather API client" \
  --authentication-type "ApiKey"

Example 2: OAuth2 Library with Metrics

dotnet new connectsoft-api-library \
  --name ConnectSoft.MicrosoftGraph \
  --api-service-name "MicrosoftGraphClient" \
  --api-service-description "Microsoft Graph API client" \
  --authentication-type "OAuth" \
  --use-metrics

Example 3: Public API (No Authentication)

dotnet new connectsoft-api-library \
  --name ConnectSoft.PublicAPI \
  --api-service-name "PublicAPIClient" \
  --api-service-description "Public API client" \
  --authentication-type "None" \
  --use-metrics false

dotnet new connectsoft-api-library \
  --name ConnectSoft.EnterpriseAPI \
  --api-service-name "EnterpriseService" \
  --api-service-description "Enterprise API integration" \
  --authentication-type "OpenIDConnect" \
  --use-metrics \
  --build-definition-number "100" \
  --framework net9.0

By understanding and utilizing these parameters, you can efficiently scaffold API libraries that are perfectly aligned with your project's requirements and architectural standards.