Getting Started¶

The ConnectSoft Microservice Template provides a production-ready foundation for building scalable, cloud-native microservices. This guide will help you get started with the template, understand its structure, and begin building your microservice.

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 (recommended)

Optional Tools¶

Docker Desktop: For local container development
Kubernetes: For local Kubernetes development (minikube, kind, or Docker Desktop)
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 Microservice 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.MicroserviceTemplate.1.0.0.nupkg

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

dotnet new install ConnectSoft.MicroserviceTemplate::1.0.0

Step 3: Verify Installation¶

Verify that the template is installed correctly:

dotnet new list connectsoft-microservice

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

Creating a New Microservice Project¶

Using the .NET CLI¶

Use the dotnet new command to generate a new microservice project:

dotnet new connectsoft-microservice \
  --name MyMicroservice \
  --microservice-name "MyMicroservice" \
  --use-nhibernate \
  --use-masstransit

Using Visual Studio¶

Open Visual Studio 2022
Select Create a new project
Search for ConnectSoft Microservice Template
Click Next
Configure your project:
Project name: Enter your microservice name
Location: Choose where to save the project
Click Next
Configure additional parameters (persistence, messaging, etc.)
Click Create

Understanding the Generated Structure¶

After creating your project, you'll have a complete solution structure. See Solution Structure for detailed information about:

Project organization by architectural layers
Dependency flow and rules
Project naming conventions
Folder organization

Key Projects¶

Application: Entry point and host configuration
DomainModel: Domain interfaces and contracts
DomainModel.Impl: Domain service implementations
PersistenceModel: Repository interfaces
ServiceModel: API DTOs and contracts
ServiceModel.RestApi: REST API controllers
ApplicationModel: DI registration and middleware

Next Steps¶

Review the Architecture: Understand the Architecture patterns and enforcement
Configure Your Service: Update appsettings.json with your configuration
Define Your Domain: Create entities, aggregates, and domain logic
Implement APIs: Add REST, gRPC, or GraphQL endpoints
Add Persistence: Configure NHibernate or MongoDB repositories
Set Up Observability: Configure logging, metrics, and tracing
Write Tests: Add unit tests, integration tests, and BDD tests

Configuration¶

Basic Configuration¶

Update appsettings.json with your service configuration:

{
  "Microservice": {
    "MicroserviceName": "MyMicroservice",
    "StartupWarmupSeconds": 30
  }
}

See Configuration for comprehensive configuration options.

Startup Warmup¶

The template includes startup warmup mechanisms for graceful initialization. See Startup and Warmup for details on:

StartupWarmupGate configuration
Health check integration
Kubernetes startup probe patterns

Running Your Microservice¶

Local Development¶

cd MyMicroservice.Application
dotnet run

The service will start on the configured ports (typically HTTP on 8080, HTTPS on 8081).

With Docker¶

docker-compose up

See Docker Compose for Docker configuration.

Exploring the Template¶

Architecture¶

Review the Architecture documentation to understand:
Architecture model and visualization
Automated architecture enforcement
Architecture testing patterns

Features¶

Check out the Features to see all available capabilities

Use Cases¶

Review Use Cases for common implementation patterns

Solution Structure: Understanding project organization
Architecture: Architecture patterns and enforcement
Features: Complete feature list
Startup and Warmup: Application initialization patterns
Clean Architecture: Clean Architecture principles
Domain-Driven Design: DDD patterns

Summary¶

The Microservice Template provides:

✅ Complete Solution Structure: Pre-organized projects following Clean Architecture
✅ Architecture Enforcement: Automated validation of architectural rules
✅ Multiple Technologies: Support for various persistence and messaging technologies
✅ Production-Ready: Health checks, observability, security built-in
✅ Comprehensive Testing: Unit, integration, BDD, and architecture tests
✅ Cloud-Native: Kubernetes, Docker, and cloud platform support

By following this guide, you'll have a fully functional microservice ready for development and deployment.