Verwenden von ASP.NET Core-APIs in einer Klassenbibliothek

Artikel
01/21/2025

Dieses Dokument enthält Anleitungen für die Verwendung von ASP.NET Core-APIs in einer Klassenbibliothek. Informationen zu allen anderen Bibliotheksrichtlinien finden Sie unter Open-Source-Bibliotheksrichtlinien.

Ermitteln, welche ASP.NET Core-Versionen unterstützt werden sollen

ASP.NET Core entspricht der .NET Core-Supportrichtlinie. Wenden Sie sich an die Supportrichtlinie, wenn Sie bestimmen, welche ASP.NET Core-Versionen in einer Bibliothek unterstützt werden sollen. Eine Bibliothek sollte:

** Bemühen Sie sich, alle Versionen von ASP.NET Core zu unterstützen, die als Long-Term Support (LTS) klassifiziert werden.
Sich nicht der Unterstützung von ASP.NET Core-Versionen verschreiben, die als End of Life (EOL) klassifiziert sind.

Wenn Vorschauversionen von ASP.NET Core verfügbar gemacht werden, werden wichtige Änderungen im aspnet/Announcements GitHub-Repository veröffentlicht. Kompatibilitätstests von Bibliotheken können durchgeführt werden, wenn Framework-Funktionen entwickelt werden.

Verwenden Sie das Shared Framework von ASP.NET Core

Mit der Version von .NET Core 3.0 werden viele ASP.NET Core-Assemblys nicht mehr als Pakete in NuGet veröffentlicht. Stattdessen sind die Assemblys im freigegebenen Framework Microsoft.AspNetCore.App enthalten, das mit dem .NET Core SDK und Runtimeinstallationsprogrammen installiert wird. Eine Liste der Pakete, die nicht mehr veröffentlicht werden, finden Sie unter Entfernen veralteter Paketverweise.

Ab .NET Core 3.0 verweisen Projekte, die das Microsoft.NET.Sdk.Web MSBuild SDK verwenden, implizit auf das gemeinsam genutzte Framework. Projekte, die das Microsoft.NET.Sdk oder Microsoft.NET.Sdk.Razor SDK verwenden, müssen auf ASP.NET Core verweisen, um ASP.NET Core-APIs im freigegebenen Framework zu verwenden.

Um auf ASP.NET Core zu verweisen, fügen Sie der Projektdatei das folgende <FrameworkReference> Element hinzu:

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

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

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

</Project>

Einschließen von Blazor-Erweiterbarkeit

Blazor unterstützt das Erstellen von Razor Komponenten Klassenbibliotheken für serverseitige und clientseitige Apps. Um Razor-Komponenten in einer Klassenbibliothek zu unterstützen, muss die Klassenbibliothek das Microsoft.NET.Sdk.Razor-SDK verwenden.

Unterstützung von serverseitigen und clientseitigen Apps

Verwenden Sie zur Unterstützung der Nutzung von Razor-Komponenten durch serverseitige und clientseitige App über eine einzelne Bibliothek die folgenden Anweisungen für Ihren Editor.

Visual Studio
Visual Studio Code / .NET CLI

Verwenden Sie die Razor Klassenbibliothek Projektvorlage.

Anmerkung

Aktivieren Sie nicht das Kontrollkästchen Seiten und Ansichten unterstützen. Wenn Sie das Kontrollkästchen aktivieren, wird eine Klassenbibliothek angezeigt, die nur serverseitige Apps unterstützt.

Führen Sie den folgenden Befehl im integrierten Terminal (VS Code) oder einer Befehlsshell (.NET CLI) aus:

dotnet new razorclasslib

Anmerkung

Fügen Sie dem Befehl dotnet new nicht die Option -s|--support-pages-and-views hinzu. Das Anwenden der Option führt zu einer Klassenbibliothek, die nur serverseitige Apps unterstützt.

Die aus der Projektvorlage generierte Bibliothek:

Zielt auf das aktuelle .NET Framework ab, basierend auf dem installierten SDK.
Ermöglicht Überprüfungen der Browserkompatibilität für Plattformabhängigkeiten durch Einschließen von browser als unterstützte Plattform mit dem MSBuild-Element SupportedPlatform.
Fügt eine NuGet-Paketreferenz für Microsoft.AspNetCore.Components.Webhinzu.

RazorClassLibrary-CSharp.csproj (Referenzquelle)

Anmerkung

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel die Standard-Branch des Repositorys, die die aktuelle Entwicklung der nächsten Version von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205).

Unterstützung mehrerer Framework-Versionen

