ASP.NET Core-API's gebruiken in een klassebibliotheek

Artikel
01/16/2025

Dit document bevat richtlijnen voor het gebruik van ASP.NET Core-API's in een klassebibliotheek. Zie Opensource-bibliotheekrichtlijnenvoor alle andere richtlijnen voor bibliotheken.

Bepalen welke ASP.NET Core-versies moeten worden ondersteund

ASP.NET Core voldoet aan het .NET Core-ondersteuningsbeleid. Raadpleeg het ondersteuningsbeleid bij het bepalen welke ASP.NET Core-versies moeten worden ondersteund in een bibliotheek. Een bibliotheek moet:

Doe uw best om alle ASP.NET Core-versies te ondersteunen die zijn geclassificeerd als Long-Term Ondersteuning (LTS).
Voel je niet verplicht om ASP.NET Core-versies die als niet langer ondersteund (EOL) worden geclassificeerd, te ondersteunen.

Wanneer preview-versies van ASP.NET Core beschikbaar worden gemaakt, worden belangrijke wijzigingen in de aspnet/Aankondigingen GitHub-opslagplaats geplaatst. Compatibiliteitstests van bibliotheken kunnen worden uitgevoerd wanneer frameworkfuncties worden ontwikkeld.

Het gedeelde ASP.NET Core-framework gebruiken

Met de release van .NET Core 3.0 worden veel ASP.NET Core-assembly's niet meer als pakketten gepubliceerd naar NuGet. In plaats daarvan worden de assembly's opgenomen in het gedeelde framework Microsoft.AspNetCore.App, dat is geïnstalleerd met de .NET Core SDK en runtime-installatieprogramma's. Zie Verouderde pakketverwijzingen verwijderenvoor een lijst met pakketten die niet meer worden gepubliceerd.

Vanaf .NET Core 3.0 verwijzen projecten die gebruikmaken van de Microsoft.NET.Sdk.Web MSBuild SDK impliciet naar het gedeelde framework. Projecten die gebruikmaken van de Microsoft.NET.Sdk of Microsoft.NET.Sdk.Razor SDK, moeten verwijzen naar ASP.NET Core om ASP.NET Core-API's in het gedeelde framework te kunnen gebruiken.

Als u wilt verwijzen naar ASP.NET Core, voegt u het volgende <FrameworkReference> element toe aan uw projectbestand:

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

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

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

</Project>

Uitbreidbaarheid van Blazor opnemen

Blazor ondersteunt het maken van Razor onderdelen klassebibliotheken voor apps aan de serverzijde en aan de clientzijde. Als u Razor onderdelen in een klassebibliotheek wilt ondersteunen, moet de klassebibliotheek de Microsoft.NET.Sdk gebruiken.Razor SDK-.

Ondersteuning voor apps aan de serverzijde en aan de clientzijde

Gebruik de volgende instructies voor uw editor om het gebruik van Razor-componenten door server- en clienttoepassingen vanuit een enkele bibliotheek te ondersteunen.

Visual Studio
Visual Studio Code / .NET CLI

Gebruik de Razor klassebibliotheek projectsjabloon.

Notitie

Schakel niet het selectievakje Ondersteuningspagina's en weergaven in. Als u het selectievakje inschakelt, wordt een klassebibliotheek weergegeven die alleen ondersteuning biedt voor apps aan de serverzijde.

Voer de volgende opdracht uit in de geïntegreerde terminal (VS Code) of een opdrachtshell (.NET CLI):

dotnet new razorclasslib

Notitie

Voeg de optie -s|--support-pages-and-views niet toe aan de opdracht dotnet new. Het toepassen van de optie resulteert in een klassebibliotheek die alleen ondersteuning biedt voor apps aan de serverzijde.

De bibliotheek die is gegenereerd op basis van de projectsjabloon:

Is gericht op het huidige .NET Framework op basis van de geïnstalleerde SDK.
Hiermee schakelt u browsercompatibiliteitscontroles voor platformafhankelijkheden in door browser op te geven als een ondersteund platform met het SupportedPlatform MSBuild-item.
Voegt een NuGet-pakketreferentie toe voor Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (referentiebron)

Notitie

Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch-vertakkingen of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.

Ondersteuning voor meerdere frameworkversies

