ASP.NET Core Blazor pliki statyczne

W tym artykule opisano Blazor konfigurację aplikacji do obsługi plików statycznych.

Aby uzyskać ogólne informacje na temat obsługi plików statycznych przy użyciu konwencji routingu punktów końcowych usługi Mapowanie zasobów statycznych, zobacz Mapowanie plików statycznych w ASP.NET Core przed przeczytaniem tego artykułu.

Statyczne dostarczanie zasobów w aplikacjach po stronie Blazor serwera

Obsługa zasobów statycznych jest zarządzana za pomocą konwencji punktów końcowych routingu lub oprogramowania pośredniczącego opisanego w poniższej tabeli.

Funkcja	interfejs API	Wersja platformy .NET	opis
Mapowanie konwencji punktów końcowych routingu zasobów statycznych	MapStaticAssets	.NET 9 lub nowszy	Optymalizuje dostarczanie zasobów statycznych klientom.
Oprogramowanie middleware do obsługi plików statycznych	UseStaticFiles	Wszystkie wersje platformy .NET	Obsługuje zasoby statyczne dla klientów bez optymalizacji oferowanej przez "Mapowanie zasobów statycznych", ale jest przydatne do niektórych zadań, których "Mapowanie zasobów statycznych" nie jest w stanie zarządzać.

Statyczne zasoby na mapie mogą zastąpić UseStaticFiles w większości sytuacji. Jednak funkcja Mapowanie zasobów statycznych jest zoptymalizowana pod kątem obsługi zasobów ze znanych lokalizacji w aplikacji w czasie kompilacji i publikowania. Jeśli aplikacja obsługuje zasoby z innych lokalizacji, takich jak dyski lub zasoby osadzone, UseStaticFiles powinny być używane.

Mapowanie statycznych zasobów (MapStaticAssets) zastępuje również wywołania UseBlazorFrameworkFiles w aplikacjach obsługujących pliki frameworka Blazor WebAssembly, a jawne wywołanie UseBlazorFrameworkFiles w Blazor Web App nie jest konieczne, ponieważ API jest wywoływane automatycznie podczas uruchomienia AddInteractiveWebAssemblyComponents.

Gdy tryby Interaktywnego WebAssembly lub Interaktywnego Auto Renderingu są włączone:

• Blazor tworzy punkt końcowy umożliwiający uwidocznienie kolekcji zasobów jako modułu JS .
• Adres URL jest dodawany do treści żądania jako zapisany stan składnika, gdy składnik WebAssembly jest renderowany na stronie.
• W trakcie uruchamiania Blazor, WebAssembly pobiera adres URL, importuje moduł i wywołuje funkcję, aby pobrać kolekcję zasobów i odtworzyć ją w pamięci. Adres URL jest specyficzny dla zawartości i buforowany na zawsze, więc ten koszt narzucony jest opłacany tylko raz dla użytkownika, dopóki aplikacja nie zostanie zaktualizowana.
• Kolekcja zasobów jest również widoczna pod adresem URL czytelnym dla człowieka (_framework/resource-collection.js), dlatego JS ma dostęp do kolekcji zasobów na potrzeby rozszerzonej nawigacji lub implementowania funkcji innych platform i składników innych firm.

Oprogramowanie pośredniczące plików statycznych (UseStaticFiles) jest przydatne w następujących sytuacjach, w których nie można obsłużyć usługi Mapowanie zasobów statycznych (MapStaticAssets):

• Obsługa plików z dysku, które nie są częścią procesu kompilacji lub publikowania, na przykład pliki dodane do folderu aplikacji podczas lub po wdrożeniu.
• Stosowanie prefiksu do ścieżki plików zasobów statycznych, co jest omówione w sekcji Prefiks dla zasobów Blazor WebAssembly.
• Konfigurowanie mapowań plików rozszerzeń na określone typy zawartości i ustawianie opcji plików statycznych, które zostały omówione w sekcji Mapowania plików i opcje plików statycznych.

Aby uzyskać więcej informacji, zobacz Pliki statyczne platformy ASP.NET Core.

Dostarczaj zasoby zgodnie z konwencjami routingu punktów końcowych dla statycznych zasobów map

Ta sekcja dotyczy aplikacji po stronie Blazor serwera.

