Condividi tramite

ASP.NET Core file statici Blazor

Annotazioni

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 10 di questo articolo.

Avvertimento

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Questo articolo descrive la Blazor configurazione dell'app per la gestione di file statici.

Per informazioni generali sulla distribuzione di file statici tramite la mappatura degli asset statici con le convenzioni degli endpoint di routing, consulta File statici in ASP.NET Core prima di leggere questo articolo.

Asset statici del framework precaricati Blazor

In Blazor Web Apps, gli asset statici del framework vengono precaricati automaticamente tramite Link intestazioni, il che consente al browser di precaricare le risorse prima che la pagina iniziale venga acquisita e sottoposta a rendering.

Nelle app autonome Blazor WebAssembly , gli asset del framework sono pianificati per il download e la memorizzazione nella cache con priorità elevata durante l'elaborazione delle pagine del browser index.html quando:

  • La OverrideHtmlAssetPlaceholders proprietà MSBuild nel file di progetto dell'app (.csproj) è impostata su true:

    <PropertyGroup>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>

  • L'elemento seguente <link> che contiene rel="preload" è presente nel <head> contenuto di wwwroot/index.html:

    <link rel="preload" id="webassembly" />

Distribuzione di asset statici lato server nelle app Blazor

La gestione degli asset statici viene gestita dalle convenzioni degli endpoint di routing o da un middleware descritto nella tabella seguente.

Caratteristica / Funzionalità API (Interfaccia di Programmazione delle Applicazioni) Versione di .NET Descrizione
Mappare le convenzioni di routing degli endpoint per gli asset statici MapStaticAssets .NET 9 o versione successiva Ottimizza il recapito di risorse statiche ai clienti.
Middleware dei file statici UseStaticFiles Tutte le versioni di .NET Serve asset statici ai client senza le ottimizzazioni di Map Static Assets, ma utile per alcune attività che Map Static Assets non è in grado di gestire.

Le risorse statiche della mappa possono sostituire UseStaticFiles nella maggior parte delle situazioni. Tuttavia, Map Static Assets è ottimizzato per gestire gli asset da posizioni note nell'app in fase di compilazione e pubblicazione. Se l'app fornisce asset da altre posizioni, ad esempio risorse su disco o incorporate, UseStaticFiles deve essere utilizzato.

Map Static Assets (MapStaticAssets) sostituisce anche la chiamata UseBlazorFrameworkFiles nelle app che gestiscono Blazor WebAssembly i file del framework e non è necessario chiamare UseBlazorFrameworkFiles in modo esplicito in un Blazor Web App perché l'API viene chiamata automaticamente quando si richiama AddInteractiveWebAssemblyComponents.

Quando sono abilitate le modalità di rendering Interattivo WebAssembly o Interactive Auto :

  • Blazor crea un endpoint per esporre la raccolta di risorse come JS modulo.
  • L'URL viene generato nel corpo della richiesta come stato del componente persistente quando viene eseguito il rendering di un componente WebAssembly nella pagina.
  • Durante l'avvio di WebAssembly, Blazor recupera l'URL, importa il modulo e chiama una funzione per recuperare la raccolta di asset e ricostruirla in memoria. L'URL è specifico del contenuto e memorizzato nella cache per sempre, quindi questo costo overhead viene pagato una sola volta per utente fino a quando l'app non viene aggiornata.
  • La raccolta di risorse viene esposta anche in un URL leggibile (_framework/resource-collection.js), quindi JS ha accesso alla raccolta di risorse per la navigazione avanzata o per implementare funzionalità di altri framework e componenti di terze parti.

Il middleware dei file statici (UseStaticFiles) è utile nelle seguenti situazioni che non possono essere gestite da Map Static Assets (MapStaticAssets):

  • Gestire i file dal disco che non fanno parte del processo di compilazione o pubblicazione, ad esempio i file aggiunti alla cartella dell'applicazione durante o dopo la distribuzione.
  • Applicazione di un prefisso di percorso ai Blazor WebAssembly file di asset statici, illustrati nella sezione Prefisso per Blazor WebAssembly gli asset .
  • Configurazione della mappatura delle estensioni dei file a tipi di contenuto specifici e impostazione delle opzioni dei file statici, descritte nella sezione Mapping file e opzioni di file statici.

Per altre informazioni, vedere File statici in ASP.NET Core.

Distribuire asset con le convenzioni di routing degli asset statici di Map Static Assets

Questa sezione si applica alle app del lato Blazor server.

