Użyj interfejsów API ASP.NET Core w bibliotece klas

Artykuł
01/16/2025

Ten dokument zawiera wskazówki dotyczące używania interfejsów API ASP.NET Core w bibliotece klas. Aby uzyskać wszystkie inne wskazówki dotyczące biblioteki, zobacz wskazówki dotyczące biblioteki open source .

Określenie, które wersje ASP.NET Core wspierać

ASP.NET Core jest zgodna z zasadami obsługi platformy .NET Core .NET Core. Zapoznaj się z polityką wsparcia podczas określania, które wersje ASP.NET Core należy obsługiwać w bibliotece. Biblioteka powinna:

Staraj się obsługiwać wszystkie wersje ASP.NET Core sklasyfikowane jako Long-Term Support (LTS).
Nie należy wspierać wersji ASP.NET Core sklasyfikowanych jako End of Life (EOL).

W miarę udostępniania wersji zapoznawczych ASP.NET Core, znaczące zmiany są publikowane w repozytorium aspnet/Announcements GitHub. Testowanie zgodności bibliotek można przeprowadzić w miarę opracowywania funkcji platformy.

Korzystanie z platformy udostępnionej ASP.NET Core

Wraz z wydaniem platformy .NET Core 3.0 wiele zestawów ASP.NET Core nie jest już publikowanych w programie NuGet jako pakietów. Zamiast tego biblioteki są zawarte w Microsoft.AspNetCore.App udostępnionej platformie, która jest instalowana przez instalatory .NET Core SDK oraz środowiska uruchomieniowego. Aby uzyskać listę pakietów, które nie są już publikowane, zobacz Usuń przestarzałe odwołania do pakietów.

Od wersji .NET Core 3.0 projekty korzystające z zestawu SDK msBuild Microsoft.NET.Sdk.Web niejawnie odwołują się do struktury udostępnionej. Projekty korzystające z zestawu SDK Microsoft.NET.Sdk lub Microsoft.NET.Sdk.Razor muszą odwoływać się do ASP.NET Core, aby korzystać z interfejsów API platformy ASP.NET Core we wspólnej strukturze.

Aby odwołać się do ASP.NET Core, dodaj następujący element <FrameworkReference> do pliku projektu:

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

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

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

</Project>

Uwzględnij rozszerzalność Blazor

Blazor obsługuje tworzenie składników Razor bibliotek klas dla aplikacji po stronie serwera i aplikacji po stronie klienta. Aby obsługiwać składniki Razor w bibliotece klas, biblioteka klas musi używać zestawu SDK Microsoft.NET.SdkRazor.

Obsługa aplikacji po stronie serwera i po stronie klienta

Aby obsługiwać użycie składników Razor przez aplikacje po stronie serwera i po stronie klienta z jednej biblioteki, skorzystaj z poniższych instrukcji dla edytora.

programu Visual Studio
Visual Studio Code / interfejs linii poleceń .NET

Użyj szablonu projektu biblioteki klas Razor.

Notatka

Nie zaznacz pola wyboru Strony i widoki pomocy technicznej. Zaznaczenie pola wyboru powoduje wyświetlenie biblioteki klas, która obsługuje tylko aplikacje po stronie serwera.

Uruchom następujące polecenie w zintegrowanym terminalu (VS Code) lub powłoce poleceń (interfejs wiersza polecenia platformy.NET):

dotnet new razorclasslib

Notatka

Nie dodawaj opcji -s|--support-pages-and-views do polecenia dotnet new. Zastosowanie opcji powoduje utworzenie biblioteki klas, która obsługuje tylko aplikacje po stronie serwera.

Biblioteka wygenerowana na podstawie szablonu projektu:

Dotyczy bieżącej platformy .NET framework opartej na zainstalowanym zestawie SDK.
Umożliwia sprawdzanie zgodności przeglądarki pod kątem zależności platformy przez uwzględnienie browser jako obsługiwanej platformy z elementem SupportedPlatform MSBuild.
Dodaje odwołanie do pakietu NuGet dla Microsoft.AspNetCore.Components.Web.

(źródło referencyjne)

Notatka

Linki w dokumentacji do kodu źródłowego platformy .NET zwykle ładują domyślną gałąź repozytorium, która reprezentuje bieżący rozwój dla następnego wydania .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać znacznik wersji kodu źródłowego ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Obsługa wielu wersji platformy

