dotnet/samples: The Code Behind the .NET Documentation

What dotnet/samples is for, and who should clone it

Every code listing that appears inside a topic under the .NET documentation has a home in this repository. The README states that the repo "contains all the sample code that is part of any topic under the .NET documentation," and that the sub-folders are organized similarly to the docs themselves. That single sentence defines the audience. If you are reading a page about LINQ query syntax, async patterns, or MSBuild targets and you want the exact project the page was written against, this is where it lives.

It is not a library, a template gallery, or a scaffold generator. Nothing here is published to NuGet, and the README never suggests copying a folder as the starting point for a product. The value is verification: a sample that builds is a claim you can check rather than trust. The cost is that the repository is a mirror of the docs, so its shape changes when the docs change, not when a release ships. The most recent release listed on the repository is from 2020, while the last push to the default branch was on 2026-09-18, which tells you the day-to-day activity is maintenance of existing samples rather than new releases.

How the repository is laid out and what a sample must contain

The top level is a set of topic areas rather than a single solution: async/, azure/, core/, csharp/, framework/, iot/, machine-learning/, mef/, msbuild/, orleans/, standard/, upgrades/, windowsforms/, wpf/, plus github-actions/. That list is the fastest way to judge whether a subject you care about is covered. If you need a Windows Forms example, go to windowsforms/. If you need an Orleans grain, go to orleans/. There is no index file that maps a docs URL to a folder, so you navigate by topic name.

The contribution rules in the README are the real specification, and they are stricter than they first look. A sample must be part of a buildable project, and where possible the project should build on every platform .NET Core supports, with the explicit exception of samples that demonstrate a platform-specific feature or tool. Samples should follow the runtime coding style, and the README adds a preference for static methods over instance methods when the sample does not need an object. Exception handling is required, and the rule is specific: handle the exceptions the called method actually throws, not Exception or SystemException. That last point is the one most likely to trip up a contributor, because it turns a stylistic guideline into a reviewable condition.

Building and running a sample from the command line

The README gives a two-command workflow that works for any .NET Core sample. Change into the sample's directory, then build and run. The SDK is a prerequisite; the README points to the .NET Core SDK download page for it.

dotnet build
dotnet run

The first command restores any needed dependencies and compiles the project, so a failure here is usually a missing SDK feature band or a target framework your installed SDK no longer carries. The second command executes the project. For a console sample you should see its console output in the same terminal.

Multi-project samples differ. The README says those have instructions in their root directory in a README.md file, so read that before running anything. A few samples are specific to Visual Studio and require Visual Studio 2017 or later, and others target the .NET Framework, run only on Windows, and need the Developer Pack for the target framework version. The README does not document rollback or pinning a specific SDK version, so if a build fails on framework resolution the repository gives you no prescribed fix.

If you are adding a sample rather than running one, the README's sequence is: file or comment on an issue in dotnet/docs, write the topic that explains the concept, write the sample, and add a Program.cs entry point that calls it. The example it gives looks like this.

public class Program
{
    public void Main(string[] args)
    {
        WhereClause1.QuerySyntaxExample();

        // Add the method syntax as an example.
        WhereClause1.MethodSyntaxExample();
    }
}

Each sample also needs a README.md in its root directory with a brief description and a pointer to the article that references it. The README advises against checking in a solution file when it contains only one project.

Where the repository stops being the right tool

The clearest boundary is issue handling. Issues are turned off on this repository. The README directs bug reports for existing samples and suggestions for new ones to dotnet/docs or dotnet/dotnet-api-docs, and says that if you are unsure, choose dotnet/docs. The stated reason is to keep issues attached to the articles that explain each sample's concepts. Practically, that means a broken sample is reported on the documentation page that quotes it, not in the repository where the code lives. If your workflow assumes you can open a ticket next to the code, this repository will not support it.

A second boundary is portability. The README's own list of exceptions is long: Visual Studio-only samples, platform-specific samples, and .NET Framework samples that run only on Windows. The promise of cross-platform builds is qualified by "except where noted," and the notes live in individual sample READMEs. A sample that looks like a clean console project can still be Windows-bound.

The third boundary is stability. This is documentation support code, and the folder structure follows the docs. Nothing in the README promises API stability, semantic versioning, or a deprecation window. Build a product on top of a file you found here and you own that file, including every future framework change.

dotnet/samples compared with dotnet/runtime and the docs themselves

The nearest alternative for a working code reference is the product repository itself. dotnet/runtime carries its own coding-style document, which the samples README links to as the style samples should conform to. The difference in approach is purpose. Runtime samples exist to exercise and validate the runtime, and they live beside the code they test. The samples here exist to be quoted by a documentation page, and they are organized to match that page's location in the docs tree. If you want to see how a feature behaves under the project's own test infrastructure, go to the product repository. If you want the exact snippet a docs page shows you, go here.

The other alternative is to skip the repository and read the docs page alone. That is faster and often enough, because each sample's README.md points back to the article. The trade is that you cannot run the code, and running it is the only way to see which target framework it actually needs and whether it still builds with your SDK. For a reader who just wants the syntax, the docs page wins. For a reader debugging a mismatch between what the page says and what their compiler says, the sample project is the tiebreaker.

Licence, maintenance and the cost of keeping a sample working

The repository carries two licence files, LICENSE and LICENSE-CODE, and the repository metadata identifies the licence as CC-BY-4.0. The split between a content licence and a code licence is worth noticing before you reuse anything, because the terms that apply to a code sample and the terms that apply to prose in a README may not be the same. Read both files and confirm which one covers the specific folder you intend to reuse. Nothing in the README addresses attribution requirements for downstream use, so that question has to be answered from the licence text itself, not from the documentation.

Maintenance cost is the part contributors underestimate. The README asks that samples build on the widest set of platforms possible, and it names the runtimes the CI build system uses for standalone packages: win7-x64, win8-x64, win81-x64, and ubuntu.16.04-x64. Those are old runtime identifiers, and they sit next to a promise of a cross-platform build. A contributor adding a sample inherits that tension: satisfy the stated runtime list, or argue in the sample's README why the sample is an exception. The repository also runs version-sweep and build-validation workflows, visible as badges in the README, and a dotnet-versionsweeper.json file sits at the top level. That machinery is what keeps hundreds of small projects compiling as target frameworks move, and it is the reason the last push date is recent even though the newest listed release is from 2020.

What to check before you depend on a sample

Start with the folder's own README.md. The README states that each sample has one and that it explains the sample and links to more resources. If a folder has no README, treat the sample as unverified against the contribution rules.

Next, check the target framework in the project file against the SDK you have installed. The README's build instructions assume the .NET Core CLI, and the exception list explicitly includes samples that need the .NET Framework Developer Pack. A build failure at restore time is more often a framework mismatch than a code defect.

Finally, decide what you are doing with the code. Reading it, running it, and copying it are three different activities with three different risk levels. The repository is built for the first two. The third is governed by the licence files, and the README does not walk you through it.

Editorial conclusion

Adopt dotnet/samples when you are reading a .NET docs page and want to run the code it quotes, or when you are adding a sample to a docs topic and need to follow the repository's buildable-project rules. Do not adopt it as an application template or a package dependency: it is not distributed as a library, and issues are turned off here, so any bug report goes to dotnet/docs or dotnet/dotnet-api-docs instead. Before you rely on a subfolder, check that its own readme.md exists and that the project targets a framework your SDK still supports.

Frequently asked questions

Official sources

1. dotnet/samples on GitHub
2. License: CC-BY-4.0
3. Project website
4. README
5. Releases