Använda ASP.NET Core-API:er i ett klassbibliotek

Artikel
01/16/2025

Det här dokumentet innehåller vägledning om hur du använder ASP.NET Core-API:er i ett klassbibliotek. All annan biblioteksvägledning finns i vägledning för bibliotek med öppen källkod.

Avgöra vilka ASP.NET Core-versioner som ska stödjas

ASP.NET Core följer .NET Core-supportprincipen. Läs supportpolicyn när du fastställer vilka ASP.NET Core-versioner som ska stödjas i ett bibliotek. Ett bibliotek bör:

Gör ett försök att stödja alla ASP.NET Core-versioner som klassificeras som Long-Term Support (LTS).
Känner dig inte skyldig att stödja ASP.NET Core-versioner som klassificeras som End of Life (EOL).

När förhandsversioner av ASP.NET Core görs tillgängliga publiceras brytande ändringar i aspnet/Announcements GitHub-repositorium. Kompatibilitetstestning av bibliotek kan utföras när ramverksfunktioner utvecklas.

Använda det delade ASP.NET Core-ramverket

Med lanseringen av .NET Core 3.0 publiceras inte längre många ASP.NET Core-sammansättningar till NuGet som paket. I stället ingår samlingarna i det Microsoft.AspNetCore.App delade ramverket, som installeras med .NET Core SDK och installationsprogram för runtime. En lista över paket som inte längre publiceras finns i Ta bort föråldrade paketreferenser.

Från och med .NET Core 3.0 refererar projekt som använder Microsoft.NET.Sdk.Web MSBuild SDK implicit till det delade ramverket. Projekt som använder Microsoft.NET.Sdk eller Microsoft.NET.Sdk.Razor SDK måste referera till ASP.NET Core för att använda ASP.NET Core-API:er i det delade ramverket.

Om du vill referera till ASP.NET Core lägger du till följande <FrameworkReference> element i projektfilen:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Inkludera Blazor utökningsbarhet

Blazor har stöd för att skapa Razor komponenter klassbibliotek för appar på serversidan och på klientsidan. För att stödja Razor komponenter i ett klassbibliotek måste klassbiblioteket använda Microsoft.NET.Sdk.Razor SDK.

Stöd för appar på serversidan och på klientsidan

Använd följande instruktioner för redigeringsprogrammet för att stödja Razor komponentförbrukning av appar på serversidan och klientsidan från ett enda bibliotek.

Visual Studio
Visual Studio Code/.NET CLI

Använd projektmallen Razor Klassbibliotek.

Note

Markera inte kryssrutan supportsidor och vyer. Om du markerar kryssrutan visas ett klassbibliotek som endast stöder appar på serversidan.

Kör följande kommando i den integrerade terminalen (VS Code) eller ett kommandogränssnitt (.NET CLI):

dotnet new razorclasslib

Anteckning

Lägg inte till alternativet -s|--support-pages-and-views i kommandot dotnet new. Om alternativet tillämpas resulterar det i ett klassbibliotek som endast stöder appar på serversidan.

Biblioteket som genereras från projektmallen:

Riktar in sig på det aktuella .NET-ramverket baserat på det installerade SDK:et.
Aktiverar webbläsarkompatibilitetskontroller för plattformsberoenden genom att inkludera browser som en plattform som stöds med det SupportedPlatform MSBuild-objektet.
Lägger till en NuGet-paketreferens för Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (referenskälla)

Not

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Växla grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Stöd för flera ramverksversioner

Om biblioteket måste stödja funktioner som lagts till i Blazor i den aktuella versionen samtidigt som det stöder en eller flera tidigare versioner, bör biblioteket konfigureras för att stödja flera målversioner. Ange en semikolonavgränsad lista över Target Framework Monikers (TFM) i egenskapen TargetFrameworks MSBuild:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

I föregående exempel representerar platshållaren {TARGET FRAMEWORKS} den semikolonavgränsade TFM-listan. Till exempel netcoreapp3.1;net5.0.

Stöd endast för förbrukning på serversidan

Klassbibliotek skapas sällan för att endast stödja appar på serversidan. Om klassbiblioteket bara kräver specifika funktioner på serversidan, till exempel åtkomst till CircuitHandler eller Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, eller använder ASP.NET Core-specifika funktioner, till exempel mellanprogram, MVC-styrenheter eller Razor Sidor, använder du en av följande metoder:

Ange att biblioteket stöder sidor och vyer när biblioteket skapas med kryssrutan Supportsidor och vyer (Visual Studio) eller alternativet -s|--support-pages-and-views med kommandot dotnet new:
```
dotnet new razorclasslib -s
```
Ange endast en ramverksreferens till ASP.NET Core i bibliotekets projektfil utöver andra nödvändiga MSBuild-egenskaper:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Mer information om bibliotek som innehåller Razor komponenter finns i Consume ASP.NET Core Razor components from a Razor class library (RCL).

Inkludera MVC-utökningsbarhet

Det här avsnittet beskriver rekommendationer för bibliotek som innehåller:

Razor vyer eller Razor sidor
Tagghjälpare
Visa komponenter

