DRN-Project

TL;DR: You can

• use Nuget packages to easily develop and test distributed reliable dotnet applications.
• use Argo CD GitOps to easily deploy your apps to a kubernetes cluster with Linkerd service mesh.
• use Nexus App (not functional yet)
  • for service discovery
  • to get remote settings
  • to get unified microservices topology and their self-documentation
• get opinionated ideas about soft skills for engineering and management

Please contact me via LinkedIn for information on obtaining a more flexible commercial license

Table of Contents

• Quick Start
• Verify Published NuGet Packages
• Verify Published Container Images
• About Project
• Solution Structure
• About Design and Architecture
• About Management
• Engineering Manifest

Quick Start

Prerequisites

• .NET 10 SDK 10.0.401 or a later compatible SDK selected by global.json
• Docker (for integration tests with Testcontainers)

Nice to have: JetBrains Rider (recommended), Visual Studio, or VS Code with C# Dev Kit. All operations can also be performed from the terminal.

Build, Run & Test

dotnet build DRN.slnx                                  # Build the entire solution
dotnet run --project Sample.Hosted                      # Run the sample web application (requires Docker)
dotnet run --project DRN.Test.Unit                      # Run unit tests
dotnet run --project DRN.Test.Analyzer                  # Run analyzer tests
dotnet run --project DRN.Test.Integration               # Run integration tests (requires Docker)
dotnet run --project DRN.Test.Performance -c Release     # Run all performance benchmarks (requires Release build)
dotnet run --project DRN.Test.Performance -c Release -- --filter-method DRN.Test.Performance.Benchmark.Framework.Utils.SourceKnownIdUtilsPerformanceTests.Run_Benchmarks  # Run SKID/SKEID performance benchmark only
dotnet run --project DRN.Test.Performance -c Release -- --filter-method DRN.Test.Performance.Benchmark.Framework.Utils.SourceKnownIdUtilsSaturationPerformanceTests.Run_Benchmarks  # Run SKID/SKEID saturation benchmark only

All test projects (unit, analyzer, integration, and performance) use Microsoft Testing Platform (MTP) 2.x with xUnit v3 and are built as standalone executables. Use dotnet run --project to execute them.

Debugging tip: If the application fails to start in Development mode, DrnProgramBase attempts to generate a StartupExceptionReport.html in the output directory with a detailed, browsable error report.

Installation

For web applications (see Sample.Hosted.csproj):

dotnet add package DRN.Framework.Hosting

For test projects (see DRN.Test.Integration.csproj, DRN.Test.Unit.csproj):

dotnet add package DRN.Framework.Testing

Hosting pulls Utils and SharedKernel transitively. Testing pulls Hosting, EntityFramework, Utils, and SharedKernel transitively.

To create a new project from scratch:

dotnet new web -n MyApp && cd MyApp && dotnet add package DRN.Framework.Hosting
cd .. && dotnet new xunit -n MyApp.Tests && cd MyApp.Tests && dotnet add package DRN.Framework.Testing

After scaffolding, compare your .csproj files with the reference projects and apply the adjustments (see Sample.Hosted.csproj, DRN.Test.Integration.csproj, DRN.Test.Unit.csproj).

Update your configuration files (see appsettings.json, appsettings.Development.json):

appsettings.json — Kestrel excerpt to merge into the linked full DRN configuration:

{
  "Kestrel": {
    "EndpointDefaults": { "Protocols": "Http1" },
    "Endpoints": { "All": { "Url": "http://*:5998" } }
  }
}

appsettings.Development.json — development-only settings:

{
  "DrnDevelopmentSettings": {
    "LaunchExternalDependencies": true
  }
}

Use the Drn.Framework Nuget badges for detailed documentation such as configuration options, features, and examples.

For performance benchmarks, see DRN.Test.Performance and its benchmark reports.

Create an Application

Replace the generated MyApp/Program.cs with the following minimal example. See SampleProgram.cs for a full implementation.

using DRN.Framework.Hosting.DrnProgram;
using DRN.Framework.Utils.DependencyInjection;
using DRN.Framework.Utils.Logging;
using DRN.Framework.Utils.Settings;

public class Program : DrnProgramBase<Program>, IDrnProgram
{
    public static async Task Main(string[] args) => await RunAsync(args);

    protected override Task AddServicesAsync(WebApplicationBuilder builder,
        IAppSettings appSettings, IScopedLog scopedLog)
    {
        builder.Services.AddServicesWithAttributes();
        return Task.CompletedTask;
    }
}

Integration Tests

Integration tests use [DataInline] with DrnTestContext and Testcontainers for real database testing:

• QAContextTagTests.cs — Entity ID generation, type-safe entity type checking, date-time filtering
• QAContextTests.cs — CRUD operations, concurrency conflict detection, extended properties
• TagRepositoryTests.cs — Source-Known Repository pattern, pagination, filtering
• SourceKnownEntityIdUtilsTests.cs — SKID/SKEID stress test: ~786K concurrent IDs across 8 threads, uniqueness
• SourceKnownIdUtilsTests.cs — SKID stress test: ~786K concurrent IDs, sequence ordering, time-bucket distribution and cap validation

