Verwenden von ASP.NET Core-APIs in einer Klassenbibliothek

  • Artikel

Von Scott Addie

Dieses Dokument enthält Anleitungen zum Verwenden von ASP.NET Core-APIs in einer Klassenbibliothek. Weitere Informationen zur Bibliothek finden Sie unter Open-Source-Bibliotheksleitfaden.

Bestimmen der zu unterstützenden ASP.NET Core-Versionen

ASP.NET Core entspricht der .NET Core-Unterstützungsrichtlinie. Überprüfen Sie beim Bestimmen der in einer Bibliothek zu unterstützenden ASP.NET Core-Versionen die Supportrichtlinie. Eine Bibliothek sollte diese Merkmale aufweisen:

  • Alle als Long-Term Support (LTS) klassifizierten ASP.NET Core-Versionen zu unterstützen versuchen.
  • 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 nicht abwärtskompatible Änderungen im GitHub-Repository aspnet/Announcements veröffentlicht. Kompatibilitätstests von Bibliotheken können im Rahmen der Entwicklung von Frameworkfeatures durchgeführt werden.

Verwenden des freigegebenen ASP.NET Core-Frameworks

Mit der Veröffentlichung 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 von Verweisen auf veraltete Pakete.

Seit .NET Core 3.0 verweisen Projekte, die das Microsoft.NET.Sdk.Web MSBuild SDK verwenden, implizit auf das freigegebene 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 Ihrer 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 Klassenbibliotheken von Razor-Komponenten 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ützen serverseitiger und clientseitiger Komponenten

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.

Verwenden Sie die Projektvorlage Razor-Klassenbibliothek.

Hinweis

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

Die aus der Projektvorlage generierte Bibliothek:

  • Zielt auf die aktuelle .NET Framework-Version basierend auf dem installierten SDK ab.
  • 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 (Verweisquelle)

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release 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 How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Unterstützen mehrerer Frameworkversionen

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 erstellt, um lediglich serverseitige Apps zu unterstützen. 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 über das Kontrollkästchen Seiten und Ansichten unterstützen (Visual Studio) oder die Option -s|--support-pages-and-views mit dem Befehl dotnet new erstellt wird:

    dotnet new razorclasslib -s

  • Geben Sie nur einen Frameworkverweis auf ASP.NET Core in der Projektdatei der Bibliothek zusätzlich zu allen anderen erforderlichen MS Build-Eigenschaften an:

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

Einschließen von MVC-Erweiterbarkeit

In diesem Abschnitt werden Empfehlungen für Bibliotheken erläutert, die Folgendes umfassen:

In diesem Abschnitt wird nicht die Unterstützung mehrerer Zielplattformen erörtert, um mehrere Versionen von MVC zu unterstützen. Anleitungen zum Unterstützen mehrerer ASP.NET Core-Versionen finden Sie unter Unterstützung 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 für das Projekt .NET Core 3.x als Ziel festgelegt ist, wird Folgendes benötigt:

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

Die Projektvorlage Razor-Klassenbibliothek erfüllt die obigen Voraussetzungen für Projekte für .NET Core. Verwenden Sie die folgenden Anweisungen für Ihren Editor.

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

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 ASP.NET Core 3.0 in das freigegebene Framework 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>

Taghilfsprogramme

Ein Projekt, das Taghilfsprogramme umfasst, sollte das Microsoft.NET.Sdk SDK verwenden. Fügen Sie für .NET Core 3.x als Ziel ein <FrameworkReference>-Element für das freigegebene 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>

Ansichtskomponenten

Ein Projekt, das Ansichtskomponenten umfasst, sollte das Microsoft.NET.Sdk SDK verwenden. Fügen Sie für .NET Core 3.x als Ziel ein <FrameworkReference>-Element für das freigegebene 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ützung mehrerer ASP.NET Core-Versionen

Multi-Targeting ist erforderlich, um eine Bibliothek zu erstellen, die mehrere Varianten von ASP.NET Core unterstützt. Stellen Sie sich ein Szenario vor, in dem eine Taghilfsprogramm-Bibliothek 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 TargetFrameworks-Eigenschaft:

