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

  • Artykuł

Autor: Scott Addie

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ślanie, które wersje ASP.NET Core do obsługi

ASP.NET Core jest zgodna z zasadami obsługi platformy .NET Core. Zapoznaj się z zasadami pomocy technicznej podczas określania, które wersje ASP.NET Core do obsługi w bibliotece. Biblioteka powinna:

  • Staraj się obsługiwać wszystkie wersje ASP.NET Core sklasyfikowane jako obsługa długoterminowa (LTS).
  • Nie należy wspierać wersji ASP.NET Core sklasyfikowanych jako End of Life (EOL).

W miarę udostępniania wersji zapoznawczych ASP.NET Core zmiany powodujące niezgodność są publikowane w repozytorium GitHub aspnet/Anonss . 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 zestawy są zawarte w strukturze udostępnionej Microsoft.AspNetCore.App , która jest instalowana z instalatorami zestawu .NET Core SDK i środowiska uruchomieniowego. Aby uzyskać listę pakietów, które nie są już publikowane, zobacz Usuwanie przestarzałych odwołań do pakietów.

Od wersji .NET Core 3.0 projekty korzystające z Microsoft.NET.Sdk.Web zestawu MSBuild SDK niejawnie odwołują się do udostępnionej platformy. Projekty korzystające z zestawu Microsoft.NET.Sdk SDK Microsoft.NET.Sdk.Razor lub muszą odwoływać się ASP.NET Core do korzystania z interfejsów API ASP.NET Core w strukturze udostępnionej.

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

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

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

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

</Project>

Uwzględnij Blazor rozszerzalność

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

Obsługa aplikacji po stronie serwera i po stronie klienta

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

Użyj szablonu Razor projektu Biblioteka klas.

Uwaga

Nie zaznaczaj pól wyboru Strony i widoki pomocy technicznej. Zaznaczenie pola wyboru powoduje wyświetlenie 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, uwzględniając browser jako obsługiwaną platformę z elementem SupportedPlatform MSBuild.
  • Dodaje odwołanie do pakietu NuGet dla pliku Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (źródło referencyjne)

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .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ć tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Obsługa wielu wersji platformy

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

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

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

Obsługa tylko użycia 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 funkcji specyficznych dla rdzenia, takich jak oprogramowanie pośredniczące, kontrolery MVC lub Razor strony, należy użyć jednej z następujących metod:

  • Określ, że biblioteka obsługuje strony i widoki po utworzeniu biblioteki za pomocą pola wyboru Strony pomocy technicznej i widoki (Visual Studio) lub -s|--support-pages-and-views opcję za dotnet new pomocą polecenia :

    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 Razor składniki, zobacz Używanie składników ASP.NET Core Razor z Razor biblioteki klas (RCL).

Uwzględnij rozszerzalność MVC

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

W tej sekcji nie omówiono wielowersyjności w celu obsługi wielu wersji wzorca MVC. Aby uzyskać wskazówki dotyczące obsługi wielu wersji ASP.NET Core, zobacz Obsługa wielu wersji ASP.NET Core.

Razor widoki lub Razor strony

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

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

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

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

Użyj szablonu Razor projektu Biblioteka klas. Należy zaznaczyć pole wyboru Strony i widoki pomocy technicznej szablonu.

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, wymagane jest odwołanie do pakietu Microsoft.AspNetCore.Mvc . Pakiet Microsoft.AspNetCore.Mvc został 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 zawierający pomocników tagów powinien używać zestawu Microsoft.NET.Sdk SDK. W przypadku określania wartości docelowej platformy .NET Core 3.x dodaj <FrameworkReference> element dla platformy udostępnionej. 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 pliku 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>

Składniki widoku

Projekt zawierający składniki Widoku powinien używać zestawu Microsoft.NET.Sdk SDK. W przypadku określania wartości docelowej platformy .NET Core 3.x dodaj <FrameworkReference> element dla platformy udostępnionej. Na przykład:

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

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

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

</Project>

W przypadku określania wartości docelowej dla platformy .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

Wiele elementów docelowych 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 TargetFrameworks właściwości :

<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.
  • Dla użytkowników przeznaczonych dla platformy .NET Framework 4.6.1 lub nowszej lub .NET Core 2.x jest dodawane odwołanie do platformy Microsoft.AspNetCore.MvcRazor . Wersja 2.1.0 pakietu działa z ASP.NET Core 2.2 ze względu na zgodność z poprzednimi wersjami.
  • Do platformy udostępnionej odwołuje się użytkownik przeznaczony dla platformy .NET Core 3.x. Pakiet Microsoft.AspNetCore.Mvc.Razor jest uwzględniony w strukturze udostępnionej.

Alternatywnie można użyć platformy .NET Standard 2.0 zamiast kierowania na platformy .NET Core 2.1 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, UWP i Xamarin.
  • 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 ulepszyć środowisko dla użytkowników przy użyciu programu .NET Framework 4.6.1 do 4.7.1, wybierając platformę .NET Framework 4.6.1.

Jeśli biblioteka musi wywoływać interfejsy API specyficzne dla platformy, docelowe implementacje platformy .NET zamiast .NET Standard. Aby uzyskać więcej informacji, zobacz Multi-target (Obsługa wielu elementów docelowych).

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 oprogramowania pośredniczącego ASP.NET Core używane w bibliotece nie uległy zmianie między 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 ze wskazówkami dotyczącymi biblioteki standardowej.
  • 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 ma 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 element docelowy dla platformy .NET Core 3.1.
  • <FrameworkReference> Dodaj element dla platformy udostępnionej.
  • Użyj dyrektywy #if preprocesora z odpowiednim symbolem struktury docelowej, aby warunkowo skompilować kod.

Na przykład synchroniczne odczyty i zapisy w strumieniach żądań HTTP i odpowiedzi są domyślnie wyłączone jako ASP.NET Core 3.1. 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. Zastanów się nad następującymi pytaniami:

  1. Czy biblioteka funkcjonalnie wymaga nowego interfejsu API?
  2. 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:

  • Docelowy tylko program .NET Core 3.x.
  • <FrameworkReference> Dodaj element dla platformy udostępnionej.

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

  • Dodaj platformę .NET Core 3.x jako platformę docelową.
  • <FrameworkReference> Dodaj element dla platformy 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 wprowadzonego IWebHostEnvironment w ASP.NET Core 3.1. Odbiorcy docelowi platformy .NET Core 3.1 wykonują ścieżkę kodu zdefiniowaną przez symbol platformy NETCOREAPP3_1 docelowej. Typ parametru konstruktora pomocnika tagów zmienia się na IHostingEnvironment dla użytkowników platformy .NET Core 2.1 i .NET Framework 4.6.1. Ta zmiana była konieczna, ponieważ ASP.NET Core 3.1 oznaczone IHostingEnvironment jako przestarzałe i zalecane 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 pakietu.

Aby na przykład dodać klienta internetowego 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