Understanding Hexagonal Architecture - A Guide to Ports and Adapters
Learn what Hexagonal Architecture is, why it's called Ports and Adapters, and how it protects your core logic from external chaos.
Read more →Notes on .NET, testing, and simpler code
Everything here comes from something I've built or broken. Mostly C# and .NET, mostly about testing, architecture, and cutting what you don't need.
Featured
All Posts
-
• 4 min read
How to use AGENTS.md to define AI Rules across any IDE
Learn how AGENTS.md gives your team one standard file to define AI coding rules that work in Cursor, VS Code, GitHub Copilot, and more.
-
• 2 min read
How to Use Cursor Rules to Plan and Execute Tasks
Learn how to create Cursor rules and workflows to plan, execute, and track tasks step by step for faster, predictable results.
-
• 5 min read
Year in review 2025
A year of steady work, tiny wins, and simplicity. First keynote at NDC Porto, two Dometrain courses, a half-marathon with Ankylosing Spondylitis, and the conviction that slower can be better.
-
• 3 min read
Assembly Fixtures - The Best New Feature in xUnit v3
Learn how xUnit v3 Assembly Fixtures replace Collection Fixtures, enabling parallel test execution while sharing setup logic across your test assembly.
-
• 4 min read
xUnit v3's CaptureConsole Will Save You Hours of Debugging Hell
Stop guessing why your integration tests fail. xUnit v3's CaptureConsole shows you console output in test results - but you'll need extra setup for logging frameworks.
-
• 5 min read
How to Control Culture in xUnit Tests (with v3 Support)
Prevent flaky tests caused by system culture differences. Learn 4 ways to set culture in xUnit tests, including assembly-wide config in xUnit v3.
-
• 3 min read
Stop Serving 2015 Images - Ship WebP & AVIF
Learn how switching from JPEG and PNG to modern WebP and AVIF formats can reduce image sizes by 30-50%, improve Core Web Vitals, and deliver faster page loads without sacrificing visual quality.
-
• 2 min read
A Small but Powerful Feature in xUnit v3 You’ll Use Everywhere
xUnit v3 game-changing feature - test-aware cancellation tokens for better async test management and automatic resource cleanup.
-
• 12 min read
Building a C# Repository with Selective Caching and MongoDB Search Index (And Why It's Not as Simple as It Looks)
Build C# Repository with selective caching and MongoDB search - complex patterns, cache invalidation, and performance optimization.
-
• 5 min read
Why Vertical Slice Architecture Makes Your Team Faster (and Happier)
Vertical Slice Architecture benefits - faster teams, reduced coupling, feature-focused development over layered approaches.
-
• 3 min read
How to Debug .NET Code in Cursor AI (Even on M1/M2 Macs)
Debug .NET code in Cursor AI on M1/M2 Macs - comprehensive setup guide using Samsung's open-source debugger alternative.
-
• 5 min read
Coupling and Cohesion in Software Engineering - A Practical Guide
Software engineering coupling and cohesion fundamentals - build maintainable code with low coupling and high cohesion principles.
-
• 2 min read
The 10 Best Architecture Diagramming Tools you need in 2025
Top 10 architecture diagramming tools 2025 - comprehensive comparison of Miro, Lucidchart, draw.io, and essential design platforms.
-
• 3 min read
Less guessing, more C# à la Rust
C# Result pattern inspired by Rust - implement explicit error handling, reduce guesswork, and improve function clarity and safety.
-
• 7 min read
Building Serverless APIs with AWS Lambda and DynamoDB in .NET
Build serverless .NET APIs with AWS Lambda and DynamoDB - infrastructure-free development, automatic scaling, and pay-as-you-go pricing.
-
• 3 min read
3 KafkaFlow Features Hard to Ignore
3 compelling KafkaFlow features - multi-threaded consumers, message ordering, and .NET dependency injection for Apache Kafka.
-
• 8 min read
A BETTER Way to Kafka Event-Driven Applications with C#
Build better C# Kafka event-driven applications with KafkaFlow - simplified patterns, middleware, and maintainable architecture.
-
• 6 min read
Refactoring C# Code with the Chain of Responsibility Design Pattern
Refactor C# code with Chain of Responsibility pattern - decouple business logic, segregate responsibilities, and improve maintainability.
-
• 5 min read
Discover an Easy Trick to Simplify Your C# Test Assertions!
Simplify C# test assertions with domain-specific extensions - create readable, expressive Fluent Assertions for complex objects.
-
• 4 min read
Data Transfer Objects (DTOs) - When to Use Them and When to Avoid
DTOs analysis - when to use Data Transfer Objects, benefits vs drawbacks, and the tradeoffs between boundaries and complexity.
-
• 5 min read
Moving from Controllers to .NET Minimal APIs
Migrate ASP.NET Controllers to Minimal APIs - refactoring guide with feature-driven organization and practical examples.
-
• 3 min read
.NET Integration Testing with Docker Compose
.NET integration testing with Docker Compose - reuse existing compose files, avoid duplicate infrastructure definitions, TestContainers alternative.
-
• 2 min read
My Simple Testing Stack (for .NET developers) [2023]
Comprehensive .NET testing stack 2023 - xUnit framework, Fluent Assertions, Moq mocking, FluentDocker containers, and K6 load testing.
-
• 5 min read
Why I Don't Use Loops on My Tests
Eliminate loops from test code - apply Zero, One, or Many testing principle for clearer, more maintainable unit test cases.
-
• 9 min read
3 TDD Techniques Most People Don’t Know
Master 3 TDD techniques most developers ignore - Fake It, Obvious Implementation, and Triangulation for effective test-driven development.
-
• 6 min read
Why I Always Avoid InternalsVisibleTo in .NET, Unless...
Avoid InternalsVisibleTo in .NET testing - explore alternatives, maintain proper encapsulation, and design better APIs.
-
• 2 min read
3 Types of Unit Tests (for C# Developers)
Learn 3 types of C# unit tests - Result-based, State-based, and Component Interaction testing patterns for maintainable test suites.
-
• 5 min read
3 Fluent Assertions Features You Should be Using
Master 3 Fluent Assertions features - assertion scopes for multiple checks, HttpResponseMessage testing, and advanced assertion techniques.
-
• 3 min read
How to Organize your .NET Dependency Injection Configuration
Organize .NET Dependency Injection by features - move beyond technical grouping to feature-based DI configuration patterns.
-
• 3 min read
How Structure Sensitive Tests Make Refactoring's Fail
Structure-sensitive tests break refactoring - mock implementation details, coupling issues, and behavior-focused testing strategies.
-
• 3 min read
The Biggest Folder Structure Mistake on .NET
Avoid the librarian folder structure mistake - organize .NET projects by features, not technical concerns, for better navigation.
-
• 4 min read
Building the Netflix Intro Animation in a .NET Console App
Recreate Netflix intro in .NET Console - Spectre.Console animations, SkiaSharp GIF processing, and terminal graphics programming.
-
• 2 min read
DateTimeOffset vs DateTime - What's the difference?
DateTimeOffset vs DateTime differences - Microsoft recommendations, timezone handling, and avoiding UTC conversion pitfalls.
-
• 4 min read
How the DRY Principle can damage your tests (C# Developers)
Why DRY principle damages C# test readability - avoid over-abstraction, maintain test clarity, and embrace necessary duplication.
-
• 5 min read
The missing Project that fixes everything in .NET
The missing Composition Root project in .NET - organize Clean Architecture dependencies and avoid coupling to frameworks.
-
• 6 min read
How to apply Hexagonal Architecture with .NET
Implement Hexagonal Architecture in .NET - project structure, dependency inversion, and practical Ports & Adapters examples.
-
• 3 min read
Hexagonal Architecture for .NET Developers (Beginners)
Hexagonal Architecture guide for .NET developers - Ports & Adapters pattern, testability, and swappable dependencies explained.
-
• 3 min read
5 things Microsoft needs to do to make Central Package Management widely used
5 improvements needed for .NET Central Package Management adoption - tooling enhancements, IDE support, and developer experience.
-
• 4 min read
C# 11 Required Members, the imperfectly awesome feature
C# 11 Required Members replace constructor brittleness - object initializers with mandatory fields and improved instantiation.
-
• 3 min read
C# 11 Auto Default Structs in depth
C# 11 Auto Default Structs eliminate field initialization requirements - improved maintainability and Class-Struct consistency.
-
• 3 min read
Finding .NET Transitive Dependencies and Tidying Up Your Project
Clean up .NET transitive dependencies with Snitch tool - identify unnecessary references, reduce package conflicts, and optimize projects.
-
• 3 min read
C# 11 UTF-8 String Literals - Ignore everything you have seen so far
C# 11 UTF-8 String Literals evolution - design changes, community feedback, and performance-readability balance in web scenarios.
-
• 4 min read
C# 11 Generic Attributes More Than Syntax Sugar
C# 11 Generic Attributes beyond syntax sugar - compile-time constraints, type safety, and framework quality-of-life improvements.
-
• 3 min read
A Gentle Introduction to C# 11 List Patterns
C# 11 List Patterns introduction - pattern matching with collections, array shapes, and F#-inspired syntax for elegant code.
-
• 5 min read
The Complete Guide to C# 11 Raw String Literals
Complete C# 11 Raw String Literals guide - escape-free JSON, SQL, XML strings with triple quotes and indentation handling.
-
• 3 min read
The Blind Spot of C# Records Immutability
C# Records immutability blind spot - mutable collections break immutability promises, understand reference vs value semantics.
-
• 2 min read
Quick Wins for .NET build pipelines
Optimize .NET build pipelines - CLI configuration options, Release mode, --no-restore, --no-build flags for faster CI/CD cycles.
-
• 3 min read
Providing a better experience for .NET developers with Caller Argument Expressions
Improve .NET developer experience with CallerArgumentExpression - better error messages, guard clauses, and API usability.
-
• 4 min read
Embedding dotnet format in your development cycle
Embed dotnet format in CI/CD pipelines - automate C# code formatting, enforce standards, and reduce code review friction.
-
• 3 min read
Looking into C# Property Patterns Performance
C# Property Patterns performance analysis - benchmark comparisons with traditional approaches and guard clause optimization tips.
-
• 3 min read
Taking control over xUnit test names
Customize xUnit test names with configuration files - DisplayName attributes, naming conventions, and test readability improvements.
-
• 3 min read
Expressive C# code with Property Patterns
Learn expressive c# code with property patterns techniques and best practices for C# development for software developers and engineers.
-
• 3 min read
C# 10 Global Usings - Best Practices for File Organization
Organize C# 10 Global Usings effectively - central placement strategies, project-level declarations, and tidier source code management.
-
• 2 min read
Uploading files with ASP.NET Minimal APIs
File uploads in ASP.NET Minimal APIs - migration from Controllers, IFormFile handling, and 415 Unsupported Media Type fixes.
-
• 2 min read
Azure Storage Integration Testing with Azurite
Azure Storage local testing with Azurite emulator - Docker container setup, integration tests, and offline development benefits.
-
• 4 min read
React components doing too much (and how to simplify them)
Simplify complex React components - recognize boolean prop warnings, component contracts, and Single Responsibility violations.
-
• 2 min read
Avoiding Booleans in React Components with a State Enum
Replace React boolean flags with state enums for cleaner component management - finite state machines, XState library, and better state control.
-
• 1 min read
Continuous Refactoring - Why Small Code Improvements Beat Big Rewrites
Make refactoring a continuous practice - TDD cycle integration, daily habits, and avoiding technical debt accumulation.
-
• 2 min read
Avoid GetAwaiter().GetResult() at all cost
Avoid GetAwaiter().GetResult() in C# at all costs - prevents deadlocks, thread pool starvation, and ensures proper async/await usage.
-
• 1 min read
When should a function return? Return Early
Embrace early return pattern - reduce cyclomatic complexity, improve readability, and eliminate nested conditions in functions.
-
• 3 min read
Eleventy - The Simplest Static Site Generator
Migrate to Eleventy static site generator - simplest 11ty setup, GitHub Pages hosting, markdown support, and Gatsby comparison.
-
Speaking • 5 min read
Speaking at a Virtual Conference
Virtual conference speaking guide - NDC Oslo 2020 experience, setup requirements, camera positioning, and online presentation tips.
-
Refactoring, Improvement • 1 min read
That flag argument is yelling at you
Avoid boolean flag arguments that violate Single Responsibility Principle - refactor into separate, focused methods for cleaner code.
-
• 1 min read
Don't comment what your code is doing, comment the Why
Write meaningful code comments - explain the 'why' not the 'what', avoid obvious statements, and improve code documentation.
-
Refactoring, Improvement • 1 min read
Manage your code as a successful restaurant
Avoid boolean flag arguments that violate Single Responsibility Principle - refactor into separate, focused methods for cleaner code.
-
• 1 min read
A simple way to build your JavaScript tests data
Build JavaScript test data simply with spread operator - elegant alternative to complex builder pattern for object creation.
-
• 1 min read
Don't declare your Variables at the top
Declare variables close to usage, not at the top - reduce cognitive load, improve readability, and signal function extraction.
-
.NET • 1 min read
windbg a .net core 3.1 app memory leak
Debug .NET Core memory leaks with WinDbg - setup SOS extension, analyze garbage collector handles, and find heap issues.
-
React • 2 min read
Optimizing React Render - 3 things that I wish to know before
Optimize React rendering performance - avoid object references, prevent unnecessary re-renders, and improve component efficiency.
-
Team, Improvement • 3 min read
One-on-ones - Using behavioural science to maximize the impact
Maximize one-on-one meeting impact with behavioral science - effective goal setting, achievement strategies, and team development.
-
Creativity, Improvement • 2 min read
Start thinking inside the box
Think inside the box for better creativity - how constraints like iPhone design limitations drive innovation more than limitless freedom.
-
Refactoring, Improvement, C#, .net • 2 min read
A simple tip to improve your code maintainability - Decompose IF statements into methods
Improve code maintainability by extracting complex IF statements into well-named methods - reduce cognitive load and enhance readability.
-
Remote Work, Improvement, Team • 2 min read
You should start working remotely once a week
Start remote work gradually - 5 reasons to work from home once weekly, productivity benefits, and convincing management strategies.
-
Improvement, Feedback • 3 min read
The secret to know Yourself
Discover self-awareness secrets - why voice recordings reveal truth about ourselves and how observation beats introspection.
-
Feedback • 4 min read
Leading Improvement through Honest Feedback
Build improvement culture through honest feedback - overcome restaurant politeness syndrome and lead teams with genuine, constructive criticism.
-
.net, .net Core, gRPC, Serilog • 4 min read
Logging gRPC requests using Serilog
Log gRPC requests with Serilog using interceptors - correlation IDs, response times, request tracking, and unary call monitoring.
-
Cake, .net, .net Core • 3 min read
Versioning .net Core applications using Cake
Version .NET Core applications with Cake Build - Directory.Build.props integration, automated versioning, and build strategies.
-
Docker • 4 min read
Exploring the Docker Container metaphor
Understand Docker containers through shipping metaphors - servers as ships, containers for isolation, and containerization benefits.
-
• 1 min read
JSON Patch Builder Online
JSON Patch Builder Online tool - create RFC6902-compliant patches for HTTP PATCH operations with visual JSON transformation.
-
ASP.NET Core • 3 min read
Implementing the HTTP Prefer Header with an ASP.NET Core Filter
Implement HTTP Prefer Header in ASP.NET Core - RFC-7240 compliance for return=representation and return=minimal preferences.
-
• 1 min read
Please don't name it "Utils"!
Stop naming classes 'Utils' - improve code readability, discoverability, and maintainability with meaningful class names like Logger.
-
Azure • 1 min read
Rebuilding SQL Database indexes using Azure Function
Automate SQL Database index maintenance with Azure Functions - rebuild fragmented indexes, reorganize thresholds, multi-database support.
-
Cake • 2 min read
5 reasons to convince your boss to adopt Cake (C# Make)
5 compelling reasons to convince your boss to adopt Cake Build - C# familiarity, living documentation, and automation benefits.
-
• 1 min read
Tuga IT - Build Automation? It's a piece of Cake
Tuga IT conference talk - Cake Build automation presentation with slides, demos, references, and practical build examples.
-
.NET • 1 min read
Adding Custom Arguments to Topshelf
Add custom command-line arguments to Topshelf Windows services using AddCommandLineDefinition with practical examples.
-
Cake • 1 min read
Create a Web Deployment Package with Cake Build
Create ASP.NET Web Deployment Packages with Cake Build - MSBuild integration, configuration settings, and packaging automation.
-
• 1 min read
NetPonto - Como construir software altamente eficiente com CQRS
NetPonto Portuguese talk - building efficient software with CQRS. Includes video, slides, and comprehensive CQRS references.
-
Azure • 2 min read
Azure WebJobs dependency injection with Unity
Implement dependency injection in Azure WebJobs using Unity container - IJobActivator interface, UnityJobActivator, and configuration setup.
-
.NET • 4 min read
The shining new C# Scripting API
C# Scripting API with Roslyn - runtime code evaluation, expression parsing, and scripting capabilities for .NET applications.
-
• 3 min read
Is CQRS too complicated? No!
CQRS simplified - Command Query Responsibility Segregation isn't complicated, just separate read and write models effectively.
-
• 3 min read
Use T4 as email template in 6 steps
Create email templates in .NET using T4 text templates - 6-step guide for HTML emails with dynamic content and formatting.
-
• 2 min read
Using Trello to manage your Wine Cellar
Organize your wine cellar with Trello - track bottles by location, manage inventory, and choose wines using stickers and boards.
-
NetPonto • 1 min read
7th Meeting of NetPonto Community in Oporto
NetPonto Community 7th meeting in Porto - SOLR in .NET search solutions and ECMAScript vNext talks at ISEP, free registration.
-
Windows Phone, Android • 5 min read
Are you sure that Android is better than Windows Phone?
Honest comparison - Android vs Windows Phone from a long-time WP user's perspective after switching for one month testing period.
-
Node.js • 2 min read
Reduce the path length of a Node.js project
Solve Windows path length limitations in Node.js projects - tips for npm dependencies, Visual Studio development, and Azure deployment.
-
NetPonto • 1 min read
6th Meeting of NetPonto Community in Oporto
NetPonto Community 6th meeting in Porto - ASP.NET VNext on Mac and Xamarin Forms talks at ISEP, free registration required.
-
Azure, Revista PROGRAMAR • 5 min read
Create an API in Azure App Service - Revista PROGRAMAR Nº 49
Azure App Service API Apps tutorial published in Portuguese Revista PROGRAMAR magazine - features, benefits, and implementation guide.
-
• 2 min read
Lessons learned from Agile Portugal 2015
Key lessons from Agile Portugal 2015 - visual management importance, user story writing, and building transparent team culture with physical boards.
-
Azure • 1 min read
Azure App Service API Apps - Microsoft Rest HttpOperationException
Troubleshoot Azure App Service API Apps Microsoft.Rest.HttpOperationException errors with debugging techniques and solutions.
-
AngularJS • 1 min read
AngularJS - After Render Directive
Create AngularJS after-render directive - execute code after template rendering completes using \ and custom attributes.
-
Azure • 2 min read
A developer's thoughts on Azure SQL Database performance levels
Azure SQL Database performance tiers analysis - comparing Web/Business models to new Basic/Standard/Premium pricing and performance.
-
AngularJS • 2 min read
AngularJS - Input number with 2 decimal places
Create AngularJS number inputs with 2 decimal validation - HTML5 step attribute, ng-pattern regex, and mobile keyboard support.
-
Node.js, .NET • 1 min read
How to Encrypt in Node.js and Decrypt in C#
Cross-platform encryption - encrypt data in Node.js with AES256 and decrypt in C# using RijndaelManaged for secure messaging.
-
Azure, Node.js • 1 min read
How to access Azure storage emulator using Node.js SDK
Connect to Azure Storage Emulator with Node.js SDK using generateDevelopmentStorageCredentials() for local development testing.
-
SQL • 1 min read
T-SQL: Which schema is consuming more space?
T-SQL query to identify which database schemas consume most space in multi-tenant architectures using sys.dm_db_partition_stats.
-
• 1 min read
5 awesome tools to craft the perfect Domain Name
Discover 5 tools for perfect domain names - WORDOID, Name Mesh, Panabee, Impossibility, and DomainsBot for finding available .com domains.
-
Node.js • 1 min read
Overcome the DEPTH_ZERO_SELF_SIGNED_CERT on Node.js
Resolve Node.js DEPTH_ZERO_SELF_SIGNED_CERT errors - handle self-signed certificates in development with NODE_TLS_REJECT_UNAUTHORIZED.
-
ASP.NET MVC • 1 min read
Disable your html cache
Control browser caching behavior in ASP.NET - disable HTML cache while enabling resource file caching through web.config settings.
-
Azure • 1 min read
Azure deploy and the path length limitation
Fix Windows path length limitation in Azure Cloud Service deployments by configuring ServiceOutputDirectory in .ccproj files.
-
Azure • 1 min read
Azure SQL Database: Automatic Backups
Configure automatic Azure SQL Database backups - set up scheduled exports to storage accounts without PowerShell scripts or custom code.
-
Productivity • 2 min read
How to implement Getting Things Done with Trello
Implement Getting Things Done (GTD) methodology with Trello - combine David Allen's productivity system with Kanban boards for workflow.
-
• 2 min read
Automate NuGet package creation using Grunt
Automate NuGet package creation with Grunt for metro-bootstrap - streamline builds, eliminate manual packaging, and integrate with CI/CD workflows.
-
metro-bootstrap • 1 min read
metro-bootstrap 3.2.0.1 released
Metro-bootstrap 3.2.0.1 release notes - Bootstrap 3.2.0 update, Bower main configuration, and new tile font size variables.
-
Windows Phone • 1 min read
Have fun with Cortana
Discover fun and useful Windows Phone Cortana voice commands - jokes, reminders, calendar, music, weather, and entertaining interactions.
-
Entrepreneurship • 2 min read
Your product needs an identity
Build products with strong identity using Seth Godin's philosophy. Learn why targeting everyone means targeting no one in product development.
-
Azure • 1 min read
Analyse Azure Log Tables using SQL Queries
Query Azure diagnostic logs with SQL using AzureLogSpelunker tool. Escape slow Azure Storage Explorer with fast, local SQLite analysis.
-
metro-bootstrap • 2 min read
metro-bootstrap with improved tiles
Metro-bootstrap 3.1.1.2 release - improved tiles with flexible positioning, new colors, dashboard template, and Bootstrap grid integration.
-
.NET, ASP.NET • 1 min read
Add documentation to your Web API in 5 steps
Auto-generate ASP.NET Web API documentation in 5 steps using HelpPage package. Create XML comments and interactive API docs effortlessly.
-
• 2 min read
Update GitHub Pages using a project subfolder
Automate GitHub Pages deployment using git subtree - push project subfolders to gh-pages branch without manual branch management.
-
metro-bootstrap • 2 min read
Bringing Grunt and Bower to metro-bootstrap
Add Grunt and Bower to metro-bootstrap open source project - automate builds, manage dependencies, and structure frontend workflows.
-
• 2 min read
Reasons to blogging with GitHub Pages and Sandra.Snow
Why choose GitHub Pages and Sandra.Snow over WordPress for .NET developers - markdown writing, no database, version control, and zero maintenance.
-
AngularJS • 2 min read
AngularJS - Smart Float Directive
Build an improved AngularJS smart-float directive for number validation with comma/dot decimal separators and thousands separators support.
-
Productivity • 2 min read
Pomodoro Technique, the productivity sauce
Master the Pomodoro Technique for developers - 25-minute focused work sessions with breaks to boost productivity and eliminate distractions.
-
.NET • 2 min read
The dark side of dynamic typing
Discover C# dynamic typing performance costs vs static typing with benchmarks. Learn when to avoid dynamic for better .NET application speed.
-
Azure • 1 min read
Move your database to new SQL Azure Service Tiers
Step-by-step guide to migrate SQL databases to new Azure Basic and Standard tiers with bacpac export/import and troubleshooting tips.
-
• 1 min read
Let's blog
Meet Portuguese .NET developer Guilherme Ferreira sharing software development lessons, entrepreneurship tips, and productivity insights from Porto.
Developer Insights
What I'm building, learning, and discovering each week.