I det här avsnittet diskuteras inte flera mål för att stödja flera versioner av MVC. Information om hur du stöder flera ASP.NET Core-versioner finns i Stöd för flera ASP.NET Core-versioner.

Razor vyer eller Razor sidor

Ett projekt som innehåller Razor vyer eller Razor Pages måste använda Microsoft.NET.Sdk.Razor SDK.

Om projektet är avsett för .NET Core 3.x krävs följande:

En AddRazorSupportForMvc MSBuild-egenskap inställd på true.
Ett <FrameworkReference> element för det delade ramverket.

Projektmallen Razor Class Library uppfyller ovanstående krav för projekt som riktar sig till .NET Core. Använd följande instruktioner för redigeringsprogrammet.

Visual Studio
Visual Studio Code/.NET CLI

Använd projektmallen Razor Klassbibliotek. Kryssrutan för mallens support-sidor och vyer ska vara markerad.

Kör följande kommando i den integrerade terminalen (VS Code) eller ett kommandogränssnitt (.NET CLI):

dotnet new razorclasslib -s

Till exempel:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Om projektet i stället är avsett för .NET Standard krävs en Microsoft.AspNetCore.Mvc- paketreferens. Det Microsoft.AspNetCore.Mvc paketet flyttades till det delade ramverket i ASP.NET Core 3.0 och publiceras därför inte längre. Till exempel:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Tagghjälpare

Ett projekt som innehåller Tag Helpers bör använda Microsoft.NET.Sdk SDK. Om du riktar in dig på .NET Core 3.x lägger du till ett <FrameworkReference>-element för det delade ramverket. Till exempel:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Om du riktar in dig på .NET Standard (för att stödja tidigare versioner än ASP.NET Core 3.x) lägger du till en paketreferens till Microsoft.AspNetCore.Mvc.Razor. Det Microsoft.AspNetCore.Mvc.Razor paketet flyttades till det delade ramverket och publiceras därför inte längre. Till exempel:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Visa komponenter

Ett projekt som innehåller View-komponenter ska använda Microsoft.NET.Sdk SDK. Om du riktar in dig på .NET Core 3.x lägger du till ett <FrameworkReference>-element för det delade ramverket. Till exempel:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Om du riktar in dig på .NET Standard (för att stödja tidigare versioner än ASP.NET Core 3.x) lägger du till en paketreferens till Microsoft.AspNetCore.Mvc.ViewFeatures. Det Microsoft.AspNetCore.Mvc.ViewFeatures paketet flyttades till det delade ramverket och publiceras därför inte längre. Till exempel:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.ViewFeatures" Version="2.2.0" />
  </ItemGroup>

</Project>

Stöd för flera ASP.NET Core-versioner

Multi-targeting krävs för att skapa ett bibliotek som stöder flera varianter av ASP.NET Core. Tänk dig ett scenario där ett Tag Helpers-bibliotek måste ha stöd för följande ASP.NET Core-varianter:

ASP.NET Core 2.1 för .NET Framework 4.6.1
ASP.NET Core 2.x för .NET Core 2.x
ASP.NET Core 3.x som riktar sig mot .NET Core 3.x

Följande projektfil stöder dessa varianter via egenskapen TargetFrameworks:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Med föregående projektfil:

Paketet Markdig läggs till för alla konsumenter.
En referens till Microsoft.AspNetCore.Mvc.Razor läggs till för konsumenter som riktar sig till .NET Framework 4.6.1 eller senare eller .NET Core 2.x. Version 2.1.0 av paketet fungerar med ASP.NET Core 2.2 på grund av bakåtkompatibilitet.
Det delade ramverket refereras till för konsumenter som riktar sig till .NET Core 3.x. Det Microsoft.AspNetCore.Mvc.Razor paketet ingår i det delade ramverket.

Alternativt kan .NET Standard 2.0 vara mål i stället för att rikta in sig på både .NET Core 2.1 och .NET Framework 4.6.1:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;netcoreapp3.1</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Med den föregående projektfilen finns följande varningar:

Eftersom biblioteket bara innehåller Tag Helpers är det enklare att rikta in sig på de specifika plattformar som ASP.NET Core körs på: .NET Core och .NET Framework. Tag Helpers kan inte användas av andra .NET Standard 2.0-kompatibla målramverk som Unity och UWP.
Att använda .NET Standard 2.0 från .NET Framework har vissa problem som har åtgärdats i .NET Framework 4.7.2. Du kan förbättra upplevelsen för konsumenter med hjälp av .NET Framework 4.6.1 till 4.7.1 genom att rikta in dig på .NET Framework 4.6.1.

Om biblioteket behöver anropa plattformsspecifika API:er ska du rikta in dig på specifika .NET-implementeringar i stället för .NET Standard. Mer information finns i multi-targeting.

Använda ett API som inte har ändrats

Föreställ dig ett scenario där du uppgraderar ett mellanprogrambibliotek från .NET Core 2.2 till 3.1. API:erna för ASP.NET Core-mellanprogram som används i biblioteket har inte ändrats mellan ASP.NET Core 2.2 och 3.1. Utför följande steg för att fortsätta stödja mellanprogrambiblioteket i .NET Core 3.1:

