This article is about that missing discipline. More specifically, it is about the spec-driven development process: how to turn a vague feature request into a clear specification, a reviewed plan, and a sequence of small, testable steps that keep the developer in control. The goal is not to slow AI down. It is to give that speed structure, so that what gets built still reflects deliberate design rather than improvised output.

If Part 1 was about principles and tooling, this article is about workflow. We will look at how specifications, plans, and Red-Green-Refactor with human gates fit together into a practical process you can actually use on a real project.

The Problem: Vibe Coding Feels Fast Until It Doesn't

Most teams experimenting with AI coding assistants fall into the same trap.

Someone types:

"Add a subscriptions feature to the app."

The model starts working. Entities appear. Repositories show up. Controllers and DTOs materialize. A page gets scaffolded. Twenty minutes later there are fifteen new files across half the solution, and at first glance it all looks plausible.

That is exactly the danger.

The code often looks coherent long before it actually is. The entity does not match the database schema. The DTO exposes fields the UI never uses and misses fields it needs. The controller returns a shape the client does not expect. Naming drifts away from the rest of the codebase. Tests are missing or meaningless. And the developer, who is still accountable for the result, can no longer explain why the design looks the way it does.

That is what I mean by vibe coding: using AI in a way that creates the feeling of momentum while steadily eroding control.

The alternative is spec-driven development. Instead of asking the AI to improvise, you give it a clear contract, a reviewed plan, and a tight execution loop. The model still writes code, but it does so inside a process the developer controls.

The Three Pillars

In practice, spec-driven development with AI rests on three pillars:

1. Specifications — define what should be built before code exists.
2. Plans — break the work into small vertical slices before implementation starts.
3. Red-Green-Refactor with human gates — implement one verified step at a time.

Each pillar solves a different failure mode.

• Specs stop the AI from guessing.
• Plans stop the AI from wandering across the architecture.
• Red-Green-Refactor with gates stops mistakes from compounding across multiple steps.

Once these three are in place, the AI becomes much more useful. It stops behaving like an overeager intern and starts behaving like a disciplined teammate.

Pillar 1: Specifications — The Contract Between the Developer and the Model

Why Specs Matter

Without a spec, the AI is forced to infer intent from a vague prompt.

"Add subscriptions" sounds simple, but it leaves too many decisions open:

• What properties does a subscription have?
• Who is allowed to create one?
• Which validation rules apply?
• Which endpoints are required?
• What happens when there are no subscriptions?
• What is intentionally out of scope?

The model will happily answer all of those questions for you. The problem is that it answers them by guessing.

A good specification removes that guesswork. It captures the things the AI should not invent for itself:

• Who the feature is for
• What the user can do
• Acceptance criteria for done
• Data model and constraints
• API surface
• Business rules and expected error messages
• Edge cases
• Out-of-scope items

Once this exists, the developer and the AI are working from the same contract.

A Concrete Spec Example

Here is a realistic spec for a "Patient Subscriptions" feature:

# Spec: Patient Subscriptions

## User Story

**As a** patient,
**I want to** view my active medication subscriptions,
**So that** I can track which medications are being dispensed on my behalf.

---

## Acceptance Criteria

| # | Given | When | Then |
|---|-------|------|------|
| AC-1 | Patient is authenticated | They navigate to /subscriptions | A list of active subscriptions is displayed |
| AC-2 | Patient has no subscriptions | They navigate to /subscriptions | An empty-state message is shown |
| AC-3 | A subscription has expired | The list is loaded | Expired subscriptions are not shown |
| AC-4 | Doctor creates a valid subscription | They submit the form | The subscription appears in the patient's list |
| AC-5 | Doctor submits invalid data | They click Save | Validation errors are shown and nothing is persisted |

---

## Data Model

### Entity: `Subscription`

| Property | Type | Required | Constraints |
|----------|------|----------|-------------|
| Id | int | PK | Auto-generated |
| PatientId | int | Yes | FK -> Patient |
| MedicationName | string | Yes | Max 200 chars |
| StartDate | DateOnly | Yes | Must be today or later |
| EndDate | DateOnly | No | Must be after StartDate |
| CreatedBy | string | Yes | Doctor's national register ID |

---

## API Endpoints

### `GET /api/subscriptions?patientId={id}`
**Purpose**: Return active subscriptions for a patient.
**Auth**: Bearer (patient or doctor role)
**Response** (200):
```json
[
  {
    "id": 1,
    "medicationName": "Metformin 500mg",
    "startDate": "2026-04-01",
    "endDate": "2026-10-01"
  }
]
```
**Error responses**: 401 -> Unauthorized, 403 -> Wrong patient

### `POST /api/subscriptions`
**Purpose**: Create a new subscription.
**Auth**: Bearer (doctor role only)
**Request body**:
```json
{
  "patientId": 42,
  "medicationName": "Metformin 500mg",
  "startDate": "2026-04-01",
  "endDate": "2026-10-01"
}
```
**Response** (201): Created subscription
**Error responses**: 400 -> Validation errors, 401, 403

---

## Business Rules

| # | Rule | Error message |
|---|------|---------------|
| BR-1 | MedicationName is required | "Medication name is required" |
| BR-2 | StartDate must be today or later | "Start date cannot be in the past" |
| BR-3 | EndDate, if provided, must be after StartDate | "End date must be after start date" |
| BR-4 | Only doctors can create subscriptions | HTTP 403 |

---

## Out of Scope

- Editing or deleting subscriptions
- Medication lookup or auto-complete
- Notifications when a subscription is created
- Prescription history

This is not documentation for documentation's sake. It is the minimum structure needed to stop the AI from improvising on critical details.

What the Spec Actually Buys You

The value of a spec is not abstract. It shows up immediately in review.

If the AI writes validation logic using >= instead of >, you can point directly to BR-3. If it adds edit and delete endpoints, you can point to the out-of-scope section. If it makes EndDate required, you can point to the data model.

That changes the developer's role. Instead of arguing with code, you are validating implementation against an agreed contract.

Writing the Spec with AI

This is one of the most useful ways to use AI early in the process.

You do not need to sit down and write the whole spec from a blank page. A better approach is an interview-style prompt that asks focused questions and assembles the answers into a structured _specs/<FeatureName>.md file.

That is why this repo now includes a dedicated write-spec prompt. The workflow is simple:

1. The developer brings the feature idea.
2. The AI runs a short Q&A session.
3. The AI drafts the user story, acceptance criteria, data model, API surface, business rules, edge cases, and out-of-scope section.
4. The developer reviews and adjusts the spec.
5. Only then does planning begin.

This matters because the interview happens at the right level. You are discussing intent, not classes and folders. That keeps the conversation grounded in product and business behaviour before implementation details take over.

When to Write Specs

Not every change needs a specification.

• Spec required: new feature, new user-facing behaviour, new API surface
• Spec optional: larger refactor, infrastructure change, architecture decision
• No spec needed: bugfix, config correction, 1-2 file change

In this workflow, specs live at _specs/<FeatureName>.md in the repository root.

Pillar 2: Plans — Turning Intent into an Execution Strategy

From Spec to Plan

The spec defines what should exist. The plan defines how the work will be delivered.

That distinction matters.

The spec says, "patients can view subscriptions" and "doctors can create subscriptions." The plan says, "first build the list page with a stubbed service, then wire it to the real API, then build the create form, then wire the create flow." The plan translates intent into an ordered set of implementation steps.

A plan lives at _plans/<FeatureName>.md. Each step is one Red-Green-Refactor cycle with explicit scope, tests, proof criteria, and a human gate.

The Planning Gate

Before any code is written, the plan must be reviewed and approved.

This is the hard stop between thinking and doing.

The AI should ask a simple question:

Does this change need a plan?

If the answer is yes, the AI writes the plan and stops. No production code starts until the developer approves it.

That single rule prevents a remarkable amount of wasted work.

Vertical Slices, Not Horizontal Layers

This is the planning principle that matters most.

The natural instinct, for both humans and models, is to decompose work by layer:

Step 1 — Create the Subscription entity
Step 2 — Add SubscriptionRepository
Step 3 — Create SubscriptionCreateHandler
Step 4 — Add GET endpoint
Step 5 — Add POST endpoint
Step 6 — Build the subscriptions list page
Step 7 — Build the create form

It looks organized. In reality, it delays feedback and pushes integration risk to the end.

By the time you reach the UI, you may discover that the entity shape is wrong, the DTO is incomplete, the query returns the wrong projection, or the route contract does not match the client. Now several "completed" steps have to be reopened.

Vertical slicing avoids that by planning around user-visible behaviour instead of technical layers:

Step 1 — Display subscription list (stubbed)
Step 2 — Wire subscription list to real API
Step 3 — Create subscription form (stubbed)
Step 4 — Wire subscription create to real API

Each slice has two phases:

1. Stub — build the UI against a fake or mocked service so the user can validate the experience early.
2. Wire — replace the stub with real production code from controller to persistence and database.

This gives you three practical advantages:

• You fail fast. Contract mismatches show up on Step 2 instead of Step 7.
• You get UI feedback early. The user can review the shape of the feature before backend code sprawls.
• You reduce blast radius. If something changes, one slice moves, not the whole architecture.

A Concrete Plan Example

Here is a more realistic plan for the subscriptions feature:

# Plan: Patient Subscriptions — Patient views active medication subscriptions

## Overview
Patients can view their active medication subscriptions. Doctors can create new
subscriptions. Reference feature: **Doctors**.

---

## Step 1 — Display subscription list (stubbed)

**Scope** *(Presentation only — stub phase)*:
- `src/Presentation/Subscriptions/ViewModels/SubscriptionsViewModel.cs` *(create)*
- `src/Presentation/Subscriptions/ServiceClients/ISubscriptionServiceClient.cs` *(create)*
- `src/Presentation/Subscriptions/ServiceClients/SubscriptionServiceClientStub.cs` *(create)*
- `src/Presentation/Subscriptions/Pages/Subscriptions.razor` *(create)*
- `src/Contracts/Subscriptions/Api/SubscriptionDto.cs` *(create)*
- `src/Test/Unit/Presentation/Subscriptions/SubscriptionsViewModelTests.cs` *(create)*

**RED**:
- Test: `InitializeAsync_WithSubscriptions_LoadsList`
- Command: `{{TestExePath}} --filter "SubscriptionsViewModelTests"`

**GREEN**:
- `SubscriptionDto` with Id, MedicationName, StartDate, EndDate
- `ISubscriptionServiceClient` with `GetByPatientAsync(int patientId)`
- Stub service returning three fake subscriptions
- `SubscriptionsViewModel` with `IsBusy` guard and `InitializeAsync`
- `Subscriptions.razor` bound to `ViewModel.Items`

**DB changes**: none

**🛑 HUMAN GATE**:
- [ ] Behavioral: ViewModel test passes and the page renders three stubbed items
- [ ] Review: Page layout matches the reference feature pattern

---

## Step 2 — Wire subscription list to real API

**Scope** *(all backend layers — wire phase)*:
- `src/Core/Domain/Functionalities/Subscriptions/Subscription.cs` *(create)*
- `src/Core/Persistence/EntityTypeConfigurations/SubscriptionConfiguration.cs` *(create)*
- `src/Core/Persistence/Repositories/SubscriptionRepository.cs` *(create)*
- `src/Core/Application/Functionalities/Subscriptions/Queries/GetSubscriptions/` *(create)*
- `src/Host/Client/Controllers/SubscriptionController.cs` *(create — GET only)*
- `src/Database/Scripts/0001_CreateSubscriptionTable.sql` *(create)*
- `src/Presentation/Subscriptions/ServiceClients/SubscriptionServiceClient.cs` *(create — real Refit-backed service client)*
- `src/Presentation/Shared/ServiceClients/Bff/Clients/ISubscriptionClient.cs` *(create)*
- `src/Test/Unit/Application/Subscriptions/GetSubscriptionsQueryTests.cs` *(create)*
- `src/Test/Integration/Endpoints/Subscriptions/GetSubscriptionsTest.cs` *(create)*

**RED**:
- Unit: `Execute_WithActiveSubscriptions_ReturnsList`
- Integration: `GetSubscriptions_Authenticated_ReturnsOk`
- Integration: `GetSubscriptions_WrongPatient_ReturnsForbidden`

**GREEN**:
- `Subscription` entity and repository
- `IGetSubscriptionsQuery` and `GetSubscriptionsQuery`
- `SubscriptionController` GET `/api/subscriptions?patientId={id}`
- Refit client + real service client replacing the stub
- EF configuration + DbUp script

