skip to content

A .NET 10 class library holding a courier start-up's shared ASP.NET Core middleware needs HttpContext and ControllerBase — how should its project file reference ASP.NET Core?

level: seniorimportance: should knowfreq 28%

answer

  1. keep Microsoft.NET.Sdk
  2. FrameworkReference, not PackageReference
  3. NETSDK1080 on the old metapackage
  4. Web SDK forces OutputType Exe
  5. Razor UI: Microsoft.NET.Sdk.Razor

basics

~10 s

Keep the library on Microsoft.NET.Sdk and add FrameworkReference Include="Microsoft.AspNetCore.App". Neither the Web SDK, which makes it an executable, nor a PackageReference to the old metapackage or 2.x Microsoft.AspNetCore.* packages is right.

solid answer

~40 s

A library that uses ASP.NET Core types stays on `Microsoft.NET.Sdk` and adds `<FrameworkReference Include="Microsoft.AspNetCore.App" />`. That compiles it against the shared framework the host app already runs on, so versions always match. Switching the library to `Microsoft.NET.Sdk.Web` sets `OutputType` to `Exe` and `IsPackable` to `false`, so a library with no entry point stops building and cannot be packed. A `PackageReference` to `Microsoft.AspNetCore.App` raises NETSDK1080 and is swapped for the framework reference. Old `Microsoft.AspNetCore.*` packages such as `Microsoft.AspNetCore.Mvc.Core` are no longer produced since 3.0, so referencing them pins 2.x-era assemblies. Pieces outside the shared framework, such as `Microsoft.AspNetCore.Authentication.JwtBearer`, stay `PackageReference`s; a library with Razor views or components uses `Microsoft.NET.Sdk.Razor` instead.

code

xml · 14 lines
xml
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.12" />
  </ItemGroup>

</Project>

go deeper

for a junior

Recall that ASP.NET Core types reach a non-web project through a FrameworkReference to Microsoft.AspNetCore.App, not a NuGet package.

for a middle

Explain why the Web SDK makes a library an executable, what NETSDK1080 means, and which add-on packages still need PackageReferences.

for a senior

Review shared-library project files: catch 2.x Microsoft.AspNetCore.* packages, Web SDK libraries and missing out-of-framework packages before they cause version conflicts.

for a principal

Decide which cross-cutting web code lives in shared libraries versus each service, and how their ASP.NET Core version moves with the hosts.

