csharp-sdk/.github/skills/prepare-release/references/readme-snippets.md

README Code Sample Validation

This reference describes how to validate that C# code samples in README files compile against the current SDK.

Which READMEs to Validate

Validate code samples from the package README files — these are shipped with NuGet packages and are the primary documentation users see:

README	Package
README.md (root)	ModelContextProtocol
src/ModelContextProtocol.Core/README.md	ModelContextProtocol.Core
src/ModelContextProtocol.AspNetCore/README.md	ModelContextProtocol.AspNetCore

Sample README files (samples/*/README.md) are excluded — the samples themselves are buildable projects and are validated by CI.

What to Extract

Extract only fenced code blocks tagged as csharp (```csharp). Skip blocks tagged as plain ``` (shell commands, install instructions) or any other language.

Handling Incomplete Snippets

README samples are often incomplete — they use ... for placeholder values, omit using directives, or show only a method body. The validation wrapper must account for this:

• Placeholder expressions like IChatClient chatClient = ...; — replace ... on the right-hand side of assignments with null!
• Missing usings — the wrapper file supplies all common namespaces (see template below)
• Top-level statements — wrap in an async Task method so await works
• Suppressed warnings — disable CS1998 (async without await), CS8321 (unused local function), and similar non-substantive warnings

Snippets That Cannot Be Validated

Some code blocks are illustrative fragments that cannot compile even with wrappers (e.g., partial class definitions shown in isolation, pseudo-code). If a snippet fails to compile after applying the standard fixups, examine the error:

• API mismatch (missing member, wrong type, wrong signature) → this is a real bug in the README that must be reported and fixed
• Structural issue (missing context, incomplete fragment) → exclude this specific snippet from validation with a comment explaining why

Test Project Approach

Create a temporary test project that references the SDK projects, wraps each README's code samples in compilable methods, and builds.

Project File Template

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <OutputType>Library</OutputType>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <LangVersion>preview</LangVersion>
    <NoWarn>CS1998;CS8321;CS0168;CS0219;CS1591;CS8602</NoWarn>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\..\src\ModelContextProtocol\ModelContextProtocol.csproj" />
    <ProjectReference Include="..\..\src\ModelContextProtocol.AspNetCore\ModelContextProtocol.AspNetCore.csproj" />
  </ItemGroup>
</Project>

Place the project at tests/ReadmeSnippetValidation/ReadmeSnippetValidation.csproj.

Source File Template

Create one .cs file per README. Each file wraps the README's code blocks in static methods inside a class. Use this pattern:

#pragma warning disable CS1998
#pragma warning disable CS8321

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;
using ModelContextProtocol.Server;
using System.ComponentModel;
using System.Text.Json;

namespace ReadmeSnippetValidation;

public static class RootReadmeSamples
{
    // Snippet 1: Client example
    public static async Task ClientExample()
    {
        // ... pasted snippet code ...
    }

    // Snippet 2: Server example
    public static async Task ServerExample()
    {
        // ... pasted snippet code ...
    }

    // Snippet with attributed types (tools, prompts) go as nested or sibling types
    [McpServerToolType]
    public static class EchoTool
    {
        [McpServerTool, Description("Echoes the message back to the client.")]
        public static string Echo(string message) => $"hello {message}";
    }
}

Build Commands

# Restore and build the validation project
dotnet restore tests/ReadmeSnippetValidation/ReadmeSnippetValidation.csproj
dotnet build tests/ReadmeSnippetValidation/ReadmeSnippetValidation.csproj

### Cleanup

After validation, **always delete** the `tests/ReadmeSnippetValidation/` directory. It must not be committed.

## Reporting Results

### All Snippets Compile

Report success and move to the next step:
> ✅ All README code samples compile successfully against the current SDK.

### Compilation Failures

For each failure:
1. Identify the README file and which code block failed
2. Show the compiler error
3. Classify the error:
   - **API mismatch**: The README uses an API that doesn't exist or has a different signature. This indicates the README is outdated and needs updating.
   - **Structural**: The snippet is a fragment that can't be wrapped. Note it for exclusion.
4. For API mismatches, investigate the correct current API and propose a fix
5. Present all findings to the user for confirmation before making any README edits

### Fixing Issues

If the user approves fixes:
1. Edit the README files directly with minimal, surgical changes
2. Re-run the validation build to confirm fixes compile
3. Ensure the overall solution still builds: `dotnet build`
4. Include the README fixes in the same release or as a prerequisite PR — the user decides