Eventi
19 nov, 23 - 21 nov, 23
Partecipa alle sessioni online di Microsoft Ignite create per espandere le tue competenze e aiutarti a risolvere i problemi complessi di oggi.
Iscriviti subitoQuesto browser non è più supportato.
Esegui l'aggiornamento a Microsoft Edge per sfruttare i vantaggi di funzionalità più recenti, aggiornamenti della sicurezza e supporto tecnico.
Di Scott Addie
Questo documento fornisce indicazioni per l'uso delle API di base di ASP.NET in una libreria di classi. Per tutte le altre linee guida per le librerie, vedere Linee guida per la libreria open source.
ASP.NET Core rispetta i criteri di supporto di .NET Core. Consultare i criteri di supporto per determinare quali ASP.NET versioni core da supportare in una libreria. Una libreria deve:
Man mano che vengono rese disponibili le versioni di anteprima di ASP.NET Core, le modifiche di rilievo vengono pubblicate nel repository GitHub aspnet/Announcements . I test di compatibilità delle librerie possono essere eseguiti durante lo sviluppo di funzionalità del framework.
Con il rilascio di .NET Core 3.0, molti assembly ASP.NET Core non vengono più pubblicati in NuGet come pacchetti. Gli assembly vengono invece inclusi nel Microsoft.AspNetCore.App
framework condiviso, che viene installato con .NET Core SDK e i programmi di installazione di runtime. Per un elenco dei pacchetti non più pubblicati, vedere Rimuovere i riferimenti ai pacchetti obsoleti.
A partire da .NET Core 3.0, i progetti che usano Microsoft.NET.Sdk.Web
MSBuild SDK fanno riferimento implicitamente al framework condiviso. I progetti che usano Microsoft.NET.Sdk
o Microsoft.NET.Sdk.Razor
SDK devono fare riferimento a ASP.NET Core per usare ASP.NET API Core nel framework condiviso.
Per fare riferimento a ASP.NET Core, aggiungere l'elemento seguente <FrameworkReference>
al file di progetto:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
Blazor supporta la creazione di Razor librerie di classi dei componenti per le app lato server e lato client. Per supportare Razor i componenti in una libreria di classi, la libreria di classi deve usare Microsoft.NET.Sdk.Razor SDK.
Per supportare l'utilizzo Razor dei componenti da parte di app lato server e lato client da una singola libreria, usare le istruzioni seguenti per l'editor.
Usare il Razor modello di progetto Libreria di classi.
Nota
Non selezionare la casella di controllo Pagine e visualizzazioni di supporto. Se si seleziona la casella di controllo, viene restituita una libreria di classi che supporta solo le app lato server.
Libreria generata dal modello di progetto:
browser
come piattaforma supportata con l'elemento SupportedPlatform
MSBuild.RazorClassLibrary-CSharp.csproj
(origine di riferimento)
Nota
I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).
Se la libreria deve supportare le funzionalità aggiunte a Blazor nella versione corrente, supportando anche una o più versioni precedenti, la libreria con più entità di destinazione. Specificare un elenco delimitato da punto e virgola dei moniker del framework di destinazione nella TargetFrameworks
proprietà MSBuild:
<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>
Nell'esempio precedente il {TARGET FRAMEWORKS}
segnaposto rappresenta l'elenco tfms delimitato da punto e virgola. Ad esempio: netcoreapp3.1;net5.0
.
Le librerie di classi vengono compilate raramente per supportare solo le app lato server. Se la libreria di classi richiede solo funzionalità specifiche del lato server, ad esempio l'accesso a CircuitHandler o Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, o usa funzionalità specifiche di ASP.NET Core, ad esempio middleware, controller MVC o Razor Pages, usare uno degli approcci seguenti:
Specificare che la libreria supporta pagine e visualizzazioni quando la raccolta viene creata con la casella di controllo Pagine e visualizzazioni del supporto (Visual Studio) o l'opzione -s|--support-pages-and-views
con il dotnet new
comando :
dotnet new razorclasslib -s
Fornire solo un riferimento al framework per ASP.NET Core nel file di progetto della libreria, oltre a qualsiasi altra proprietà MSBuild necessaria:
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
Per altre informazioni sulle librerie contenenti Razor componenti, vedere Utilizzare componenti di Razor base ASP.NET da una Razor libreria di classi (RCL).
Questa sezione illustra le raccomandazioni per le librerie che includono:
Questa sezione non illustra il multitargeting per supportare più versioni di MVC. Per indicazioni sul supporto di più versioni di ASP.NET Core, vedere Supportare più versioni di ASP.NET Core.
Un progetto che include Razor visualizzazioni oRazor pagine deve usare Microsoft.NET.Sdk.Razor SDK.
Se il progetto è destinato a .NET Core 3.x, è necessario:
AddRazorSupportForMvc
MSBuild impostata su true
.<FrameworkReference>
per il framework condiviso.Il Razor modello di progetto Libreria di classi soddisfa i requisiti precedenti per i progetti destinati a .NET Core. Usare le istruzioni seguenti per l'editor.
Usare il Razor modello di progetto Libreria di classi. È necessario selezionare la casella di controllo Support pages and views (Pagine e visualizzazioni di supporto) del modello.
Ad esempio:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
Se invece il progetto è destinato a .NET Standard, è necessario un riferimento al pacchetto Microsoft.AspNetCore.Mvc . Il Microsoft.AspNetCore.Mvc
pacchetto è stato spostato nel framework condiviso in ASP.NET Core 3.0 e pertanto non viene più pubblicato. Ad esempio:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
</ItemGroup>
</Project>
Un progetto che include helper tag deve usare l'SDK Microsoft.NET.Sdk
. Se la destinazione è .NET Core 3.x, aggiungere un <FrameworkReference>
elemento per il framework condiviso. Ad esempio:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
Se la destinazione è .NET Standard (per supportare versioni precedenti a ASP.NET Core 3.x), aggiungere un riferimento al pacchetto a Microsoft.AspNetCore.Mvc.Razor Il Microsoft.AspNetCore.Mvc.Razor
pacchetto è stato spostato nel framework condiviso e pertanto non viene più pubblicato. Ad esempio:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
</ItemGroup>
</Project>
Un progetto che include i componenti di visualizzazione deve usare l'SDK Microsoft.NET.Sdk
. Se la destinazione è .NET Core 3.x, aggiungere un <FrameworkReference>
elemento per il framework condiviso. Ad esempio:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
Se la destinazione è .NET Standard (per supportare versioni precedenti a ASP.NET Core 3.x), aggiungere un riferimento al pacchetto a Microsoft.AspNetCore.Mvc.ViewFeatures. Il Microsoft.AspNetCore.Mvc.ViewFeatures
pacchetto è stato spostato nel framework condiviso e pertanto non viene più pubblicato. Ad esempio:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc.ViewFeatures" Version="2.2.0" />
</ItemGroup>
</Project>
Per creare una libreria che supporta più varianti di ASP.NET Core, è necessario il multitargeting. Si consideri uno scenario in cui una libreria helper tag deve supportare le varianti principali di ASP.NET seguenti:
Il file di progetto seguente supporta queste varianti tramite la TargetFrameworks
proprietà :
<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>
Con il file di progetto precedente:
Markdig
pacchetto viene aggiunto per tutti i consumer.Microsoft.AspNetCore.Mvc.Razor
pacchetto è incluso nel framework condiviso.In alternativa, .NET Standard 2.0 potrebbe essere destinato a .NET Core 2.1 e .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>
Con il file di progetto precedente, esistono le avvertenze seguenti:
Se la libreria deve chiamare API specifiche della piattaforma, specificare come destinazione implementazioni .NET invece di .NET Standard. Per altre informazioni, vedere Multi-targeting.
Si immagini uno scenario in cui si sta aggiornando una libreria middleware da .NET Core 2.2 a 3.1. Le API middleware di ASP.NET Core usate nella libreria non sono cambiate tra ASP.NET Core 2.2 e 3.1. Per continuare a supportare la libreria middleware in .NET Core 3.1, seguire questa procedura:
Si immagini uno scenario in cui si sta aggiornando una libreria da .NET Core 2.2 a .NET Core 3.1. Un'API core ASP.NET usata nella libreria presenta una modifica di rilievo in ASP.NET Core 3.1. Valutare se la libreria può essere riscritta per non usare l'API interrotta in tutte le versioni.
Se è possibile riscrivere la libreria, eseguire questa operazione e continuare a usare un framework di destinazione precedente ,ad esempio .NET Standard 2.0 o .NET Framework 4.6.1 con riferimenti al pacchetto.
Se non è possibile riscrivere la libreria, seguire questa procedura:
<FrameworkReference>
elemento per il framework condiviso.Ad esempio, le letture e le scritture sincrone nei flussi di richiesta e risposta HTTP sono disabilitate per impostazione predefinita a partire da ASP.NET Core 3.1. ASP.NET Core 2.2 supporta il comportamento sincrono per impostazione predefinita. Si consideri una libreria middleware in cui le letture e le scritture sincrone devono essere abilitate in caso di I/O. La libreria deve racchiudere il codice per abilitare le funzionalità sincrone nella direttiva del preprocessore appropriata. Ad esempio:
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);
}
Si supponga di voler usare un'API ASP.NET Core introdotta in ASP.NET Core 3.1. Prendere in considerazione le domande seguenti:
Se la libreria richiede funzionalmente l'API e non è possibile implementarla di livello inferiore:
<FrameworkReference>
elemento per il framework condiviso.Se la libreria può implementare la funzionalità in modo diverso:
<FrameworkReference>
elemento per il framework condiviso.Ad esempio, l'helper tag seguente usa l'interfaccia IWebHostEnvironment introdotta in ASP.NET Core 3.1. I consumer destinati a .NET Core 3.1 eseguono il percorso del codice definito dal simbolo del NETCOREAPP3_1
framework di destinazione. Il tipo di parametro del costruttore dell'helper tag cambia in IHostingEnvironment per i consumer .NET Core 2.1 e .NET Framework 4.6.1. Questa modifica è stata necessaria perché ASP.NET Core 3.1 contrassegnato IHostingEnvironment
come obsoleto e consigliato IWebHostEnvironment
come sostituzione.
[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
}
Il file di progetto multi-destinazione seguente supporta questo scenario helper tag:
<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>
Per usare un assembly ASP.NET Core rimosso dal framework condiviso, aggiungere il riferimento al pacchetto appropriato. Per un elenco dei pacchetti rimossi dal framework condiviso in ASP.NET Core 3.1, vedere Rimuovere i riferimenti ai pacchetti obsoleti.
Ad esempio, per aggiungere il client API Web:
<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>
Feedback su ASP.NET Core
ASP.NET Core è un progetto di open source. Selezionare un collegamento per fornire feedback:
Eventi
19 nov, 23 - 21 nov, 23
Partecipa alle sessioni online di Microsoft Ignite create per espandere le tue competenze e aiutarti a risolvere i problemi complessi di oggi.
Iscriviti subito