ASP.NET file statici core Blazor

  • Articolo

Nota

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

Avviso

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

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

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

Distribuzione statica degli asset nelle app lato Blazor server

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

Funzionalità API Versione .NET Descrizione
Eseguire il mapping delle convenzioni degli endpoint di routing degli asset statici MapStaticAssets .NET 9 o versione successiva Ottimizza il recapito di asset statici ai client.
Middleware dei file statici UseStaticFiles Tutte le versioni di .NET Serve asset statici ai client senza le ottimizzazioni di Mapping di asset statici, ma utile per alcune attività che eseguono il mapping di asset statici non è in grado di gestire.

Configurare Map Static Assets chiamando MapStaticAssets nella pipeline di elaborazione delle richieste dell'app, che esegue le operazioni seguenti:

Map Static Assets opera combinando processi di compilazione e pubblicazione per raccogliere informazioni sugli asset statici nell'app. Queste informazioni vengono utilizzate dalla libreria di runtime per gestire in modo efficiente gli asset statici ai browser.

Gli asset statici mappa possono essere sostituiti 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 serve asset da altre posizioni, ad esempio risorse disco o incorporate, UseStaticFiles deve essere usata.

Map Static Assets (MapStaticAssets) sostituisce 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.

Mapping di asset statici offre i vantaggi seguenti che non sono disponibili quando si chiama UseStaticFiles:

  • Compressione in fase di compilazione per tutti gli asset nell'app, inclusi JavaScript (JS) e fogli di stile, ma escludendo gli asset di immagine e carattere già compressi. La compressione Gzip (Content-Encoding: gz) viene usata durante lo sviluppo. La compressione Gzip con Brotli (Content-Encoding: br) viene usata durante la pubblicazione.
  • Impronta digitale per tutti gli asset in fase di compilazione con una stringa con codifica Base64 dell'hash SHA-256 del contenuto di ogni file. Ciò impedisce di riutilizzare una versione precedente di un file, anche se il file precedente viene memorizzato nella cache. Gli asset con impronta digitale vengono memorizzati nella cache usando la immutable direttiva , che comporta che il browser non richieda mai più l'asset fino a quando non cambia. Per i browser che non supportano la immutable direttiva, viene aggiunta una max-age direttiva .
    • Anche se un asset non è con impronta digitale, i contenuti basati su ETags vengono generati per ogni asset statico usando l'hash delle impronte digitali del file come ETag valore. In questo modo, il browser scarica un file solo se il contenuto cambia (o il file viene scaricato per la prima volta).
    • Internamente, Blazor esegue il mapping degli asset fisici alle impronte digitali, che consente all'app di:
      • Trovare gli asset generati Blazor automaticamente, ad esempio Razor css con ambito componente per Blazorla funzionalità di isolamento CSS e JS gli asset descritti dalle JS mappe di importazione.
      • Generare tag di collegamento nel <head> contenuto della pagina per precaricare gli asset.
  • Durante i test di sviluppo di Visual Studio Ricaricamento rapido:
    • Le informazioni sull'integrità vengono rimosse dagli asset per evitare problemi quando un file viene modificato durante l'esecuzione dell'app.
    • Gli asset statici non vengono memorizzati nella cache per assicurarsi che il browser recuperi sempre il contenuto corrente.

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.

Mapping di asset statici non fornisce funzionalità per la minimizzazione o altre trasformazioni di file. La minificazione viene in genere gestita da codice personalizzato o strumenti di terze parti.

Il middleware dei file statici (UseStaticFiles) è utile nelle situazioni seguenti che non è possibile gestire gli asset statici (MapStaticAssets):

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

Distribuire asset con convenzioni di routing degli asset statici mappate

Questa sezione si applica alle app 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 Blazor foglio di stile dell'app modello di progetto (app.css) e il foglio di stile di isolamento CSS (in base allo spazio dei nomi di un'app di BlazorSample) sono collegati in un componente radice, in genere il App componente (Components/App.razor):

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

Importare mappe

Questa sezione si applica alle app lato Blazor server.

Il componente Import Map (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 <head> contenuto del componente radice, in genere il App componente (Components/App.razor).

<ImportMap />

Se un oggetto personalizzato ImportMapDefinition non è assegnato a un componente Di importazione mappa, la mappa di importazione viene generata in base agli asset dell'app.

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 con ambito:

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

Configurare il middleware dei file statici per gestire asset 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.

Questa sezione si applica a tutte le versioni e Blazor le app .NET.

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

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

Per il percorso del contenuto in cui sono posizionati i collegamenti di file statici, vedere ASP.NET struttura del <head> progetto 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 asset Web statico

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

L'impostazione .Client necessaria <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> nel progetto di un Blazor Web App asset statico ripristina Blazor WebAssembly i comportamenti degli asset statici rispetto alle impostazioni predefinite, in modo che il progetto si comporti come parte del progetto ospitato. 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.

File statici in ambienti nonDevelopment

Questa sezione si applica ai file statici lato server.

Quando si esegue un'app in locale, gli asset Web statici sono abilitati solo nell'ambiente Development . Per abilitare i file statici per ambienti diversi da Development durante lo sviluppo locale e il test (ad esempio, Staging), chiamare UseStaticWebAssets nel WebApplicationBuilder Program file .

Avviso

Chiamare UseStaticWebAssets l'ambiente esatto per impedire l'attivazione della funzionalità nell'ambiente di produzione, perché serve i file da percorsi separati su disco diverso dal progetto se chiamato in un ambiente di produzione. L'esempio in questa sezione controlla l'ambiente Staging chiamando IsStaging.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

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 per Blazor WebAssembly gli asset. 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 è il moniker del framework di destinazione (TFM), ad esempio net6.0.

Se la <StaticWebAssetBasePath> proprietà in un'app autonoma Blazor WebAssembly imposta il percorso dell'asset statico pubblicato su app1, il percorso radice dell'app nell'output pubblicato è /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 è il moniker del framework di destinazione (TFM), ad esempio net6.0.

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 ospitataBlazor WebAssembly:/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • In un'app autonoma Blazor WebAssembly : /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

Se la <StaticWebAssetBasePath> proprietà nel Client progetto di un'app ospitata Blazor WebAssembly o in un'app autonoma Blazor WebAssembly imposta il percorso dell'asset statico pubblicato su 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 altre informazioni, vedere Più app ospitate ASP.NET CoreBlazor WebAssembly. La proprietà è efficace anche nelle app autonome Blazor WebAssembly .

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

Mapping di file e opzioni di file statici

Questa sezione si applica ai file statici lato server.

Per creare mapping di file aggiuntivi con un oggetto o configurare un FileExtensionContentTypeProvider altro 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. Lo spazio dei nomi per l'API seguente è Microsoft.AspNetCore.StaticFiles.

  • Configurare le opzioni tramite l'inserimento Program delle dipendenze nel file usando StaticFileOptions:

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

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

app.UseStaticFiles();

  • Passare direttamente StaticFileOptions a UseStaticFiles nel Program file:

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

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

Per creare mapping di file aggiuntivi con un oggetto o configurare un FileExtensionContentTypeProvider altro 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 tramite l'inserimento Program delle dipendenze nel file usando 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 indicazioni contenute in questa sezione si applicano solo 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 l'istruzione seguente using all'inizio del file del Program progetto server:

using Microsoft.Extensions.FileProviders;

Nel file del progetto server prima della Program 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 componenteHome.razor () dell'app Home fare riferimento all'immagine con un <img> tag:

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

Eseguire l'app.

Risorse aggiuntive