Als de bibliotheek functies moet ondersteunen die zijn toegevoegd aan Blazor in de huidige release en tevens een of meer eerdere releases moet ondersteunen, moet de bibliotheek zich richten op meerdere doelplatformen. Geef een door puntkomma's gescheiden lijst op van Target Framework Monikers (TFM's) in de eigenschap TargetFrameworks MSBuild:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

In het vorige voorbeeld vertegenwoordigt de tijdelijke aanduiding {TARGET FRAMEWORKS} de lijst met door puntkomma's gescheiden TFM's. Bijvoorbeeld netcoreapp3.1;net5.0.

Alleen ondersteuning voor verbruik aan de serverzijde

Klassebibliotheken zijn zelden gebouwd om alleen apps aan de serverzijde te ondersteunen. Als voor de klassebibliotheek alleen specifieke functies aan de serverzijde zijn vereist, zoals toegang tot CircuitHandler of Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, of ASP.NET Kernspecifieke functies, zoals middleware, MVC-controllers of Razor Pagina's, gebruikt u een van de volgende methoden:

Geef aan dat de bibliotheek ondersteuning voor pagina's en weergaven biedt wanneer de bibliotheek wordt aangemaakt met het selectievakje "Ondersteuning voor pagina's en weergaven" (Visual Studio) of de optie -s|--support-pages-and-views met de opdracht dotnet new.
```
dotnet new razorclasslib -s
```
Geef alleen een frameworkreferentie op naar ASP.NET Core in het projectbestand van de bibliotheek, naast eventuele andere vereiste MSBuild-eigenschappen:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Zie voor meer informatie over bibliotheken met Razor onderdelen ASP.NET Core Razor-onderdelen gebruiken vanuit een Razor klassebibliotheek (RCL).

MVC-uitbreidbaarheid opnemen

In deze sectie vindt u een overzicht van aanbevelingen voor bibliotheken met:

Razor weergaven of Razor pagina's
Tag Helpers
onderdelen weergeven

In deze sectie wordt niet over meerdere targetings besproken ter ondersteuning van meerdere versies van MVC. Zie Ondersteuning voor meerdere ASP.NET Core-versiesvoor hulp bij het ondersteunen van meerdere ASP.NET Core-versies.

Razor weergaven of Razor pagina's

Een project met Razor weergaven of Razor Pages moet de Microsoft.NET.Sdk gebruiken.Razor SDK-.

Als het project is gericht op .NET Core 3.x, is het volgende vereist:

Een AddRazorSupportForMvc MSBuild-eigenschap die is ingesteld op true.
Een <FrameworkReference>-element voor het gedeelde framework.

De Razor Klassebibliotheek projectsjabloon voldoet aan de voorgaande vereisten voor projecten die zijn gericht op .NET Core. Gebruik de volgende instructies voor uw editor.

Visual Studio
Visual Studio Code / .NET CLI

Gebruik de Razor class library projectsjabloon. Het selectievakje Ondersteuningspagina's en weergaven van de sjabloon moet zijn ingeschakeld.

Voer de volgende opdracht uit in de geïntegreerde terminal (VS Code) of een opdrachtshell (.NET CLI):

dotnet new razorclasslib -s

Bijvoorbeeld:

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

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

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

</Project>

Als het project zich in plaats daarvan richt op .NET Standard, is een Microsoft.AspNetCore.Mvc- pakketreferentie vereist. Het Microsoft.AspNetCore.Mvc-pakket is verplaatst naar het gedeelde framework in ASP.NET Core 3.0 en wordt daarom niet meer gepubliceerd. Bijvoorbeeld:

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

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

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

</Project>

Tag Helpers

Een project met Tag Helpers moet de Microsoft.NET.Sdk SDK gebruiken. Als u zich richt op .NET Core 3.x, voegt u een <FrameworkReference>-element toe voor het gedeelde framework. Bijvoorbeeld:

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

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

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

</Project>

Als u zich richt op .NET Standard (ter ondersteuning van versies ouder dan ASP.NET Core 3.x), voegt u een pakketreferentie toe aan Microsoft.AspNetCore.Mvc.Razor. Het Microsoft.AspNetCore.Mvc.Razor pakket is verplaatst naar het gedeelde framework en wordt daarom niet meer gepubliceerd. Bijvoorbeeld:

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

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

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