Wenn die Bibliothek Funktionen unterstützen muss, die Blazor im aktuellen Release hinzugefügt wurden, und gleichzeitig mindestens ein früheres Release unterstützen muss, sollten Sie die Bibliothek mit mehreren Zielen versehen. Stellen Sie eine durch Semikolons getrennte Liste der Zielframeworkmoniker (TFMs) in der MSBuild-Eigenschaft TargetFrameworks bereit:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

Im vorherigen Beispiel stellt der Platzhalter {TARGET FRAMEWORKS} die durch Semikolons getrennte TFM-Liste dar. Beispiel: netcoreapp3.1;net5.0.

Alleiniges Unterstützen des serverseitigen Verbrauchs

Klassenbibliotheken werden selten nur zur Unterstützung von serverseitigen Apps entwickelt. Wenn die Klassenbibliothek nur serverseitige Features wie den Zugriff auf CircuitHandler oder Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage benötigt oder ASP.NET Core-spezifische Features wie Middleware, MVC-Controller oder Razor Pages verwendet, verwenden Sie einen der folgenden Ansätze:

Geben Sie an, dass die Bibliothek Seiten und Ansichten unterstützt, wenn die Bibliothek mit dem Kontrollkästchen "Support pages and views" (Visual Studio) oder der Option -s|--support-pages-and-views mit dem Befehl dotnet new erstellt wird:
```
dotnet new razorclasslib -s
```
Fügen Sie in der Projektdatei der Bibliothek nur einen Frameworkverweis auf ASP.NET Core hinzu, neben allen anderen benötigten MSBuild-Eigenschaften:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Weitere Informationen zu Bibliotheken mit Razor-Komponenten finden Sie unter Nutzen von ASP.NET Core Razor-Komponenten über eine Razor-Klassenbibliothek (RCL).

MVC-Erweiterbarkeit einschließen

In diesem Abschnitt werden Empfehlungen für Bibliotheken beschrieben, die Folgendes enthalten:

Razor Ansichten oder Razor Seiten
Tag Helper
Ansichtskomponenten

In diesem Abschnitt wird nicht die Unterstützung mehrerer Zielplattformen erörtert, um mehrere Versionen von MVC zu unterstützen. Anleitungen zur Unterstützung mehrerer ASP.NET Core-Versionen finden Sie unter Unterstützen mehrerer ASP.NET Core-Versionen.

Razor Ansichten oder Razor Seiten

Ein Projekt, das Razor Ansichten oder Razor Seiten enthält, muss das Microsoft.NET.Sdk.Razor SDK verwenden.

Wenn das Projekt auf .NET Core 3.x ausgerichtet ist, ist Folgendes erforderlich:

Eine AddRazorSupportForMvc-MSBuild-Eigenschaft, die auf true festgelegt ist.
Ein <FrameworkReference>-Element für das freigegebene Framework.

Die Projektvorlage für die Razor-Klassenbibliothek erfüllt die vorherigen Anforderungen an Projekte, die .NET Core anvisieren. Verwenden Sie die folgenden Anweisungen für Ihren Editor.

Visual Studio
Visual Studio Code / .NET CLI

Verwenden Sie die Razor Klassenbibliothek Projektvorlage. Das Kontrollkästchen Seiten und Ansichten unterstützen sollte aktiviert sein.

Führen Sie den folgenden Befehl im integrierten Terminal (VS Code) oder einer Befehlsshell (.NET CLI) aus:

dotnet new razorclasslib -s

Zum Beispiel:

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

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

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

</Project>

Wenn das Projekt stattdessen .NET Standard als Ziel hat, ist ein Paketverweis auf Microsoft.AspNetCore.Mvc erforderlich. Das Microsoft.AspNetCore.Mvc-Paket wurde in das freigegebene Framework in ASP.NET Core 3.0 verschoben und wird daher nicht mehr veröffentlicht. Zum Beispiel:

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

Ein Projekt, das Tag Helper umfasst, sollte das Microsoft.NET.Sdk SDK verwenden. Wenn Sie auf .NET Core 3.x ausgerichtet sind, fügen Sie ein <FrameworkReference>-Element für das gemeinsame Framework hinzu. Zum Beispiel:

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

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

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

</Project>

Bei .NET Standard als Ziel (um Versionen vor ASP.NET Core 3.x zu unterstützen), fügen Sie einen Paketverweis auf Microsoft.AspNetCore.Mvc.Razor hinzu. Das Microsoft.AspNetCore.Mvc.Razor-Paket wurde in das freigegebene Framework verschoben und wird daher nicht mehr veröffentlicht. Zum Beispiel:

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

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

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

</Project>

Komponenten anzeigen