**DB changes**: `src/Database/Scripts/0001_CreateSubscriptionTable.sql`

**🛑 HUMAN GATE**:
- [ ] Behavioral: Integration tests pass and GET `/api/subscriptions` returns the expected list
- [ ] Review: Entity, query, repository, and controller follow the reference pattern

---

## Step 3 — Create subscription form (stubbed)

**Scope** *(Presentation only — stub phase)*:
- `src/Presentation/Subscriptions/ViewModels/AddSubscriptionViewModel.cs` *(create)*
- `src/Presentation/Subscriptions/Pages/AddSubscription.razor` *(create)*
- `src/Contracts/Subscriptions/Api/AddSubscriptionDto.cs` *(create)*
- `src/Test/Unit/Presentation/Subscriptions/AddSubscriptionViewModelTests.cs` *(create)*

**RED**:
- Test: `Submit_EmptyMedicationName_ShowsValidationError`
- Test: `Submit_ValidData_CallsService`

**GREEN**:
- `AddSubscriptionDto`
- `AddSubscriptionViewModel` with BR-1 through BR-3 validation
- Stub submission flow
- `AddSubscription.razor` with validated fields

**DB changes**: none

**🛑 HUMAN GATE**:
- [ ] Behavioral: Validation errors render correctly and valid submission calls the stub service
- [ ] Review: Form matches the business rules in the spec

---

## Step 4 — Wire subscription create to real API

**Scope** *(all backend layers — wire phase)*:
- `src/Core/Application/Functionalities/Subscriptions/Commands/AddSubscription/` *(create)*
- `src/Host/Client/Controllers/SubscriptionController.cs` *(modify — add POST)*
- `src/Presentation/Subscriptions/ServiceClients/SubscriptionServiceClient.cs` *(modify — add AddAsync)*
- `src/Test/Unit/Application/Subscriptions/AddSubscriptionHandlerTests.cs` *(create)*
- `src/Test/Integration/Endpoints/Subscriptions/PostSubscriptionTest.cs` *(create)*

**RED**:
- Unit: `Execute_ValidCommand_ReturnsSuccess`
- Unit: `Execute_PastStartDate_ReturnsFailure`
- Integration: `PostSubscription_ValidData_ReturnsCreated`
- Integration: `PostSubscription_MissingFields_ReturnsBadRequest`

**GREEN**:
- `AddSubscriptionCommand` and `AddSubscriptionCommandHandler`
- POST `/api/subscriptions`
- Real `AddAsync` implementation in the service client

**DB changes**: none

**🛑 HUMAN GATE**:
- [ ] Behavioral: Integration tests pass; valid POST creates a record; invalid POST returns 400
- [ ] Review: Authorization and business rules are enforced correctly

The important thing here is not the exact class names. It is the shape of the plan:

• step names describe behaviour
• each slice is completed before the next starts
• the stub phase is intentionally narrow
• the wire phase crosses layers on purpose
• every step has explicit proof and review criteria

The Interview Before the Plan

Good planning starts with the right questions.

Before an AI writes a plan, it should confirm that it has enough information to do so safely:

1. Which existing feature is the reference pattern?
2. What entities and properties are involved?
3. Is there a database change?
4. Are there relationships to existing entities?
5. Which endpoints are needed?
6. Which UI pages or routes are needed?
7. Are there auth or claims requirements?

If any of that is missing, the AI should ask now, not halfway through implementation.

Pillar 3: Red-Green-Refactor with Human Gates

The Core Loop

Every plan step should run through the same execution loop:

READ      — Read the plan step and understand the scope.
RED       — Write the failing test first. Run it. Confirm it fails.
GREEN     — Write the minimum production code needed to pass.
REFACTOR  — Clean up without changing behaviour.
ANALYSE   — Run static analysis and fix issues.
PROVE     — Build, test, and format checks all pass.
🛑 STOP   — Present results and wait for human approval.
MARK DONE — After approval, update the plan checkboxes.

Three rules are non-negotiable:

1. Never skip RED. The test must fail before production code exists.
2. Never batch steps. One step, one proof cycle, one review.
3. Never skip the human gate. Approval is part of the workflow, not an optional extra.

Why RED Must Come First

The most common AI mistake is writing the test and the production code at the same time.

It feels efficient, but it breaks the feedback loop.

If the test was never observed failing, you do not know whether it would have caught a real defect. The assertion may be wrong. The mock setup may be too permissive. The test may accidentally validate nothing.

When the test fails first and then passes after the code change, the relationship is clear. The test is meaningful, and the production code is the reason it now passes.

That matters even more with AI-generated tests, because they often look correct while hiding subtle mistakes.

RED-First in Practice

Take Step 2 from the subscriptions example: return active subscriptions for a patient.

The AI starts by writing the failing unit test:

[TestClass]
public class GetSubscriptionsQueryTests
{
    [TestMethod]
    public async Task Execute_WithActiveSubscriptions_ReturnsList()
    {
        // Arrange
        var mockRepo = new Mock<ISubscriptionRepository>();
        mockRepo.Setup(r => r.GetActiveByPatientAsync(42))
            .ReturnsAsync(new List<Subscription>
            {
                new()
                {
                    Id = 1,
                    PatientId = 42,
                    MedicationName = "Metformin 500mg",
                    StartDate = new DateOnly(2026, 4, 1),
                    EndDate = new DateOnly(2026, 10, 1),
                },
            });

        var query = new GetSubscriptionsQuery(mockRepo.Object);

        // Act
        var result = await query.Execute(42);

        // Assert
        Assert.AreEqual(1, result.Count);
        Assert.AreEqual("Metformin 500mg", result[0].MedicationName);
    }
}

At this point the test fails, because GetSubscriptionsQuery does not exist yet. Good. That is exactly what should happen.

Only then does the AI create the minimal production code: the repository contract, the query implementation, the mapping, and the endpoint path needed for the full slice. When the test turns green, you know it turned green for a reason.

The Human Gate

After the proof step, the AI stops and presents results.

For example:

Step 2 — Wire subscription list to real API

Build:   0 warnings, 0 errors
Tests:   24 passed, 0 failed
Format:  no changes required

🛑 HUMAN GATE:
- [ ] Integration test GetSubscriptions_Authenticated_ReturnsOk passes
- [ ] Query, repository, controller, and DTO follow the reference feature pattern

This is where the developer checks the behaviour and the design:

• Does the implementation satisfy the spec?
• Do the tests cover the acceptance criteria?
• Do the file locations and naming match the codebase?
• Are risk areas handled correctly?

Only after approval does the next step begin.

That gate is what prevents AI errors from cascading into later steps.

Bugfixes: Regression Test First

The same principle applies to bugfixes, just with a smaller workflow:

1. Investigate the root cause.
2. Write a regression test that reproduces the bug.
3. Confirm it fails.
4. Make the smallest fix.
5. Confirm the test passes.
6. Run the standard proof commands.

This keeps bugfixes honest. The AI does not get to poke at code until symptoms disappear. It has to prove it understands the failure first.

Progress Tracking Across Sessions

One of the hardest things about AI-assisted development is that sessions are ephemeral. Context disappears when the conversation ends.

Plan files solve that with a very simple convention: checkboxes on the human gate.

## Step 1 — Display subscription list (stubbed)
...
**🛑 HUMAN GATE**:
- [x] Behavioral: ViewModel test passes and the list renders with stubbed data
- [x] Review: Layout matches the reference feature

## Step 2 — Wire subscription list to real API
...
**🛑 HUMAN GATE**:
- [ ] Behavioral: Integration tests pass and GET /api/subscriptions returns data
- [ ] Review: Query, repository, and controller follow existing patterns

When a new session starts, the AI reads the plan and finds the first unchecked box. That is the next step.

No guesswork. No repeated work. No fragile reliance on chat history.

Encoding the Process into AI Instructions

What makes this approach practical is that the workflow is not just a team convention. It is encoded into the repo's instructions, agents, prompts, and skills.

That gives the model structure before the conversation even begins.

AGENTS.md — The Workflow Backbone

This file defines the planning gate, the mandatory workflow rules, the vertical-slice strategy, and the stop points.

It is the reason the AI knows that planning comes before coding and that one step must finish before the next begins.

planner.agent.md — The Planning Specialist

This agent is deliberately constrained. It can read the codebase and produce _plans/<FeatureName>.md, but it cannot write production code.

That separation matters. Planning is a different task from implementation, and mixing the two is where many AI workflows lose discipline.

copilot-instructions.md — Project Rules and Boundaries

This file tells the AI what kind of system it is working in: project structure, naming rules, dependency boundaries, verification commands, and critical architectural constraints.

It answers questions the AI should not answer by improvisation.

write-spec.prompt.md — AI-Assisted Specification Writing

This prompt fills an important gap in the process.

Before planning, it interviews the developer section by section and produces _specs/<FeatureName>.md from the spec template. It turns a vague idea into something concrete enough to plan safely.

build-feature/SKILL.md — The Execution Engine

This skill tells the AI how to execute an approved plan step using the right layer patterns and proof loop. It does not replace judgement, but it gives the model reliable rails.

Supporting Project-Level Folders

The wider workflow also benefits from a small set of project-level folders with clear intent:

• _specs/ for feature specifications
• _plans/ for approved implementation plans
• _decisions/ for ADRs and architectural choices
• _qa/ for smoke-test plans and QA artifacts
• _infrastructure/ for infrastructure specs and environment records

None of these are complicated. Their value comes from being explicit, predictable, and easy for both humans and AI to discover.

Putting It All Together

At a high level, the workflow looks like this:

Idea -> Spec -> Plan -> Step 1 -> Review -> Step 2 -> Review -> Step 3 -> Review -> Step 4 -> Review

More concretely:

1. A developer identifies a feature.
2. The AI helps write the spec through a focused Q&A session.
3. The planner reads the spec and the codebase, then proposes a vertical-slice plan.
4. The developer approves the plan.
5. The AI implements one step at a time using Red-Green-Refactor.
6. After each step, the AI proves the result and stops for review.
7. The plan file tracks progress across sessions.

This keeps the developer in control of design while still capturing the speed benefits of AI-assisted implementation.

Summary

The shift from vibe coding to spec-driven development is not about producing more documents. It is about preserving control.

The spec makes intent explicit. The plan makes execution deliberate. Red-Green-Refactor makes each change verifiable. Human gates keep the developer accountable.

AI is most useful when it accelerates a process you already trust. Without that process, speed just multiplies ambiguity.

With it, you get the best of both worlds: faster delivery and stronger control.

The practices described in this article are encoded in the open-source github-copilot-configs repository — a reusable template library of GitHub Copilot and Claude Code configuration files for .NET projects.

Previous: Part 1 — Best Practices for AI-Assisted Coding

An open-source library of GitHub Copilot and Claude Code configuration files that encode a disciplined, repeatable engineering process into AI agents, skills, and instructions.

Repository: Part 1 of 2. This article covers the motivation, best practices, and the configuration library. For a hands-on walkthrough of the spec-driven process, see Part 2: The Process in Action.

Over the past year I've spent hundreds of hours working with AI coding agents — GitHub Copilot, Claude Code, and various MCP tool integrations. I learned a lot, made plenty of mistakes, and eventually landed on a workflow that works reliably.

The problem was: every time I started a new project, I was rebuilding the same configuration from scratch. The same planning discipline. The same Red-Green-Refactor loop. The same human gates. The same layer-specific coding conventions. Each project had slight variations, and none of them captured everything I'd learned.

So I built github-copilot-configs — a reusable template library of AI agent configuration files that I copy into every new .NET project. It encodes the engineering process I've developed over my career — now translated into agents, skills, and instruction files that AI assistants follow automatically.

The goal is twofold:

1. Quick project setup — Copy the files, run the /init skill, and every AI assistant in the project immediately knows the architecture, conventions, test commands, and development workflow. No more explaining the same things in every chat session.
2. Consistent engineering process — The agents enforce plan-first development, test-first implementation, vertical slicing, and mandatory human review gates. This isn't just guidance — it's a process that prevents the most common AI coding failures I've encountered.

This article shares what I've learned and how the configuration library works. Whether you adopt it wholesale or just borrow ideas, I hope it saves you some of the trial and error I went through.