Entities use [EntityType] with AggregateRoot<TModel> — see Tag.cs for an example.

Unit Tests

Unit tests use [DataInlineUnit] with DrnTestContextUnit for fast, isolated testing without external dependencies:

• SourceKnownEntityIdUtilsTests.cs — SKID/SKEID generation, parsing, secure/plain conversion, tamper detection
• SourceKnownIdUtilsTests.cs — Source-Known ID bit layout, timestamp extraction, ordering

Developer Environment

Add the following to your shell profile (e.g. ~/.zshrc) to opt out of telemetry:

# Opt out of .NET CLI telemetry
export DOTNET_CLI_TELEMETRY_OPTOUT=1

# Opt out of .NET Testing Platform telemetry
export TESTINGPLATFORM_TELEMETRY_OPTOUT=1

Verify Published NuGet Packages

Published packages are available from two locations:

• For normal consumption, open the NuGet.org profile, select the package and version, then use Download package.
• For the exact pre-publish files, open the stable release or preview release workflow, select the matching release run, then download the packages entry under Artifacts. It contains the original .nupkg and .snupkg files plus the generated SBOM for the repository's configured artifact-retention period.

Replace RELEASE_VERSION in the example path, then verify an original workflow artifact's provenance and SPDX 2.2 SBOM attestation directly (for preview packages, replace release.yml with release-preview.yml):

gh attestation verify \
  artifacts/packages/DRN.Framework.Hosting.RELEASE_VERSION.nupkg \
  -R duranserkan/DRN-Project \
  --signer-workflow duranserkan/DRN-Project/.github/workflows/release.yml

gh attestation verify \
  artifacts/packages/DRN.Framework.Hosting.RELEASE_VERSION.nupkg \
  -R duranserkan/DRN-Project \
  --signer-workflow duranserkan/DRN-Project/.github/workflows/release.yml \
  --predicate-type https://spdx.dev/Document/v2.2

NuGet.org adds .signature.p7s, changing the package digest. Verify the repository signature first, then remove it from a copy before verifying GitHub provenance and SBOM attestations:

dotnet nuget verify DRN.Framework.Hosting.RELEASE_VERSION.nupkg --all

mkdir -p attestation
cp DRN.Framework.Hosting.RELEASE_VERSION.nupkg attestation/

zip -d attestation/DRN.Framework.Hosting.RELEASE_VERSION.nupkg .signature.p7s

gh attestation verify \
  attestation/DRN.Framework.Hosting.RELEASE_VERSION.nupkg \
  -R duranserkan/DRN-Project \
  --signer-workflow duranserkan/DRN-Project/.github/workflows/release.yml

gh attestation verify \
  attestation/DRN.Framework.Hosting.RELEASE_VERSION.nupkg \
  -R duranserkan/DRN-Project \
  --signer-workflow duranserkan/DRN-Project/.github/workflows/release.yml \
  --predicate-type https://spdx.dev/Document/v2.2

Repeat for each package. If verification fails, use the exact package from the workflow's packages artifact.

Verify Published Container Images

Stable and preview releases publish provenance for each multi-platform image index and a separate SPDX 2.3 SBOM attestation for each linux/amd64 and linux/arm64 manifest. Separate platform bindings prevent one architecture's inventory from representing another. Replace RELEASE_VERSION, inspect the image, then replace PLATFORM_MANIFEST_HEX_DIGEST with the hexadecimal part of the corresponding platform digest (for preview images, replace release.yml with release-preview.yml):

docker buildx imagetools inspect docker.io/duranserkan/drn-project-sample:RELEASE_VERSION

gh attestation verify \
  oci://index.docker.io/duranserkan/drn-project-sample:RELEASE_VERSION \
  -R duranserkan/DRN-Project \
  --signer-workflow duranserkan/DRN-Project/.github/workflows/release.yml

gh attestation verify \
  oci://index.docker.io/duranserkan/drn-project-sample@sha256:PLATFORM_MANIFEST_HEX_DIGEST \
  -R duranserkan/DRN-Project \
  --signer-workflow duranserkan/DRN-Project/.github/workflows/release.yml \
  --predicate-type https://spdx.dev/Document/v2.3

Replace drn-project-sample with drn-project-nexus to verify the Nexus image.

About Project

Distributed Reliable .Net project aims to provide somewhat opinionated design and out of the box solutions to enterprise application development. Expected result is spending less time on wiring while getting better maintainability and observability. The project benefits from the best practices, open source solutions and personal production experience. This project is about managing software complexity, architecting good solutions and a promise to deliver a good software.

In DRN-Project context, reliability is defined with following characteristics:

• Secure
• Observable
• Maintainable
• Performance optimized
• Efficient
• Scalable
• Self-documenting

DRN Project is not another framework that will bite the dust. It is more than a simple framework. It is a distilled knowledge that contains:

• A beautiful framework to work with
• Management best practices
• Engineering manifest
• Reference documents for design, architecture and microservices
• A nexus app to manage microservices (will be released with v1.0.0)

This project is result of a productive and curious mindset that respects good solutions and best practices of others while enjoys from creating its own. It is not about coding. It is about process of creating and enhancing good things.

