Getting Started¶

The ConnectSoft API Library Template simplifies the process of building robust, reusable API service agent libraries in .NET Core. This guide provides step-by-step instructions to help you create, configure, and use a new API library project generated from the template.

Prerequisites¶

Before you begin, ensure you have the following prerequisites installed and configured:

Required Tools¶

.NET SDK 8.0 or later (required)
- Download .NET SDK
- Verify installation: dotnet --version
.NET SDK 9.0 (recommended for multi-targeting support)

Development Environment¶

IDE: Visual Studio 2022 (v17.14+ for .slnx support) or JetBrains Rider
Package Manager: NuGet CLI or access to NuGet package manager
Git: For version control (optional but recommended)

Optional Tools¶

Azure DevOps account (for CI/CD pipeline integration)
Python 3.x with pip (for MkDocs documentation generation)

Installing the Template¶

Step 1: Obtain the Template Package¶

Download the .nupkg file for the ConnectSoft API Library Template from your package source (Azure Artifacts, NuGet.org, or local repository).

Step 2: Install the Template¶

Install the template using the .NET CLI:

dotnet new install ./ConnectSoft.ApiLibraryTemplate.1.0.0.nupkg

Alternatively, if the template is available in a NuGet feed:

dotnet new install ConnectSoft.ApiLibraryTemplate::1.0.0

Step 3: Verify Installation¶

Verify that the template is installed correctly:

dotnet new list connectsoft-api-library

You should see the template listed with its description and available parameters.

Creating a New API Library Project¶

Using the .NET CLI¶

Use the dotnet new command to generate a new API library project. The following example creates a library for Google Analytics:

dotnet new connectsoft-api-library \
  --name ConnectSoft.GoogleAnalytics \
  --api-service-name "GoogleAnalytics" \
  --api-service-description "Google Analytics Measurement Protocol API" \
  --authentication-type "ApiKey" \
  --use-metrics \
  --build-definition-number 54

Using Visual Studio¶

Open Visual Studio 2022
Select Create a new project
Search for ConnectSoft API Library Template
Click Next
Configure your project:
- Project name: Enter your library name (e.g., ConnectSoft.GoogleAnalytics)
- Location: Choose where to save the project
Click Next
Configure additional parameters:
- API Service Name: Enter the service name (e.g., GoogleAnalytics)
- API Service Description: Enter a description
- Authentication Type: Select from dropdown (None, Basic, ApiKey, OAuth, OpenIDConnect)
- Enable Metrics: Check to enable metrics support
- Build Definition Number: Enter Azure DevOps build definition number (optional)
Click Create

Required Parameters¶

Parameter	CLI Flag	Description	Example
`ApiServiceName`	`--api-service-name`	Required. The service name used in code (e.g., `GoogleAnalytics`, `StripeClient`). This value replaces `ExchangeRate` throughout the generated code.	`GoogleAnalytics`
`ApiServiceDescription`	`--api-service-description`	Required. A short human-readable description of the API being wrapped. Used in XML documentation and comments.	`Google Analytics Measurement Protocol API`

Optional Parameters¶

Parameter	CLI Flag	Default	Description
`name`	`-n`, `--name`	`ConnectSoft.ApiLibrary1`	The name of the generated library project and solution.
`AuthenticationType`	`--authentication-type`	`None`	Authentication mechanism: `None`, `Basic`, `ApiKey`, `OAuth`, `OpenIDConnect`.
`UseMetrics`	`--use-metrics`	`true`	Enable built-in metrics support using `System.Diagnostics.Metrics`.
`buildDefinitionNumber`	`--build-definition-number`	`""`	Azure DevOps build definition number for CI/CD integration.
`Framework`	`--framework`	`net8.0`	Target framework (`net8.0` or `net9.0`). The template supports multi-targeting.

For detailed information about all parameters, see the Parameters documentation.

Understanding the Generated Structure¶

After creating your project, you'll have a complete solution structure. Here's a high-level overview:

ConnectSoft.GoogleAnalytics/
├── src/
│   └── ConnectSoft.GoogleAnalytics/
│       ├── ConnectSoft.GoogleAnalytics.csproj
│       ├── IGoogleAnalyticsService.cs
│       ├── GoogleAnalyticsService.cs
│       ├── GoogleAnalyticsServiceException.cs
│       ├── GoogleAnalyticsResponse.cs
│       ├── GoogleAnalyticsResult.cs
│       ├── GoogleAnalyticsError.cs
│       ├── GoogleAnalyticsServiceExtensions.cs
│       ├── Options/                      # Configuration options
│       ├── Metrics/                      # (if UseMetrics=true)
│       └── Resilience/                   # (empty, for custom policies)
├── tests/
│   └── ConnectSoft.GoogleAnalytics.UnitTests/
│       ├── ConnectSoft.GoogleAnalytics.UnitTests.csproj
│       ├── GoogleAnalyticsServiceUnitTests.cs
│       ├── GoogleAnalyticsServiceWithMockedServerUnitTests.cs
│       └── appsettings.UnitTests.json
├── ConnectSoft.GoogleAnalytics.slnx      # Modern solution format
├── ConnectSoft.GoogleAnalytics.sln       # Legacy solution format
├── Directory.Build.props                 # Shared build properties
├── Directory.Packages.props              # Central Package Management
├── azure-pipelines.yml                   # CI/CD pipeline
└── README.md                             # Project documentation

For a detailed breakdown of the generated structure, see the Generated Structure documentation.