Jeśli biblioteka musi obsługiwać funkcje dodane do Blazor w bieżącej wersji, a jednocześnie obsługiwać co najmniej jedną starszą wersję, należy zastosować wielokierunkowe targetowanie biblioteki. Podaj rozdzieloną średnikami listę Target Framework Monikers (TFMs) we właściwości TargetFrameworks MSBuild:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

W poprzednim przykładzie symbol zastępczy {TARGET FRAMEWORKS} reprezentuje listę TFMs oddzieloną średnikami. Na przykład netcoreapp3.1;net5.0.

Wsparcie tylko dla przetwarzania po stronie serwera

Biblioteki klas są rzadko tworzone tak, aby obsługiwały tylko aplikacje po stronie serwera. Jeśli biblioteka klas wymaga tylko funkcji specyficznych dla serwera, takich jak dostęp do CircuitHandler lub Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, lub używa ASP.NET podstawowych funkcji, takich jak oprogramowanie pośredniczące, kontrolery MVC lub Razor Pages, należy użyć jednej następujących metod:

Określ, że biblioteka obsługuje strony i widoki, zaznaczając pole wyboru Obsługa stron i widoków podczas tworzenia biblioteki (Visual Studio) lub używając opcji -s|--support-pages-and-views z poleceniem dotnet new.
```
dotnet new razorclasslib -s
```
Oprócz innych wymaganych właściwości programu MSBuild podaj odwołanie do platformy ASP.NET Core w pliku projektu biblioteki:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Aby uzyskać więcej informacji na temat bibliotek zawierających składniki Razor, zobacz artykuł na temat używania składników ASP.NET Core Razor z bibliotek klas Razor (RCL).

Uwzględnij rozszerzalność MVC

W tej sekcji opisano zalecenia dotyczące bibliotek, które obejmują:

widoki Razor lub Razor Strony
pomocników tagów
Wyświetl składniki

W tej sekcji nie omówiono wieloplatformowości mającej na celu obsługę wielu wersji MVC. Aby uzyskać wskazówki dotyczące obsługi wielu wersji ASP.NET Core, zobacz Obsługa wielu wersji ASP.NET Core.

widoki Razor lub strony Razor

Projekt zawierający widoki Razor lub Razor Pages musi używać Microsoft.NET.Sdk.Razor SDK.

Jeśli projekt jest przeznaczony dla platformy .NET Core 3.x, wymaga:

Właściwość AddRazorSupportForMvc MSBuild ustawiona na wartość true.
Element <FrameworkReference> dla struktury udostępnionej.

Szablon projektu biblioteki klas Razor spełnia powyższe wymagania dotyczące projektów przeznaczonych dla platformy .NET Core. Skorzystaj z poniższych instrukcji dla edytora.

programu Visual Studio
programu Visual Studio Code/ interfejsu wiersza polecenia .NET

Użyj szablonu projektu biblioteki klas Razor. Należy zaznaczyć pole wyboru szablonu dla stron pomocy technicznej i widoków.

Uruchom następujące polecenie w zintegrowanym terminalu w VS Code lub konsoli poleceń (.NET CLI):

dotnet new razorclasslib -s

Na przykład:

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

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

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

</Project>

Jeśli projekt jest przeznaczony dla platformy .NET Standard, wymagana jest referencja do pakietu Microsoft.AspNetCore.Mvc. Pakiet Microsoft.AspNetCore.Mvc przeniesiony do struktury udostępnionej w ASP.NET Core 3.0 i dlatego nie jest już publikowany. Na przykład:

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

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

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

</Project>

Pomocnicy tagów

Projekt obejmujący pomocników tagów powinien używać zestawu SDK Microsoft.NET.Sdk. W przypadku określania wartości docelowej platformy .NET Core 3.x dodaj element <FrameworkReference> dla wspólnej platformy. Na przykład:

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

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

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

</Project>

Jeśli jest przeznaczona dla platformy .NET Standard (aby obsługiwać wersje wcześniejsze niż ASP.NET Core 3.x), dodaj odwołanie do pakietu do Microsoft.AspNetCore.Mvc.Razor. Pakiet Microsoft.AspNetCore.Mvc.Razor został przeniesiony do struktury udostępnionej i dlatego nie został już opublikowany. Na przykład:

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

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

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

</Project>

Wyświetlanie składników

Projekt zawierający składniki View powinien używać zestawu SDK Microsoft.NET.Sdk. Jeśli docelową platformą jest .NET Core 3.x, dodaj element <FrameworkReference> dla ramy współdzielonej. Na przykład:

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

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

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

