Obsługa plików statycznych w aplikacjach ASP.NET Core

Note

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

Warning

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

Dowiedz się, jak obsługiwać, zabezpieczać i optymalizować pliki statyczne w aplikacjach ASP.NET Core przy użyciu konwencji punktów końcowych map statycznych zasobów lub oprogramowania pośredniczącego plików statycznych. Pliki statyczne, nazywane również zasobami statycznymi, nie są generowane dynamicznie i są dostarczane bezpośrednio klientom; obejmują one m.in. HTML, CSS, obrazy i JavaScript.

Aby uzyskać wskazówki dotyczące plików statycznych Blazor, które dodają lub zastępują wskazówki zawarte w tym artykule, patrz ASP.NET Core Blazor plików statycznych.

Aby włączyć obsługę plików statycznych w programie ASP.NET Core, wywołaj metodę MapStaticAssets.

Domyślnie pliki statyczne są przechowywane w katalogu głównym projektu . Domyślny katalog to {CONTENT ROOT}/wwwroot, gdzie {CONTENT ROOT} symbol zastępczy jest katalogem głównym zawartości aplikacji. Tylko pliki w folderze wwwroot są adresowalne, więc nie musisz martwić się o pozostałą część kodu.

Tylko pliki z określonymi rozszerzeniami plików mapowane na obsługiwane typy multimediów są traktowane jako statyczne zasoby internetowe.

Statyczne zasoby internetowe są odnajdywane w czasie kompilacji i optymalizowane przy użyciu odcisków palców opartych na zawartości, aby zapobiec ponownemu używaniu starych plików. Zasoby są również kompresowane w celu skrócenia czasu dostarczania zasobów.

W czasie działania odnalezione statyczne zasoby internetowe są udostępniane jako punkty końcowe z zastosowanymi nagłówkami HTTP, takimi jak nagłówki buforowania i nagłówki typu zawartości. Zasób jest obsługiwany raz, dopóki plik nie ulegnie zmianie lub przeglądarka wyczyści jego pamięć podręczną. Nagłówki ETag, Last-Modified i Content-Type są ustawione. Przeglądarka nie może używać nieaktualnych zasobów po zaktualizowaniu aplikacji.

Dostarczanie zasobów statycznych jest oparte na routingu punktów końcowych, dlatego działa z innymi funkcjami obsługującymi punkty końcowe, takimi jak autoryzacja. Jest ona przeznaczona do pracy ze wszystkimi strukturami interfejsu użytkownika, w tym Blazor, Razor Pages i MVC.

Mapowanie zasobów statycznych zapewnia następujące korzyści:

  • Kompresja czasu kompilacji dla wszystkich zasobów w aplikacji, w tym JavaScript (JS) i arkuszy stylów, ale z wyłączeniem zasobów obrazów i czcionek, które są już skompresowane. Kompresja Gzip (Content-Encoding: gz) jest używana podczas opracowywania. Kompresja Gzip i Brotli (Content-Encoding: br) są używane podczas publikowania.
  • Odcisk palca dla wszystkich zasobów w czasie kompilacji z ciągiem zakodowanym w formacie Base64 skrótu SHA-256 zawartości każdego pliku. Zapobiega to ponownemu użyciu starej wersji pliku, nawet jeśli stary plik jest buforowany. Zasoby z odciskami palców są buforowane przy użyciu immutable dyrektywy , co powoduje, że przeglądarka nigdy nie zażąda zasobu ponownie, dopóki nie ulegnie zmianie. W przypadku przeglądarek, które nie obsługują immutable dyrektywy, dodawana jest dyrektywa max-age.
    • Nawet jeśli zasób nie jest personalizowany, zawartość oparta na ETags jest generowana dla każdego statycznego zasobu przy użyciu skrótu odcisków palców pliku jako wartości ETag. Dzięki temu przeglądarka pobiera plik tylko wtedy, gdy jego zawartość ulegnie zmianie (lub plik jest pobierany po raz pierwszy).
    • Wewnętrznie framework przypisuje zasobom fizycznym ich charakterystyki identyfikacyjne, co umożliwia aplikacji:
      • Znajdź automatycznie wygenerowane zasoby, takie jak Razor arkusz CSS o zakresie składników dla Blazorfunkcji izolacji CSS i JS zasobów opisanych przez JS mapy importu.
      • Generuj etykiety linków w zawartości strony <head> w celu wstępnego ładowania zasobów.

Usługa Mapowanie zasobów statycznych nie udostępnia cech związanych z minifikacją ani innych przekształceń plików. Minifikacja jest zwykle realizowana przez niestandardowy kod lub narzędzia innych firm.

Note

MapStaticAssets samodzielnie nie udostępnia dokumentów domyślnych. Aby obsłużyć dokumenty domyślne, wywołaj metodę UseDefaultFiles, a następnie .UseStaticFiles Aby uzyskać więcej informacji, zobacz sekcję Obsługa dokumentów domyślnych .

Aby włączyć obsługę plików statycznych w programie ASP.NET Core, wywołaj metodę UseStaticFiles.

Domyślnie pliki statyczne są przechowywane w katalogu głównym projektu . Domyślny katalog to {CONTENT ROOT}/wwwroot, gdzie {CONTENT ROOT} symbol zastępczy jest katalogem głównym zawartości aplikacji. Tylko pliki w folderze wwwroot są adresowalne, więc nie musisz martwić się o pozostałą część kodu.

W czasie wykonywania statyczne zasoby internetowe są zwracane przez statyczne oprogramowanie pośredniczące plików po zażądaniu modyfikacji zasobu i zastosowanych nagłówków typu zawartości. Nagłówki ETag, Last-Modified i Content-Type są ustawione.

Oprogramowanie pośredniczące obsługujące pliki statyczne umożliwia udostępnianie plików statycznych i jest używane przez aplikację, gdy UseStaticFiles jest wywoływane w potoku przetwarzania żądań aplikacji. Pliki są obsługiwane ze ścieżki określonej w IWebHostEnvironment.WebRootPath lub WebRootFileProvider, która jest domyślnie ustawiona na folder główny sieci Web, zazwyczaj wwwroot.

Możesz również udostępniać statyczne zasoby internetowe z przywołynych projektów i pakietów.

Zmienianie katalogu głównego sieci Web

Aby zmienić katalog główny sieci Web, użyj UseWebRoot metody . Aby uzyskać więcej informacji, zobacz omówienie podstaw platformy ASP.NET Core.

Zapobiegaj publikowaniu plików w wwwroot za pomocą elementu <Content> w pliku projektu. Poniższy przykład uniemożliwia publikowanie treści w katalogu wwwroot/local i jego podkatalogach:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

Metoda CreateBuilder ustawia katalog główny zawartości na bieżący katalog:

var builder = WebApplication.CreateBuilder(args);