AI coding assistants like GitHub Copilot are changing how developers write software. But without clear practices, teams drift into what I call vibe coding — letting the AI generate code with no plan, no verification, and no accountability. The result? Code nobody fully understands.

Before diving into workflows, every developer should understand three foundational concepts:

The Model — The LLM behind Copilot. Different models have different strengths, costs, and context windows. Choosing the right model for the task is a deliberate decision, not an afterthought.

The Context — Everything the model sees when generating a response: your open files, instructions, conversation history, and workspace structure. Context quality directly determines output quality.

The Agent — The orchestration layer that can inspect files, reason about tasks, propose plans, make changes, run checks, launch commands, and iterate through workflows. Agents interact with tools including MCP servers, making them far more capable than simple chat completions.

Tokens — the unit of model consumption — are finite on any plan. Practical consequences:

• Use short, focused sessions
• Keep prompts specific and bounded
• Choose the right model for the task
• Avoid unnecessary retries in polluted sessions
• Use lighter models for simple work
• Reserve premium models for harder problems

Not every task needs the most powerful model. Here's how I think about model selection:

The rule: use Haiku or Flash for quick simple work, Sonnet as the daily default, and Opus only when the problem genuinely demands it. Don't burn premium tokens on formatting a JSON file.

The main danger of AI-assisted coding isn't wrong code — it's no longer knowing what the AI changed, why it changed it, or whether it still matches the design.

The antidote is spec-driven development: start with a specification, produce a plan, implement in small verified steps, and stay in control throughout. That's what this configuration library encodes.

A good AI coding session has one task, one goal, a small scope, only relevant files, and clear validation criteria. A bad session involves multiple unrelated tasks, too much history, broad exploration, repeated retries, and unclear ownership.

Rule: if the topic changes, start a new session. Session pollution — accumulated irrelevant context — is one of the most common causes of degraded AI output.

Verification is the single biggest improvement you can make in AI-assisted coding.

What counts as verification:

• Failing tests that turn green
• Successful builds
• Static analyzers passing
• Expected output matching
• Deterministic scripts

Without verification, the AI produces plausible but potentially wrong code, and you become the only feedback loop — a feedback loop that gets tired and loses attention.

In my workflow, every change follows: RED → GREEN → REFACTOR → ANALYSIS → PROOF → HUMAN GATE.

This is the workflow backbone:

1. Explore — Understand the codebase, existing patterns, and the real problem
2. Specify — Write a detailed, AI-friendly specification (acceptance criteria, constraints, edge cases)
3. Plan — Produce a concrete implementation plan before code changes
4. Implement — Execute one step at a time and verify after each step
5. Commit — Checkpoint small, validated changes in Git

Planning is most valuable for new features, multi-file changes, or risk areas. Tiny fixes can be done directly — but still verified.

Good prompts are not long prompts — they are scoped, specific, and verifiable.

The pattern is always the same: scope the task, reference existing patterns, and define what "done" looks like.

Knowing best practices is one thing. Making every AI session follow them automatically is another. That's what the github-copilot-configs library does — it encodes your architecture, conventions, and development process into configuration files that GitHub Copilot and Claude Code follow without you repeating yourself every session.

Target stack: ASP.NET Core + Blazor WebAssembly · Onion/Screaming Architecture · CQRS-lite · .NET 10. But the patterns and workflow are adaptable to any .NET project.

Agents are invoked via @name in VS Code chat. Each is a specialized role with its own constraints, workflow, and tools.

Each agent follows the shared workflow rules in AGENTS.md: plan-first discipline, Red-Green-Refactor loops, and mandatory human gates.

The @devops agent deserves special attention because it encodes a pattern I found particularly valuable: the Architecture.md → Bicep → Deployment-Info pipeline.

The workflow separates what should exist (Architecture.md) from what does exist (Deployment-Info-{env}.md):

1. Architecture.md is the specification — the desired infrastructure state, including resource topology, SKUs, cost estimates, DNS records, and URL maps
2. Bicep templates implement that specification
3. Deployment-Info-stg.md / Deployment-Info-prd.md record the actual deployed state — real resource names, FQDNs, and live URLs

This separation means the devops agent always knows the current state of each environment and can reason about what needs to change. It also means the @smoke-test and @debug agents can discover live URLs automatically — no hardcoded values.

The @smoke-test agent is designed for post-deployment verification. Instead of relying on hardcoded URLs, it dynamically builds its environment URL table by reading the infrastructure documentation files. It then executes a structured test plan:

• Health endpoints: Checks /health, /health/ready, /health/live on every API
• Page loads: Navigates to each web application, verifies content renders
• Console errors: Captures JavaScript errors and failed resource loads
• Network errors: Monitors for 4xx/5xx HTTP responses
• Authentication flows: Verifies login redirects appear on protected routes (without entering real credentials)

The agent produces a structured report with pass/fail counts, collected errors, and details on every failure. It's read-only by design — it never submits forms or modifies data, especially in production.

Skills are invoked via /name in chat and guide the AI through multi-step code generation tasks.

• _specs/<Feature>.md — Feature specifications (the contract between developer and AI). Written before planning using templates/spec-template.md.
• _plans/<Feature>.md — Implementation plans with vertical-slice steps, created by @planner from the spec.

Instruction files activate automatically when you edit files matching their applyTo glob pattern. When you open a domain entity file, the AI silently loads domain conventions. When you edit a controller, it loads BFF patterns.

This means the AI always knows the conventions for the layer you're working in — without you needing to mention them.

Templates use {{MustacheStyle}} placeholders that the /init skill replaces with project-specific values:

Copy the files, run /init, and the entire AI configuration is project-specific in seconds.

You don't need to use the exact same stack. The engineering process — plan first, test first, one step at a time — works for any project. Here's how to get started:

Clone or download github-copilot-configs and copy the relevant files into your project:

your-project/
├── .github/
│   ├── copilot-instructions.md   ← from this repo's root copilot-instructions.md
│   ├── instructions/             ← auto-activated by applyTo glob patterns
│   ├── agents/                   ← invoked via @name in chat
│   ├── skills/                   ← invoked via /name in chat
│   └── prompts/                  ← available in prompt picker
├── AGENTS.md                     ← shared agent workflow rules (always-on)
├── CLAUDE.md                     ← optional, for Claude Code users
└── templates/                    ← referenced by agents and skills

The .github/copilot-instructions.md in this repo is meta (for the template library itself). Copy the root-level copilot-instructions.md to .github/copilot-instructions.md in your project.

Open VS Code chat and type /init. The skill will:

1. Discover your project's tokens automatically (solution name, namespace root, test executable path, etc.)
2. Ask for values that can't be auto-discovered
3. Replace all {{token}} placeholders across your config files
4. Verify no unreplaced tokens remain

# 1. Plan the feature
@planner Add subscription management with list and create

# 2. Review and approve the plan

# 3. Implement step by step
/build-feature Step 1 — Display subscription list

These files are templates. After running /init, adapt them to your project:

• Different architecture? Edit the project structure in .github/copilot-instructions.md and update applyTo globs in instruction files
• Different test runner? Update {{TestExePath}} references
• Additional layers? Create new <topic>.instructions.md files with an applyTo glob in .github/instructions/
• Additional agents? Create <name>.agent.md in .github/agents/ following the existing pattern
• Different CI/CD? Update the @devops agent with your pipeline conventions

The most valuable thing in this repo isn't the boilerplate — it's the workflow encoded in agents. Consider building agents for your own recurring tasks:

• A code review agent that checks PRs against your team's conventions
• A migration agent that handles framework or library upgrades
• A documentation agent that keeps API docs in sync with implementation
• A performance agent that profiles and suggests optimizations

The pattern is always the same: define the agent's role, constraints, workflow steps, and tools — then let it execute within guardrails you control.

Parts 1–3 covered principles and tooling. This part describes the concrete development process we encode into our templates — the workflow an AI agent follows when building features. This is where spec-driven development, Red-Green-Refactor, vertical slicing, and human gates come together into a single disciplined loop.

Every feature follows five phases. The AI agent is responsible for executing them, but the developer stays in control at every gate.

Explore → Specify → Plan → Implement → Commit

Explore — The agent reads the codebase to understand existing patterns, the reference feature, and the problem space. No code changes happen here.

Specify — A specification file (_specs/<FeatureName>.md) captures user stories, acceptance criteria, data model, and business rules. This is the contract between the developer and the AI.

Plan — A plan file (_plans/<FeatureName>.md) decomposes the feature into concrete implementation steps. Each step is a vertical behaviour slice with explicit file paths, test methods, and verification criteria. The plan must be approved before any code is written.

Implement — The agent executes the plan one step at a time using Red-Green-Refactor. Each step ends at a human gate — the developer reviews and approves before the next step starts.

Commit — Small, validated changes are checkpointed in Git after each approved step.

Not every change needs a plan. The configuration library encodes a simple decision matrix:

The planning gate prevents the most common AI failure mode: the agent starts writing code before understanding the scope, creates files in the wrong locations, misses existing patterns, and produces work that has to be thrown away.

This is the most important planning principle and the one most teams get wrong when working with AI.

The problem with horizontal slicing: A natural instinct — for both humans and AI — is to plan layer by layer: "Step 1: Create the entity. Step 2: Add the repository. Step 3: Build the controller. Step 4: Create the page." This feels orderly, but it has a critical flaw: you don't discover integration problems until the very end. The entity might not match the DTO. The query might return the wrong shape. The page might need data the controller doesn't provide. By the time you find out, you've built four layers of code that need rework.

The vertical slice alternative: Decompose features into the smallest possible user-visible behaviours, not into layers. Each slice delivers something a user or a test can verify end-to-end.

The strategy is UI first with mocks, then replace mocks top-to-bottom:

1. Stub phase — Build the page, form, or component at the Presentation layer with a stubbed service returning fake data. The user validates the UI and interaction design immediately. Tests verify the ViewModel behaviour against the mock.

2. Wire phase — Replace the stub with real production code, working from top to bottom: controller → application handler → domain → persistence → database. Integration tests verify the full stack. Remove the stub.

This two-phase approach has three benefits:

• Fail fast — Integration mismatches between layers surface on the second step, not after building the entire feature in isolation.
• UI feedback early — The user sees and validates the interface before any backend work begins, catching UX issues when they're cheap to fix.
• Smaller blast radius — If the backend step reveals that the contract needs to change, only one stub step and one wire step are affected — not four independent layers.

Slice A — View subscriptions:

Slice B — Create a subscription:

Notice: each slice is completed (UI + backend) before the next slice starts. Step 1 and Step 2 are adjacent — they belong to the same user behaviour. The agent never jumps to Slice B before Slice A is fully wired.

Compare with the anti-pattern: Step 1 "Create Entity + Repository", Step 2 "Build Application handlers", Step 3 "GET endpoint", Step 4 "POST endpoint", Step 5 "List page", Step 6 "Create page". This builds layers in isolation. The UI is validated last, when it should be validated first.

Each plan step is executed as a single Red-Green-Refactor cycle. This is the loop the AI agent follows for every step:

READ       — Read the plan step. Understand scope, files, and the test to write.
RED        — Write the failing test FIRST. Run it. Confirm it fails.
GREEN      — Write the minimal production code to make the test pass. Run it. Confirm it passes.
REFACTOR   — Clean up if needed. Do not change behaviour.
ANALYSE    — Run static analysis. Fix all violations. Run the full test suite.
PROVE      — Build (zero warnings) + all tests pass + format check passes.
🛑 STOP    — Present results. Wait for human approval.
MARK DONE  — After approval, update the plan file checkboxes.

Three rules are non-negotiable:

1. Never skip RED. The test must exist and fail before any production code is written. This proves the test actually validates something. An AI that writes the test and production code simultaneously has no guarantee the test would have caught a real failure.

2. Never batch steps. One step per interaction. The agent completes a step, proves it, presents results, and stops. The developer reviews before the next step begins. This prevents the common AI failure of compounding errors across multiple steps.

3. Never proceed past the human gate. The 🛑 STOP is absolute. The agent does not continue until the developer explicitly approves. This is the single most important control mechanism — it keeps the developer accountable for every change.

The human gate is not a rubber stamp. Each gate requires behavioural verification — a concrete assertion that the system now does something it didn't before:

• "Integration test GetSubscriptionsTest passes — GET /api/subscriptions returns a list."
• "Form renders with validation — entering an empty name shows 'Name is required'."
• "POST /api/subscriptions with valid data returns 200; with invalid data returns 400 with error message."