</Project>

Aby korzystać z .NET Standard (w celu obsługi wersji wcześniejszych niż ASP.NET Core 3.x), dodaj odwołanie do pakietu Microsoft.AspNetCore.Mvc.ViewFeatures. Pakiet Microsoft.AspNetCore.Mvc.ViewFeatures został przeniesiony do struktury udostępnionej i dlatego nie został już opublikowany. Na przykład:

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

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

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

</Project>

Obsługa wielu wersji ASP.NET Core

Wielokrotne kierowanie jest wymagane do utworzenia biblioteki obsługującej wiele wariantów ASP.NET Core. Rozważmy scenariusz, w którym biblioteka pomocników tagów musi obsługiwać następujące warianty ASP.NET Core:

ASP.NET Core 2.1 przeznaczone dla platformy .NET Framework 4.6.1
ASP.NET Core 2.x przeznaczone dla platformy .NET Core 2.x
ASP.NET Core 3.x przeznaczone dla platformy .NET Core 3.x

Następujący plik projektu obsługuje te warianty za pośrednictwem właściwości 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>

Z poprzednim plikiem projektu:

Pakiet Markdig jest dodawany dla wszystkich użytkowników.
Odwołanie do Microsoft.AspNetCore.Mvc.Razor jest dodawane dla odbiorców docelowych na .NET Framework 4.6.1 lub nowszej lub .NET Core 2.x. Wersja 2.1.0 pakietu działa z ASP.NET Core 2.2 dzięki zgodności wstecznej.
Odwołuje się do wspólnej platformy przeznaczonej dla użytkowników celujących w .NET Core 3.x. Pakiet Microsoft.AspNetCore.Mvc.Razor znajduje się w strukturze udostępnionej.

W alternatywie, można celować w .NET Standard 2.0 zamiast celować zarówno w .NET Core 2.1, jak i .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>

W poprzednim pliku projektu istnieją następujące zastrzeżenia:

Ponieważ biblioteka zawiera tylko pomocników tagów, łatwiej jest kierować do określonych platform, na których działa ASP.NET Core: .NET Core i .NET Framework. Pomocnicy tagów nie mogą być używane przez inne platformy docelowe zgodne ze standardem .NET Standard 2.0, takie jak Unity i UWP.
Korzystanie z platformy .NET Standard 2.0 z programu .NET Framework ma pewne problemy, które zostały rozwiązane w programie .NET Framework 4.7.2. Możesz poprawić doświadczenie użytkowników korzystających z platformy .NET Framework od wersji 4.6.1 do 4.7.1, celując w platformę .NET Framework 4.6.1.

Jeśli biblioteka musi wywoływać interfejsy API specyficzne dla platformy, prosimy celować w konkretne implementacje .NET zamiast .NET Standard. Aby uzyskać więcej informacji, zobacz wielotargetowość.

Używanie interfejsu API, który nie został zmieniony

Wyobraź sobie scenariusz, w którym uaktualniasz bibliotekę oprogramowania pośredniczącego z platformy .NET Core 2.2 do wersji 3.1. Interfejsy API middleware ASP.NET Core używane w bibliotece nie uległy zmianie pomiędzy wersjami ASP.NET Core 2.2 i 3.1. Aby kontynuować obsługę biblioteki oprogramowania pośredniczącego na platformie .NET Core 3.1, wykonaj następujące czynności:

Postępuj zgodnie z wytycznymi dotyczącymi standardowej biblioteki .
Dodaj odwołanie do pakietu NuGet dla każdego pakietu NuGet interfejsu API, jeśli odpowiedni zestaw nie istnieje w strukturze udostępnionej.

Używanie zmienionego interfejsu API

Wyobraź sobie scenariusz, w którym uaktualniasz bibliotekę z platformy .NET Core 2.2 do platformy .NET Core 3.1. Interfejs API platformy ASP.NET Core używany w bibliotece zawiera zmianę powodującą niezgodność w ASP.NET Core 3.1. Zastanów się, czy biblioteka może zostać przepisana, aby nie używać uszkodzonego interfejsu API we wszystkich wersjach.

Jeśli możesz ponownie napisać bibliotekę, zrób to i przejdź do wcześniejszej platformy docelowej (na przykład .NET Standard 2.0 lub .NET Framework 4.6.1) z odwołaniami do pakietów.