Gli asset vengono recapitati tramite la ComponentBase.Assets proprietà , che risolve l'URL con impronta digitale per un determinato asset. Nell'esempio seguente Bootstrap, il foglio di stile dell'app del modello di progetto (Blazor) e il foglio di stile per l'isolamento CSS (app.css) (basato sul namespace dell'app ) sono collegati a un componente radice, solitamente componente BlazorSample (App):

<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />

Componente ImportMap

Questa sezione si applica a Blazor Web App che chiamano MapRazorComponents.

Il ImportMap componente (ImportMap) rappresenta un elemento della mappa di importazione (<script type="importmap"></script>) che definisce la mappa di importazione per gli script del modulo. Il componente Import Map viene inserito nel contenuto <head> del componente radice, in genere il componente App (Components/App.razor).

<ImportMap />

Se un oggetto personalizzato ImportMapDefinition non è assegnato a un componente Mappa di Importazione, la mappa di importazione viene generata in base alle risorse dell'app.

Annotazioni

ImportMapDefinition Le istanze sono costose da creare, quindi è consigliabile memorizzarle nella cache durante la creazione di un'istanza aggiuntiva.

Gli esempi seguenti illustrano le definizioni delle mappe di importazione personalizzate e le mappe di importazione create.

Mappa di importazione di base:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

Il codice precedente restituisce la mappa di importazione seguente:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

Mappa di importazione a scopo definito

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

Il codice precedente restituisce la mappa di importazione seguente:

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

Importare la mappa con integrità:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    new Dictionary<string, string>
    {
        { "https://cdn.example.com/jquery.js", "sha384-abc123" },
    });

Il codice precedente restituisce la mappa di importazione seguente:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

Combinare le definizioni delle mappe di importazione (ImportMapDefinition) con ImportMapDefinition.Combine.

Importare la mappa creata da un oggetto ResourceAssetCollection che esegue il mapping degli asset statici agli URL univoci corrispondenti:

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

Il codice precedente restituisce la mappa di importazione seguente:

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

Importare violazioni dei criteri di sicurezza del contenuto (CSP) della mappa

Questa sezione si applica a Blazor Web App che chiamano MapRazorComponents.

Il componente ImportMap viene reso come tag inline <script>, il che viola un rigoroso criterio di sicurezza dei contenuti (CSP - Content Security Policy) che imposta la direttiva default-src o script-src.

Per esempi di come risolvere la violazione dei criteri con l'integrità della sottorisorsa (SRI) o un nonce crittografico, vedere Risoluzione delle violazioni CSP con l'integrità della sottorisorsa (SRI) o un nonce.

Configurare il middleware dei file statici per servire contenuti statici ai client chiamando UseStaticFiles nella pipeline di elaborazione delle richieste dell'app. Per altre informazioni, vedere File statici in ASP.NET Core.

Nelle versioni precedenti a .NET 8, Blazor i file statici del framework, ad esempio lo Blazor script, vengono gestiti tramite middleware di file statici. In .NET 8 o versione successiva, Blazor i file statici del framework vengono mappati usando il routing degli endpoint e il middleware dei file statici non viene più usato.

Impronta digitale delle risorse statiche lato client nelle app autonome Blazor WebAssembly

Nelle app autonome Blazor WebAssembly durante la compilazione/pubblicazione, il framework sovrascrive i segnaposto in index.html con i valori calcolati durante la build per creare impronte digitali degli asset statici per il rendering lato client. Un'impronta digitale viene inserita nel nome del blazor.webassembly.js file di script e viene generata una mappa di importazione per altri asset .NET.

Affinché sia adottato il fingerprinting, la seguente configurazione wwwwoot/index.html deve essere presente nel file di un'app autonoma Blazor WebAssembly.

<head>
    ...
    <script type="importmap"></script>
    ...
</head>

<body>
    ...
    <script src="_framework/blazor.webassembly#[.{fingerprint}].js"></script>
    ...
</body>

</html>

Nel file di progetto (.csproj) la <OverrideHtmlAssetPlaceholders> proprietà è impostata su true:

<PropertyGroup>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>

Quando si risolvono le importazioni per l'interoperabilità JavaScript, la mappa di importazione viene usata dal browser per risolvere i file con impronta digitale.

Qualsiasi script in index.html con il marcatore di impronta digitale è tracciato dal framework. Ad esempio, un file di script denominato scripts.js nella cartella dell'app wwwroot/js è con impronta digitale aggiungendo #[.{fingerprint}] prima dell'estensione del file (.js):

<script src="js/scripts#[.{fingerprint}].js"></script>

Improntare digitalmente gli asset statici lato client in Blazor Web Apps

Per il rendering lato client (CSR) in Blazor Web Apps (modalità di rendering Interactive Auto o Interactive WebAssembly), il "fingerprinting" lato server degli asset statici è abilitato adottando le convenzioni dell'endpoint di routing per gli asset statici (), il componente MapStaticAssets e la proprietà (ImportMap). Per altre informazioni, vedere File statici in ASP.NET Core.