Metoda CreateDefaultBuilder ustawia katalog główny zawartości na bieżący katalog:

Host.CreateDefaultBuilder(args)

W potoku przetwarzania żądań po wywołaniu metody UseHttpsRedirection wywołaj metodę MapStaticAssets, aby włączyć obsługę plików statycznych z katalogu głównego sieci Web aplikacji:

app.MapStaticAssets();

W potoku przetwarzania żądań po wywołaniu metody UseHttpsRedirection wywołaj metodę UseStaticFiles, aby włączyć obsługę plików statycznych z katalogu głównego sieci Web aplikacji:

app.UseStaticFiles();

Pliki statyczne są dostępne za pośrednictwem ścieżki względem katalogu głównego sieci Web.

Aby uzyskać dostęp do obrazu pod adresem wwwroot/images/favicon.png:

  • Format adresu URL: https://{HOST}/images/{FILE NAME}
    • Symbol zastępczy {HOST} jest hostem.
    • Symbol zastępczy {FILE NAME} to nazwa pliku.
  • Przykłady
    • Bezwzględny adres URL: https://localhost:5001/images/favicon.png
    • Względny adres URL katalogu głównego: images/favicon.png

Blazor W aplikacji images/favicon.png ładuje obraz ikony (favicon.png) z folderu aplikacjiwwwroot/images:

<link rel="icon" type="image/png" href="images/favicon.png" />

W Razor aplikacjach Pages i MVC znak ~ tyldy wskazuje katalog główny aplikacji webowej. W poniższym przykładzie ~/images/favicon.png ładuje obraz ikony (favicon.png) z folderu aplikacji wwwroot/images :

<link rel="icon" type="image/png" href="~/images/favicon.png" />

Skrócenie działania potoku oprogramowania pośredniczącego

Aby uniknąć uruchamiania całego potoku oprogramowania pośredniczącego po dopasowaniu elementu zawartości statycznej, co jest zachowaniem UseStaticFiles, wywołaj ShortCircuit na MapStaticAssets. Wywołanie ShortCircuit natychmiast wykonuje punkt końcowy i zwraca odpowiedź, uniemożliwiając innemu oprogramowaniu pośredniczącemu wykonanie dla żądań zasobów statycznych.

app.MapStaticAssets().ShortCircuit();

Kontrolowanie buforowania plików statycznych podczas programowania

Podczas uruchamiania w Development środowisku, na przykład podczas testowania funkcji Przeładowywanie na gorąco w Visual Studio, framework zastępuje nagłówki pamięci podręcznej, aby uniemożliwić przeglądarkom buforowanie plików statycznych. To zachowanie pomaga zapewnić, że najnowsza wersja plików jest używana podczas zmiany plików, unikając problemów z nieaktualną zawartością. W środowisku produkcyjnym platforma ustawia poprawne nagłówki pamięci podręcznej, dzięki czemu przeglądarki mogą buforować zasoby statyczne zgodnie z oczekiwaniami.

Aby wyłączyć to zachowanie, ustaw wartość EnableStaticAssetsDevelopmentCaching na true w Development pliku ustawień aplikacji środowiska (appsettings.Development.json).

Pliki statyczne w środowiskach innych niżDevelopment

Podczas lokalnego uruchamiania aplikacji środowisko Development jest jedynym środowiskiem, w którym są włączone statyczne zasoby sieci Web. Aby włączyć pliki statyczne dla środowisk innych niż Development podczas lokalnego programowania i testowania (na przykład w środowisku Staging), wywołaj metodę UseStaticWebAssetsWebApplicationBuilder.

Warning

Wywołaj UseStaticWebAssets, aby uzyskać dokładne szczegóły środowiska, aby zapobiec aktywowaniu funkcji w środowisku produkcyjnym, ponieważ obsługuje pliki z oddzielnych lokalizacji na dysku poza projektem. Przykład w tej sekcji sprawdza środowisko Staging przy użyciu IsStaging.

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

Obsługa plików spoza katalogu głównego sieci Web za pośrednictwem polecenia IWebHostEnvironment.WebRootPath

Po ustawieniu IWebHostEnvironment.WebRootPath folderu innego niż wwwrootaplikacja wykazuje następujące domyślne zachowania:

  • W środowisku Development zasoby statyczne są obsługiwane z wwwroot, jeśli zasoby o tej samej nazwie znajdują się zarówno w folderze wwwroot, jak i w innym folderze przypisanym do elementu WebRootPath.
  • W dowolnym środowisku innym niż Development zduplikowane zasoby statyczne są serwowane z folderu WebRootPath.

Rozważmy aplikację internetową utworzoną na podstawie pustego szablonu internetowego:

  • Zawiera plik Index.html w plikach wwwroot i wwwroot-custom.
  • Plik Program jest aktualizowany w celu ustawienia WebRootPath = "wwwroot-custom".
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    WebRootPath = "wwwroot-custom"
});

Domyślnie w przypadku żądań do /:

  • W środowisku Development zwracane jest wwwroot/Index.html.
  • W dowolnym środowisku innym niż Developmentwwwroot-custom/Index.html zwracana jest.

Aby upewnić się, że zasoby z wwwroot-custom są zawsze zwracane, użyj jednego z następujących podejść:

  • Usuń zduplikowane zasoby o tej samej nazwie w wwwroot.

  • Ustaw ASPNETCORE_ENVIRONMENT w Properties/launchSettings.json na dowolną wartość inną niż Development.

  • Wyłącz statyczne zasoby internetowe, ustawiając wartość <StaticWebAssetsEnabled> na false w pliku projektu aplikacji. OSTRZEŻENIE: Wyłączenie statycznych zasobów internetowych powoduje wyłączenie Razor bibliotek klas.

  • Dodaj następujący kod XML do pliku projektu:

    <ItemGroup>
  <Content Remove="wwwroot\**" />
</ItemGroup>

Poniższy kod aktualizuje WebRootPath do wartości innej niż Development (Staging), co gwarantuje, że zduplikowana zawartość jest zwracana z wwwroot-custom zamiast wwwroot.

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    EnvironmentName = Environments.Staging,
    WebRootPath = "wwwroot-custom"
});

Oprogramowanie pośredniczące do obsługi plików statycznych

Oprogramowanie pośrednie plików statycznych umożliwia udostępnianie plików statycznych w określonych scenariuszach związanych z plikami statycznymi, zwykle jako uzupełnienie konwencji routingu punktów końcowych Map Static Assets (MapStaticAssets).

Uwzględnij oprogramowanie pośredniczące obsługujące pliki statyczne w przetwarzaniu żądań, gdy wywołujesz UseStaticFiles w potoku przetwarzania żądań aplikacji, zwykle po dodaniu konwencji punktu końcowego Map Static Assets (MapStaticAssets).