Solution Structure

This solution consists of 6 parts that are being developed with Jetbrains Rider on macOS with arm-based M2 chip. However, I expect it to work on any modern machine since it is a cross-platform solution

1. Docker Folder: It contains Dockerfile and standalone compose definitions for dependencies. Docker/Infra/docker-compose.yml remains the combined infra compose for PostgreSQL, RabbitMQ, and Graylog.
2. Docs: It contains project documents. This docs will be supported with articles and a YouTube playlist.
3. Items: It contains file that does not belong anywhere else such as .gitignore, .dockerignore and .github workflows
4. Src: It contains 3 folders that define 3 different DRN domain.
   • Nexus: Nexus is intended to connect all services and apis developed with DRN.Framework. The one microservice to rule them all.
     • It is a unified web app that contains nexus api and background services.
     • It will have the following features as a start:
       • Configuration Management: Nexus can provide configurations to connected microservices
       • Migration Management: Nexus can manage microservice database migrations which includes schema management and sharding
       • Service Discovery: Nexus discloses microservice network
       • Observability, Documentation and Monitoring Hub: Nexus provides and visualizes workflow graph and information regarding them.
   • Framework: DRN.Framework source codes belongs to generalized solutions that can be used within compatible .NET 10 projects as nuget packages.
   • Sample: Nexus connectable sample app demonstrates DRN.Framework usage. It is used for testing, presentation and documentation purposes.
5. Test: It contains all the unit, integration and performance tests.
6. docker-compose: Root application compose for Sample.Hosted plus its local PostgreSQL, RabbitMQ, and Graylog dependencies. Use root .sample-env as the template for root .env.

About Design and Architecture

• Chris Patterson's Great Article - Software Architect for Life
• DDD Oriented Microservice
• Strategic Domain Driven Design
• Tactical Domain Driven Design
• DDD and Hexagonal Architecture

About Management

Security Management

• Security is always your most important requirement.
• Always be defensive and secure by default.
• Prefer whitelisting over blacklisting. Blacklists can be penetrated.

Task Management

• Always make a To-Do List.
• Prioritize tasks - use your insights or MoSCoW prioritization, etc.
• Warm up - start with one easy task, then focus on the hard one.
• Know your options 4D+E - do it, drop it, delegate it, defer it, or escalate.

4D comes from David Allen's 4D model. +E is my personal addition to it. Escalation is your friend. Inform others and ask their opinions whenever you are not sure what to do.

Time Management

• Small things add up then become big things. Do them while they are small and avoid stress.
• Don't micromanage; delegate whenever possible.
  • Delegation requires shared understanding. It is not a fire-and-forget process. Guide and track results when needed.
• Don't over-optimize. Good enough is better than excellent.

Quality Management

• Follow best practices and solutions. Don't reinvent the wheel
• Denormalize when needed. Understand how it works. Don't follow rules blindly.
  • You can accomplish things that considered not possible if you understand how things works.
  • Understand concepts and how they relate with each other.
• Prefer quality over quantity.
• Always test before deliver.
• Measure performance

Risk Management

• No risk no reward
• Take managed risk and risk what you are willing to lose
• Sandbox risks and threats
• Improve your odds
• Make reasonable assumptions

Personal Management

• Be kind and focus on good thoughts
• Be persistent and pay attention to details
• Be good to yourself
• Don't compromise your integrity
• You can only expand yourself as your environment allows. Don't hesitate to change it when necessary
• You are not a tree. You can always walk away. Don't stay in hostile or harmful environment.
• "Never attribute to malice that which is adequately explained by stupidity." - Hanson's razor

Duran's Engineering Manifest

Today, I hereby declare that as an engineer,

• I am passionate about designing, developing, delivering high quality and cost-effective software.
• I acquire new skills with continuous learning.
• I am involved in every stage of the Software Development Life Cycle from planning to implementation.
• I am a conceptual thinker.
• I do not hesitate to take initiative.
• I support all standardization activities that make my work easier and understandable.
• I force myself to improve myself and those around me.
• I won't be trapped in habits and comfort zone.
• I pay attention to details and deal with problems with a holistic approach.
• I care about quality in my work.
• I do my best not to leave technical debt. If I have to leave technical debt, I will remove the technical debt as soon as possible.
• I manage time and stress under pressure, and I am not afraid to compromise and ask for help.
• I will always keep communication channels open.
• I will always give constructive and positive feedback whenever possible and appropriate.
• I will always be open to constructive and positive feedback.
• I will always be conscientious, transparent and will live by values and goals.

Celebrating Republic of Türkiye and Mustafa Kemal Atatürk's Enlightenment Ideals

In honor of the Republic of Türkiye's centenary, my family celebrates the enduring legacy of Mustafa Kemal Atatürk's enlightenment ideals. While these ideals have illuminated Türkiye's path for a century, we recognize that the journey towards their full realization continues. This dedication is a reminder of the profound impact of Atatürk's vision and a call to continue striving for the ideals of enlightenment, progress, and unity that have guided Türkiye's remarkable journey.

Since 1923 To Forever ∞ Semper Progressivus: Always Progressive