Zasoby są dostarczane za pośrednictwem ComponentBase.Assets właściwości, która rozpoznaje adres URL z odciskiem palca dla danego zasobu. W poniższym przykładzie Bootstrap, Blazor arkusz stylów aplikacji szablonu projektu (app.css) i arkusz stylów izolacji CSS (na podstawie przestrzeni nazw aplikacji BlazorSample) są połączone w składniku głównym, zazwyczaj składniku App (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"]" />

Importowanie map

Ta sekcja dotyczy aplikacji po stronie Blazor serwera.

Składnik Mapy importu () reprezentuje element mapy importu (ImportMap<script type="importmap"></script>), który definiuje mapę importu dla skryptów modułów. Składnik Mapy importu jest umieszczany wewnątrz zawartości składnika korzeniowego, zazwyczaj składnika App (Components/App.razor).

<ImportMap />

Jeśli niestandardowy ImportMapDefinition element nie jest przypisany do składnika Mapy importu, mapa importu jest generowana na podstawie zasobów aplikacji.

W poniższych przykładach pokazano niestandardowe definicje mapy importu i utworzone przez nich mapy importu.

Podstawowa mapa importu:

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

Powyższy kod powoduje wykonanie następującej mapy importu:

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

Mapa importu o określonym zakresie:

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

Powyższy kod powoduje wykonanie następującej mapy importu:

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

Importuj mapę z integralnością:

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

Powyższy kod powoduje wykonanie następującej mapy importu:

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

Połącz definicje mapy importu (ImportMapDefinition) z ImportMapDefinition.Combine.

Zaimportuj mapę utworzoną na podstawie elementu ResourceAssetCollection , która mapuje zasoby statyczne na odpowiadające im unikatowe adresy URL:

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

Powyższy kod powoduje wykonanie następującej mapy importu:

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

Import mapy naruszeń Polityki Bezpieczeństwa Treści (CSP)

Składnik ImportMap jest renderowany jako wbudowany tag <script>, co narusza rygorystyczną politykę zabezpieczeń treści (CSP), która ustanawia dyrektywę default-src lub script-src.

Aby zapoznać się z przykładami rozwiązywania naruszeń zasad CSP za pomocą Integralności Podzasobów (SRI) lub kryptograficznego nonce, zobacz Rozwiązywanie naruszeń CSP z Integralnością Podzasobów (SRI) lub nonce.

W wersjach wcześniejszych niż .NET 8, pliki statyczne platformy, takie jak skrypt Blazor, są serwowane za pośrednictwem middleware do obsługi plików statycznych. W .NET 8 lub nowszych wersjach Blazor statyczne pliki platformy są mapowane za pomocą routingu punktów końcowych, a oprogramowanie pośredniczące do obsługi plików statycznych nie jest już używane.

Podsumowanie formatów plików <link>href statycznych

Ta sekcja dotyczy wszystkich wersji i Blazor aplikacji platformy .NET.

W poniższych tabelach podsumowano formaty plików <link>href statycznych według wersji platformy .NET.

Aby uzyskać informacje o lokalizacji <head> zawartości, w której znajdują się linki do plików statycznych, zobacz Blazor projektu ASP.NET Core). Statyczne linki zasobów można również dostarczać przy użyciu <HeadContent> składników w poszczególnych Razor składnikach.

.NET 9 lub nowszy

Typ aplikacji	href wartość	Przykłady
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" />
Autonomiczna Blazor WebAssembly	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Typ aplikacji	href wartość	Przykłady
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" />
Autonomiczna Blazor WebAssembly	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x lub starszy

Typ aplikacji	href wartość	Przykłady
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Hostowana 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† jest obsługiwana na platformie .NET 8 lub nowszym, ale nie jest już szablonem projektu po programie .NET 7.
{Zalecamy zaktualizowanie hostowanych Blazor WebAssembly aplikacji do Blazor Web Apps podczas wdrażania platformy .NET 8 lub nowszej.

Tryb projektu zasobów statycznych dla stron internetowych

Ta sekcja dotyczy .Client projektu obiektu Blazor Web App.

Wymagane <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> ustawienie w .Client projekcie Blazor Web App przywraca Blazor WebAssembly statyczne zachowania zasobów z powrotem do wartości domyślnych, tak aby projekt działał w ramach hostowanego projektu. Zestaw Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) konfiguruje statyczne zasoby internetowe w określony sposób, aby działały w trybie "samodzielnym", podczas gdy serwer jedynie korzysta z danych wyjściowych z biblioteki. Nie jest to odpowiednie dla elementu Blazor Web App, gdzie część WebAssembly aplikacji jest logiczną częścią hosta i musi zachowywać się bardziej jak biblioteka. Na przykład projekt nie uwidacznia pakietu stylów (na przykład BlazorSample.Client.styles.css) i zamiast tego udostępnia hostowi tylko pakiet projektu, dzięki czemu host może uwzględnić go we własnym pakiecie stylów.

Zmiana wartości (Default) <StaticWebAssetProjectMode> lub usunięcie właściwości z projektu .Client nie jest obsługiwane.

Pliki statyczne w środowiskach innych niżDevelopment

Ta sekcja dotyczy plików statycznych po stronie serwera.

W przypadku uruchamiania aplikacji lokalnie, statyczne zasoby internetowe są włączone tylko w środowisku Development. Aby włączyć pliki statyczne dla środowisk innych niż Development w trakcie lokalnego rozwoju i testowania (na przykład Staging), wywołaj UseStaticWebAssets na elemencie WebApplicationBuilder w pliku Program.

Ostrzeżenie

Wywołaj , aby uzyskać dokładne środowisko, aby zapobiec aktywowaniu funkcji w środowisku produkcyjnym, ponieważ w takim przypadku obsługuje pliki z różnych lokalizacji na dysku różnych od projektu w środowisku produkcyjnym. Przykład w tej sekcji sprawdza Staging środowisko, wywołując IsStaging.

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

