dotnet/aspnetcore.docs.samples

dotnet/dotnet - Home of the .NET VMR

This repository is a Virtual Monolithic Repository (VMR) which includes all the source code and infrastructure needed to build the .NET SDK.

What this means:

• Monolithic - a join of multiple repositories that make up the whole product, such as dotnet/runtime or dotnet/sdk.
• Virtual - a mirror (not replacement) of product repos where sources from those repositories are synchronized into.

In the VMR, you can find:

• source files of each product repository which are mirrored inside of their respective directories under src/,
• tooling that enables building the whole .NET product from source on Linux platforms,
• small customizations, in the form of patches, applied on top of the original code to make the build possible,
• [in future] E2E tests for the whole .NET product.

Just like the development repositories, the VMR will have a release branch for every feature band (e.g. release/8.0.1xx). Similarly, VMR's main branch will follow main branches of product repositories (see Synchronization Based on Declared Dependencies).

More in-depth documentation about the VMR can be found in VMR Design And Operation. See also dotnet/source-build for more information about our whole-product source-build.

Goals

• The main purpose of the dotnet/dotnet repository is to have all source code necessary to build the .NET product available in one repository and identified by a single commit.
• The VMR also aims to become the place from which we release and service future versions of .NET to reduce the complexity of the product construction process. This should allow our partners and and 3rd parties to easily build, test and modify .NET using their custom infrastructure as well as make the process available to the community.
• Lastly, we hope to solve other problems that the current multi-repo setup brings:
  • Enable the standard down-/up-stream open-source model.
  • Fulfill requirements of .NET distro builders such as RedHat or Canonical to natively include .NET in their distribution repositories.
  • Simplify scenarios such as client-run testing of bug fixes and improvements. The build should work in an offline environment too for certain platforms.
  • Enable developers to make and test changes spanning multiple repositories.
  • More efficient pipeline for security fixes during the CVE pre-disclosure process.

We will achieve these goals while keeping active coding work in the separate repos where it happens today. For example: ASP.NET features will continue to be developed in dotnet/aspnetcore and CLR features will be continue to be developed in dotnet/runtime. Each of these repos have their own distinct communities and processes, and aggregating development into a true mono-repo would work against that. Hence, the "virtual" monolithic repo: the VMR gives us the simplicity of a mono-repo for building and servicing the product, while active development of components of that product stays in its various existing repos. The day to day experience for typical contributors will not change.

Limitations

This is a work-in-progress. There are considerable limitations to what is possible at the moment. For an extensive list of current limitations, please see Temporary Mechanics.
See the Unified Build roadmap for more details.

Supported platforms

• 8.0
  • source-build configuration on Linux
• 9.0+ (WIP)
  • source-build configuration on Linux
  • non-source-build configuration on Linux, Mac, and Windows

For the latest information about Source-Build support for new .NET versions, please check our GitHub Discussions page for announcements.

Code flow

For the time being, the source code only flows one way - from the development repos into the VMR. More details on this process:

• Source Synchronization Process
• Synchronization Based on Declared Dependencies
• Moving Code and Dependencies between the VMR and Development Repos

We expect the code flow to start working both ways in the .NET 9 timeframe. See the Unified Build roadmap for more details.

Contribution

At this time, the VMR will not accept any changes and is a read-only mirror of the development repositories only. Please, make the changes in the respective development repositories (e.g., dotnet/runtime or dotnet/sdk) and they will get synchronized into the VMR automatically.

Dev instructions

Please note that this repository is a work-in-progress and there are some usability issues connected to this. These can be nuisances such as some checked-in files getting modified by the build itself and similar. For the latest information about Source-Build support, please watch for announcements posted on our GitHub Discussions page.

Prerequisites

The dependencies for building can be found here. In case you don't want to / cannot prepare your environment per the requirements, consider using Docker.

Building

1. Clone the repository

   git clone https://github.com/dotnet/dotnet dotnet-dotnet
   cd dotnet-dotnet

2. Build the .NET SDK

   Choose one of the following build modes:

   • Microsoft based build

     For Unix:

     ./build.sh --clean-while-building

     For Windows:

     .\build.cmd -cleanWhileBuilding

   • Building from source

     # Prep the source to build on your distro.
     # This downloads a .NET SDK and a number of .NET packages needed to build .NET from source.
     ./prep-source-build.sh
     
     # Build the .NET SDK
     ./build.sh -sb --clean-while-building

   The resulting SDK is placed at artifacts/assets/Release/dotnet-sdk-9.0.100-[your-RID].tar.gz (for Unix) or artifacts/assets/Release/dotnet-sdk-9.0.100-[your-RID].zip (for Windows).