Ein Projekt mit View-Komponenten sollte das Microsoft.NET.Sdk SDK verwenden. Wenn Sie auf .NET Core 3.x ausgerichtet sind, fügen Sie ein <FrameworkReference>-Element für das gemeinsame Framework hinzu. Zum Beispiel:

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

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

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

</Project>

Bei .NET Standard als Ziel (um Versionen vor ASP.NET Core 3.x zu unterstützen), fügen Sie einen Paketverweis auf Microsoft.AspNetCore.Mvc.ViewFeatures hinzu. Das Microsoft.AspNetCore.Mvc.ViewFeatures-Paket wurde in das freigegebene Framework verschoben und wird daher nicht mehr veröffentlicht. Zum Beispiel:

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

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

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

</Project>

Unterstützen mehrerer ASP.NET Core-Versionen

Multi-Targeting ist erforderlich, um eine Bibliothek zu erstellen, die mehrere Varianten von ASP.NET Core unterstützt. Berücksichtigen Sie ein Szenario, in dem eine Tag-Hilfsbibliothek die folgenden ASP.NET Core-Varianten unterstützen muss:

ASP.NET Core 2.1 mit dem Ziel .NET Framework 4.6.1
ASP.NET Core 2.x mit dem Ziel .NET Core 2.x
ASP.NET Core 3.x mit dem Ziel .NET Core 3.x

Die folgende Projektdatei unterstützt diese Varianten über die eigenschaft 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>

Dies erfolgt mit der vorstehenden Projektdatei:

Das Markdig-Paket wird für alle Consumer hinzugefügt.
Ein Verweis auf Microsoft.AspNetCore.Mvc.Razor wird für Anwender hinzugefügt, die auf .NET Framework 4.6.1 oder höher beziehungsweise .NET Core 2.x abzielen. Version 2.1.0 des Pakets funktioniert aufgrund der Abwärtskompatibilität mit ASP.NET Core 2.2.
Auf das freigegebene Framework wird für Consumer mit dem Ziel .NET Core 3.x verwiesen. Das Microsoft.AspNetCore.Mvc.Razor-Paket ist im gemeinsam genutzten Framework enthalten.

Alternativ kann .NET Standard 2.0 anstelle von .NET Core 2.1 und .NET Framework 4.6.1 als Ziel verwendet werden:

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

Bei der vorherigen Projektdatei sind die folgenden Vorbehalte vorhanden:

Da die Bibliothek nur Tag-Hilfsprogramme enthält, ist es einfacher, auf die spezifischen Plattformen zu abzielen, auf denen ASP.NET Core ausgeführt wird: .NET Core und .NET Framework. Tag Helper können nicht von anderen .NET-Standard 2.0-kompatiblen Ziel-Frameworks wie z. B. Unity und UWP verwendet werden.
Die Verwendung von .NET Standard 2.0 aus .NET Framework weist einige Probleme auf, die in .NET Framework 4.7.2 behoben wurden. Sie können die Erfahrung für Benutzer verbessern, die .NET Framework 4.6.1 über 4.7.1 verwenden, indem Sie .NET Framework 4.6.1 als Ziel festlegen.

Wenn Ihre Bibliothek plattformspezifische APIs aufrufen muss, richten Sie bestimmte .NET-Implementierungen anstelle von .NET Standard ein. Weitere Informationen finden Sie unter Multi-Targeting.

Verwenden Sie eine API, die nicht verändert wurde

Stellen Sie sich ein Szenario vor, in dem Sie eine Middleware-Bibliothek von .NET Core 2.2 auf 3.1 aktualisieren. Die in der Bibliothek verwendeten ASP.NET Core Middleware-APIs wurden zwischen ASP.NET Core 2.2 und 3.1 nicht geändert. Führen Sie die folgenden Schritte aus, um die Middleware-Bibliothek in .NET Core 3.1 weiterhin zu unterstützen:

Befolgen Sie den Standardbibliotheksleitfaden.
Fügen Sie einen Paketverweis für das NuGet-Paket jeder API hinzu, wenn die entsprechende Assembly nicht im freigegebenen Framework vorhanden ist.

Verwenden einer API, die geändert wurde

Stellen Sie sich ein Szenario vor, in dem Sie eine Bibliothek von .NET Core 2.2 auf .NET Core 3.1 aktualisieren. Eine ASP.NET Core-API, die in der Bibliothek verwendet wird, weist einen Breaking Change in ASP.NET Core 3.1 auf. Überlegen Sie, ob die Bibliothek neu geschrieben werden kann, um die fehlerhafte API nicht in allen Versionen zu verwenden.