"Code review" alone is never sufficient as the sole verification. If a step cannot be verified through observable behaviour, it should be merged into a step that can.

Gates also trigger at higher-risk moments:

• After plan creation (before any code is written)
• Before any Git push
• On any change to authentication, PII handling, shared contracts, or database schema

The specification file (_specs/<FeatureName>.md) is written before the plan and serves as the contract between developer intent and AI execution. A good spec contains:

• User stories — Who benefits and what they can do
• Acceptance criteria — Concrete, testable conditions for "done"
• Data model — Entities, properties, relationships
• Business rules — Validation, constraints, edge cases
• Non-goals — What is explicitly out of scope

The spec prevents a common AI failure: scope creep. Without a spec, the AI infers what "Add subscriptions" means and may add features nobody asked for, use patterns that don't match the codebase, or miss critical business rules. The spec makes intent unambiguous.

The plan is then derived from the spec. Every plan step traces back to an acceptance criterion. If a step doesn't serve an acceptance criterion, it shouldn't exist.

AI coding sessions are ephemeral — context is lost when a session ends. Our plan files solve this with a simple convention: checkbox tracking.

## Step 1 — Display subscription list (stubbed)
...
**🛑 HUMAN GATE**:
- [x] Behavioral verification: ViewModel test passes, page renders list with fake data
- [x] Code review: Page layout matches reference feature

## Step 2 — Wire subscription list to real API
...
**🛑 HUMAN GATE**:
- [ ] Behavioral verification: Integration test passes, GET /api/subscriptions returns list
- [ ] Code review: Repository, query, controller follow reference patterns

When a new session starts, the agent reads the plan file and finds the first unchecked [ ] — that's where to resume. No context is lost. Any agent, in any session, can pick up exactly where the last one left off.

The key insight is that this entire process — planning gates, vertical slicing, Red-Green-Refactor, human gates, progress tracking — is encoded as AI instruction files that the agent reads and follows automatically. It's not a convention that developers need to remember; it's a constraint the AI enforces on itself.

When a developer says "build the Subscriptions feature", the AI reads these files, asks clarifying questions, produces a vertically-sliced plan, waits for approval, and executes one step at a time with test-first discipline and mandatory human gates. The developer's job shifts from writing boilerplate to reviewing vertical slices of working behaviour.

AI coding assistants are powerful, but they amplify both good and bad practices. The developers who benefit most will be those who:

1. Adopt deliberate workflows — Explore, Specify, Plan, Implement, Commit
2. Require verification — never trust AI output without automated proof
3. Keep sessions focused — one task, one goal, clear validation
4. Choose models wisely — match cost to complexity
5. Encode their process into AI configuration — turn personal engineering discipline into agents that enforce it automatically

I built github-copilot-configs because I got tired of re-explaining my process to every AI session in every project. Now I copy the files, run /init, and every agent — planner, bugfix, debug, devops, smoke-test, git — knows the architecture, the conventions, and the workflow. The AI becomes a disciplined teammate instead of an unpredictable code generator.

The library is open source and designed to be forked and adapted. Take what works for you, modify what doesn't, and build your own agent library on top of it. The investment in encoding your engineering process pays for itself on the first feature you build with it.

The practices described in this article are encoded in the github-copilot-configs open-source repository — a reusable template library of GitHub Copilot and Claude Code configuration files for .NET projects.

It's crucial to understand that the testing pyramid must be tailored to a project's unique requirements. The team is responsible for fine-tuning the ideal testing architecture for their project.

I'm offering an example of a basic test pyramid suited to the Onion architecture I commonly employ in my projects. My intent is to showcase what a testing pyramid might look like for DDD (Domain-Driven Design) projects. However, always consider that it might need further adjustments to fit specific project circumstances.

At the core of my testing strategy lie unit tests. These focus on individual components or functions and are quick to write and maintain. They ensure the fundamental components of our application remain robust.

It's worth noting that a pyramid doesn't stand solely on its base. While unit tests are foundational, they represent just one facet. Beyond unit tests, I implement Service tests to validate the entire backend's integration. These play a pivotal role in ensuring proper interactions with databases and external services. They're generally slower and more intricate than unit tests, which is why I house them in separate projects.

The term "Service test" originates from the idea that these tests operate from the service layer.

By segregating Service Tests from unit tests and placing them in distinct projects, I enhance the manageability and scalability of my testing approach. This separation allows for unit tests to validate individual components, while integration tests or Service tests verify interactions with databases and services.

Unit Tests At the pyramid's base, you find the unit test. This positioning implies a higher volume of unit tests compared to other kinds. A unit test is an automated test that targets a small, isolated code segment, typically an individual method or class. The unit test's objective is to confirm the correctness of this specific code piece.

The included diagram showcases typical software layers for an Onion/Clean architecture, with color-coding to highlight their testing suitability.

• Green: Layers such as ViewModels, Application, and Domain are primary unit testing candidates. They offer high value when tested in isolation due to their quick execution and maintainability.
• Yellow: The yellow layers are less efficient when tested standalone. Their unit tests often bring limited added value since they usually rely heavily on the layer below. Therefore, integration tests are generally used to verify the accurate functionality and interaction of these components.
• Red: Testing red layers usually results in fragile or sluggish tests that demand considerable maintenance. These layers typically offer lower testing ROI, making integration tests a more pragmatic choice.

Some attributes my unit tests adhere to include:

• Testing Single Units: A unit test evaluates one class or method at a time. This limited scope makes it simpler to identify issues, aiding codebase maintenance and refactoring.
• Testing Pure Logic: The primary purpose of a unit test is to confirm the class or method logic. This encompasses checking if the method returns expected results for given inputs or handles edge cases effectively.
• Mocking Dependencies: To ensure code isolation, unit tests shouldn't depend on external systems. For instance, a class interacting with a database should be tested with a mock or stub, not a real database connection.
• Fast Execution: Due to their foundational role, unit tests need swift execution to facilitate frequent runs, ideally after each code alteration.

UI Test

UI Tests validate user interactions and the application's interface. They replicate real user scenarios involving UI elements, ensuring the application operates as anticipated. My UI Test are done in isolation of the Service Tier, they exclusively test an application's presentation layer. As these test are performed in isolation you can see them as a specialized subset of unit tests. Using the MVVM pattern within my Blazor components enables to abstract away the UI logic and free the test from depending on UI specific details that make the test brittle.  For testing the logic in the Razor views I typically use BUnit but try to avoid them as much as possible.

However, while UI Tests are insightful, they can be fragile and require regular updates, especially if UI elements undergo changes. They might not detect all UI issues, emphasizing the need for a comprehensive testing strategy that incorporates End2End tests for thorough application quality verification.

Service Tests

Occupying the pyramid's middle layer, Service Tests anchor my integration testing strategy. They center on the application's back-end components, ensuring that services, APIs, and business logic layers cohesively function. They also serve as a type of acceptance testing for complex logic. Due to their ability to test business flows without UI test fragility, Service Tests often yield the highest ROI, making them indispensable in my testing strategy.

For Service Tests, I utilize Specflow and follow the BDD (Behavior-Driven Development) approach. This method bridges the gap between non-technical and technical team members, fostering shared application behavior understanding.

Domain-Driven Design's concept of Ubiquitous Language pairs seamlessly with BDD. It denotes a shared language among team members, ensuring mutual understanding of domain concepts and requirements.

SpecFlow, a renowned BDD tool, enables business analysts to describe expected application behaviors in Gherkin syntax. Developers then create step definitions, which are code pieces that map scenarios to test actions. By adopting a BDD approach with tools like SpecFlow, I ensure the Ubiquitous Language isn't just documentation but living specifications executable as tests. This promotes clear communication and a cohesive application.

Database: In-memory or Disk-based?

Efficiency and speed are paramount for all tests, especially when integrated into a continuous integration process on a build server. Database selection significantly influences this.

From my experience, an in-memory database like SQLite is typically more build-time efficient. However, there are instances where SQLite might be unsuitable, especially when integrating with complex databases with features like stored procedures. In such cases, a closer representation of the production environment, like SQL Server, is essential. To optimize tests without compromising build times, I suggest making tests configurable to different databases. For instance, SQLite can be used on the build server for rapid tests, while SQL Server is employed locally.

It's also crucial to emphasize that tests should mock external services, ensuring the application's logic is the primary testing focus.

Conclusion Structuring my test pyramid with unit tests at the base, Service Tests in the middle, and UI tests at the peak results in a comprehensive testing strategy. While UI tests play a role, Service Tests truly underpin a quality product. Combining these tests ensures both the individual components' integrity and the smooth interaction between the application's various tiers.

Many professionals in our industry believe that the key to an effective testing strategy is a robust system of automated tests that interact with the User Interface (UI). Imagine an advanced tool that can meticulously record user interactions and replay them to check for consistent results.

However, when applied in practice, this approach reveals several problems. The most significant issue is the fragility of these tests. Even minor UI changes can cause numerous tests to fail, resulting in a time-consuming process of re-recording. Moreover, these tests tend to run at a slow pace and require substantial infrastructure to execute effectively. A testing strategy solely focused on automating UI tests is too expensive, delicate, and time intensive.

My consideration of the effectiveness of automated testing was restored when I discovered the concept of the test pyramid. This concept, integrated within the Software Development Life Cycle (SDLC), organizes tests across different layers of the application stack. Visualize a pyramid with a sturdy and balanced structure. The broad base consists of quick and efficient unit tests, while the narrow peak represents a smaller set of slower, more complex end-to-end tests, often performed through the UI. This approach prioritizes comprehensive coverage at the foundational levels where tests are simpler, faster, and more cost-effective, while still conducting sufficient high-level tests to ensure the harmonious functioning of system components.

However, the test pyramid does not stop at the base and the peak. It also incorporates an intermediate layer of tests that operate discreetly through an application's service layer. These tests combine the strengths of end-to-end tests while bypassing the complexities of UI frameworks. For applications based on a three-tier architectures, this corresponds to testing through the second tier, the Backend For Frontend. For two-tier applications, this can be done through the Application layer.

It is also important to note that there can be variations of the test pyramid based on different philosophies or specific needs of a project. It is up to the team to fine-tune the right testing strategy for his project. Here I provide a straightforward strategy that should fit most scenarios but not all. You should take account of your specific circumstances and adapt this strategy to your specific situation.

In my previous blog post, I explained the importance of writing testable code. In this post, I will explore some common best practices for unit testing in C#, focusing on key areas such as test structuring, mocking frameworks, test naming, and differentiating between unit and integration tests.

Follow the Arrange-Act-Assert (AAA) Pattern

The AAA pattern provides a structured approach for organizing unit tests. Follow these steps:

• Arrange: Set up the object to be tested and its dependencies.
• Act: Perform the action to be tested.
• Assert: Verify that the action led to the expected result.

Using the AAA pattern enhances readability and maintainability of your tests.

using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace MyApp.Tests
{
    [TestClass]
    public class CalculatorTests
    {
        [TestMethod]
        public void Add_GivenTwoIntegers_ReturnsTheirSum()
        {
            // Arrange
            var calculator = new Calculator();
            int number1 = 2;
            int number2 = 3;

            // Act
            int result = calculator.Add(number1, number2);

            // Assert
            Assert.AreEqual(5, result, "The addition of 2 and 3 should equal 5");
        }
    }
}

 Use Mocking Frameworks Wisely

Mocking frameworks, like Moq, allow the creation of mock implementations of dependencies. However, use them judiciously to avoid potential pitfalls:

• False Sense of Security: Over-mocking can lead to tests passing despite real-world failures.
• Brittle Tests: Unmet mock expectations due to code changes can cause unnecessary test failures.
• Overemphasis on Implementation Details: Too many mocks may shift focus from testing behavior to testing implementation.
• Increased Complexity: Tests with excessive mocks become harder to understand and maintain.
• Balance the use of mocking frameworks to isolate code units effectively without introducing unnecessary complexity.

Write Meaningful Test Names

A good test name should describe what the test does and provide a clear idea of what went wrong in case of failure. Follow a convention like "MethodName_StateUnderTest_ExpectedBehavior" to improve test name clarity and simplicity.

Separate Unit and Integration Tests

Distinguish between unit tests and integration tests to ensure effective testing and maintainable code.

• Unit Tests: Focus on testing individual components in isolation, with mocked or stubbed dependencies. They are fast, cheap, and provide valuable feedback on small code units.
• Integration Tests: Verify interactions and integration between components, including infrastructure. They have higher code coverage but can be more complex and fragile.