</Project>

Onderdelen weergeven

Een project dat View-componenten bevat, moet de Microsoft.NET.Sdk SDK gebruiken. Als u zich richt op .NET Core 3.x, voegt u een <FrameworkReference>-element toe voor het gedeelde framework. Bijvoorbeeld:

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

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

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

</Project>

Als u zich richt op .NET Standard (ter ondersteuning van versies ouder dan ASP.NET Core 3.x), voegt u een pakketreferentie toe aan Microsoft.AspNetCore.Mvc.ViewFeatures. Het Microsoft.AspNetCore.Mvc.ViewFeatures pakket is verplaatst naar het gedeelde framework en wordt daarom niet meer gepubliceerd. Bijvoorbeeld:

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

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

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

</Project>

Ondersteuning voor meerdere ASP.NET Core-versies

Multi-targeting is vereist voor het ontwerpen van een bibliotheek die ondersteuning biedt voor meerdere varianten van ASP.NET Core. Overweeg een scenario waarin een Tag Helpers-bibliotheek de volgende ASP.NET Core-varianten moet ondersteunen:

ASP.NET Core 2.1 gericht op .NET Framework 4.6.1
ASP.NET Core 2.x gericht op .NET Core 2.x
ASP.NET Core 3.x gericht op .NET Core 3.x

Het volgende projectbestand ondersteunt deze varianten via de eigenschap 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>

Met het voorgaande projectbestand:

Het Markdig-pakket wordt toegevoegd voor alle consumenten.
Een verwijzing naar Microsoft.AspNetCore.Mvc.Razor wordt toegevoegd voor consumenten die gericht zijn op .NET Framework 4.6.1 of hoger of .NET Core 2.x. Versie 2.1.0 van het pakket werkt met ASP.NET Core 2.2 vanwege compatibiliteit met eerdere versies.
Er wordt verwezen naar het gedeelde framework voor consumenten die gericht zijn op .NET Core 3.x. Het Microsoft.AspNetCore.Mvc.Razor-pakket is opgenomen in het gedeelde framework.

U kunt ook .NET Standard 2.0 targeten in plaats van zowel .NET Core 2.1 als .NET Framework 4.6.1 te targeten.

<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>

Met het voorgaande projectbestand bestaan de volgende opmerkingen:

Omdat de bibliotheek alleen Tag Helpers bevat, is het eenvoudiger om te richten op de specifieke platforms waarop ASP.NET Core wordt uitgevoerd: .NET Core en .NET Framework. Tag Helpers kunnen niet worden gebruikt door andere .NET Standard 2.0-compatibele doelframeworks, zoals Unity en UWP.
Het gebruik van .NET Standard 2.0 van .NET Framework heeft enkele problemen die zijn opgelost in .NET Framework 4.7.2. U kunt de ervaring voor consumenten verbeteren met .NET Framework 4.6.1 tot en met 4.7.1 door te mikken op .NET Framework 4.6.1.

Als uw bibliotheek platformspecifieke API's moet aanroepen, richt u zich op specifieke .NET-implementaties in plaats van .NET Standard. Voor meer informatie, zie Multi-targeting.

Een API gebruiken die niet is gewijzigd

Stel dat u een scenario hebt waarin u een upgrade uitvoert van een middlewarebibliotheek van .NET Core 2.2 naar 3.1. De ASP.NET Core middleware-API's die in de bibliotheek worden gebruikt, zijn niet gewijzigd tussen ASP.NET Core 2.2 en 3.1. Voer de volgende stappen uit om de middleware-bibliotheek in .NET Core 3.1 te blijven ondersteunen:

Volg de standaardbibliotheekrichtlijnen.
Voeg een pakketreferentie toe voor het NuGet-pakket van elke API als de bijbehorende assembly niet bestaat in het gedeelde framework.

Een API gebruiken die is gewijzigd

Stel dat u een scenario hebt waarin u een bibliotheek upgradet van .NET Core 2.2 naar .NET Core 3.1. Een ASP.NET Core-API die in de bibliotheek wordt gebruikt, heeft een belangrijke wijziging in ASP.NET Core 3.1. Overweeg of de bibliotheek kan worden herschreven om de verbroken API niet in alle versies te gebruiken.