Jeśli nie możesz ponownie napisać biblioteki, wykonaj następujące kroki:

Dodaj cel dla .NET Core 3.1.
Dodaj element <FrameworkReference> dla struktury udostępnionej.
Użyj dyrektywy #if preprocesora z odpowiednim symbolem struktury docelowej, aby warunkowo skompilować kod.

Na przykład, począwszy od wersji ASP.NET Core 3.1, synchroniczne odczyty i zapisy w strumieniach żądań HTTP i odpowiedzi są domyślnie wyłączone. program ASP.NET Core 2.2 domyślnie obsługuje zachowanie synchroniczne. Rozważ bibliotekę oprogramowania pośredniczącego, w której należy włączyć synchroniczne odczyty i zapisy, w których występują operacje we/wy. Biblioteka powinna ująć kod, aby włączyć funkcje synchroniczne w odpowiedniej dyrektywie preprocesora. Na przykład:

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

Korzystanie z interfejsu API wprowadzonego w wersji 3.1

Załóżmy, że chcesz użyć interfejsu API core ASP.NET wprowadzonego w ASP.NET Core 3.1. Weź pod uwagę następujące pytania:

Czy biblioteka funkcjonalnie wymaga nowego interfejsu API?
Czy biblioteka może zaimplementować tę funkcję w inny sposób?

Jeśli biblioteka funkcjonalnie wymaga interfejsu API i nie ma możliwości zaimplementowania go na poziomie podrzędnym:

Tylko .NET Core 3.x jako docelowy.
Dodaj element <FrameworkReference> dla struktury udostępnionej.

Jeśli biblioteka może zaimplementować tę funkcję w inny sposób:

Dodaj platformę .NET Core 3.x jako platformę docelową.
Dodaj element <FrameworkReference> dla struktury udostępnionej.
Użyj dyrektywy #if preprocesora z odpowiednim symbolem struktury docelowej, aby warunkowo skompilować kod.

Na przykład poniższy pomocnik tagów używa interfejsu IWebHostEnvironment wprowadzonego w ASP.NET Core 3.1. Odbiorcy docelowi platformy .NET Core 3.1 wykonują ścieżkę kodu zdefiniowaną przez symbol platformy docelowej NETCOREAPP3_1. Typ parametru konstruktora pomocnika tagów zmienia się na IHostingEnvironment dla użytkowników platform .NET Core 2.1 i .NET Framework 4.6.1. Ta zmiana była konieczna, ponieważ ASP.NET Core 3.1 oznaczyło IHostingEnvironment jako przestarzałe i zaleciło IWebHostEnvironment jako zamiennik.

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

Następujący wielokierunkowy plik projektu obsługuje ten scenariusz pomocnika tagów:

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

Używanie interfejsu API usuniętego ze struktury udostępnionej

Aby użyć zestawu ASP.NET Core usuniętego ze struktury udostępnionej, dodaj odpowiednie odwołanie do pakietu. Aby uzyskać listę pakietów usuniętych ze struktury udostępnionej w programie ASP.NET Core 3.1, zobacz Usuwanie przestarzałych odwołań do pakietów.

Aby na przykład dodać klienta webowego interfejsu API:

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

Dodatkowe zasoby

Interfejs użytkownika Razor wielokrotnego użytku w bibliotekach klas z ASP.NET Core
korzystanie ze składników Razor Core ASP.NET Core z biblioteki klas Razor (RCL)
obsługa implementacji platformy .NET
zasady obsługi platformy .NET

Udostępnij za pośrednictwem

Użyj interfejsów API ASP.NET Core w bibliotece klas

Określenie, które wersje ASP.NET Core wspierać

Korzystanie z platformy udostępnionej ASP.NET Core

Uwzględnij rozszerzalność Blazor

Obsługa aplikacji po stronie serwera i po stronie klienta

Obsługa wielu wersji platformy

Wsparcie tylko dla przetwarzania po stronie serwera

Uwzględnij rozszerzalność MVC

widoki Razor lub strony Razor

Pomocnicy tagów

Wyświetlanie składników

Obsługa wielu wersji ASP.NET Core

Używanie interfejsu API, który nie został zmieniony

Używanie zmienionego interfejsu API

Korzystanie z interfejsu API wprowadzonego w wersji 3.1

Używanie interfejsu API usuniętego ze struktury udostępnionej

Dodatkowe zasoby

Dodatkowe zasoby