3. (Optional) Unpack and install the .NET SDK

   For Unix:

   mkdir -p $HOME/dotnet
   tar zxf artifacts/assets/Release/dotnet-sdk-9.0.100-[your-RID].tar.gz -C $HOME/dotnet
   ln -s $HOME/dotnet/dotnet /usr/bin/dotnet

   For Windows:

   mkdir %userprofile%\dotnet
   tar -xf artifacts/assets/Release/dotnet-sdk-9.0.100-[your RID].zip -C %userprofile%\dotnet
   set "PATH=%userprofile%\dotnet;%PATH%"

   To test your built SDK, run the following:

   dotnet --info

Note

Run ./build.sh --help (for Unix) or .\build.cmd -help (for Windows) to see more information about supported build options.

Building using Docker

You can also build the repository using a Docker image which has the required prerequisites inside. The example below creates a Docker volume named vmr and clones and builds the VMR there.

docker run --rm -it -v vmr:/vmr -w /vmr mcr.microsoft.com/dotnet-buildtools/prereqs:centos-stream8
git clone https://github.com/dotnet/dotnet .

# - Microsoft based build
./build.sh --clean-while-building

# - Building from source
./prep-source-build.sh && ./build.sh -sb --clean-while-building

mkdir -p $HOME/.dotnet
tar -zxf artifacts/assets/Release/dotnet-sdk-9.0.100-centos.8-x64.tar.gz -C $HOME/.dotnet
ln -s $HOME/.dotnet/dotnet /usr/bin/dotnet

Codespaces

You can also utilize GitHub Codespaces where you can find preset containers in this repository.

Building from released sources

You can also build from sources (and not from a context of a git repository), such as the ones you can acquire from a dotnet/dotnet release. In this case, you need to provide additional information which includes the original repository and commit hash the code was built from so that the SDK can provide a better debugging experience (think the Step into.. functionality). Usually, this means the dotnet/dotnet repository together with the commit the release tag is connected to.

In practice, this means that when calling the main build script, you need to provide additional arguments when building outside of a context of a git repository.
Alternatively, you can also provide a manifest file where this information can be read from. This file (release.json) can be found attached with the dotnet/dotnet release.

Synchronizing code into the VMR

Sometimes you want to make a change in a repository and test that change in the VMR. You could of course make the change in the VMR directly (locally, as the VMR is read-only for now) but in case it's already available in your repository, you can synchronize it into the VMR (again locally).

To do this, you can either start a dotnet/dotnet Codespace - you will see instructions right after it starts. Alternatively, you can clone the repository locally and use the vmr-sync.sh or vmr-sync.ps1 script to pull your changes in. Please refer to the documentation in the script for more details.

List of components

The full list of components synchronized into the VMR is here (Components.md).

The repository also contains a JSON manifest listing all components in a machine-readable format.

Filing Issues

This repo does not accept issues as of now. Please file issues to the appropriate development repos. For issues with the VMR itself, please use the source-build repository.

Useful Links

• Design documentation for the VMR - a set of documents describing the high-level design and the why's and how's
  • Design and Operation
  • Upstream/Downstream Relationships
  • Code and Build Workflow
  • Strategy for Managing External Source Dependencies
• .NET Source-Build
• What is .NET

.NET Foundation

.NET Runtime is a .NET Foundation project.

License

.NET is licensed under the MIT license.

aspnetcore.docs.samples's Issues

separate the unit tests from the integration tests into different projects

See the note just above Test app prerequisites

When creating a test project for an app, separate the unit tests from the integration tests into different projects. This helps ensure that infrastructure testing components aren't accidentally included in the unit tests. Separation of unit and integration tests also allows control over which set of tests are run.

@fiyazbinhasan can you split out your integration and unit tests?

Clean up IAuthorizationRequirementData

See Improved support for custom authorization policies with IAuthorizationRequirementData

ToDo:

• Fix all the null warnings and other warnings
• Fix 415 error

See the project here