Configuring the API Library¶

Step 1: Configure Service Options¶

Update the appsettings.json file (or appsettings.{Environment}.json) with your API-specific settings:

{
  "GoogleAnalyticsService": {
    "BaseUrl": "https://www.googleapis.com/analytics/v3/",
    "DefaultTimeout": "0:00:10",
    "WebProxy": {
      "UseProxy": false,
      "ProxyAddress": null
    },
    "EnableHttpStandardResilience": true,
    "HttpStandardResilience": {
      "TotalRequestTimeout": { "Timeout": "0:00:30" },
      "Retry": { "MaxRetryAttempts": 3, "BackoffType": "Constant", "Delay": "00:00:02" },
      "CircuitBreaker": { "FailureRatio": 0.1, "MinimumThroughput": 2, "SamplingDuration": "00:00:30", "BreakDuration": "00:00:05" }
    },
    "ApiKeyAuthentication": {
      "ApiKey": "your-api-key-here",
      "HeaderName": "X-API-Key"
    }
  }
}

Step 2: Register the Service¶

In your consuming application's Program.cs or Startup.cs, register the API service:

using ConnectSoft.GoogleAnalytics;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// Add and validate API library options
builder.Services.AddGoogleAnalyticsOptions(builder.Configuration);

// Add the API service as a typed HTTP client
builder.Services.AddGoogleAnalyticsService();

// If metrics are enabled
builder.Services.AddGoogleAnalyticsMetrics();

var app = builder.Build();
app.Run();

Step 3: Use the Service¶

Inject the service interface into your classes:

using ConnectSoft.GoogleAnalytics;

public class AnalyticsController
{
    private readonly IGoogleAnalyticsService _analyticsService;

    public AnalyticsController(IGoogleAnalyticsService analyticsService)
    {
        _analyticsService = analyticsService;
    }

    public async Task<GoogleAnalyticsResult> GetAnalyticsDataAsync()
    {
        var result = await _analyticsService.GetAnalyticsDataAsync();
        return result;
    }
}

For detailed configuration examples, see the Configuration documentation.

Building and Testing¶

Build the Library¶

Build the solution using the .NET CLI:

dotnet build

Or build a specific project:

dotnet build src/ConnectSoft.GoogleAnalytics/ConnectSoft.GoogleAnalytics.csproj

Run Tests¶

Execute all unit tests:

dotnet test

Run tests with code coverage:

dotnet test --collect:"XPlat Code Coverage"

For more information about testing, see the Testing documentation.

Package the Library¶

Create a NuGet package:

dotnet pack --configuration Release --output ./packages

This creates a .nupkg file in the ./packages directory.

Publish the Package¶

Publish the package to a NuGet feed:

dotnet nuget push ./packages/ConnectSoft.GoogleAnalytics.1.0.0.nupkg \
  --source "YourNuGetSource" \
  --api-key "YourApiKey"

Or use Azure Artifacts:

dotnet nuget push ./packages/ConnectSoft.GoogleAnalytics.1.0.0.nupkg \
  --source "https://pkgs.dev.azure.com/YourOrg/YourProject/_packaging/YourFeed/nuget/v3/index.json" \
  --api-key "YourApiKey"

Next Steps¶

Now that you have created and configured your API library, consider the following next steps:

1. Explore the Documentation¶

Overview: Comprehensive overview of the template and its features
Parameters: Detailed reference for all template parameters
Architecture: Understanding the design principles and structure
Features: Complete list of features and capabilities
Configuration: Configuration management and options pattern
Authentication: Authentication mechanisms and setup
Resiliency & Chaos: Resilience patterns and chaos engineering
Testing: Testing strategies and best practices
Development Guide: Development workflow and guidelines
Use Cases: Real-world examples and scenarios

2. Customize Your Library¶

Add API Methods: Extend the service interface and implementation with additional API endpoints
Custom Authentication: Implement custom authentication handlers if needed
Resilience Policies: Add custom resilience policies in the Resilience/ folder
Metrics: Add custom metrics in the Metrics/ folder (if enabled)
Error Handling: Customize error handling and exception types

3. Configure CI/CD¶

The template includes a pre-configured azure-pipelines.yml file. To use it:

Push your code to Azure DevOps
Create a new pipeline from the YAML file
Configure pipeline variables (if needed)
Set up build definition number (if using badges)

For detailed pipeline information, see the Runbook documentation.

4. Add Documentation¶

Update the generated README.md with usage instructions specific to your API
Add XML documentation comments to your service methods
Generate API documentation using tools like DocFX or MkDocs

Uninstalling the Template¶

To uninstall the template, use the following command:

dotnet new uninstall ConnectSoft.ApiLibraryTemplate

Or if installed from a local package:

dotnet new uninstall ./ConnectSoft.ApiLibraryTemplate.1.0.0.nupkg

Getting Help¶

If you encounter issues or have questions:

Review the comprehensive documentation in the API Library Template section
Check the Overview for common use cases and examples
Review the Development Guide for troubleshooting tips
Consult the Runbook for CI/CD pipeline issues

Summary¶

You've successfully:

✅ Installed the ConnectSoft API Library Template
✅ Created a new API library project
✅ Configured the library with your API settings
✅ Registered and used the service in your application
✅ Built, tested, and packaged the library

The template provides a production-ready foundation for building robust, maintainable, and scalable API service agent libraries. Continue exploring the documentation to unlock the full potential of the template's features.