## The situation A courier start-up has two web projects — a parcel-locker API and a Razor Pages admin site — and wants one library, `Couriers.Web.Shared`, for a correlation-id middleware, a base `ApiControllerBase`, some `IEndpointFilter`s and extension methods on `IServiceCollection`. Those types live in ASP.NET Core: `HttpContext` and `RequestDelegate` in `Microsoft.AspNetCore.Http`, `ControllerBase` in `Microsoft.AspNetCore.Mvc`. The question is how the library's `.csproj` gets them. ## The right reference ```xml <Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>net10.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> </PropertyGroup> <ItemGroup> <FrameworkReference Include="Microsoft.AspNetCore.App" /> </ItemGroup> </Project> ``` `Microsoft.AspNetCore.App` is the **ASP.NET Core shared framework**, installed with the ASP.NET Core runtime. A **`FrameworkReference`** compiles against that framework's reference assemblies and records a dependency on it; it restores nothing from NuGet. Because the web apps load the same shared framework at run time, the library can never disagree with the host about which version of `HttpContext` it gets. The SDK also flows framework references transitively by default, so a test project referencing the library sees the shared framework too (`DisableTransitiveFrameworkReferences` turns that off). ## Why the alternatives go wrong | Attempt | What happens | |---|---| | `Sdk="Microsoft.NET.Sdk.Web"` on the library | The Web SDK sets `OutputType` to `Exe`, so a project with no entry point fails to build; it also sets `IsPackable` to `false` and server GC, none of which a library wants | | `<PackageReference Include="Microsoft.AspNetCore.App" />` | The .NET SDK raises **NETSDK1080** ("not necessary when targeting .NET Core 3.0 or higher"), removes it and adds the framework reference itself — dead weight that misleads readers | | `PackageReference`s to individual `Microsoft.AspNetCore.*` assemblies such as `Microsoft.AspNetCore.Mvc.Core` or `Microsoft.AspNetCore.Http.Abstractions` | Since .NET Core 3.0 those assemblies ship only inside the shared framework (the source marks them `IsAspNetCoreApp`; `Mvc.Core` is `IsPackable` false), so the newest packages are 2.x-era builds — old APIs at compile time and version conflicts with the host | | No reference, copying types instead | Duplicated abstractions that the framework will not recognise as its own | ## What still needs a package The shared framework is not all of ASP.NET Core. A library that configures JWT bearer authentication needs `Microsoft.AspNetCore.Authentication.JwtBearer`; one that customises OpenAPI documents needs `Microsoft.AspNetCore.OpenApi`; one that touches Identity's EF Core stores needs `Microsoft.AspNetCore.Identity.EntityFrameworkCore`. Those are ordinary `PackageReference`s **alongside** the framework reference, and their versions should track the host's ASP.NET Core version (central package management helps). ## Libraries with UI If the shared library also carries Razor Pages, views or Razor components — say a common login partial for the admin site — it uses **`Microsoft.NET.Sdk.Razor`**, the Razor class library SDK that `dotnet new razorclasslib` writes. The Razor SDK compiles `.cshtml` and `.razor` files and packages static web assets; it does not set `OutputType` to `Exe`. A library that only needs server-side MVC types adds the same `FrameworkReference`. ## Checklist for review 1. The library's `Sdk` is `Microsoft.NET.Sdk` (or `Microsoft.NET.Sdk.Razor` for UI), never `Microsoft.NET.Sdk.Web`. 2. It has `<FrameworkReference Include="Microsoft.AspNetCore.App" />` and no `Microsoft.AspNetCore.App` package. 3. No `Microsoft.AspNetCore.*` package that is part of the shared framework appears in its `PackageReference`s. 4. Out-of-framework packages (JwtBearer, OpenApi, Identity stores) are referenced explicitly and versioned with the host. 5. Code moved out of a web project gets its missing `using` lines back: the library's implicit usings are the base SDK's seven only. A library built this way adds no ASP.NET Core package to the consuming app's dependency graph: the app itself supplies the shared framework the library compiled against. ## Why interviewers ask it The question separates people who have only worked inside one web project from those who have split a growing solution. The traps are all real project files seen in upgraded codebases: libraries flipped to the Web SDK "because it made the red squiggles go away", a versioned `Microsoft.AspNetCore.App` package carried over from 2.x, and a stack of `Microsoft.AspNetCore.*` 2.x packages that compile but drag old assemblies into a .NET 10 build. A strong answer names the one correct line, explains what the shared framework is, and says which add-ons still come from NuGet.

  • When should the shared library use Microsoft.NET.Sdk.Razor instead of Microsoft.NET.Sdk?
    When it carries Razor markup — views, Razor Pages, partials or `.razor` components — or static web assets for them. The Razor SDK compiles that markup and packages the assets; a library with only C# middleware, filters and controllers needs just `Microsoft.NET.Sdk` with the framework reference.
  • Why is a PackageReference to Microsoft.AspNetCore.Mvc.Core a problem in a .NET 10 library?
    Since .NET Core 3.0 that assembly is produced only inside the `Microsoft.AspNetCore.App` shared framework, so the package is a 2.x-era build. The library compiles against old APIs and can clash with the version the host loads; the `FrameworkReference` gives the current one.

  • Switch the library to Microsoft.NET.Sdk.Web to get ASP.NET Core types
  • Add PackageReference Include="Microsoft.AspNetCore.App" with a version number
  • Reference Microsoft.AspNetCore.Mvc.Core from NuGet for ControllerBase
  • A FrameworkReference means the JwtBearer handler is included too
  • A library with FrameworkReference gets the Web SDK's implicit usings