1. Create a token and DOB via this command and save token
2. run the app
3. curl -i -H "Authorization: Bearer <token>" http://localhost:{port}/api/greetings/hello

Output shows:

Evaluating authorization requirement for age >= 16
info: MinimumAgeAuthorizationHandler[0]
      Minimum age authorization requirement 16 satisfied

But request returns a 415 error.

@kevinchalet can you help? CC @jxwaters if you can help

contributes to dotnet/AspNetCore.Docs#29291

problem details service from middleware

Create sample that generates a problem details response from middleware:

@sammychinedu2ky are you interested in this?

Change Integration tests to use SQLite rather than SQL Server

https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/test/integration-tests/IntegrationTestsSample

See the sentence just above this link

The EF-Core in-memory database provider can be used for limited and basic testing, however the SQLite provider is the recommended choice for in-memory testing.

Antiforgery integration for minimal APIs

See Antiforgery integration for minimal APIs

and this sample

In this code I pass in the action so

app.MapGet("/DisableAntiforgery", () =>
{
    return Results.Content(MyHtml.html("/todo"), "text/html");
});

app.MapGet("/post2", () =>
{
    return Results.Content(MyHtml.html("/todo2"), "text/html");
});

Can use the same HTML when they pass in the action arg.

Is there a clean way to do this to pass in an arg for

<input name="{token.FormFieldName}" 
                              type="hidden" value="{token.RequestToken}" />

Maybe that makes things too messy. Perhaps I should duplicate most of the HTML and not get the HTML from a method while passing the action.

public static string html2(string action, AntiforgeryTokenSet token) => $"""
    <html><body>
        <form action="{action}" method="POST" enctype="multipart/form-data">
            <input name="{token.FormFieldName}" 
                          type="hidden" value="{token.RequestToken}" />
            <input type="text" name="name" />
            <input type="date" name="dueDate" />
            <input type="checkbox" name="isCompleted" />
            <input type="submit" />
        </form>
    </body></html>
""";

Works, but I'm not sure it's an improvement. There's no way to pass in a null token.

@sammychinedu2ky @david-acker

cc @guardrex