Użyj konwencji punktu końcowego Map Static Assets w aplikacjach przeznaczonych do obsługi platformy .NET 9 lub nowszej. Użyj oprogramowania pośredniczącego do obsługi plików statycznych w aplikacjach przeznaczonych dla wersji platformy .NET wcześniejszych niż .NET 9.

Middleware plików statycznych udostępnia pliki statyczne, ale nie zapewnia takiego samego poziomu optymalizacji jak konwencje punktów końcowych Map Static Assets. Funkcje kompresji podczas kompilacji i nadawania odcisków palca dostępne w konwencjach punktów końcowych funkcji Map Static Assets nie są dostępne, gdy korzystasz wyłącznie z middleware obsługującego pliki statyczne.

Konwencje punktów końcowych są zoptymalizowane pod kątem obsługi zasobów, o których aplikacja wie w czasie wykonywania. Jeśli aplikacja obsługuje zasoby z innych lokalizacji, takich jak dyski lub zasoby osadzone, użyj statycznego oprogramowania pośredniczącego plików.

Następujące funkcje omówione w tym artykule są obsługiwane w przypadku oprogramowania pośredniczącego plików statycznych, ale nie z konwencjami punktów końcowych map statycznych zasobów:

Obsługa plików spoza katalogu głównego sieci Web za pośrednictwem polecenia UseStaticFiles

Rozważ następującą hierarchię katalogów z plikami statycznymi znajdującymi się poza katalogiem głównym aplikacji w folderze o nazwie ExtraStaticFiles:

  • wwwroot
    • css
    • images
    • js
  • ExtraStaticFiles
    • images
      • red-rose.jpg

Żądanie może uzyskać dostęp do red-rose.jpg, konfigurując nowe wystąpienie oprogramowania pośredniczącego do obsługi plików statycznych:

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.Extensions.FileProviders;

W potoku przetwarzania żądań po istniejącym wywołaniu elementu MapStaticAssets (.NET 9 lub nowszy) lub UseStaticFiles (.NET 8 lub starszy):

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files"
});

W poprzednim kodzie ExtraStaticFiles hierarchia katalogów jest publicznie dostępna za pośrednictwem segmentu static-files adresu URL. Żądanie do https://{HOST}/StaticFiles/images/red-rose.jpg, gdzie {HOST} symbol zastępczy jest hostem, obsługuje red-rose.jpg plik.

Następujące odniesienia do znaczników ExtraStaticFiles/images/red-rose.jpg:

<img src="static-files/images/red-rose.jpg" alt="A red rose" />

W poprzednim przykładzie Razor strony i widoki MVC obsługują notację tyldy z ukośnikiem (src="~/StaticFiles/images/red-rose.jpg"), ale Razor komponenty w aplikacjach Blazor nie obsługują tej notacji.

Obsługa plików z wielu lokalizacji

Wskazówki zawarte w tej sekcji dotyczą Razor aplikacji Pages i MVC. Aby uzyskać wskazówki dotyczące Blazor Web App, zobacz statyczne pliki Blazor ASP.NET Core.

Rozważmy następujący znacznik, który wyświetla logo firmy:

<img src="~/logo.png" asp-append-version="true" alt="Company logo">

Deweloper zamierza użyć Pomocnika Tagu Obrazka, aby dodać wersję i obsłużyć plik z niestandardowej lokalizacji, czyli z folderu o nazwie ExtraStaticFiles.

Następujące przykładowe wywołania MapStaticAssets do obsługi plików z wwwroot i UseStaticFiles do obsługi plików z ExtraStaticFilesprogramu :

W potoku przetwarzania żądań po istniejącym wywołaniu elementu MapStaticAssets (.NET 9 lub nowszy) lub UseStaticFiles (.NET 8 lub starszy):

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles"))
});

Poniższy przykład wywołuje UseStaticFiles dwukrotnie, aby obsługiwać pliki zarówno z wwwroot, jak i ExtraStaticFiles.

W potoku przetwarzania żądań, po istniejącym wywołaniu metody UseStaticFiles:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles"))
});

Przy użyciu poprzedniego kodu, plik ExtraStaticFiles/logo.png zostanie wyświetlony. Jednak Image Tag Helper (AppendVersion) nie jest stosowany, ponieważ zależy od WebRootFileProvider, który nie został zaktualizowany w celu uwzględnienia folderu ExtraStaticFiles.

Poniższy kod aktualizuje WebRootFileProvider, aby uwzględnić katalog ExtraStaticFiles przy użyciu CompositeFileProvider. Dzięki temu pomocnik tagu obrazów może zastosować wersję do obrazów w folderze ExtraStaticFiles.

Przestrzeń nazw dla następującego interfejsu API:

using Microsoft.Extensions.FileProviders;

W potoku przetwarzania żądań przed istniejącym wywołaniem MapStaticAssets (.NET 9 lub nowszym) lub UseStaticFiles (.NET 8 lub starszym):

var webRootProvider = new PhysicalFileProvider(builder.Environment.WebRootPath);
var newPathProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles"));

var compositeProvider = new CompositeFileProvider(webRootProvider, newPathProvider);

app.Environment.WebRootFileProvider = compositeProvider;

UseStaticFiles i UseFileServer domyślnie do dostawcy plików wskazujących na wwwroot. Możesz udostępnić dodatkowe wystąpienia UseStaticFiles i UseFileServer innym dostawcom plików do obsługi plików z innych lokalizacji. Aby uzyskać więcej informacji, zobacz "UseStaticFiles still needed with UseFileServer for wwwroot" (dotnet/AspNetCore.Docs #15578).

Ustawianie nagłówków odpowiedzi HTTP

Służy StaticFileOptions do ustawiania nagłówków odpowiedzi HTTP. Oprócz konfigurowania middleware do obsługi plików statycznych, poniższy kod ustawia nagłówek Cache-Control na 604 800 sekund (jeden tydzień).

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.AspNetCore.Http;

W potoku przetwarzania żądań po istniejącym wywołaniu elementu MapStaticAssets (.NET 9 lub nowszy) lub UseStaticFiles (.NET 8 lub starszy):

app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = ctx =>
    {
        ctx.Context.Response.Headers.Append(
            "Cache-Control", "public, max-age=604800");
    }
});

Duża kolekcja zasobów

W przypadku obsługi dużych kolekcji zasobów, czyli około 1000 lub większej liczby zasobów, użyj pakietu, aby zmniejszyć ostateczną liczbę zasobów, które aplikacja obsługuje, lub połączyć MapStaticAssets z elementem UseStaticFiles.

MapStaticAssets chętnie ładuje wstępnie skompilowane metadane przechwycone podczas procesu kompilacji dla zasobów w celu obsługi kompresji, buforowania i odcisków palców. Te funkcje kosztują większe użycie pamięci przez aplikację. W przypadku zasobów, do których często uzyskuje się dostęp, koszty są zwykle opłacalne. W przypadku aktywów, które nie są często używane, kompromis może nie być wart kosztów.