Separating these test types in separate projects or folders or namespaces allows developers to leverage the strengths of each approach while maintaining code quality.

Utilize Parametrized or Data-Driven Tests

Parametrized tests allow running the same test method with different inputs and expected outcomes. In C#, you can use parameterized tests or data-driven tests with frameworks like MSTest. These tests provide flexibility and code reuse.

[TestClass]
public class CalculatorTests
{
private Calculator _calculator;

[TestInitialize]
public void Setup()
{
    _calculator = new Calculator();
}

[TestMethod]
public void Add_PositiveNumbers_CorrectSum()
{
    AddAndVerify(1, 1, 2);
    AddAndVerify(2, 2, 4);
    AddAndVerify(3, 3, 6);
}

[TestMethod]
public void Add_NegativeNumbers_CorrectSum()
{
    AddAndVerify(-1, -1, -2);
    AddAndVerify(-2, -2, -4);
    AddAndVerify(-3, -3, -6);
}

private void AddAndVerify(int a, int b, int expected)
{
    // Arrange - setup is done before this

    // Act
    int result = _calculator.Add(a, b);

    // Assert
    Assert.AreEqual(expected, result);
}

By applying these best practices, you can write robust, reliable, and maintainable unit tests in C#. The Arrange-Act-Assert pattern brings clarity and structure to your tests. Using mocking frameworks wisely, writing meaningful test names, separating unit and integration tests, and leveraging parametrized or data-driven tests enhance the effectiveness and efficiency of your test suite. Unit testing is an essential tool for building high-quality software, and following these best practices will greatly contribute to your success.

Testable code stands as a cornerstone in the realm of quality software development. Crafting code that can be effortlessly verified for correctness through automated testing is not just a skill, but an art. In this blog post, we will embark on a journey through six fundamental principles that serve as the pillars of writing testable and maintainable code in C#. Whether you are an experienced software engineer or taking your first steps in the C# landscape, these principles will equip you with the tools needed to sculpt your code into a masterpiece of quality and reliability.

1. Single Responsibility Principle (SRP): Each class or method should have a single responsibility, meaning it should only have one reason to change. If a class or method does too many things, it becomes harder to test because each test must consider the different paths through the code.

2. Use Dependency Injection: Dependency injection is a technique where an object's dependencies (the other objects it needs to do its job) are provided to it, rather than creating them itself. This allows the dependencies to be swapped out with fake or mock objects in tests, making the code easier to test. For example, you could inject a database service into your class, and replace it with a mock database service in your tests.

public class OrderService
{
    private readonly IOrderDatabase _database;

    public OrderService(IOrderDatabase database)
    {
        _database = database;
    }

    public void PlaceOrder(OrderedParallelQuery order)
    {
        // ... some logic ...
        _database.AddOrder(order);
    }

    // ... rest of class ...
}

[TestClass]
public class OrderServiceTests
{
    [TestMethod]
    public void PlaceOrder_OrderIsValid_AddsOrderToDatabase()
    {
        // Arrange
        var mockDatabase = new Mock<IOrderDatabase>();
        var orderService = new OrderService(mockDatabase.Object);
        var order = new Order { /* initialize order here */ };

        // Act
        orderService.PlaceOrder(order);

        // Assert
        mockDatabase.Verify(db => db.AddOrder(order), Times.Once, "Order should be added to database once");
    }
}

3. Use Interfaces and Abstractions: Relying on concrete classes makes your code more tightly coupled and harder to test. By depending on abstractions (like interfaces or abstract classes), you can easily substitute real implementations with mock ones for testing.

4. Avoid Static and Singleton Classes: Static methods and singleton classes cannot be substituted with mock implementations, making your code harder to test. They also hold state between tests, leading to tests that are not independent.

Static and Singleton classes can hinder testability by preventing substitution with mock implementations, making testing more difficult and relying on real-world dependencies. Additionally, static methods and singleton classes can hold state between tests, leading to interdependent tests and potential inconsistencies.

While static and singleton classes should usually be avoided, there are cases where using static classes is appropriate. This includes scenarios such as defining utility functions or extension methods, which encapsulate reusable pure functions or extend the behavior of existing types without modifying their source code. In these cases, static classes can provide organization and improve code readability.

For more explicit examples on when using static methods see the last part: 6. Write Pure Functions When Possible

5. Favor Composition Over Inheritance: Composition refers to building complex objects by combining simpler ones, while inheritance describes a relationship between parent and child classes. Composition is more flexible and easier to test because you can replace parts of the composed object with mocks.
This example highlights the benefits of using composition for achieving better testable code:

// Composed object that uses composition instead of inheritance
public class ComposedObject : ISimpleObject
{
    private readonly ISimpleObject _simpleObject;

    public ComposedObject(ISimpleObject simpleObject)
    {
        _simpleObject = simpleObject;
    }

    public void PerformAction()
    {
        // Additional logic can be added here
        Console.WriteLine("Performing action in ComposedObject");

        // Delegating the action to the composed object
        _simpleObject.PerformAction();
    }
}

[TestClass]
public class ComposedObjectTests
{
    [TestMethod]
    public void PerformAction_Should_Call_PerformAction_Method_On_SimpleObject()
    {
        // Arrange
        var mockSimpleObject = new Mock<ISimpleObject>();
        var composedObject = new ComposedObject(mockSimpleObject.Object);

        // Act
        composedObject.PerformAction();

        // Assert
        mockSimpleObject.Verify(m => m.PerformAction(), Times.Once);
    }
}

By favoring composition over inheritance, the code becomes more flexible and easier to test. The example demonstrates how the ComposedObject class is constructed by injecting dependencies through its constructor, allowing for easy substitution of real implementations with mock objects during testing. This decoupling of dependencies enables isolated testing, focusing solely on the behavior of the ComposedObject without being tightly coupled to the implementation details of its dependencies. The ability to inject and replace dependencies with mocks or stubs provides greater control over the testing environment and leads to more reliable and maintainable tests. Embracing composition enhances testability and promotes modular and testable code.

6. Write Pure Functions When Possible: A pure function's output is solely determined by its input, and it does not have any side effects (like changing global variables). This makes it easy to test, because you just need to check the output for a given input.

Take this example where the method “StoreAverageOfPrimes” is extremely hard to test:

public void StoreAverageOfPrimes(int number)
{
    List<int> primeNumbers = new List<int>();

    using (SqlConnection connection = new SqlConnection(_connectionString))
    {
        connection.Open();

        for (int i = 2; i <= number; i++)
        {
            bool isPrime = true;

            for (int j = 2; j < i; j++)
            {
                if (i % j == 0)
                {
                    isPrime = false;
                    break;
                }
            }

            if (isPrime)
            {
                primeNumbers.Add(i);

                SqlCommand command = new SqlCommand("INSERT INTO PrimeNumbers (Value) VALUES (@Value)", connection);
                command.Parameters.AddWithValue("@Value", i);
                command.ExecuteNonQuery();
            }
        }

        SqlCommand command = new SqlCommand("INSERT INTO Results (Value) VALUES (@Value)", connection);
        command.Parameters.AddWithValue("@Value", primeNumbers.Average());
        command.ExecuteNonQuery();
    }
}

This code suffers from the same challenges when it comes to testing the calculation logic in isolation. The code tightly couples the calculation logic with the database access code, making it difficult to write focused unit tests. The lack of separation and abstraction hinders code reusability and maintainability.

In the refactored code here under, the StoreAverageOfPrimes method has been modified to separate the calculation logic from the data access code:

public static List<int> GetPrimeNumbers(int number)
{
    List<int> primeNumbers = new List<int>();

    for (int i = 2; i <= number; i++)
    {
        if (IsPrime(i))
        {
            primeNumbers.Add(i);
        }
    }

    return primeNumbers;
}

public static bool IsPrime(int number)
{
    if (number < 2)
        return false;

    for (int i = 2; i <= Math.Sqrt(number); i++)
    {
        if (number % i == 0)
            return false;
    }

    return true;
}

public void StoreAverageOfPrimes(int number)
{
    List<int> primeNumbers = GetPrimeNumbers(number);
    double average = primeNumbers.Average();

    using (SqlConnection connection = new SqlConnection(_connectionString))
    {
        connection.Open();

        StorePrimeNumbers(primeNumbers, connection);
        StoreResult(average, connection);
    }
}

private void StorePrimeNumbers(List<int> primeNumbers, SqlConnection connection)
{
    foreach (int number in primeNumbers)
    {
        SqlCommand command = new SqlCommand("INSERT INTO PrimeNumbers (Value) VALUES (@Value)", connection);
        command.Parameters.AddWithValue("@Value", number);
        command.ExecuteNonQuery();
    }
}

private void StoreResult(double result, SqlConnection connection)
{
    SqlCommand command = new SqlCommand("INSERT INTO Results (Value) VALUES (@Value)", connection);
    command.Parameters.AddWithValue("@Value", result);
    command.ExecuteNonQuery();
}

In this updated code, the pure functions GetPrimeNumbers and IsPrime have been made static. By making them static, they can be accessed directly without an instance of the CalculationService class.

The static nature of these functions allows them to be more easily testable and promotes code reusability, as they can be used independently without requiring an instance of the class.

When writing testable code, it is important to consider the nature of the functions you are working with. Pure functions, which have the characteristic of producing the same output for a given set of inputs and having no side effects, are particularly beneficial for testability.

In the context of testability, pure functions can be made static to further enhance their usability. By making pure functions static, they can be accessed and used directly without the need to create an instance of the class containing them. This eliminates the dependency on the object's state, making the functions more independent and self-contained.

The static nature of pure functions simplifies the testing process. Since they rely only on the provided input and produce a deterministic output, you can easily write focused unit tests for these functions without the need to set up complex object states or manage external dependencies. You can simply pass different inputs to the functions and verify their outputs against expected results.

In contrast, functions with side effects, such as those interacting with databases or modifying global variables, are more difficult to test due to their reliance on external resources and potential interference with the test environment. These functions often require complex setup and teardown procedures to isolate and restore the system state, which can complicate the testing process.

By separating pure functions and making them static, you create modular and testable units of code that are easier to verify in isolation. This promotes code maintainability, reusability, and testability, allowing you to write more effective and reliable tests for your applications.

Ah, the famous 80% code coverage - the golden number that many developers I've encountered seem to believe has magical powers to keep all the coding gremlins away. It means that 80% of the new code should be put to the test, as if saying, “Prove your worth, code!” This bar is high, no doubt, and is set to make sure that most of our codebase is given a good check.

However, let’s not get too starry-eyed about this 80%. Sometimes, depending on the type of project or part of the code, it’s like trying to fit a square peg in a round hole. It just doesn’t work! In such cases, it’s smarter to focus on creating solid, quality tests rather than running a race to hit that 80%.

Now, when deciding how much testing is just right, we need to think about complexity and risk. Imagine them as partners in crime – when complexity goes up, risk is right there with it. That means more chances of things going wrong. To set the right target for code coverage, you have to keep an eye on how complicated the code is. The SonarQube Coverage Overview report is like a helpful friend in this mission. It’s easy on the eyes and shows the connection between code coverage and complexity.

Here’s the quick tour of what the report shows:

• Bottom-right corner: This is where complex but well-tested code hangs out. Think of it like a tough puzzle that’s been solved.
• Bottom-left corner: The dream zone! Code here is simple and has been tested a lot. It’s where you’d want most of your code to be.
• Top-right corner: Red alert area! Code here is like a tangled mess and hasn’t been tested enough. It’s risky and needs attention ASAP.
• Top-left corner: This area has simple code, but it hasn’t been tested much. It’s not ideal, but not a total disaster.

So, in summary, this report is like a handy map for your code. It helps you see what needs your attention and testing effort. This way, you can make sure your software is in good shape. But always remember, 80% is a guiding light, not a magic spell!

Hello everyone! Before we dive deep into the technical side of automated testing in my upcoming articles, I want to hit the pause button and shine a spotlight on something super important: writting automated test is a team sport!

Yes, as developers, sometimes we feel like testing is our own little kingdom. But you know what? Building amazing software is like painting a beautiful picture - it needs different brushes and colors. That’s why testing should be a high-five moment with the whole team involved. We developers must open the doors and roll out the red carpet for everyone to join in. So, let’s bring everyone into the spotlight and see how this teamwork makes the dream work! Onward to the backstage tour!

Developers and Analysts as the Architects of Software

As developers, we are like the master builders of the software world. We draw up nifty blueprints – which are, of course, our much-loved automated tests – making sure the software is solid from the ground up. But here’s the thing: we’ve got teammates! Analysts are the awesome folks who help set the stage. They’re like the planners who make sure everything’s in the right place. They use their smarts and know-how to create a shared lingo – kind of like a secret code that everyone on the team can understand. This means everyone’s singing from the same song sheet, which makes everything tick along nicely.

The Testers’ Detective Work in Polishing the Software Masterpiece

Next up, let’s hear it for the testers – our software’s very own detective squad! They swing into action when it's time to put the software through its paces, sniffing out any sneaky bugs or issues. They have a knack for spotting the little things that might trip us up, and they’re great at making sure everything is shipshape. And it's even better when they join forces with developers and analysts to make sure our software is top-notch.

Scrum Masters and Project Managers Harmonizing the Ensemble

Hang on, we’re not done with the shout-outs! We can’t forget the Scrum Masters and Project Managers. These superstars are like the conductors of our orchestra. They keep the tunes flowing, helping everyone to play in sync. They’re the ones who make sure the communication lines are open, that roadblocks are smashed, and that everyone's on the same page with testing goals.

The secret sauce

Now, for the secret sauce that glues everything together – SpecFlow! Especially for the .Net folks out there, SpecFlow is like a magic wand in the world of Behavior-Driven Development (BDD). It’s an ace tool for cooking up automated and testable game plans. What’s cool is that SpecFlow speaks a language called Gherkin, which is easy-peasy for everyone to understand, even if you’re not a coding whiz. So everyone can jump in and help shape things up, making the team bond even stronger.

So, my friends, before we get our geek on with all the techy details of automated testing, let’s remember this: testing is all about teamwork. It's the special moment where everyone – analysts, testers, Scrum Masters, Project Managers – all huddle up for a group high-five, aiming to build the best software ever. Together, with smarts, teamwork, and nifty tools like SpecFlow, we’re unstoppable. Trust me, this team adventure is the real deal, and you don’t want to miss it!

Today, I want to chat about how automated testing in software development is like scaffolding in building construction. Why? Because both of them give amazing support and strength to what we are building.

• The Strong Support: Just like how a building needs scaffolding to keep it steady, our software needs automated testing for support. Scaffolding holds up the building while it’s being built. In the same way, automated testing holds our code together, making sure it's strong and safe.
• The Watchful Eyes: Scaffolding helps workers see and reach every part of the building. Similarly, automated testing keeps an eye on the software. It checks every nook and cranny to make sure that everything is running smoothly and correctly.
• The Safety Net: When constructing a building, scaffolding acts as a safety net. If something goes wrong, it's there to catch it. Likewise, automated testing catches little problems in our code before they become big headaches.
• The Flexible Friend: Scaffolding can be adjusted and moved as the building goes up. This is just like automated testing, which we can change and adapt as our software grows and evolves.
• Building The Master Plan: In construction, scaffolding is part of the big plan to build something amazing. For us developers, automated testing is a crucial part of our master plan for our software. It guides us and helps us make changes safely.
• Not A One-Man Show: But wait, scaffolding can’t build a building on its own, and automated testing can’t make perfect software by itself. That’s why we have the construction workers, and in coding, we have manual testers. They are like the heroes who check everything up close and find anything that might have been missed.
• Making It Future-Proof: Using scaffolding means that the building will be built right, so it will last a long time. In the same way, when we use automated testing, our code is solid. This means it will keep working great even as time goes by, and we can add new features without worries.

Now, let’s not end this chat without looking ahead. This post is like saying “Hello” before we start an awesome adventure. Over the next few weeks, I’ll be sharing even more posts. We’ll talk about the best ways to do things, tools that make life easier, and examples from real life that show how all of this stuff works.

So, if you’re excited to learn how to write even better code, make sure you keep coming back to check out what’s new. Whether you’re new to coding or have been doing it for years, there will be something for you. Can’t wait to see you here! Stay tuned, friends!

(When you build enterprise business apps using DotNet)

Introduction

This post compares and explains in detail the pros and cons of the 2 most used SPA frameworks by .net developers, Angular and Blazor.

My customers are enterprises that use .Net for building their line of business applications. I compared these 2 UI technologies, to find which one is the best fit for them and when they should use them instead of traditional ASP.NET MVC.

This study is primarily based on my many years of experience in architecting and developing solutions based on Angular and .NET. It is based on research over the internet and the feedback of other architects and IT consultants. Because I had no formal experience with Blazor I invested time in studying the Blazor framework and in building some small applications with Blazor. I also interviewed other developers that had experience with Blazor and integrated their feedback into this study.

Single Page Applications

There are two general approaches to building web applications today: traditional web applications also called Multi Page Applications (MPA’s) because they are made of multiple pages. These perform most of the application logic on the server. On the other hand, you have single-page applications (SPAs) that perform most of the user interface logic in a web browser, communicating with the web server primarily using web APIs. A hybrid approach is also possible, the simplest being to host one or more rich SPA-like sub-applications within a larger traditional web application.

MPA reloads the entire page and displays the new one when a user interacts with the web app. 

A SPA is more like a traditional application because it’s initially loaded and then it refreshes part of the page without reloading it. When a user interacts with the application, it displays content without the need to be fully updated since different pieces of content are downloaded automatically as per request. It is possible thanks to AJAX technology. In single-page applications, there is only one HTML page, and this one page downloads a bunch of assets, CSS, and images but typically also a lot of JavaScript. Speaking of the latter, the code will then listen to clicks on links and then re-render parts of the DOM in the loaded page whenever a user needs something. 

Although SPA applications are extremely popular because they usually account for a better user experience it does not mean that every web application should be built with a SPA architecture. Let’s take, for instance, a news portal like CNN. It is a good example of a multi-page application. How can we see it? Just click any link and watch the reload icon on the top of your browser. You see that reloading has started because a browser is now reaching out to our public server and fetching that page and all the resources needed. The interesting thing about multi-page applications is that every new page is downloaded. Every request we send to the server, like whenever we type a new URL or click on a link, leads to a new page being sent back from the server. Notable examples of multiple-page applications are giants like Amazon or eBay. Using them, you always get a new file for every request.

ASP. Net Core MVC is an excellent choice for websites that are better developed as MPAs (see later). But as explained here above SPAs usually supplies a better user experience when our application is more like an interactive application.   

Angular

Angular still is by far the most used SPA framework by .NET developers. This is because it has a lot of similarities with the .Net ecosystem.

• TypeScript: Angular use TypeScript by default. This means that all documentation, articles, and source code are provided in TypeScript. TypeScript is a superset of JavaScript that compiles JavaScript. C# and Typescript are both designed by Anders Hejlsberg, and in many ways, TypeScript feels like the result of adding parts of C# to JavaScript. They share similar features and syntax, and both use the compiler to check for type safety. So, it's more straightforward to learn TypeScript for a C# dev as JavaScript.
• MVVM: Angular uses the MVVM pattern. This Pattern was invented for WPF & Silverlight (.NET). So many developers coming from .NET that wanted to do Web development have turned to Angular because it used the same pattern.
• All in the box: Unlike other Js frameworks like Vue or React, Angular is a complete framework that tends to supply everything you need, libs, and tooling and spare you of the dependency hell so that you can focus on your application. Just like the .NET framework. 