Följ riktlinjerna för standardbibliotek.
Lägg till en paketreferens för varje API:s NuGet-paket om motsvarande sammansättning inte finns i det delade ramverket.

Använda ett API som har ändrats

Föreställ dig ett scenario där du uppgraderar ett bibliotek från .NET Core 2.2 till .NET Core 3.1. I ett bibliotek används en ASP.NET Core API som har en ändring som bryter kompatibiliteten i ASP.NET Core 3.1. Fundera på om biblioteket kan skrivas om för att inte använda det brutna API:et i alla versioner.

Om du kan skriva om biblioteket gör du det och fortsätter att rikta in dig på ett tidigare målramverk (till exempel .NET Standard 2.0 eller .NET Framework 4.6.1) med paketreferenser.

Om du inte kan skriva om biblioteket gör du följande:

Lägg till ett mål för .NET Core 3.1.
Lägg till ett <FrameworkReference>-element för det delade ramverket.
Använd #if förprocessordirektivet med rätt målramverkssymbol för att villkorligt kompilera kod.

Synkrona läsningar och skrivningar på HTTP-begärande- och svarsströmmar inaktiveras som standard från och med ASP.NET Core 3.1. ASP.NET Core 2.2 stöder synkront beteende som standard. Överväg ett mellanprogrambibliotek där synkrona läsningar och skrivningar ska aktiveras där I/O inträffar. Biblioteket bör omsluta koden för att aktivera synkrona funktioner i lämpligt förprocessordirektiv. Till exempel:

public async Task Invoke(HttpContext httpContext)
{
    if (httpContext.Request.Path.StartsWithSegments(_path, StringComparison.Ordinal))
    {
        httpContext.Response.StatusCode = (int) HttpStatusCode.OK;
        httpContext.Response.ContentType = "application/json";
        httpContext.Response.ContentLength = _bufferSize;

#if !NETCOREAPP3_1 && !NETCOREAPP5_0
        var syncIOFeature = httpContext.Features.Get<IHttpBodyControlFeature>();
        if (syncIOFeature != null)
        {
            syncIOFeature.AllowSynchronousIO = true;
        }

        using (var sw = new StreamWriter(
            httpContext.Response.Body, _encoding, bufferSize: _bufferSize))
        {
            _json.Serialize(sw, new JsonMessage { message = "Hello, World!" });
        }
#else
        await JsonSerializer.SerializeAsync<JsonMessage>(
            httpContext.Response.Body, new JsonMessage { message = "Hello, World!" });
#endif
        return;
    }

    await _next(httpContext);
}

Använda ett API som introducerades i 3.1

Anta att du vill använda ett ASP.NET Core API som introducerades i ASP.NET Core 3.1. Tänk på följande frågor:

Kräver biblioteket funktionellt det nya API:et?
Kan biblioteket implementera den här funktionen på ett annat sätt?

Om biblioteket funktionellt kräver API:et och det inte finns något sätt att implementera det på nednivå:

Målet är endast .NET Core 3.x.
Lägg till ett <FrameworkReference>-element för det delade ramverket.

Om biblioteket kan implementera funktionen på ett annat sätt:

Lägg till .NET Core 3.x som ett målramverk.
Lägg till ett <FrameworkReference>-element för det delade ramverket.
Använd #if förprocessordirektivet med rätt målramverkssymbol för att villkorligt kompilera kod.

Följande Tag Helper använder till exempel IWebHostEnvironment-gränssnittet som introducerades i ASP.NET Core 3.1. Användare som riktar in sig på .NET Core 3.1 kör den kodsökväg som definieras av symbolen för målramverket NETCOREAPP3_1. Parametertypen för Tag Helpern ändras till IHostingEnvironment för användare av .NET Core 2.1 och .NET Framework 4.6.1. Den här ändringen var nödvändig eftersom ASP.NET Core 3.1 markerade IHostingEnvironment som föråldrad och rekommenderade IWebHostEnvironment som ersättning.

[HtmlTargetElement("script", Attributes = "asp-inline")]
public class ScriptInliningTagHelper : TagHelper
{
    private readonly IFileProvider _wwwroot;

#if NETCOREAPP3_1
    public ScriptInliningTagHelper(IWebHostEnvironment env)
#else
    public ScriptInliningTagHelper(IHostingEnvironment env)
#endif
    {
        _wwwroot = env.WebRootFileProvider;
    }

    // code omitted for brevity
}

Följande projektfil med flera mål stöder det här tagghjälpscenariot:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Använda ett API som tagits bort från det delade ramverket

Om du vill använda en ASP.NET Core-sammansättning som har tagits bort från det delade ramverket lägger du till lämplig paketreferens. En lista över paket som tagits bort från det delade ramverket i ASP.NET Core 3.1 finns i Ta bort föråldrade paketreferenser.

Om du till exempel vill lägga till webb-API-klienten:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.7" />
  </ItemGroup>

</Project>

Dela via