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
• About Project
• Solution Structure
• About Design and Architecture
• About Management
• Engineering Manifest

Quick Start

Prerequisites

• .NET 10 SDK 10.0.403 or a later compatible SDK selected by global.json
• Docker with the daemon running (for the sample app and integration tests with Testcontainers)
• Node.js >=24.22.1 and npm for rebuilding frontend assets (see package.json). Built assets are checked in, so this is optional when simply running the sample. GitHub Actions pins Node.js 24.22.1 on Ubuntu 24.04 runners.

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 -c Debug              # Run the sample with local dependencies (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

The sample runs at http://localhost:5998.

In the sample, signed-in users who complete MFA can access /swagger, /Test/Htmx, and /Test/DeveloperView in Development. In Staging and Production, SystemAdmin grants both tools. Other users need a SwaggerAccess claim set to true for Swagger or a TestPagesAccess claim set to true for Test Pages. MFA is required in every environment. Navigation uses the same policies as the endpoints. Developer View is an explicit diagnostics preview. Ordinary Staging and Production errors remain redacted.

The sample provides anonymous, non-cacheable /BadRequest (400), /AccessDenied (403), /NotFound (404), and /SomethingWentWrong (500) pages. Staging and Production HTML server errors preserve their 5xx status and show only a request reference. HTML bad-request and not-found responses preserve 400 and 404. API failures for all 4xx and 5xx statuses use Problem Details JSON with a requestId in every environment. Sample and Nexus configure /Api to identify unmatched API routes without changing fallback authorization.

These pages share a lightweight, responsive layout with keyboard focus indicators, a skip link, and status-specific recovery guidance. Each displays a request reference for support. Cookie-authentication redirects to /AccessDenied preserve the denied request's reference for the next visit; direct visits use the page request's reference. They use Bootstrap classes and the existing Vite-built Bootstrap stylesheet, with no JavaScript required. Browser authentication still redirects to login for 401 responses.

For configuration and page requirements, see Hosting custom error pages.

See the Docker and Docker Compose guide for local container setup, credentials, data migration, and published image verification.

After changing frontend sources in Sample.Hosted/buildwww/, rebuild the assets from Sample.Hosted/:

npm ci --ignore-scripts
npm audit signatures
npm run build

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

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, follow the Testing NuGet README to configure the test runner, using the reference projects linked above.

Use appsettings.json and appsettings.Development.json as configuration references. Set Environment, NexusAppSettings:AppId, and NexusAppSettings:AppInstanceId explicitly. For local dependency launch, use Environment: Development and DrnDevelopmentSettings:LaunchExternalDependencies: true with the startup action below. See the Hosting NuGet README for configuration details.

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;
    }
}

To launch local PostgreSQL during development, add a DrnProgramActions class that calls builder.LaunchExternalDependenciesAsync from ApplicationBuilderCreatedAsync, as shown in SampleProgramActions.cs. The class is discovered automatically. Wrap the file in #if DEBUG and reference DRN.Framework.Testing only in Debug builds, following Sample.Hosted.csproj. Launching also requires the Development environment and LaunchExternalDependencies setting shown above.

Read the Hosting and Testing NuGet READMEs for configuration details and more examples.

Testing

Read the Testing NuGet README for unit and integration testing guidance, and see QAContextTests.cs for a database integration example.

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

For package downloads, signature verification, provenance, and SBOM attestations, see the published NuGet package verification guide.

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: Standalone dependency stacks and container configuration.
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: Local application stack for Sample.Hosted and its dependencies.

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