Wenn Sie die Bibliothek neu schreiben können, können Sie dies tun und weiterhin ein früheres Zielframework (z. B. .NET Standard 2.0 oder .NET Framework 4.6.1) mit Paketverweise verwenden.

Wenn Sie die Bibliothek nicht neu schreiben können, führen Sie die folgenden Schritte aus:

Fügen Sie ein Ziel für .NET Core 3.1 hinzu.
Fügen Sie ein <FrameworkReference>-Element für das freigegebene Framework hinzu.
Verwenden Sie die #if-Präprozessordirektive mit dem entsprechenden Ziel-Framework-Symbol, um Code bedingt zu kompilieren.

Synchrone Lese- und Schreibvorgänge in HTTP-Anforderungs- und Antwortdatenströmen sind beispielsweise standardmäßig ab ASP.NET Core 3.1 deaktiviert. ASP.NET Core 2.2 unterstützt standardmäßig das synchrone Verhalten. Stellen Sie sich eine Middleware-Bibliothek vor, in der synchrone Lese- und Schreibvorgänge aktiviert werden sollen, wenn E/A auftritt. Die Bibliothek sollte den Code einschließen, um synchrone Features in der entsprechenden Präprozessordirektive zu aktivieren. Zum Beispiel:

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

Verwenden Sie eine API, die in 3.1 eingeführt wurde

Stellen Sie sich vor, Sie möchten eine ASP.NET Core-API verwenden, die in ASP.NET Core 3.1 eingeführt wurde. Berücksichtigen Sie die folgenden Fragen:

Erfordert die Bibliothek funktionell die neue API?
Kann die Bibliothek dieses Feature anders implementieren?

Wenn die Bibliothek die API funktionell erfordert und es keine Möglichkeit gibt, sie auf der unteren Ebene zu implementieren:

Legen Sie .NET Core 3.x als alleiniges Ziel fest.
Fügen Sie ein <FrameworkReference>-Element für das freigegebene Framework hinzu.

Wenn die Bibliothek das Feature auf eine andere Weise implementieren kann:

Fügen Sie .NET Core 3.x als Zielframework hinzu.
Fügen Sie ein <FrameworkReference>-Element für das freigegebene Framework hinzu.
Verwenden Sie die #if-Präprozessor-Direktive mit dem entsprechenden Ziel-Framework-Symbol, um Code bedingt zu kompilieren.

Beispielsweise verwendet der folgende Tag Helper die in ASP.NET Core 3.1 eingeführte IWebHostEnvironment-Schnittstelle. Consumer mit .NET Core 3.1 als Ziel führen den durch das Zielframeworksymbol NETCOREAPP3_1 definierten Codepfad aus. Der Konstruktorparametertyp des Taghilfsprogramms ändert sich für .NET Core 2.1- und .NET Framework 4.6.1-Consumer in IHostingEnvironment. Diese Änderung war erforderlich, da ASP.NET Core 3.1 IHostingEnvironment als veraltet gekennzeichnet hat und IWebHostEnvironment als Ersatz empfohlen wurde.

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

Die folgende Projektdatei für mehrere Ziele unterstützt dieses Szenario eines Taghilfsprogramms:

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

Verwenden einer API, die aus dem freigegebenen Framework entfernt wurde

Um eine ASP.NET Core-Assembly zu verwenden, die aus dem freigegebenen Framework entfernt wurde, fügen Sie den entsprechenden Paketverweis hinzu. Eine Liste der Pakete, die aus dem freigegebenen Framework in ASP.NET Core 3.1 entfernt wurden, finden Sie unter Entfernen veralteter Paketverweise.

So fügen Sie beispielsweise den Web-API-Client hinzu:

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

Freigeben über

Verwenden von ASP.NET Core-APIs in einer Klassenbibliothek

Ermitteln, welche ASP.NET Core-Versionen unterstützt werden sollen

Verwenden Sie das Shared Framework von ASP.NET Core

Einschließen von Blazor-Erweiterbarkeit

Unterstützung von serverseitigen und clientseitigen Apps

Unterstützung mehrerer Framework-Versionen

Alleiniges Unterstützen des serverseitigen Verbrauchs

MVC-Erweiterbarkeit einschließen

Razor Ansichten oder Razor Seiten

Tag Helper

Komponenten anzeigen

Unterstützen mehrerer ASP.NET Core-Versionen

Verwenden Sie eine API, die nicht verändert wurde

Verwenden einer API, die geändert wurde

Verwenden Sie eine API, die in 3.1 eingeführt wurde

Verwenden einer API, die aus dem freigegebenen Framework entfernt wurde

Weitere Ressourcen

Zusätzliche Ressourcen