<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 Consumer mit dem Ziel .NET Framework 4.6.1 oder höher oder .NET Core 2.x hinzugefügt. Die 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 freigegebenen Framework enthalten.

Alternativ könnte .NET Standard 2.0 als Ziel verwendet werden, statt sowohl .NET Core 2.1 als auch .NET Framework 4.6.1 als Ziel festzulegen:

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

Für die vorstehende Projektdatei gelten die folgenden Vorbehalte:

  • Da die Bibliothek nur Taghilfsprogramme enthält, ist es einfacher, auf die spezifischen Plattformen zu abzuzielen, auf denen ASP.NET Core ausgeführt wird: .NET Core und .NET Framework. Taghilfsprogramme können von anderen mit .NET Standard 2.0 kompatiblen Zielframeworks wie Unity, UWP und Xamarin nicht verwendet werden.
  • Bei der Verwendung von .NET Standard 2.0 aus .NET Framework gibt es einige Probleme, 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, legen Sie spezifische .NET-Implementierungen anstelle von .NET Standard als Ziel fest. Weitere Informationen finden Sie unter Multi-Targeting.

Verwenden einer API, die nicht geändert wurde

Stellen Sie sich ein Szenario vor, in dem Sie ein Upgrade einer Middleware-Bibliothek von .NET Core 2.2 auf 3.1 durchführen. Die Middleware-APIs von ASP.NET Core, die in der Bibliothek verwendet werden, haben sich zwischen ASP.NET Core 2.2 und 3.1 nicht geändert. Um die Middleware-Bibliothek in .NET Core 3.1 weiterhin zu unterstützen, führen Sie die folgenden Schritte aus:

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

Verwenden einer API, die geändert wurde

Stellen Sie sich ein Szenario vor, in dem Sie ein Upgrade einer Bibliothek von .NET Core 2.2 auf .NET Core 3.1 durchführen. Eine ASP.NET Core-API, die in der Bibliothek verwendet wird, weist einen Breaking Change in ASP.NET Core 3.1 auf. Überprüfen Sie, ob die Bibliothek so umgeschrieben werden kann, dass sie die nicht funktionale API in allen Versionen nicht verwendet.

Wenn Sie die Bibliothek umschreiben können, tun Sie dies, und legen Sie weiterhin ein früheres Zielframework mit Paketverweisen fest (z. B. .NET Standard 2.0 oder .NET Framework 4.6.1).

Wenn die Bibliothek nicht umgeschrieben werden kann, 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 Zielframeworksymbol, um Code bedingt zu kompilieren.

Beispielsweise sind synchrone Lese- und Schreibvorgänge in HTTP-Anforderungs- und-Antwortdatenströmen standardmäßig ab ASP.NET Core 3.1 deaktiviert. ASP.NET Core 2.2 unterstützt das synchrone Verhalten standardmäßig. 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 in der entsprechenden Präprozessordirektive synchrone Funktionen 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 einer in Version 3.1 eingeführten API

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

  1. Erfordert die Bibliothek funktionell die neue API?
  2. Kann dieses Feature von der Bibliothek auf andere Weise implementiert werden?

Wenn die Bibliothek funktionell die API erfordert und es keine Möglichkeit gibt, sie auf einer Unterebene zu implementieren:

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

Falls dieses Feature von der Bibliothek auf andere Weise implementiert werden 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äprozessordirektive mit dem entsprechenden Zielframeworksymbol, um Code bedingt zu kompilieren.

Das folgende Taghilfsprogramm verwendet beispielsweise die in ASP.NET Core 3.1 eingeführte Schnittstelle IWebHostEnvironment. 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, weil in ASP.NET Core 3.1 IHostingEnvironment als veraltet gekennzeichnet 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 aus dem freigegebenen Framework entfernten API

Wenn Sie eine ASP.NET Core-Assembly verwenden möchten, die aus dem freigegebenen Framework entfernt wurde, fügen Sie den entsprechenden Paketverweis hinzu. Eine Liste der Pakete, die in ASP.NET Core 3.1 aus dem freigegebenen Framework entfernt wurden, finden Sie unter Entfernen von Verweisen auf veraltete Pakete.

So fügen Sie z. B. 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>

Zusätzliche Ressourcen