Skip to content

API Library Template Parameters

The ConnectSoft API Library Template offers parameters that control the generated API client solution: naming, one AuthenticationType, optional metrics, CI badge placeholders, and a primary Framework moniker.

This page is the canonical CLI and Visual Studio reference for ConnectSoft.ApiLibraryTemplate (dotnet new connectsoft-api-library). Prefer the kebab-case / documented short flags from .template.config/dotnetcli.host.json; run dotnet new connectsoft-api-library -h after dotnet new install to confirm the exact spelling on your machine.

Template parameters vs Azure Pipelines variables

  • Template parameters (dotnet new ...) come from .template.config/template.json in ConnectSoft.ApiLibraryTemplate. They control which files exist (for example BasicAuthenticationOptions.cs, Metrics/, test metrics).
  • Pipeline variables in the generated repo’s azure-pipelines.yml (for example codeCoverageThreshold) are not dotnet new switches—set them in Azure DevOps when you run CI.

Framework vs multi-targeting

The generated library and test projects always multi-target net8.0;net9.0;net10.0. The Framework parameter (default net10.0) is a primary moniker for tooling and documentation; it does not change TargetFrameworks in the .csproj.

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 No The service name used in code (e.g., ExchangeRate, GoogleAnalytics, StripeClient). Override the default for real libraries.
ApiServiceDescription --api-service-description, -api-srv-desc string Exchange rate No Short human-readable description of the API. Override for real libraries.
AuthenticationType --authentication-type, -auth-type choice None No Single choice: None, Basic, OAuth, OpenIDConnect, ApiKey. Determines auth options files and packages—not multiple independent flags.
buildDefinitionNumber --build-definition-number, -bdn string "" (empty string) No Azure DevOps build definition id for README/pipeline placeholders.
UseMetrics --use-metrics, -metrics bool true No When true, includes Metrics/ and metrics unit tests; adds Microsoft.Extensions.Diagnostics.
Framework --framework, -f choice net10.0 No Primary moniker: net8.0, net9.0, net10.0. Does not alter TargetFrameworks.

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: No (override for production scaffolds)
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: No (override for production scaffolds)
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: --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: net10.0
Required: No
CLI Flags: -f, --framework
Choices: net8.0, net9.0, net10.0

Selects the primary framework moniker (default .NET 10). The scaffolded .csproj always lists net8.0;net9.0;net10.0; changing --framework does not remove TFMs.

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; override defaults for real libraries).
    • A short human-readable description of the API being wrapped: Text field (corresponds to --api-service-description; override defaults for real libraries).
    • 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 net8.0;net9.0;net10.0 in TargetFrameworks, regardless of Framework.
  • Framework is the primary moniker for IDE/docs only.

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.