app.MapPost("/fileUp", async (IFormFile file)

See https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-net-7-preview-1/
Put in https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/fundamentals/minimal-apis/samples/IFormFile

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapPost("/fileUp", async (IFormFile file) =>
{
    string tempfile = Path.GetTempFileName();
    using var stream = File.OpenWrite(tempfile);
    await file.CopyToAsync(stream);
});

app.MapPost("/FilesUp", async (IFormFileCollection myFiles) =>
{
    foreach (var file in myFiles)
    {
        string tempfile = Path.GetTempFileName();
        using var stream = File.OpenWrite(tempfile);
        await file.CopyToAsync(stream);
    }
});

app.Run();

Update readme.txt with instructions on testing.

Create sample using IProblemDetailsWriter

IProblemDetailsWriter from problem details response

In https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/fundamentals/middleware/problem-details-service or write a new sample in https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/fundamentals/middleware

cc @sammychinedu2ky

Add Blazor WebAssembly standalone identity example

An example of how to use the new identity API with a standalone Blazor WebAssembly app.

Remove unnecessary code from RDG samples

See this comment

[JsonSerializable(typeof(Todo[]))]
internal partial class AppJsonSerializerContext : JsonSerializerContext

And more can likely be removed from many of these samples

cc @timdeschryver

Which license applies to the examples?

Could you please provide the license information for your examples? We are uncertain which license applies to the examples and would appreciate it if you could add the relevant license information to the repository. Additionally, we would like to confirm if it is permissible to use the examples (e.g. test/integration-tests/IntegrationTestsSample) in our own public repository. Thank you.

Update ASP.NET Core streaming sample

ASP.NET Core streaming sample to be cross platform. See this comment

@logiclrd do you have an ETA for that?

Update tests to use TypedResults

Change this line to

 public static async Task<Ok<Todo[]>> GetAllTodos(TodoGroupDbContext database)
    {
        var todos = await database.Todos.ToArrayAsync();
        return TypedResults.Ok(todos);
    }

and changed test that uses that endpoint

cc @fiyazbinhasan

Related to dotnet/AspNetCore.Docs#28850

rewritten test must include test of returned result type

/ Assert: Check the returned result type is correct
    Assert.IsType<Ok<Todo[]>>(result);

Shorten long lines of code in FormBinding sample

Trying to avoid horizontal scroll bars in the rendered articles.

Self-describing minimal APIs with IEndpointMetadataProvider and IEndpointParameterMetadataProvider

Create sample code. See https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-7-preview-4/

Possibly same code can do dotnet/sdk#77

Example of Using 2FA with ASP.NET Core Identity and Angular

Hello everyone!

I've been delving into the Identity Documentation, particularly the sections covering 2FA with Razor Pages, and it's been an enlightening experience!

However, I'm currently facing a gap in documentation when it comes to integrating 2FA with Single Page Applications (SPAs).

Would it be possible to provide a comprehensive example for 2FA with ASP.NET Core Identity and Angular? I'm specifically interested in understanding how to leverage endpoints for seamless SPA integration. Unfortunately, I couldn't find any information related to 2FA TOTP in the Angular Sample.

This addition would immensely benefit developers looking for a thorough guide on 2FA integration with Angular. Your efforts in this regard would be highly appreciated! Thank you!

OpenAPI improvements for minimal APIs sample code

Write sample in https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/fundamentals/minimal-apis/samples/openApi (create folder openApi)

OpenAPI improvements for minimal APIs

write sample using service for rate limit

Use a service per #13 (comment)

Put the code in this folder and delete the readme.md.

Why is that necessary?

Trying to do the Arrangement based on IndexPageTests.cs but a failure came and said that no such table.

Until

db.Database.EnsureCreated();

was added in a line before

Utilities.ReinitializeDbForTests(db);

So it's look like this
db.Database.EnsureCreated();
Utilities.ReinitializeDbForTests(db);

I am wondering, why is it necessary

https://github.com/dotnet/AspNetCore.Docs.Samples/blob/main/test/integration-tests/IntegrationTestsSample/tests/RazorPagesProject.Tests/IntegrationTests/IndexPageTests.cs

IProblemDetailsService.WriteAsync with API controller

See the middleware version

/api/values/Squareroot/-1 returns the generic type and title
{"type":"https://tools.ietf.org/html/rfc7231#section-6.5.1","title":"Bad Request",
not the type and title that's set
{"type":"https://en.wikipedia.org/wiki/Square_root","title":"Wrong Input"

When I Customize problem details with CustomizeProblemDetails see also source code

the API controller returns the correct problem details.

When I step through the middleware version in the debugger, everything is set correctly.

@sammychinedu2ky

Unneeded reference

https://github.com/dotnet/AspNetCore.Docs.Samples/blob/f0867786d7a46a80ce19d10950f9816a4071abae/fundamentals/minimal-apis/samples/MinApiTestsSample/IntegrationTests/IntegrationTests.csproj#L13C48-L13C48

As dotnet test tool suggests, this ref is only needed in .NET Core projects, but not in .NET 7

Add options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;

Add options.RejectionStatusCode = StatusCodes.Status429TooManyRequests; to JWT sample

@Kahbazi can you PR that?

Create samples for Route groups with MapGroup

Need dedicated sample for Route groups with MapGroup
@sammychinedu2ky can you create a PR here with your code from dotnet/AspNetCore.Docs#26476 so we have code dedicated to route groups. I think maintaining the same code for testing and routegroups might be a problem.

Create a folder routeGroups under https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/fundamentals/minimal-apis/samples

Create sample with ModelState.AddModelError

In https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/mvc/models folder

Use in memory DB.
also show how to add a model error to the model, not the property:

ModelState.AddModelError(string.Empty, "My error message");

see dotnet/AspNetCore.Docs#27861

sample: Return multiple result types from minimal APIs

Return multiple result types from minimal APIs

Possibly same code can do #76

Update validation sample to include Name and ShortName

Update the model:

public class Contact
{
    public int Id { get; set; }

    public string Name { get; set; } = String.Empty;
    public string ShortName { get; set; } = String.Empty;
    public string Email { get; set; } = String.Empty;
    public string PhoneNumber { get; set; } = String.Empty;
}

Then have a validation check like:

        if (Contact.Name == Contact.ShortName) {
            ModelState.AddModelError(nameof(Contact.ShortName),
                                               "Short name can't be the same as Name.");
        }

Code at https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/mvc/models/ModelStateError

It's easier to delete the existing code and create a new project and scaffold it.

Bonus points if you move from MVC to Razor Pages.

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 0156ffc3-47ac-d5da-fbc2-9ff5018b071b
• Version Independent ID: 615db388-a244-41f7-21b5-a4085d9ed479
• Content: Model validation in ASP.NET Core MVC
• Content Source: aspnetcore/mvc/models/validation.md
• Product: aspnet-core
• Technology: aspnetcore-mvc
• GitHub Login: @Rick-Anderson
• Microsoft Alias: riande

---

Fix possible null warning in test API

fundamentals/minimal-apis/samples/IResultImplementation/Tests/IResultImplementationTest.cs

Typed results for minimal APIs

See Typed results for minimal APIs

It would be great to have the sample from that blog here. You can get the starter project code from https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/tutorials/first-web-api/samples/6.0/TodoApi

Create your new project in a new folder typed-results under https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/fundamentals/minimal-apis/samples

See tests in https://github.com/dotnet/aspnetcore/tree/main/src/Mvc/Mvc.ApiExplorer/test

cc @sammychinedu2ky if you're interested.

@brunolins16 is the expert on this. See dotnet/aspnetcore#40656

IResult implementation types are now publicly available

In MinApiTestsSample, create at least one sample that uses the IResult implementation types are now publicly available from Improved unit testability for minimal route handlers

@brunolins16 dotnet/aspnetcore#40965 mentions all these <HTTP Status>HttpResult mentioned in the blog, but they're no longer in the source and I can't find a PR where they were renamed. The history of Results.cs doesn't make the renaming obvious. Please advise.

Problem details sample returns Division_by_zero when it should return 404

Problem details code returns

{"type":"https://wikipedia.org/wiki/Division_by_zero",
"title":"Wrong Input",
"status":404,
"detail":"Divison by zero is not defined."}

When there is no endpoint rather than just 404.

@sammychinedu2ky fixed that by adding HasPath, but that's an error prone solution.

@brunolins16 can you suggest a better mechanism to detect when there's no matching endpoint?

Rate limiter provides no feedback when limit is hit

Consider the following code:

using Microsoft.AspNetCore.RateLimiting;
using System.Threading.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRateLimiter(_ => _
    .AddFixedWindowLimiter(policyName: "fixed", options =>
    {
        options.PermitLimit = 4;
        options.Window = TimeSpan.FromSeconds(120);
        options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        options.QueueLimit = 2;
    }));

var app = builder.Build();

app.UseRateLimiter();

static string GetTicks() => (DateTime.Now.Ticks & 0x11111).ToString("00000");

app.MapGet("/", () => Results.Ok($"Hello {GetTicks()}"))
                           .RequireRateLimiting("fixed");

app.Run();

Browse to / on localhost and quickly hit refresh multiple times. After the rate limit is hit, the browser doesn't show a problem, it's displaying the last response. F12 tools don't show any thing and there is nothing in the log.

@wtgodbe how can the client be notified? What's the best way to log this? Why isn't the default rejection status 503 returned?
cc @fiyazbinhasan

.NET 7 RC1 improvements to Rate limiting middleware

Rate limiting middleware improvements

• Code to update
• Add [EnableRateLimitingAttribute("MyControllerPolicy")] to Home2Controller
• disable rate limiting on a specific endpoint within that group
• apply policies directly to endpoints.
• add an instance of it directly to an endpoint
• Add

builder.Services.AddRateLimiter(options =>
{
   options.AddTokenBucketLimiter("MyControllerPolicy", options =>
   {
       options.TokenLimit = 1;
       options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
       options.QueueLimit = 1;
       options.ReplenishmentPeriod = TimeSpan.FromSeconds(10);
       options.TokensPerPeriod = 1;
   })
   .AddPolicy<string>("MyGroupPolicy", new MyRateLimiterPolicy());
});

Then @Rick-Anderson can update Rate limiting middleware in ASP.NET Core

@Kahbazi can you do these updates?

Also, the updates requested in #14

Rationalize EXPOSE instructions

EXPOSE instructions should have the following characteristics:

• Match ASP.NET Core defaults.
• No TLS/HTTPS since that's a deployment concern

Ideally, we wouldn't need to use EXPOSE at all, but I'm guessing that VS Code relies on it.

https://github.com/search?q=repo%3Adotnet%2FAspNetCore.Docs.Samples%20EXPOSE&type=code

FYI for .NET 8: dotnet/core#8133 (comment)