Per eseguire l'impronta digitale di moduli JavaScript aggiuntivi per csr, usare l'elemento <StaticWebAssetFingerprintPattern> nel file di progetto dell'app (.csproj). Nell'esempio seguente viene aggiunta un'impronta digitale per tutti i file forniti dallo .mjs sviluppatore nell'app:

<ItemGroup>
  <StaticWebAssetFingerprintPattern Include="JSModule" Pattern="*.mjs" 
    Expression="#[.{fingerprint}]!" />
</ItemGroup>

Quando si risolvono le importazioni per l'interoperabilità JavaScript, la mappa di importazione viene usata dal browser per risolvere i file con impronta digitale.

Blazor

Le tabelle seguenti riepilogano i formati di file <link>href statici in base alla versione .NET.

Per il percorso del <head>contenuto in cui sono posizionati i collegamenti di file statici, vedere la struttura del progetto ASP.NET CoreBlazor. I collegamenti ad asset statici possono essere forniti anche usando <HeadContent> componenti in componenti Razor singoli.

Per il percorso del <head>contenuto in cui sono posizionati i collegamenti di file statici, vedere la struttura del progetto ASP.NET CoreBlazor.

.NET 9 o versione successiva

Tipo di app valore href Esempi
Blazor Web App @Assets["{PATH}"] <link rel="stylesheet" href="@Assets["app.css"]" />
<link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Blazor Server† @Assets["{PATH}"] <link href="@Assets["css/site.css"]" rel="stylesheet" />
<link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Autonomo Blazor WebAssembly {PATH} <link rel="stylesheet" href="css/app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Tipo di app valore href Esempi
Blazor Web App {PATH} <link rel="stylesheet" href="app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor Server† {PATH} <link href="css/site.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Autonomo Blazor WebAssembly {PATH} <link rel="stylesheet" href="css/app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x o versioni precedenti

Tipo di app valore href Esempi
Blazor Server† {PATH} <link href="css/site.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Ospitato Blazor WebAssembly* {PATH} <link href="css/app.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly {PATH} <link href="css/app.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

Blazor Server† è supportato in .NET 8 o versione successiva, ma non è più un modello di progetto dopo .NET 7.
*È consigliabile aggiornare le app ospitate Blazor WebAssembly a Blazor Web Apps quando si adotta .NET 8 o versione successiva.

Modalità progetto di risorse web statiche

Questa sezione si applica al progetto .Client di un Blazor Web App.

L’impostazione necessaria <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> nel progetto .Client di un Blazor Web App ripristina i comportamenti degli asset statici Blazor WebAssembly alle impostazioni predefinite, così che il progetto si comporti come parte del progetto ospitante. L'SDK Blazor WebAssembly (Microsoft.NET.Sdk.BlazorWebAssembly) configura gli asset Web statici in modo specifico per funzionare in modalità "autonoma" con un server che usa semplicemente gli output dalla libreria. Questo non è appropriato per un oggetto Blazor Web App, in cui la parte WebAssembly dell'app è una parte logica dell'host e deve comportarsi in modo più simile a una libreria. Ad esempio, il progetto non espone il bundle di stili (ad esempio , BlazorSample.Client.styles.css) e fornisce invece solo l'host con il bundle di progetto, in modo che l'host possa includerlo nel proprio bundle di stili.

La modifica del valore (Default) di <StaticWebAssetProjectMode> o la rimozione della proprietà dal .Client progetto non è supportata.

Prefisso per Blazor WebAssembly gli asset

Questa sezione si applica a Blazor Web Apps.

Usare l'opzione WebAssemblyComponentsEndpointOptions.PathPrefix endpoint per impostare la stringa di percorso che indica il prefisso degli asset Blazor WebAssembly. Il percorso deve corrispondere a un progetto di applicazione a cui si fa Blazor WebAssembly riferimento.

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

Nell'esempio precedente il {PATH PREFIX} segnaposto è il prefisso del percorso e deve iniziare con una barra (/).

Nell'esempio seguente il prefisso del percorso è impostato su /path-prefix:

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Percorso di base dell'asset Web statico

Questa sezione si applica alle app autonome Blazor WebAssembly .

La pubblicazione dell'app inserisce gli asset statici dell'app, inclusi Blazor i file framework (_framework asset di cartelle), nel percorso radice (/) nell'output pubblicato. La <StaticWebAssetBasePath> proprietà specificata nel file di progetto (.csproj) imposta il percorso di base su un percorso non radice:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

Nell'esempio precedente il {PATH} segnaposto è il percorso.

Senza impostare la <StaticWebAssetBasePath> proprietà, un'app autonoma viene pubblicata in /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