Jeśli nie używasz pakietowania, połącz MapStaticAssets z UseStaticFiles. W poniższym przykładzie pokazano podejście.

W pliku projektu (.csproj) właściwość MSBuild StaticWebAssetEndpointExclusionPattern jest używana do filtrowania punktów końcowych z końcowego manifestu elementu MapStaticAssets. Wykluczone pliki są udostępniane przez UseStaticFiles i nie korzystają z kompresji, buforowania ani fingerprintingu.

Aby zachować domyślny wzorzec wykluczeń platformy, zachowaj $(StaticWebAssetEndpointExclusionPattern) podczas ustawiania wartości StaticWebAssetEndpointExclusionPattern. Dodaj więcej wzorców na liście rozdzielanej średnikami.

W poniższym przykładzie wzorzec wykluczania dodaje pliki statyczne w lib/icons folderze, który reprezentuje hipotetyczną partię ikon:

<StaticWebAssetEndpointExclusionPattern>
  $(StaticWebAssetEndpointExclusionPattern);lib/icons/**
</StaticWebAssetEndpointExclusionPattern>

Po przetworzeniu przez middleware przekierowania HTTPS (app.UseHttpsRedirection();) w pliku Program:

app.UseStaticFiles();

app.UseAuthorization();

app.MapStaticAssets();

Manifest zasobów statycznych

MapStaticAssets obsługuje zasoby z manifestu zasobów statycznych, a nie przez skanowanie katalogu głównego sieci Web w czasie wykonywania. Manifest jest generowany podczas kompilacji i publikowania oraz zawiera informacje o statycznych zasobach sieci Web wykrytych dla aplikacji wraz z metadanymi, takimi jak sygnatury zawartości, nagłówki Content-Type, nagłówki buforowania oraz wstępnie obliczone reprezentacje skompresowane (Gzip i Brotli). W czasie wykonywania MapStaticAssets odczytuje manifest, rejestruje punkt końcowy dla każdego zasobu i obsługuje zoptymalizowane odpowiedzi.

Proces kompilacji generuje manifest w katalogu wyjściowym kompilacji. Jego nazwa pliku jest oparta na nazwie zestawu projektu (na przykład {ASSEMBLY NAME}.staticwebassets.endpoints.json, gdzie {ASSEMBLY NAME} symbol zastępczy jest wartością MSBuild AssemblyName aplikacji). Aby udostępnić manifest z innej lokalizacji, zobacz sekcję Zapewnianie niestandardowego manifestu plików statycznych .

Ponieważ MapStaticAssets tylko udostępnia zasoby wymienione w manifeście, nie obsługuje plików, które nie są częścią manifestu. Pliki nie są częścią manifestu, gdy są:

  • Zlokalizowane poza głównym katalogiem sieci Web w czasie kompilacji, na przykład pliki udostępniane z dysku, zasoby osadzone lub niestandardowy element WebRootPath ustawiany w czasie wykonywania.
  • Wykluczone z manifestu z właściwością StaticWebAssetEndpointExclusionPattern MSBuild (zobacz sekcję Duża kolekcja zasobów ).

Aby obsłużyć pliki, które nie są w manifeście, wywołaj metodę UseStaticFiles, która obsługuje pliki bezpośrednio z katalogu głównego sieci Web w czasie wykonywania. To również dlatego serwowanie domyślnych dokumentów za pomocą MapStaticAssets wymaga wywołania UseStaticFiles.

Integracja plików wygenerowanych podczas kompilacji ze statycznymi zasobami sieci Web

Narzędzia kompilacji, takie jak kompilatory języka TypeScript i pakiety Języka JavaScript, często tworzą pliki podczas kompilacji. Aby obsłużyć te wygenerowane pliki za pomocą odcisków palców, kompresji i buforowania, które MapStaticAssets udostępniają, pliki muszą zostać odnalezione jako statyczne zasoby internetowe podczas kompilacji. Wygenerowane pliki są zwykle przechowywane poza katalogiem głównym sieci Web (wwwroot) i wykluczone z kontroli źródła, więc nie są one domyślnie odnajdywane jako statyczne zasoby internetowe. Tylko pliki ustalone jako znajdujące się w obszarze wwwroot, gdy statyczne zasoby sieci Web są ustalane podczas kompilacji, są dodawane do manifestu zasobów statycznych i obsługiwane przez MapStaticAssets. Pliki podlinkowane w wwwroot (na przykład za pomocą elementu <Content> i Link) są również uwzględniane, nawet gdy plik źródłowy jest przechowywany poza wwwroot.

Aby uwzględnić pliki generowane przez kompilację jako statyczne zasoby internetowe, użyj jednej z poniższych metod.

Dodaj element, który <Content>Link umieszcza każdy wygenerowany plik w obszarze wwwroot. Plik, do którego odwołuje się wwwroot, jest wykrywany przez potok statycznych zasobów sieci Web i udostępniany przez MapStaticAssets z fingerprintingiem, kompresją i buforowaniem, mimo że plik źródłowy jest przechowywany poza wwwroot.

W poniższym przykładzie krok kompilacji generuje main.js w folderze generated, a element <Content> dołącza plik do wwwroot:

<ItemGroup>
  <Content Include="generated\main.js" Link="wwwroot\main.js"
    CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Wygenerowany plik musi istnieć, gdy proces kompilacji rozpoznaje statyczne zasoby internetowe.

Używanie projektu JavaScript dla złożonych potoków kompilacji

W przypadku złożonej kompilacji klienta JavaScript lub TypeScript należy użyć oddzielnego projektu JavaScript, który kompiluje zasoby klienta przy użyciu systemu projektu JavaScript ( Microsoft.VisualStudio.JavaScript.Sdk zestawu MSBuild SDK i .esproj pliku projektu). Dodaj odwołanie do projektu JavaScript w aplikacji ASP.NET Core, aby jego dane wyjściowe były używane jako statyczne zasoby internetowe. Aby zapoznać się z przykładem, zobacz Microsoft.FluentUI.AspNetCore.Components.Assets.esproj plik projektu (microsoft/fluentui-blazor repozytorium GitHub).

Autoryzacja pliku statycznego

Gdy aplikacja przyjmuje zasady autoryzacji rezerwowej, wymaga autoryzacji dla wszystkich żądań, które nie określają jawnie zasad autoryzacji. To wymaganie obejmuje żądania dotyczące plików statycznych po żądaniu przetwarzania żądań oprogramowania pośredniczącego autoryzacji. Aby zezwolić na anonimowy dostęp do plików statycznych, zastosuj AllowAnonymousAttribute do konstruktora punktu końcowego dla plików statycznych:

app.MapStaticAssets().Add(endpointBuilder => 
    endpointBuilder.Metadata.Add(new AllowAnonymousAttribute()));

Gdy aplikacja stosuje zapasową politykę autoryzacji, autoryzacja jest wymagana dla wszystkich żądań, które nie określają jawnie polityki autoryzacji, w tym żądań dotyczących plików statycznych po przetworzeniu żądań przez oprogramowanie pośredniczące autoryzacji. Szablony ASP.NET Core umożliwiają anonimowy dostęp do plików statycznych przez wywołanie UseStaticFiles przed wywołaniem UseAuthorization. Większość aplikacji podąża za tym wzorcem. Gdy oprogramowanie pośredniczące pliku statycznego jest wywoływane przed oprogramowaniem pośredniczącym autoryzacji:

  • W plikach statycznych nie są wykonywane kontrole autoryzacji.
  • Pliki statyczne obsługiwane przez oprogramowanie pośredniczące plików statycznych, takie jak pliki w katalogu głównym sieci Web (zazwyczaj wwwroot), są publicznie dostępne.

Aby obsługiwać pliki statyczne na podstawie autoryzacji:

  • Upewnij się, że aplikacja ustawia politykę autoryzacji zapasowej, które wymagają uwierzytelnionych użytkowników.
  • Zapisz plik statyczny poza głównym katalogiem sieciowym aplikacji.
  • Po wywołaniu UseAuthorization wywołaj UseStaticFiles, określając ścieżkę do folderu plików statycznych znajdującego się poza katalogiem głównym sieci Web.

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.FileProviders;

Rejestracja usługi:

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

Po wywołaniu metody UseAuthorization w potoku przetwarzania żądań:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "SecureStaticFiles")),
    RequestPath = "/static-files"
});

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.FileProviders;

W pliku Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

Po Startup.Configure wywołaniu metody UseAuthorization:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.ContentRootPath, "SecureStaticFiles")),
    RequestPath = "/static-files"
});

W poprzednim kodzie zasady autoryzacji rezerwowej wymagają uwierzytelnionych użytkowników. Punkty końcowe, takie jak kontrolery i Razor strony, które określają własne wymagania dotyczące autoryzacji, nie korzystają z zasad autoryzacji rezerwowej. Na przykład Razor strony, kontrolery lub metody akcji z zastosowanym atrybutem [AllowAnonymous] lub [Authorize(PolicyName="MyPolicy")] używają tego atrybutu zamiast rezerwowej polityki autoryzacji.

RequireAuthenticatedUser dodaje DenyAnonymousAuthorizationRequirement do bieżącego wystąpienia, co wymusza uwierzytelnienie bieżącego użytkownika.

Zasoby statyczne przechowywane w głównym katalogu internetowym aplikacji są publicznie dostępne, ponieważ domyślne middleware plików statycznych (UseStaticFiles) jest uruchamiane przed UseAuthorization. Zasoby statyczne w folderze SecureStaticFiles wymagają uwierzytelniania.

Alternatywną metodą udostępniania plików na podstawie autoryzacji jest:

  • Przechowuj pliki spoza katalogu głównego sieci Web i dowolnego katalogu dostępnego dla oprogramowania pośredniczącego plików statycznych.
  • Obsłuż pliki za pomocą metody akcji, do której stosuje się autoryzację, i zwróć obiekt FileResult.

z Razor strony (Pages/BannerImage.cshtml.cs):

public class BannerImageModel : PageModel
{
    private readonly IWebHostEnvironment _env;

    public BannerImageModel(IWebHostEnvironment env) => _env = env;

    public PhysicalFileResult OnGet()
    {
        var filePath = Path.Combine(
            _env.ContentRootPath, "SecureStaticFiles", "images", "red-rose.jpg");

        return PhysicalFile(filePath, "image/jpeg");
    }
}

Z kontrolera (Controllers/HomeController.cs):

[Authorize]
public IActionResult BannerImage()
{
    var filePath = Path.Combine(
        _env.ContentRootPath, "SecureStaticFiles", "images", "red-rose.jpg");

    return PhysicalFile(filePath, "image/jpeg");
}

Powyższe podejście wymaga strony lub punktu końcowego dla każdego pliku.

Poniższy przykład punktu końcowego trasy zwraca pliki dla uwierzytelnionych użytkowników.

W pliku Program:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AuthenticatedUsers", b => b.RequireAuthenticatedUser());
});

...

app.MapGet("/files/{fileName}", IResult (string fileName) => 
{
    var filePath = GetOrCreateFilePath(fileName);

    if (File.Exists(filePath))
    {
        return TypedResults.PhysicalFile(filePath, fileName);
    }

    return TypedResults.NotFound("No file found with the supplied file name");
})
.WithName("GetFileByName")
.RequireAuthorization("AuthenticatedUsers");

Poniższy przykład punktu końcowego trasy przekazuje pliki dla uwierzytelnionych użytkowników w roli administratora (admin).

W pliku Program:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminsOnly", b => b.RequireRole("admin"));
});

...

// IFormFile uses memory buffer for uploading. For handling large 
// files, use streaming instead. See the *File uploads* article
// in the ASP.NET Core documentation:
// https://learn.microsoft.com/aspnet/core/mvc/models/file-uploads
app.MapPost("/files", async (IFormFile file, LinkGenerator linker, 
    HttpContext context) =>
{
    // Don't rely on the value in 'file.FileName', as it's only metadata that can 
    // be manipulated by the end-user. Consider the 'Utilities.IsFileValid' method 
    // that takes an 'IFormFile' and validates its signature within the 
    // 'AllowedFileSignatures'.

    var fileSaveName = Guid.NewGuid().ToString("N") + 
        Path.GetExtension(file.FileName);
    await SaveFileWithCustomFileName(file, fileSaveName);

    context.Response.Headers.Append("Location", linker.GetPathByName(context, 
        "GetFileByName", new { fileName = fileSaveName}));

    return TypedResults.Ok("File Uploaded Successfully!");
})
.RequireAuthorization("AdminsOnly");

W pliku Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.AddPolicy("AuthenticatedUsers", b => b.RequireAuthenticatedUser());
});

W pliku Startup.Configure:

app.MapGet("/files/{fileName}", IResult (string fileName) => 
{
    var filePath = GetOrCreateFilePath(fileName);

    if (File.Exists(filePath))
    {
        return TypedResults.PhysicalFile(filePath, fileName);
    }

    return TypedResults.NotFound("No file found with the supplied file name");
})
.WithName("GetFileByName")
.RequireAuthorization("AuthenticatedUsers");

Poniższy kod przekazuje pliki dla uwierzytelnionych użytkowników w roli administratora (admin).

W pliku Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.AddPolicy("AdminsOnly", b => b.RequireRole("admin"));
});

W pliku Startup.Configure:

// IFormFile uses memory buffer for uploading. For handling large 
// files, use streaming instead. See the *File uploads* article
// in the ASP.NET Core documentation:
// https://learn.microsoft.com/aspnet/core/mvc/models/file-uploads
app.MapPost("/files", async (IFormFile file, LinkGenerator linker, 
    HttpContext context) =>
{
    // Don't rely on the value in 'file.FileName', as it's only metadata that can 
    // be manipulated by the end-user. Consider the 'Utilities.IsFileValid' method 
    // that takes an 'IFormFile' and validates its signature within the 
    // 'AllowedFileSignatures'.

    var fileSaveName = Guid.NewGuid().ToString("N") + 
        Path.GetExtension(file.FileName);
    await SaveFileWithCustomFileName(file, fileSaveName);

    context.Response.Headers.Append("Location", linker.GetPathByName(context, 
        "GetFileByName", new { fileName = fileSaveName}));

    return TypedResults.Ok("File Uploaded Successfully!");
})
.RequireAuthorization("AdminsOnly");

Przeglądanie katalogów

Przeglądanie katalogów umożliwia wyświetlanie listy katalogów w określonych katalogach.

Ze względów bezpieczeństwa przeglądanie katalogów jest domyślnie wyłączone. Aby uzyskać więcej informacji, zobacz Zagadnienia dotyczące zabezpieczeń plików statycznych.

Włącz przeglądanie katalogów przy użyciu następujących interfejsów API:

W poniższym przykładzie:

  • Folder images w katalogu głównym aplikacji przechowuje obrazy do przeglądania katalogów.
  • Ścieżka żądania do przeglądania obrazów to /DirectoryImages.
  • Wywoływanie UseStaticFiles i ustawianie FileProviderStaticFileOptions umożliwia wyświetlanie linków przeglądarki do poszczególnych plików.

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;

Rejestracja usługi:

builder.Services.AddDirectoryBrowser();

W potoku przetwarzania żądań po istniejącym wywołaniu elementu MapStaticAssets (.NET 9 lub nowszy) lub UseStaticFiles (.NET 8 lub starszy):

var fileProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.WebRootPath, "images"));
var requestPath = "/DirectoryImages";

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = fileProvider,
    RequestPath = requestPath
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = fileProvider,
    RequestPath = requestPath
});

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.Extensions.FileProviders;
using System.IO;

W pliku Startup.ConfigureServices:

services.AddDirectoryBrowser();

W Startup.Configure po istniejącym wywołaniu UseStaticFiles:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/DirectoryImages"
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/DirectoryImages"
});

Powyższy kod umożliwia przeglądanie zawartości katalogu wwwroot/images przy użyciu adresu URL https://{HOST}/DirectoryImages z linkami do każdego pliku i folderu, gdzie symbol zastępczy {HOST} oznacza hosta.

AddDirectoryBrowser dodaje usługi wymagane przez oprogramowanie pośredniczące przeglądania katalogów, w tym HtmlEncoder. Te usługi mogą zostać dodane przez inne wywołania, takie jak AddRazorPages, ale wywołaj AddDirectoryBrowser, aby mieć pewność, że usługi zostaną dodane.

Obsługa dokumentów domyślnych

Ustawienie strony domyślnej zapewnia odwiedzającym punkt początkowy w witrynie. Aby obsłużyć domyślny plik z wwwroot, nie wymagając uwzględnienia nazwy pliku w adresie URL żądania, wywołaj metodę UseDefaultFiles.

UseDefaultFiles jest narzędziem do przepisywania adresów URL, które nie dostarcza pliku. Ponownie zapisuje adres URL żądania do dokumentu domyślnego (na przykład / do /index.html), a inny składnik obsługuje plik.

Ponieważ MapStaticAssets obsługuje zasoby odnalezione w czasie kompilacji za pośrednictwem routingu punktu końcowego, nie obsługuje on własnych dokumentów domyślnych. Wywołaj UseDefaultFiles, aby przepisać żądanie, a następnie UseStaticFiles, aby obsłużyć przepisane żądanie dla dokumentu domyślnego:

app.UseDefaultFiles();
app.UseStaticFiles();
app.MapStaticAssets();

Important

Skonfigurowanie tylko UseDefaultFiles i MapStaticAssets (bez UseStaticFiles) zwraca odpowiedź 404 — Nie znaleziono dla żądania na /. Takie zachowanie występuje, ponieważ minimalny hosting dodaje oprogramowanie pośredniczące routingu na początku potoku przetwarzania żądań, dlatego routing punktu końcowego jest zgodny z żądaniem przed UseDefaultFiles ponownym zapisywaniem go do dokumentu domyślnego. Problem jest szczególnie widoczny, gdy zmienisz katalog główny witryny na niestandardową ścieżkę za pomocą WebRootPath, ponieważ pliki w niestandardowym katalogu głównym witryny nie są częścią manifestu statycznych zasobów tworzonego podczas kompilacji, który jest obsługiwany przez MapStaticAssets. Dodaj wywołanie do UseStaticFiles po UseDefaultFiles, jak pokazano w poprzednim przykładzie, aby obsługiwać dokumenty domyślne.

W potoku przetwarzania żądań przed istniejącym wywołaniem metody UseStaticFiles:

app.UseDefaultFiles();

Za pomocą UseDefaultFiles żądania do folderu w wwwroot wyszukują:

  • default.htm
  • default.html
  • index.htm
  • index.html

Pierwszy plik znaleziony na liście jest obsługiwany tak, jakby żądanie zawierało nazwę pliku. Adres URL przeglądarki nadal odzwierciedla żądany identyfikator URI.

Poniższy kod zmienia domyślną nazwę pliku na default-document.html:

var options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("default-document.html");
app.UseDefaultFiles(options);

Łączenie plików statycznych, dokumentów domyślnych i przeglądania katalogów

UseFileServer łączy funkcje UseStaticFiles, UseDefaultFilesi opcjonalnie UseDirectoryBrowser.

W potoku przetwarzania żądań, po istniejącym wywołaniu metody MapStaticAssets (.NET 9 lub nowszy) albo UseStaticFiles (.NET 8 lub starszy), wywołaj metodę UseFileServer, aby włączyć udostępnianie plików statycznych oraz obsługę pliku domyślnego:

app.UseFileServer();

Przeglądanie katalogów nie jest włączone dla poprzedniego przykładu.

Poniższy kod umożliwia obsługę plików statycznych, plików domyślnych i przeglądania katalogów.

Rejestracja usługi:

builder.Services.AddDirectoryBrowser();

W potoku przetwarzania żądań, po istniejącym wywołaniu metody UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

W pliku Startup.ConfigureServices:

services.AddDirectoryBrowser();

W Startup.Configure po istniejącym wywołaniu UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

Dla adresu hosta (/) UseFileServer zwraca domyślny dokument HTML przed domyślną Razor stroną (Pages/Index.cshtml) lub domyślnym widokiem MVC (Home/Index.cshtml).

Rozważ następującą hierarchię katalogów:

  • wwwroot
    • css
    • images
    • js
  • ExtraStaticFiles
    • images
      • logo.png
    • default.html

Poniższy kod umożliwia obsługę plików statycznych, pliku domyślnego i przeglądania katalogów .ExtraStaticFiles

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.Extensions.FileProviders;

Rejestracja usługi:

builder.Services.AddDirectoryBrowser();

W potoku przetwarzania żądań, po istniejącym wywołaniu metody UseStaticFiles:

app.UseFileServer(new FileServerOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files",
    EnableDirectoryBrowsing = true
});

Przestrzenie nazw dla następującego interfejsu API:

using Microsoft.Extensions.FileProviders;
using System.IO;

W pliku Startup.ConfigureServices:

services.AddDirectoryBrowser();

W Startup.Configure po istniejącym wywołaniu UseStaticFiles:

app.UseFileServer(new FileServerOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files",
    EnableDirectoryBrowsing = true
});

AddDirectoryBrowser musi być wywoływane, gdy wartość właściwości EnableDirectoryBrowsing wynosi true.

Używając poprzedniej hierarchii plików i kodu, adresy URL są rozpoznawane, jak pokazano w poniższej tabeli (symbol zastępczy {HOST} jest hostem).

URI Plik odpowiedzi
https://{HOST}/static-files/images/logo.png ExtraStaticFiles/images/logo.png
https://{HOST}/static-files ExtraStaticFiles/default.html

Jeśli w katalogu ExtraStaticFiles nie istnieje żaden plik o nazwie domyślnej, https://{HOST}/static-files zwraca listę plików w katalogu z klikalnymi linkami, gdzie {HOST} znacznik zastępczy jest hostem.

UseDefaultFiles i UseDirectoryBrowser wykonują przekierowanie po stronie klienta z docelowego URI bez końcowego / do docelowego URI z końcowym /. Na przykład od https://{HOST}/static-files (bez końcowego /) do https://{HOST}/static-files/ (zawiera końcowy /). Względne adresy URL w katalogu ExtraStaticFiles są nieprawidłowe bez końcowego ukośnika (/), chyba że opcja RedirectToAppendTrailingSlash jest używana DefaultFilesOptions.

Mapuj rozszerzenia plików na typy MIME

Note

Aby uzyskać wskazówki dotyczące Blazor aplikacji, zobacz statyczne pliki ASP.NET Core Blazor.

Służy FileExtensionContentTypeProvider.Mappings do dodawania lub modyfikowania rozszerzenia pliku do mapowań typów zawartości MIME.

Note

FileExtensionContentTypeProvider nie jest bezpieczny wątkowo w przypadku zapisów współbieżnych. Jego słownik mapowań wewnętrznych jest standardem Dictionary<string, string> bez synchronizacji. Mapowania dostawcy mają być konfigurowane raz podczas uruchamiania. Jeśli następnie wykonywane są wyłącznie operacje odczytu (wyszukiwania), dostawcę można bezpiecznie zarejestrować jako singleton. Nie dodawaj, nie usuwaj ani nie modyfikuj mapowań, gdy dostawca jest używany jednocześnie przez wiele żądań.

W poniższym przykładzie kilka rozszerzeń plików jest mapowanych na znane typy MIME. Rozszerzenie .rtf jest zastępowane, a .mp4 jest usuwane.

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;

...

// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos
provider.Mappings.Remove(".mp4");

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

Jeśli masz kilka opcji pliku statycznego do skonfigurowania, możesz też ustawić dostawcę przy użyciu polecenia StaticFileOptions:

var provider = new FileExtensionContentTypeProvider();

...

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

app.UseStaticFiles();

W pliku Startup.Configure:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;
using System.IO;

...

// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos
provider.Mappings.Remove(".mp4");

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/images",
    ContentTypeProvider = provider
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/images"
});

Aby uzyskać więcej informacji, zobacz Typy zawartości MIME.

Niestandardowe typy zawartości

Oprogramowanie pośredniczące plików statycznych rozpoznaje prawie 400 znanych typów zawartości plików. Jeśli użytkownik żąda pliku o nieznanym typie, middleware plików statycznych przekazuje żądanie do następnego middleware w potoku przetwarzania. Jeśli żadne oprogramowanie pośredniczące nie obsługuje żądania, serwer zwraca odpowiedź 404 Nie znaleziono . Jeśli przeglądanie katalogów jest włączone, serwer wyświetli link do pliku na liście katalogów.

Poniższy kod umożliwia obsługę nieznanych typów zawartości i renderuje nieznany plik jako obraz:

app.UseStaticFiles(new StaticFileOptions
{
    ServeUnknownFileTypes = true,
    DefaultContentType = "image/png"
});

W poprzednim kodzie żądanie pliku o nieznanym typie zawartości jest zwracane jako obraz.

Warning

ServeUnknownFileTypes Włączenie jest zagrożeniem bezpieczeństwa. Jest on domyślnie wyłączony, a jego użycie jest odradzane. Mapowanie rozszerzeń plików na typy MIME zapewnia bezpieczniejszą alternatywę dla obsługi plików z niestandardowymi rozszerzeniami.

Udostępnianie niestandardowego manifestu plików statycznych

Jeśli staticAssetsManifestPath jest null, element IHostEnvironment.ApplicationName jest używany do lokalizowania manifestu. Alternatywnie określ pełną ścieżkę do pliku manifestu. Jeśli używasz ścieżki względnej, struktura wyszukuje plik w pliku AppContext.BaseDirectory.

Zagadnienia dotyczące zabezpieczeń plików statycznych

Warning

UseDirectoryBrowser i UseStaticFiles mogą wyciekać tajemnice. Wyłączenie przeglądania katalogów w środowisku produkcyjnym jest zdecydowanie zalecane. Dokładnie sprawdź, które katalogi są włączone za pomocą UseStaticFiles lub UseDirectoryBrowser. Cały katalog i jego podkatalog stają się publicznie dostępne. Przechowuj pliki odpowiednie do obsługi publicznej w dedykowanym katalogu, takim jak <content_root>/wwwroot. Oddziel te pliki od widoków MVC, Razor stron, plików konfiguracji itp.

  • Adresy URL treści udostępnianych za pośrednictwem UseDirectoryBrowser i UseStaticFiles są zgodne z zasadą rozróżniania wielkości liter i ograniczeniami dotyczącymi znaków bazowego systemu plików. Na przykład system Windows jest nieczuły na wielkość liter, ale systemy macOS i Linux uwzględniają wielkość liter.

  • Aplikacje ASP.NET Core hostowane w IIS używają modułu ASP.NET Core do przekazywania wszystkich żądań do aplikacji, w tym żądań plików statycznych. Moduł obsługi plików statycznych w usługach IIS nie jest używany i nie obsługuje żądań.

  • Wykonaj następujące kroki w Menedżerze usług IIS, aby usunąć program obsługi plików statycznych usług IIS na poziomie serwera lub witryny internetowej:

    1. Przejdź do funkcji Moduły .
    2. Wybierz pozycję StaticFileModule na liście.
    3. Kliknij przycisk Usuń na pasku bocznym Akcje .

    Warning

    Jeśli program obsługi plików statycznych w usługach IIS jest włączony i moduł ASP.NET Core jest niepoprawnie skonfigurowany, pliki statyczne mogą być obsługiwane. Ten warunek występuje na przykład, jeśli web.config plik nie został wdrożony.

  • Umieść pliki kodu, w tym .cs i .cshtml, poza katalogem głównym projektu aplikacji. Ta konfiguracja tworzy logiczny podział między zawartością po stronie klienta aplikacji a kodem opartym na serwerze. Ta separacja uniemożliwia wyciek kodu po stronie serwera.

Właściwości programu MSBuild

W poniższych tabelach przedstawiono właściwości programu MSBuild i opisy metadanych plików statycznych.

Majątek Description
EnableDefaultCompressedItems Włącza domyślną kompresję dołączania i wykluczania wzorców.
CompressionIncludePatterns Rozdzielana średnikami lista wzorców plików do uwzględnienia na potrzeby kompresji.
CompressionExcludePatterns Rozdzielana średnikami lista wzorców plików do wykluczenia z kompresji.
EnableDefaultCompressionFormats Włącza domyślne formaty kompresji (Gzip i Brotli).
BuildCompressionFormats Formaty kompresji do użycia podczas kompilacji.
PublishCompressionFormats Formaty kompresji do użycia podczas publikowania.
DisableBuildCompression Wyłącza kompresję podczas kompilacji.
CompressDiscoveredAssetsDuringBuild Kompresuje odnalezione zasoby podczas kompilacji.
BrotliCompressionLevel Poziom kompresji algorytmu Brotli.
StaticWebAssetBuildCompressAllAssets Kompresuje wszystkie zasoby podczas kompilacji, a nie tylko zasoby odnalezione lub obliczone podczas kompilacji.
StaticWebAssetPublishCompressAllAssets Kompresuje wszystkie zasoby podczas publikowania, a nie tylko zasoby odnalezione lub obliczone podczas kompilacji.
Majątek Description
StaticWebAssetBasePath Podstawowa ścieżka adresu URL dla wszystkich zasobów w bibliotece.
StaticWebAssetsFingerprintContent Umożliwia odciski palców zawartości na potrzeby bustingu pamięci podręcznej.
StaticWebAssetFingerprintingEnabled Włącza funkcję odcisków palców dla statycznych zasobów internetowych.
StaticWebAssetsCacheDefineStaticWebAssetsEnabled Umożliwia buforowanie statycznych definicji zasobów internetowych.
StaticWebAssetEndpointExclusionPattern Wzorzec wykluczania punktów końcowych.
Grupa elementów Description Metadane
StaticWebAssetContentTypeMapping Mapuje wzorce plików na typy zawartości i nagłówki pamięci podręcznej dla punktów końcowych. Pattern, CachePriority
StaticWebAssetFingerprintPattern Definiuje wzorce stosowania odcisków palców do statycznych zasobów internetowych na potrzeby bustingu pamięci podręcznej. Pattern, Expression

Opisy metadanych:

  • Pattern: wzorzec globu używany do dopasowywania plików. W przypadku StaticWebAssetContentTypeMappingprogramu dopasuje pliki w celu określenia ich typu zawartości (na przykład *.js dla plików JavaScript). W przypadku StaticWebAssetFingerprintPatternprogramu identyfikuje pliki z wieloma rozszerzeniami, które wymagają specjalnego leczenia odciskiem palca (na przykład *.lib.module.js).

  • Cache: określa Cache-Control wartość nagłówka dla dopasowanego typu zawartości. Ta wartość steruje zachowaniem buforowania przeglądarki (na przykład max-age=3600, must-revalidate w przypadku plików multimedialnych).

  • Priority: Określa pierwszeństwo, gdy wiele StaticWebAssetContentTypeMapping elementów jest zgodnych z tym samym plikiem. Wyższe wartości liczbowe mają pierwszeństwo przed niższymi. Ciąg Priority jest wymagany.

  • Expression: definiuje sposób wstawiania odcisku palca do nazwy pliku. Wartość domyślna to #[.{FINGERPRINT}], która wstawia odcisk palca ({FINGERPRINT} symbol zastępczy) przed rozszerzeniem.

Poniższy przykład mapuje wzorzec pliku bitmapy (.bmp) na typ zawartości image/bmp z symbolem zastępczym {CACHE HEADER}, który reprezentuje nagłówek Cache-Control do użycia dla punktów końcowych bez użycia technologii odcisków palców.

<ItemGroup>
  <StaticWebAssetContentTypeMapping Include="image/bmp" Cache="{CACHE HEADER}"
    Pattern="*.bmp" Priority="1" />
</ItemGroup>

Opcje konfiguracji środowiska uruchomieniowego

W poniższej tabeli opisano opcje konfiguracji środowiska uruchomieniowego.

Klucz konfiguracji Description
ReloadStaticAssetsAtRuntime Umożliwia dynamiczne przeładowanie zasobów statycznych w czasie programowania: obsługuje zmodyfikowane pliki głównego katalogu webowego (wwwroot), ponownie oblicza ETag i kompresuje ponownie, jeśli jest to wymagane, zamiast korzystania z wersji manifestu utworzonej podczas kompilacji. Domyślnie włączone jest tylko wtedy, gdy obsługiwany jest manifest kompilacji, o ile nie zostanie ustawione jawnie.
DisableStaticAssetNotFoundRuntimeFallback Gdy true, wyłącza punkt końcowy awaryjny obsługujący nowo dodane pliki, które nie są obecne w manifeście kompilacji. Gdy false jest obecny lub nieobecny, sprawdzana funkcja rezerwowa {**path} (GET/HEAD) rejestruje ostrzeżenie i obsługuje plik przy użyciu obliczonego ETag.
EnableStaticAssetsDevelopmentCaching Gdy trueparametr zachowuje oryginalne Cache-Control nagłówki deskryptorów elementów zawartości. W przypadku false lub jego braku, nagłówki Cache-Control są ponownie zapisywane, aby uniknąć agresywnego buforowania klienta podczas tworzenia.
EnableStaticAssetsDevelopmentIntegrity Gdy trueprogram zachowuje właściwości integralności w deskryptorach zasobów. Gdy false lub jest nieobecny, usuwa wszelkie właściwości integralności, aby zapobiec niezgodności, gdy pliki zmieniają się podczas programowania.

Dodatkowe zasoby

  • Last updated on