Prefiks dla Blazor WebAssembly zasobów

Ta sekcja dotyczy s Blazor Web App.

Użyj opcji punktu końcowego WebAssemblyComponentsEndpointOptions.PathPrefix aby ustawić ciąg ścieżki wskazujący prefiks dla Blazor WebAssembly zasobów. Ścieżka musi odpowiadać wskazanemu projektowi aplikacji Blazor WebAssembly.

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

W poprzednim przykładzie {PATH PREFIX} element zastępczy jest prefiksem ścieżki i musi zaczynać się od ukośnika w przód (/).

W poniższym przykładzie prefiks ścieżki jest ustawiony na /path-prefix:

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

Statyczna ścieżka podstawowa zasobu internetowego

Ta sekcja dotyczy aplikacji autonomicznych Blazor WebAssembly .

Opublikowanie aplikacji umieszcza statyczne zasoby aplikacji, w tym Blazor pliki struktur (_framework zasoby folderów), w ścieżce głównej (/) w opublikowanym efekcie. Właściwość <StaticWebAssetBasePath> określona w pliku projektu (.csproj) ustawia ścieżkę podstawową na inną ścieżkę niż główna:

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

W poprzednim przykładzie element zastępczy {PATH} to ścieżka.

Bez ustawiania <StaticWebAssetBasePath> właściwości aplikacja autonomiczna jest publikowana pod adresem /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

W poprzednim przykładzie element zastępczy {TFM} oznacza Target Framework Moniker (TFM) (na przykład net6.0).

<StaticWebAssetBasePath> Jeśli właściwość w aplikacji autonomicznej Blazor WebAssembly ustawia opublikowaną statyczną ścieżkę zasobu na wartość app1, ścieżka główna aplikacji w opublikowanych danych wyjściowych to /app1.

W pliku projektu aplikacji autonomicznej Blazor WebAssembly (.csproj):

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

W opublikowanych danych wyjściowych ścieżka do aplikacji autonomicznej Blazor WebAssembly to /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

W poprzednim przykładzie {TFM} symbol zastępczy to Target Framework Moniker (TFM) (na przykład net6.0).

Mapowania plików i opcje plików statycznych

Ta sekcja dotyczy plików statycznych po stronie serwera.

Aby utworzyć dodatkowe mapowania plików za pomocą elementu FileExtensionContentTypeProvider lub skonfigurować inne StaticFileOptions, użyj jednej z poniższych metod. W poniższych przykładach {EXTENSION} symbol zastępczy jest rozszerzeniem pliku, a {CONTENT TYPE} symbol zastępczy jest typem zawartości. Przestrzeń nazw dla następującego interfejsu API to Microsoft.AspNetCore.StaticFiles.

• Skonfiguruj opcje za pomocą wstrzykiwania zależności (DI) w Program pliku przy użyciu StaticFileOptions.

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  builder.Services.Configure<StaticFileOptions>(options =>
  {
      options.ContentTypeProvider = provider;
  });
  
  app.UseStaticFiles();
  

• Przekaż plik StaticFileOptions bezpośrednio do UseStaticFiles pliku Program :

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

Obsługa plików z wielu lokalizacji

Wskazówki w tej sekcji mają zastosowanie tylko do Blazor Web Apps.

Aby obsłużyć pliki z wielu lokalizacji za pomocą polecenia CompositeFileProvider:

• Dodaj przestrzeń nazw do Microsoft.Extensions.FileProviders góry Program pliku projektu serwera.
• W pliku projektu serwera Programprzed wywołaniem UseStaticFiles:
  • Utwórz element PhysicalFileProvider ze ścieżką do zasobów statycznych.
  • Utwórz CompositeFileProvider z WebRootFileProvider i PhysicalFileProvider. Przypisz złożonego dostawcę plików z powrotem do aplikacji WebRootFileProvider.

Przykład:

Utwórz nowy folder w projekcie serwera o nazwie AdditionalStaticAssets. Umieść obraz w folderze.

Dodaj następującą using instrukcję na początku pliku projektu Program serwera:

using Microsoft.Extensions.FileProviders;

W pliku projektu Program serwera przed wywołaniem metody UseStaticFilesdodaj następujący kod:

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

W znaczniku komponentu aplikacji Home (Home.razor) odwołaj się do obrazu za pomocą tagu <img>.

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

W powyższym przykładzie:

• Symbol zastępczy {IMAGE FILE NAME} to nazwa pliku graficznego. Nie ma potrzeby podawania segmentu ścieżki, jeśli plik obrazu znajduje się w katalogu głównym AdditionalStaticAssets folderu.
• Symbol zastępczy {ALT TEXT} to tekst alternatywny obrazu.

Uruchom aplikację.

Dodatkowe zasoby

• Ścieżka podstawowa aplikacji
• Unikaj przechwytywania plików w parametrze trasy