Als u de bibliotheek kunt herschrijven, doet u dit en blijft u zich richten op een eerder doelframework (bijvoorbeeld .NET Standard 2.0 of .NET Framework 4.6.1) met pakketverwijzingen.

Als u de bibliotheek niet opnieuw kunt schrijven, voert u de volgende stappen uit:

Voeg een doel toe voor .NET Core 3.1.
Voeg een <FrameworkReference>-element toe voor het gedeelde framework.
Gebruik de #if preprocessorrichtlijn met het juiste doelframeworksymbool om code voorwaardelijk te compileren.

Synchrone lees- en schrijfbewerkingen op HTTP-aanvraag- en antwoordstreams worden bijvoorbeeld standaard uitgeschakeld vanaf ASP.NET Core 3.1. ASP.NET Core 2.2 ondersteunt standaard het synchrone gedrag. Overweeg een middlewarebibliotheek waarin synchrone lees- en schrijfbewerkingen moeten worden ingeschakeld waar I/O plaatsvindt. De bibliotheek moet de code insluiten om synchrone functies in de juiste preprocessorrichtlijn in te schakelen. Bijvoorbeeld:

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);
}

Een API gebruiken die is geïntroduceerd in 3.1

Stel dat u een ASP.NET Core-API wilt gebruiken die is geïntroduceerd in ASP.NET Core 3.1. Houd rekening met de volgende vragen:

Vereist de bibliotheek functioneel de nieuwe API?
Kan de bibliotheek deze functie op een andere manier implementeren?

Als voor de bibliotheek functioneel de API is vereist en er geen manier is om deze op down-level te implementeren:

Richt op alleen .NET Core 3.x.
Voeg een <FrameworkReference>-element toe voor het gedeelde framework.

Als de bibliotheek de functie op een andere manier kan implementeren:

Voeg .NET Core 3.x toe als doelframework.
Voeg een <FrameworkReference>-element toe voor het gedeelde framework.
Gebruik de #if preprocessorrichtlijn met het juiste doelframeworksymbool om code voorwaardelijk te compileren.

De volgende Tag Helper maakt bijvoorbeeld gebruik van de IWebHostEnvironment-interface die is geïntroduceerd in ASP.NET Core 3.1. Consumenten die gericht zijn op .NET Core 3.1 voeren het codepad uit dat is gedefinieerd door het NETCOREAPP3_1 doelframeworksymbool. Het constructorparametertype van de Tag Helper wordt gewijzigd in IHostingEnvironment voor .NET Core 2.1- en .NET Framework 4.6.1-gebruikers. Deze wijziging was nodig omdat ASP.NET Core 3.1 IHostingEnvironment als verouderd heeft gemarkeerd en IWebHostEnvironment als vervanging heeft aanbevolen.

[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
}

Het volgende projectbestand met meerdere doelgroepen ondersteunt dit Tag Helper-scenario:

<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>

Een API gebruiken die is verwijderd uit het gedeelde framework

Als u een ASP.NET Core-assembly wilt gebruiken die is verwijderd uit het gedeelde framework, voegt u de juiste pakketreferentie toe. Zie Verouderde pakketverwijzingen verwijderenvoor een lijst met pakketten die zijn verwijderd uit het gedeelde framework in ASP.NET Core 3.1.

Als u bijvoorbeeld de web-API-client wilt toevoegen:

<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>

Delen via

ASP.NET Core-API's gebruiken in een klassebibliotheek

Bepalen welke ASP.NET Core-versies moeten worden ondersteund

Het gedeelde ASP.NET Core-framework gebruiken

Uitbreidbaarheid van Blazor opnemen

Ondersteuning voor apps aan de serverzijde en aan de clientzijde

Ondersteuning voor meerdere frameworkversies

Alleen ondersteuning voor verbruik aan de serverzijde

MVC-uitbreidbaarheid opnemen

Razor weergaven of Razor pagina's

Tag Helpers

Onderdelen weergeven

Ondersteuning voor meerdere ASP.NET Core-versies

Een API gebruiken die niet is gewijzigd

Een API gebruiken die is gewijzigd

Een API gebruiken die is geïntroduceerd in 3.1

Een API gebruiken die is verwijderd uit het gedeelde framework

Aanvullende informatiebronnen

Aanvullende resources