Nell'esempio precedente, il {TFM} segnaposto è l'identificatore del framework di destinazione (TFM).

Se la proprietà <StaticWebAssetBasePath> in un'app standalone Blazor WebAssembly imposta il percorso dell'asset statico pubblicato su app1, il percorso radice dell'app nell'output finale è /app1.

Nel file di progetto dell'app autonoma Blazor WebAssembly (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

Nell'output pubblicato, il percorso dell'app autonoma Blazor WebAssembly è /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

Nell'esempio precedente, il {TFM} segnaposto è l'identificatore del framework di destinazione (TFM).

Questa sezione si applica alle app autonome Blazor WebAssembly e alle soluzioni ospitate Blazor WebAssembly .

La pubblicazione dell'app inserisce gli asset statici dell'app, inclusi Blazor i file framework (_framework asset di cartelle), nel percorso radice (/) nell'output pubblicato. La <StaticWebAssetBasePath> proprietà specificata nel file di progetto (.csproj) imposta il percorso di base su un percorso non radice:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

Nell'esempio precedente il {PATH} segnaposto è il percorso.

Senza impostare la <StaticWebAssetBasePath> proprietà, l'app client di una soluzione ospitata o un'app autonoma viene pubblicata nei percorsi seguenti:

  • Server Nel progetto di una soluzione ospitata Blazor WebAssembly: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • In un'app autonoma Blazor WebAssembly: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

Se la proprietà <StaticWebAssetBasePath> imposta il percorso dell'asset statico pubblicato su Client nel progetto Blazor WebAssembly di un'app ospitata Blazor WebAssembly o in un'app autonoma app1, il percorso radice dell'app nell'output pubblicato è /app1.

Client Nel file di progetto dell'app (.csproj) o nel file di progetto dell'app autonoma Blazor WebAssembly (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

Nell'output pubblicato:

  • Percorso dell'app client nel Server progetto di una soluzione ospitata Blazor WebAssembly : /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
  • Percorso di un'app autonoma Blazor WebAssembly : /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

La <StaticWebAssetBasePath> proprietà viene usata più comunemente per controllare i percorsi per pubblicare asset statici di più Blazor WebAssembly app in una singola distribuzione ospitata. Per ulteriori informazioni, consultare Più app ASP.NET Core ospitate. La proprietà è efficace anche nelle app autonome Blazor WebAssembly .

Negli esempi precedenti, il {TFM} segnaposto è il moniker del framework di destinazione (TFM).

Mappature di file e opzioni per file statici

Questa sezione si applica ai file statici lato server.

Per creare mapping di file aggiuntivi con un FileExtensionContentTypeProvider o configurare altri StaticFileOptions, usare uno degli approcci seguenti. Negli esempi seguenti il {EXTENSION} segnaposto è l'estensione di file e il {CONTENT TYPE} segnaposto è il tipo di contenuto.

  • Configurare le opzioni mediante iniezione delle dipendenze (DI) nel file Program utilizzando StaticFileOptions:

    using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

    Questo approccio configura lo stesso provider di file usato per gestire lo Blazor script. Assicurarsi che la configurazione personalizzata non interferisca con la gestione dello Blazor script. Ad esempio, non rimuovere il mapping per i file JavaScript configurando il provider con provider.Mappings.Remove(".js").

  • Usare due chiamate a UseStaticFiles nel Program file:

    • Configurare il provider di file personalizzato nella prima chiamata con StaticFileOptions.
    • Il secondo middleware serve lo Blazor script, che usa la configurazione predefinita dei file statici fornita dal Blazor framework.
    using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

  • È possibile evitare di interferire con la gestione _framework/blazor.server.js usando MapWhen per eseguire un middleware di file statico personalizzato:

    app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

Gestire i file da più posizioni

Le istruzioni in questa sezione sono esclusivamente applicabili a Blazor Web Apps.

Per gestire i file da più posizioni con :CompositeFileProvider

Esempio:

Creare una nuova cartella nel progetto server denominato AdditionalStaticAssets. Inserire un'immagine nella cartella .

Aggiungere la seguente istruzione using all'inizio del file del progetto del server Program.

using Microsoft.Extensions.FileProviders;

Nel file del progetto server Program della chiamata a UseStaticFilesaggiungere il codice seguente:

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

Nel markup del componente Home dell'app Home.razor, fare riferimento all'immagine con il tag <img>.

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

Nell'esempio precedente:

  • Il {IMAGE FILE NAME} segnaposto è il nome del file di immagine. Non è necessario fornire un segmento di percorso se il file di immagine si trova nella radice della AdditionalStaticAssets cartella.
  • Il {ALT TEXT} segnaposto è il testo alternativo dell'immagine.

Avvia l'app.

Risorse aggiuntive

  • Last updated on