 Most of the other Js frameworks are exactly the opposite. They only focus on one aspect but leave you with a lot of choices. Although focusing on one thing results in frameworks that are simpler to learn, .NET enterprise developers are annoyed when they must make a lot of choices. They prefer opinionated frameworks that help them in getting productive faster with better supportability.

Angular is a part of the JavaScript ecosystem and one of the most popular SPA frameworks today. AngularJs the preceding version, was introduced by Google in 2009 and was largely adopted by the development community.

In September 2016, Google released Angular 2. It was a complete rewrite of the framework by the same team. The recent version of the framework uses TypeScript as a programming language. TypeScript is a typed superset of JavaScript which has been built and maintained by Microsoft. The presence of types makes the code written in TypeScript less prone to run-time errors. As explained here above, TypeScript is the primary reason Angular is so popular in the .NET community.

The difference between the old Angular and the second version is so radical that you can’t update from AngularJs (the older version). Migrating the applications to Angular requires too many modifications due to different syntax and architecture. This means that upgrading our existing AngularJs apps to the new Angular framework will lead to a complete rewrite. 

TypeScript compiles JavaScript and integrates perfectly with the JavaScript ecosystem. So Angular is part of the JavaScript ecosystem and uses npm to manage dependencies. It can count on the largest community and number of libraries today. With Angular, you use the largest open-source ecosystem where you can find everything that you need. 

But the vast number of packages and their fast-changing rate is also a challenge in the enterprise. Making these packages available is the biggest challenge. Take a new Angular application as a sample. An empty new Angular application has the following direct dependencies:

• @angular
• @angular/cli
• @ngrx
• rxjs
• typescript
• tslint
• codelyzer
• zone.js
• core-js

And now let’s install all the dependencies by typing:

npm i
... one eternity later ...
added 1174 packages in 116.846s

A new regular Angular application without any add-on uses already 1200 packages! 

When your ecosystem has this number of dependencies, you can’t inspect them all yourself. You can’t hope they’re all secure. You can’t assume they’ve all got permissive licenses. You can’t maintain your registry by hand. You can’t formally approve packages by comity, and you can’t maintain this as many packages you’re using will get an update every single hour. You must move from manual, discrete processes to automated, continuous processes. 

Angular comes with great tools, supported by a large community. Angular has been around for over a decade, while Blazor has been in the market for only a few years. Angular is a production-ready framework with full support for MVVM applications and it is being used by many large companies. Blazor, while being used by some large brands, is early in its lifecycle. Angular and other popular Js frameworks like Razor or View come with much more content in the form of courses, books, blogs, videos, and other materials. Angular has dedicated tech events held worldwide, a huge community, and it supplies a broad choice of third-party integrations.

To illustrate the difference in adoption, consider the graphic here that compares the number of jobs offered by frontend technology. Angular comes second when Blazor is somewhere between the others:

As illustrated here above, despite being one of the oldest and one of the most mature SPA frameworks Angular is not the most used or loved framework in the JavaScript community. This is primarily due to his complexity. Even for seasoned JavaScript developers, Angular is difficult to master. His strength of being an opinionated framework using TypeScript comes at the expense of a steep learning curve. 

This is even more challenging for most .NET developers who usually have only a marginal knowledge of JavaScript. They not only have to learn a new language they also must learn an entirely new ecosystem and framework. In my own experience, this is the greatest challenge for organizations using .NET. This can be solved by recruiting Angular specialists that focus on the frontend part. Having a frontend specialist usually improves the user experience but it comes at the expense of having to segregate your devs in frontend (Angular) and backend devs (.NET). 

Mixing two technologies coming from different worlds diminishes the flexibility of resource allocation. People must specialize and the potential number of tasks they can work on diminishes. It also increases development time as you need to put more effort into integrating both technologies.

My own experience with working with .net developers having to learn Angular confirms that the learning curve is very steep for them. In the past, to cope with this problem, we recruited Angular specialists to coach our .Net teams. We also had to invest in our CI/CD pipeline to support our new technology stack. As a .Net shop that desired to adopt Angular, we had to make a considerable investment in recruiting the right profiles, supplying the right guidance, and investing in building and adapting our package management process and tools to the high velocity and number of packages that are typical for the Javascript ecosystem. Also recruiting the right skills was a challenge for the reasons explained here above and because Angular is somewhat losing traction in the Js community.

When to choose Angular over ASP.NET MVC?

If the team is unfamiliar with JavaScript or TypeScript but is familiar with pure server-side MVC development, then they will probably be able to deliver a traditional MVC App more quickly than an Angular app. Unless the team has already learned Angular or unless the user experience afforded by Angular is needed, the traditional MVC is the more productive choice. 

Blazor

Blazor is a relatively new Microsoft ASP.NET Core web framework that allows developers to write code for browsers in C#. Blazor is based on existing web technologies like HTML and CSS but then allows the developer to use C# and Razor syntax instead of JavaScript. Razor is the template markup syntax used by ASP.NET MVC and MVC developers can reuse most of their skills to build apps with Blazor. 

Blazor is very promising for .NET developers as it enables them to create SPA applications using C#, without the need for significant JavaScript skills. 

An advantage of Blazor is that it uses the latest web standards and does not need added plugins or add-ons to run in different deployment models. It can run in the browser using WebAssembly and offers a server-side ASP.NET Core option.  

Learning Blazor for .NET developers is nothing compared to Angular or other Js frameworks. First, they don’t need to master JavaScript and TypeScript but also, but they can use the enterprise-friendly .NET ecosystem they already know. For a .NET dev already accustomed to web development through MVC, we can say that developers can be productive in a matter of days/weeks compared to months/years with Angular.

But the biggest advantage of Blazor is its productivity. It allows .NET developers to build entire applications with only C#. It feels more like building desktop apps than web apps. When using the server-side version developers don’t have to think about data transfer between client and server. Also, with the client-side version, it’s a lot easier than with Angular as it’s all integrated within one .NET solution. 

Blazor seems even more productive than traditional MVC as it doesn’t require the developer to cope with server page refreshes and can use client rendering and events. It feels like what was developing with Silverlight or WPF but using Razor, Html, and CSS instead of Xaml. This was also confirmed by our discussion with a consultant at Gartner. They confirmed that based on experiences with several customers, Blazor was the most productive technology for building UIs inside the .NET ecosystem, even compared to MVC.

The adoption of Blazor outside the .NET community will probably remain low. Blazor is hard to sell to the current web developer because it means leaving behind many of the libraries and technologies that have been up for over a decade of modern JavaScript development. This means that Blazor will probably stay a niche technology. Blazor is and will be used by teams that know .NET for building internal business applications but will probably not be adopted outside this community. That means that the community and tools will mostly be supported by Microsoft. The tool and libraries support from the open-source community and vendors will remain less compared to Angular or other mainstream Js frameworks. 

One of the impediments to Blazor adoption by the .NET community is that Blazor will be the next Silverlight. They fear that it will be around only for a brief period. More than 10 years after the final Microsoft Silverlight release, some developers still fear being 'Silverlighted,' or seeing a development product in which they have invested heavily abandoned by Microsoft. This is because both technologies are similar, both are developed by Microsoft and allow us to use the .NET platform to create web applications. They both share the same core idea: Instead of using JavaScript, we can use C# as the programming language to create web applications. 

Inside the enterprise, this risk is largely mitigated by the fact that Microsoft has always supplied relatively long support periods. Even for Silverlight Microsoft continued to support it for nearly 10 years before retiring it. This risk has also a lot less impact as Blazor is not dependent on a browser plugin. Microsoft learned a lot from this story. First, ASP.NET and later ASP.NET Core do not require any browser plugins to run. Also, Microsoft decided to only use open web standards for Blazor. As long as the browsers support those open web standards, they will also support Blazor.

Client Side (Wasm) vs. Server Side Blazor

Blazor has a separation between how it calculates UI changes (app/component model) and how those changes are applied (renderer). This decouples the renderer from the platform and allows to have the same programming model for different platforms. 

Currently, Microsoft supports only 2 renderers, Blazor client (WebAssembly Renderer) and Blazor Sever (Remote Renderer). The implementation code is the same but what differs is the configuration of the hosting middleware. A good practice is to isolate your code from changes to the hosting model by using a class library where you put all the rendering code. This will ease the job if you later must migrate to another hosting model or when you need to support another supplementary model.

Blazor Server

With Blazor Server you use a classic ASP.NET Core website like ASP.NET MVC but the UI refreshes are handled over a SignalR connection.  

As for a SPA, one page is displayed on the browser and then parts of it are refreshed. On the server at the first request, the Html is generated from the Razor pages. When UI updates are triggered by user interaction and app events a UI diff is calculated and sent to the client over a SignalR connection. Then, the client-side Js library used by Blazor server applies the changes in the browser.  

Using Blazor Server behind load balancers or proxy servers requires special attention. As described in the article here, forwarded headers should be enabled (default configuration in IIS) and the load balancers should support sticky sessions. You can also use Redis to create a backplane as described here. 

Blazor Client (WebAssembly)

Here .Net code is running inside the browsers. The application code is compiled in WebAssembly (a sort of Assembly language for the web) and sent together with the .Net runtime to the browser. The Blazor WebAssembly runtime uses JavaScript interop to handle DOM manipulation and browser API calls.

WebAssembly is an open web standard and is supported by all modern web browsers. Blazor is not the only technology using WebAssembly, most of the other big vendors develop tools and platforms that make use of WebAssembly.

Blazor Server vs. client recommendation

For traditional enterprise business applications, Blazor Server seems usually the best option but for certain scenarios, Blazor Wasm has clear advantages :

-       When the responsiveness of your app must be optimal, the low latency of Blazor server will optimize the responsiveness.

-       You need offline support.

-       You expect many users (>100). Blazor Server is a less scalable solution as many users require server resources to handle multiple client connections and client states.

When to choose Blazor over ASP.NET MVC ?

As developing or maintaining apps using Blazor is more productive than ASP.NET MVC and easy to learn, Blazor is usually the best choice except when:

-       Your application has simple, possibly read-only requirements.

Many web applications are primarily consumed in a read-only fashion by most of their users. Read-only (or read-mostly) applications tend to be much simpler than those applications that maintain and manipulate a great deal of state. For example, our intranet or public websites where anonymous users can easily make requests, and there is little need for client-side logic. This type of public-facing web site usually consists mainly of content with little client-side behavior. Such applications are easily built as traditional ASP.NET MVC web applications, which perform logic on the web server and render HTML to be displayed in the browser. The fact that each unique page of the site has its own URL that can be bookmarked and indexed by search engines (by default, without having to add this functionality as a separate feature of the application) is also a clear benefit in such scenarios.

-       Your application ecosystem is based on MVC and is too small or too simple to invest in Blazor.

When your applications consist mainly of server-side processes and your UI is quite simple (e.g., Dashboard, back-office CRUD apps, …) and you’ve already made a strong investment in MVC then adding Blazor could not be worth the investment.

Angular vs. Blazor Score Card

Here we selected several criteria and attributed weight to the function of the specific needs and environment of Enterprises using .Net as their main technology stack. But, each organization is unique and adapt the scoring based on its specific needs.   

The weight ranges from 1 to 5. 5 indicates an especially important criterion, starting from 1 as minor importance to 5 as the top priority.

The score for each criterion ranges from 0 to 10. 10 shows an exceptionally high-quality attribute, 1 is the minimum.

We also take account of Risks at the bottom of the scorecard. Here the weight indicates the risk potential impact and the score the probability. Staring from 0 as 0% probability to -10 indicates a risk that will occur with 100% probability.

• Learning curve: the amount time a developer, on average, needs to invest to become productive with the technology.
• Productivity: how productive the developers are with the given platform once it has mastered the technology.
• Supportability: how well can we efficiently support the platform?
• Community: how valuable, responsive and broad is the developer's community? When a platform has a strong community the organization, its developers and its users all benefit.
• Maturity: is the platform used for long enough that most of its first faults and inherent problems have been removed or reduced?
• Full Stack efficiency: how efficient is it for the project to work and to cope with the separation of the frontend and the backend? Does the adoption of this technology diminish the efficiency of the project teams and the organization because they must deal with different skill sets for backend and frontend?
• Finding resources: how easy is it to recruit developers on the market?
• Libraries choices: a good library well suited for the needs and well maintained improves productivity while minimizing the TCO. A large choice of libraries increases the probability of finding a library that satisfies the needs.
• Opinionated: a platform that believes a certain way of approaching a problem is inherently better and enables the developer to spend less time finding the right way of solving a problem.
• Performance: which platform has the fastest render time, load time, and refresh time, and consumes a minimal number of resources?

MPA reloads the entire page and displays the new one when a user interacts with the web app. 

A SPA is more like a traditional application because it’s initially loaded and then it refreshes part of the page without reloading it. When a user interacts with the application, it displays content without the need to be fully updated since different pieces of content are downloaded automatically as per request. It is possible thanks to AJAX technology. In single-page applications, there is only one HTML page, and this one page downloads a bunch of assets, CSS, images but typically also a lot of JavaScript. Speaking of the latter, the code will then listen to clicks on links and then re-render parts of the DOM in the loaded page whenever a user need something.

Although SPA applications are extremely popular because they usually account for a better user experience it does not mean that every web application should be built with a SPA architecture. Let’s take, for instance, a news site like CNN. It is a good example of a multi-page application. How can we see it? Just click any link and watch the reload icon on the top of your browser. You see that reloading has started because a browser is now reaching out to our public server and fetching that page and all the resources needed. The interesting thing about multi-page applications is that every new page is downloaded. Every request we send to the server, like whenever we type a new URL or click on a link, leads to a new page being sent back from the server. Notable examples of multiple page applications are giants like Amazon or eBay. Using them, you always get a new file for every request.

MPA is an excellent choice for websites that provides mostly read-only content. SPAs usually supplies a better user experience when our application is more like an interactive application.

To make it work you need to:

1. Have a auth0 subscription.
2. Create an Application and a API.
3. Edit following files with your auth0 configuration info:

• \auth0-backend-demo\appsettings.config
• \auth0-angular-demo\src\app\auth.service.ts

1. In the angular app install the npm packages: cd .\auth0-angular-demo
   npm install
2. start the angular app: npm start
3. Compile and run the .NetCore Api app: cd .\auth0-backend-demo
   dotnet restore dotnet run
4. Open your browser and navigate to http://http://localhost:3000/

To better understand how to configure your app it's recommended to first complete the auth0 angular2 quickstart.

Have fun!

Feature teams is one of the ways of scaling agile over a larger organization, you divide your organization in many feature-teams.  The core idea is that the team structure is not organized by component or technical layer.  The team is long-lived, it says together but the work is cross-functional and cross-component.  The team work on a complete customer-centric feature across all components and disciplines.  Feature teams organization will diminish the need for handoffs and so waiting time what will result in faster delivery.  My personal feeling is that adopting feature teams is certainly not an easy goal to achieve certainly not for maintenance teams.  I’m also afraid that it can also lead to unmaintainable systems over time.

The first big problem I see with feature teams is the lack of accountability.  Having everyone being responsible can rapidly become indistinguishable from having no one responsible.

Another big problem is that following  Conways Law this type of organization will produce a big fat ball of mud architecture => a system without clean interfaces.  A system without clean interface is also a system you can't  redesign or change without having to deeply understand the neighboring modules. In the end it makes the system unmaintainable.

So when you want to benefit from the improved productivity of feature teams, you also need to take care of two things: discipline and design.   you need to follow the principles of weak code ownership.  Basically this is the open source model of collaboration. Everyone can participate but they need to follow the rules of a despot that owns the module.  This despot is by the way also taking responsibility of the support and will ensure that good practices as  continuous integratione and unit testing will be followed and that the code quality stays a priority.  No one can check-in code without his approval.  If you need to integrate changes inside a module you need to request a Pull-Request to the owner.  You need also a strong Architecture team responsible to define how the system is divided in modules. This team is responsible to define clear boundaries and to ensure that the feature-teams respect these boundaries. 

Large monolitic applications are characterized by big bottlenecks that slows down the entire process.  The dependencies causes a significant overhead on your deployment throughput. Cycle times are longer because of the slower builds and automated and manual tests required to validate the entire app. This creates a lot of friction in the pipeline. Dependencies brings complexity what increases the development time. Complex code bases have more opportunities for bugs what causes many waste. The dependencies also lead to less opportunities for parallelizing the work. To be able to work in group, developers need to create branches so that developers can work in isolation but this demand also to merge more often what also demand a considerable effort. 

For me bottleneck number one is Manual Testing! Manual Testing is a tedious process when the test cycles are repeated frequently. Therefore many teams adopt test automation but before they can do test automation they first need to create test data. Only when teams have adequate test data they can run automated tests, and can create that data on demand, they see better IT performance, lower change failure rates, and lower levels of deployment pain and rework. The problem with large monolitic applications is that they also go with big databases and how bigger the database how more difficult it is to manage. When the test data is difficult to setup or reason about then it become difficult to do any meaningful test automation.

Conclusion, if your database is a monolith your delivery process we’ll suffer from bottlenecks caused by lack of test automation and also by communication/coordination overhead even if you have a service oriented or microservice architecture on top of it. 

Link to my presentation about "Best practices on how to architect for faster and better delivery in the Enterprise".

Continuous Delivery in the Enterprise.pptx (3.79 mb)

In the classical view of software delivery, you need to make a trade-off between quality and speed. The traditional IT delivery process paradigm postulate that building quality software will demand longer to deliver. You trade quality with getting things done rapidly. Now, studies on teams that have adopted Continuous Delivery (CD) demonstrate exactly the opposite. Teams able to deploy by the push of a button not only deliver faster but they deliver better quality in a more reliable way.

Being able to push changes fast and reliably to production changes the rule of the game and transforms many aspects of the IT delivery process.  It reflects on aspects like:

Increased Availability & Manageability

Because you can push changes a lot faster you can make smaller changes with less downtime you don’t need to come in the middle of the night or weekends to deploy the system.  This means less overwork and stress for the team’s members. It also frees up a considerable amount of time as teams don’t need to participate at long lasting release planning's sessions to coordinate huge deployments.

Because you know you can push a change fast you’re also able to remediate faster and you don’t need to take account of being able to reverse a giant change. In place, you can adopt release strategies where you always advance forwards. In place of reverting a change you can be confident that you can fix any problem fast. This simplify the release process and lower the investment needed in process, infrastructure and tools to be able to revert back a giant change.

Reports also demonstrates that teams practicing CD sees their number of big incidents diminishing drastically. Apart from the better intrinsic quality that CD brings this is also due to the automation that CD demands.  The automated deployment pipeline eliminates errors that might result from manual configuration and error-prone practices. 

Increased efficiency and cycle time
Because you make smaller changes your tester and analyst can work in a constant flow of work.  They don’t need to test everything in a great batch at the end of the release but can continuously work in at constant pace together with the developers.

Because bugs are also detected sooner they are cheaper to fix.  When practicing continuous delivery automated tests are run immediately after each check-in what detects many bugs immediately.  The developer can get immediate feedback even before he starts working on another task and so he knows where to search for the bug.  It’s proved by many studies that bugs found before or immediately after the check-in are orders in magnitude cheaper to fix (sometimes more than 100 times).   *https://www.researchgate.net/publication/255965523_Integrating_Software_Assurance_into_the_Software_Development_Life_Cycle_SDLC

Improved testability

To be able to deploy small changes independently the systems needs to be decoupled.  This decoupling enables also to test the system more easily in isolation.  Most of the changes can be tested without deploying to an integration environment. This lowers the number of environment needed and allows for a more rapid feedback. 

Improved intrinsic product quality

Because the tremendous acceleration of time to market of a change, from once every 3 months to many times a day, product owners can experiment a lot faster enabling new product evolution strategies based on experimentation and continuous improvement.  The book Lean Enterprises describes in detail how modern software companies takes advantages of continuous delivery to design products based on experimentation.

Improved Customer Satisfaction

CD brings confidence to the customers and other stakeholders on the delivery of their new features.  CD enables to deliver new features at a constant and predictable pace and increase the visibility of the delivery process.  By practicing feature toggles and decoupling the deployment from the actual release of the feature it enables to deploy a part or a complete new capability to early adopters.  

Because organizations are more effective they can spend more time on value adding activities.  This creates a virtuous circle of continuous improvements that brings a decisive competitive advantage.  Continuous Delivery is becoming the norm in the enterprise. IT organization that still stick to the old delivery model will be forced to change or will simply disappear.  Following the 2015 State of DevOps practices study, the companies who their IT team’s practices continuous delivery has 50 % higher market capitalization growth over the 3 last years than the other and Gartner predicts that by 2020 50% of CIO’s that have not transformed their capabilities will be displaced.  

Continuous delivery is the ability to get changes into production safely and quickly in a sustainable way. 
It’s not only about deploying code in production but it’s about bringing all type of changes that helps to deliver value faster. This includes all types of IT infrastructure changes, software configuration changes, deploying data and schema migrations, …
It is a capability an enterprise need to develop and learn. Because it’s based on new paradigms that demands deep organizational changes, it’s not something an enterprise can acquire in a box but it need to develop it through a change journey.

It took Amazon or Facebook years to change their organization and architecture so that they could be sustainable by delivering faster. It can demand tremendous efforts and changes to the culture and architecture. 
Like any big change in an organization it’s not linear, how you will achieve the goal is largely unpredictable. Therefore like any change in the enterprise, it need to be carefully managed to ensure that current operations are not adversely affected.

There are numerous questions I needed to answers when mixing these technologies.

• Should I host my angular app inside an MVC View or just serve the angular app from static files.
• Should I host the angular app inside the same application that serve the Web-Api or serve it from a separate site?
• How to setup a productive development environment?
• How should I integrate angular-cli together with a ASP.NET Core app?
• Should I use Vs.Code or VisualStudio ?
• How to package and deploy the application for on prem or in the cloud?

Of course, the answer to all these questions is always the same: it depends! After experimenting with several options, I finally decided that I should go for the simplest solution that could possibly work and started with just serving static files inside a Web-Api application.  Yet, during development, what I found the most productive, is to completely separate the Angular app from the Web-Api solution. I like that my Angular and the ASP.NET Web-Api apps live separate folders beside each other. It’s only at build time that Msbuild assemble the parts by calling “ng build”.  To do that I needed to configured angular-cli to output the build in the \wwwroot folder of the ASP.NET app.

Concerning the IDE, what I found the most productivity was to develop my angular app using Vs.Code.  Thus far, for the Web-Api part I tend to prefer VisualStudio and Resharper. So, I optimized my Angular app for working with Vs.Code and my Web-Api project for VisualStudio.  During development I usually run the backend and launch the Webpack dev server through an “npm start” command.  At publish everything is nicely packaged together inside a ASP.NET app, so deploying to Azure can simply be done by using the VisualStudio publish wizard.  

On my github project core-angular-example, you can download the solution template I use for making SPA’s with Angular-cli and DotNet Core.

Here I explain the steps you need to follow to setup the basis of such an app:

0) First you need to install:

• Code
• Donetcore
• js
• Angular-cli

1) From a powershell console:

mkdir angular-dotnetcore
cd angular-dotnetcore
mkdir web-api
cd web-api
dotnet new webapi
cd ..
ng new angular-app

2) Open VisualStudio code and open the angular-dotnetcore folder

3) Disable TypeScript compilation
Since we will eventually have TypeScript files in our project, we should also disable any TypeScript compilation errors. Open the web-api.csproj file and modify the top PropertyGroup:

<PropertyGroup>

  <TargetFramework>netcoreapp2.0</TargetFramework>

  <TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>

  <TypeScriptToolsVersion>Latest</TypeScriptToolsVersion>

  <IsPackable>false</IsPackable>

</PropertyGroup>

4) Configure Startup.cs
As our web-api app will also serve the static files we need to configure the Stratup.cs file as follow:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseDefaultFiles();
    app.UseStaticFiles();

    app.Use(async (context, next) => {
        await next();
        if (context.Response.StatusCode == 404 &&
            !Path.HasExtension(context.Request.Path.Value) &&
            !context.Request.Path.Value.StartsWith("/api/")) {
                context.Request.Path = "/index.html";
                await next();
            }
    });

    // Configure application for usage as API
    // with deafult route '/api/[Controller]'
    app.UseMvcWithDefaultRoute();

    // Serve static files
    app.UseStaticFiles();
}

5) Configure angular-cli to output the build inside the wwroot of the web-api app =>
edit the .angular-cli.json file and change the OutDir parameter:

"apps": [
    {
      "root": "src",
      "outDir": "../web-api/wwwroot",

Now when running ng build inside the angular-app angular-cli should output the result inside the wwroot folder of the web-api app.

6) Modify the angular app to consume data from your web-api
Edit the following files under /angular-app/src/app file=>

App.module.ts:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';
import { HttpModule } from '@angular/http';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    HttpModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Modify app.component.ts:

import { Component, OnInit } from '@angular/core';
import { Http } from '@angular/http'
@Component({
   selector: 'app-root',
   templateUrl: './app.component.html',
   styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {
   constructor(private _httpService: Http) { }
   title = "DotNet Core Angular Example";
   apiValues: string[] = [];
   ngOnInit() {
      this._httpService.get('/api/values').subscribe(values => {
         this.apiValues = values.json() as string[];
      });
   }
}

Edit app.component.html and add this as last lines of the html file:

  <li>
    <h2>Values from ValuesController</h2>
    <p *ngFor="let value of apiValues">{{value}}</p>
  </li>
</ul>

7) Redirect api calls to your DotNet core app

To be able to redirect api calls from your angular app when running  in the webpack dev server you should create a proxy.conf.json file on the root of your angular app.  Here my dotnet webapi runs on port 5000:

{
    "/api": {
      "target": "http://localhost:5000/",
      "secure": false
    }
}

You can already test your app:

• launch the web-api app with

dotnet run

• Launch the angular app and pass the proxy configuration:

ng serve --proxy-config proxy.conf.json

• Launch Chrome and open http://localhost:4200/

8) To be able to use npm script commands edit the package.json of the angular-app and edit the script section:

"scripts": {
    "ng": "ng",
    "start": "ng serve --proxy-config proxy.conf.json",
    "build": "ng build",
    "build-prd": "ng build --prod --env=prod",

9) To be able to invoke these commands from you web-api, add a package.json inside the root of the web-api app containing.  Here we declare the same commands but first cd to the angular-app:

{
    "name": "core-angular-example",
    "version": "0.0.0",
    "license": "MIT",
    "scripts": {
        "install": "cd ../angular-app & npm install",
        "start": "cd ../angular-app & npm start",
        "build": "cd ../angular-app & npm run-script build",
        "build-prd": "cd ../angular-app & npm run-script build-prd"
    }
}

10) Finally, we configure our web-api MsBuild script to invoke the ng build script when running a release build. Therefore, we add the following targets to it:

<Target Name="EnsureNode">
  <Exec Command="node --version" ContinueOnError="true">
    <Output TaskParameter="ExitCode" PropertyName="ErrorCode" />
  </Exec>
  <Error Condition="'$(ErrorCode)' != '0'" Text="Node.js is required to build and run this project. To continue, please install Node.js from https://nodejs.org/, and then restart your command prompt or IDE." />
</Target>

<Target Name="ReleaseRunNgBuild" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Release' ">
  <CallTarget Targets="EnsureNode" />
  <Message Importance="high" Text="Install packages..." />
  <Exec Command="npm install" />
  <Message Importance="high" Text="Performing ng build for prd build..." />
  <Exec Command="npm run-script build-prd" />
</Target>

Now when you launch a Release build everything will be build together. 

You can get a package containing all your app by using the publish command.

If you want to publish your site to azure simply use the VisualStudio publish wizard or the Azure Powershell Publish commands.

There are numerous questions I needed to answers when mixing these technologies.

• Should I host my angular app inside an MVC View or just serve the angular app from static files.
• Should I host the angular app inside the same application that serve the Web-Api or serve it from a separate site?
• How to setup a productive development environment?
• How should I integrate angular-cli together with a ASP.NET Core app?
• Should I use Vs.Code or VisualStudio ?
• How to package and deploy the application for on prem or in the cloud?

Of course, the answer to all these questions is always the same: it depends! After experimenting with several options, I finally decided that I should go for the simplest solution that could possibly work and started with just serving static files inside a Web-Api application.  Yet, during development, what I found the most productive, is to completely separate the Angular app from the Web-Api solution. I like that my Angular and the ASP.NET Web-Api apps live separate folders beside each other. It’s only at build time that Msbuild assemble the parts by calling “ng build”.  To do that I needed to configured angular-cli to output the build in the \wwwroot folder of the ASP.NET app.

Concerning the IDE, what I found the most productivity was to develop my angular app using Vs.Code.  Thus far, for the Web-Api part I tend to prefer VisualStudio and Resharper. So, I optimized my Angular app for working with Vs.Code and my Web-Api project for VisualStudio.  During development I usually run the backend and launch the Webpack dev server through an “npm start” command.  At publish everything is nicely packaged together inside a ASP.NET app, so deploying to Azure can simply be done by using the VisualStudio publish wizard.  

On my github project core-angular-example, you can download the solution template I use for making SPA’s with Angular-cli and DotNet Core.

Here I explain the steps you need to follow to setup the basis of such an app:

0) First you need to install:

• Code
• Donetcore
• js
• Angular-cli

1) From a powershell console:

mkdir angular-dotnetcore
cd angular-dotnetcore
mkdir web-api
cd web-api
dotnet new webapi
cd ..
ng new angular-app

2) Open VisualStudio code and open the angular-dotnetcore folder