ścieżka podstawowa aplikacji ASP.NET Core Blazor

W tym artykule opisano ścieżkę podstawową aplikacji w aplikacjach ASP.NET Core Blazor , w tym wskazówki dotyczące konfiguracji.

Ścieżka podstawowa aplikacji to ścieżka URL katalogu głównego aplikacji. Pomyślny routing w Blazor aplikacjach wymaga konfiguracji struktury dla dowolnej głównej ścieżki adresu URL, która nie znajduje się w domyślnej ścieżce /podstawowej aplikacji.

Rozważmy następującą aplikację ASP.NET Core i aplikację podrzędną Blazor:

• Aplikacja ASP.NET Core nosi nazwę MyApp:
  • Aplikacja fizycznie znajduje się w lokalizacji d:/MyApp.
  • Żądania są odbierane pod adresem https://www.contoso.com/{MYAPP RESOURCE}.
• Aplikacja Blazor o nazwie CoolApp to podaplikacja klasy MyApp:
  • Aplikacja podrzędna fizycznie znajduje się w lokalizacji d:/MyApp/CoolApp.
  • Żądania są odbierane pod adresem https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Bez określania dodatkowej konfiguracji dla aplikacji CoolAppaplikacja podrzędna w tym scenariuszu nie ma informacji o tym, gdzie znajduje się na serwerze. Na przykład aplikacja nie może skonstruować poprawnych względnych adresów URL do zasobów bez informacji, że znajduje się ona w ścieżce względnej adresu URL /CoolApp/. Ten scenariusz dotyczy również różnych scenariuszy hostingu i zwrotnego serwera proxy, gdy aplikacja nie jest hostowana w ścieżce URL katalogu głównego.

Kontekst

Miejsce docelowe tagu kotwicy (href) może składać się z jednego z dwóch punktów końcowych:

• Lokalizacje bezwzględne, które obejmują schemat (domyślnie schemat strony, jeśli pominięto), host, port i ścieżkę lub tylko ukośnik (/), po którym następuje ścieżka.

  Przykłady: https://example.com/a/b/c lub /a/b/c

• Lokalizacje względne zawierające tylko ścieżkę i nie zaczynają się ukośnikiem (/). Są one rozpoznawane względem bieżącego adresu URL dokumentu lub wartości tagu <base> , jeśli określono.

  Przykład: a/b/c

Obecność końcowego ukośnika (/) w skonfigurowanej ścieżce podstawowej aplikacji jest znacząca, aby obliczyć ścieżkę podstawową dla adresów URL aplikacji. Na przykład https://example.com/a ma ścieżkę https://example.com/podstawową typu , a https://example.com/a/ ukośnik końcowy ma ścieżkę https://example.com/apodstawową .

Źródła linków odnoszących się do Blazor w aplikacjach platformy ASP.NET Core:

• Adresy URL w Razor składnikach (.razor) są zwykle względne.
• Adresy URL w skryptach, takie jak Blazor skrypty (blazor.*.js), są względem dokumentu.

Jeśli renderujesz aplikację Blazor z różnych dokumentów (na przykład /Admin/B/C/ i /Admin/D/E/), musisz wziąć pod uwagę ścieżkę podstawową aplikacji lub ścieżka podstawowa różni się, gdy aplikacja renderuje się w każdym dokumencie, a zasoby są pobierane z nieprawidłowych adresów URL.

Istnieją dwa podejścia do radzenia sobie z wyzwaniem prawidłowego rozwiązywania linków względnych:

• Zamapuj zasoby dynamicznie przy użyciu dokumentu, na który zostały one renderowane jako katalog główny.
• Ustaw spójną ścieżkę podstawową dla dokumentu i zamapuj zasoby w ramach tej ścieżki podstawowej.

Pierwsza opcja jest bardziej skomplikowana i nie jest najbardziej typowym podejściem, ponieważ sprawia, że nawigacja jest inna dla każdego dokumentu. Rozważmy następujący przykład renderowania strony /Something/Else:

• Renderowane w obszarze /Admin/B/C/, strona jest renderowana ze ścieżką ./Admin/B/C/Something/Else
• Renderowane w obszarze /Admin/D/E/, strona jest renderowana w tej samej ścieżce ./Admin/B/C/Something/Else

W ramach pierwszego podejścia oferty IDynamicEndpointMetadata routingu i MatcherPolicy, które w połączeniu mogą być podstawą implementacji całkowicie dynamicznego rozwiązania, które określa w czasie wykonywania dotyczące sposobu kierowania żądań.

W przypadku drugiej opcji, która jest zwykle podejściem, aplikacja ustawia ścieżkę podstawową w dokumencie i mapuje punkty końcowe serwera na ścieżki poniżej podstawy. Poniższe wskazówki przyjmują to podejście.

Po stronie serwera Blazor

Zamapuj SignalR centrum aplikacji po stronie Blazor serwera, przekazując ścieżkę do MapBlazorHub w Program pliku:

app.MapBlazorHub("base/path");

Zaletą użycia MapBlazorHub jest możliwość mapowania wzorców, takich jak "{tenant}" i nie tylko konkretne ścieżki.

Możesz również mapować SignalR centrum, gdy aplikacja znajduje się w folderze wirtualnym z rozgałęzionym potokiem oprogramowania pośredniczącego. W poniższym przykładzie żądania do /base/path/ są obsługiwane przez Blazorcentrum firmy :SignalR

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

<base> Skonfiguruj tag zgodnie ze wskazówkami w sekcji Konfigurowanie ścieżki podstawowej aplikacji.

Samodzielny Blazor WebAssembly

W aplikacji autonomicznej Blazor WebAssembly skonfigurowany jest tylko <base> tag zgodnie ze wskazówkami w sekcji Konfigurowanie ścieżki podstawowej aplikacji.

Konfigurowanie ścieżki podstawowej aplikacji

Aby zapewnić konfigurację podstawowej Blazor ścieżki https://www.contoso.com/CoolApp/aplikacji , ustaw ścieżkę podstawową aplikacji (<base>), która jest również nazywana względną ścieżką główną.

Konfigurując ścieżkę podstawową aplikacji, składnik, który nie znajduje się w katalogu głównym, może tworzyć adresy URL względem ścieżki głównej aplikacji. Składniki na różnych poziomach struktury katalogów mogą tworzyć linki do innych zasobów w lokalizacjach w całej aplikacji. Ścieżka podstawowa aplikacji służy również do przechwytywania wybranych hiperlinków, w których element docelowy href linku znajduje się w przestrzeni identyfikatora URI ścieżki podstawowej aplikacji. Składnik Router obsługuje nawigację wewnętrzną.

Umieść tag <base> w znaczniku <head> ( lokacjazawartości <head>) przed wszystkimi elementami z wartościami atrybutów, które są adresami URL, takimi jak atrybuty href elementów <link>.

W wielu scenariuszach hostingu ścieżka względna URL do aplikacji jest katalogiem głównym aplikacji. W tych domyślnych przypadkach względna ścieżka podstawowa adresu URL aplikacji jest / skonfigurowana tak jak <base href="/" /> w <head> zawartości.

Uwaga / Notatka

W niektórych scenariuszach hostingu, takich jak usługi GitHub Pages i aplikacje podrzędne usług IIS, ścieżka podstawowa aplikacji musi być ustawiona na względną ścieżkę adresu URL serwera aplikacji.

• W aplikacji po stronie Blazor serwera użyj jednej z następujących metod:

  • Opcja 1. Użyj tagu <base> , aby ustawić ścieżkę podstawową aplikacji (lokalizację <head> zawartości):

    <base href="/CoolApp/">
    

    Wymagany jest ukośnik końcowy.

  • Opcja 2: Najpierw wywołaj metodę UsePathBasew potoku przetwarzania żądań aplikacji (Program.cs) bezpośrednio po skompilowaniu WebApplicationBuilder (builder.Build()), aby skonfigurować ścieżkę podstawową dla dowolnego następującego oprogramowania pośredniczącego, które wchodzi w interakcję ze ścieżką żądania:

    app.UsePathBase("/CoolApp");
    

    Wywołanie UsePathBase jest zalecane, gdy chcesz również uruchomić aplikację Blazor Server lokalnie. Na przykład podaj adres URL uruchamiania w Properties/launchSettings.json:

    "launchUrl": "https://localhost:{PORT}/CoolApp",
    

    Symbol zastępczy {PORT} w poprzednim przykładzie to port zgodny z bezpiecznym portem w ścieżce konfiguracji applicationUrl. W poniższym przykładzie przedstawiono pełny profil uruchamiania aplikacji w porcie 7279:

    "BlazorSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7279;http://localhost:5279",
      "launchUrl": "https://localhost:7279/CoolApp",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
    }
    

    Aby uzyskać więcej informacji na launchSettings.json temat pliku, zobacz Use multiple environments in ASP.NET Core (Używanie wielu środowisk w programie ASP.NET Core). Aby uzyskać dodatkowe informacje na Blazor temat ścieżek bazowych aplikacji i hostingu, zobacz <base href="/" /> lub base-tag alternative for Blazor MVC integration (dotnet/aspnetcore #43191).

• Autonomiczny Blazor WebAssembly (wwwroot/index.html):

  <base href="/CoolApp/">
  

  Wymagany jest ukośnik końcowy.

Uwaga / Notatka

W przypadku użycia WebApplication (zobacz Migrowanie z ASP.NET Core w .NET 5 do .NET 6), app.UseRouting należy wywołać po UsePathBase, aby oprogramowanie pośredniczące w routingu mogło obserwować zmodyfikowaną ścieżkę przed dopasowaniem tras. W przeciwnym razie trasy zostaną dopasowane przed zmianą ścieżki przez UsePathBase zgodnie z opisem w artykułach Ustalanie kolejności oprogramowania pośredniczącego i Routing.

Nie używaj linków prefiksów w całej aplikacji z ukośnikiem do przodu. Unikaj używania separatora segmentów ścieżki lub używaj notacji ścieżki względnej z kropkami i ukośnikami (./):

• ❌ Niepoprawne: <a href="/account">
• ✔️ Poprawny: <a href="account">
• ✔️ Poprawny: <a href="./account">

W Blazor WebAssembly przypadku żądań internetowego interfejsu HttpClient API w usłudze upewnij się, że pomocnicy JSON (HttpClientJsonExtensions) nie prefiksują adresów URL z ukośnikiem (/):

• ❌ Niepoprawne: var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Poprawny: var rsp = await client.GetFromJsonAsync("api/Account");

Nie prefiksuj łącza względne Menedżera nawigacji z ukośnikiem do przodu. Należy unikać używania separatora segmentu ścieżki lub użyć notacji ścieżki względnej dot-slash (./) (Navigation jest wstrzykiwany NavigationManager):

• ❌ Niepoprawne: Navigation.NavigateTo("/other");
• ✔️ Poprawny: Navigation.NavigateTo("other");
• ✔️ Poprawny: Navigation.NavigateTo("./other");

W typowych konfiguracjach hostingu usług IIS/Azure dodatkowa konfiguracja zwykle nie jest wymagana. W niektórych scenariuszach hostowania i hostowania zwrotnego serwera proxy usług IIS może być wymagana dodatkowa konfiguracja oprogramowania pośredniczącego plików statycznych:

• Aby poprawnie obsługiwać pliki statyczne (na przykład app.UseStaticFiles("/CoolApp");).
• Aby obsłużyć Blazor skrypt (_framework/blazor.*.js). Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor plików statycznych.

W przypadku aplikacji Blazor WebAssembly ze ścieżką względną URL inną niż do katalogu głównego (na przykład <base href="/CoolApp/">) aplikacja nie może odnaleźć zasobów w przypadku uruchamiania lokalnego. Aby rozwiązać ten problem podczas lokalnego programowania i testowania, możesz podać argument ścieżki podstawowej, który odpowiada wartości href tagu <base> w czasie wykonywania. Nie dołączaj ukośnika końcowego. Aby przekazać argument podstawowy ścieżki podczas lokalnego uruchamiania aplikacji, wykonaj dotnet watch polecenie (lub dotnet run) z katalogu aplikacji z opcją --pathbase :

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

W przypadku aplikacji Blazor WebAssembly ze ścieżką względną URL aplikacji /CoolApp/ (<base href="/CoolApp/">) polecenie ma postać:

dotnet watch --pathbase=/CoolApp

Jeśli wolisz skonfigurować profil uruchamiania aplikacji, aby określić pathbase automatycznie zamiast ręcznie dotnet watch (lub dotnet run), ustaw właściwość w elem commandLineArgsProperties/launchSettings.json. Poniższa instrukcja konfiguruje również adres URL uruchamiania (launchUrl):

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

Przykład z aplikacją CoolApp:

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

dotnet watch Przy użyciu opcji (lub dotnet run) z --pathbase opcją lub konfiguracją profilu uruchamiania, która ustawia ścieżkę podstawową, Blazor WebAssembly aplikacja odpowiada lokalnie pod adresem http://localhost:port/CoolApp.

Aby uzyskać więcej informacji na launchSettings.json temat pliku, zobacz Use multiple environments in ASP.NET Core (Używanie wielu środowisk w programie ASP.NET Core). Aby uzyskać dodatkowe informacje na Blazor temat ścieżek bazowych aplikacji i hostingu, zobacz <base href="/" /> lub base-tag alternative for Blazor MVC integration (dotnet/aspnetcore #43191).

Uzyskiwanie ścieżki podstawowej aplikacji z konfiguracji

W poniższych wskazówkach wyjaśniono, jak uzyskać ścieżkę tagu <base> z pliku ustawień aplikacji dla różnych środowisk.

Dodaj plik ustawień aplikacji do aplikacji. Poniższy przykład dotyczy Staging środowiska (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

W aplikacji po stronie Blazor serwera załaduj ścieżkę podstawową z konfiguracji w <head> zawartości:

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

Alternatywnie aplikacja po stronie serwera może uzyskać wartość z konfiguracji programu UsePathBase. Umieść następujący kod najpierw w potoku przetwarzania żądań aplikacji (Program.cs) bezpośrednio po skompilacji WebApplicationBuilder (builder.Build()). W poniższym przykładzie użyto klucza AppBasePathkonfiguracji :

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

W aplikacji po stronie Blazor WebAssembly klienta:

• <base> Usuń tag z :wwwroot/index.html

  - <base href="..." />
  

• Podaj ścieżkę podstawową HeadContent aplikacji za pośrednictwem składnika w składniku App (App.razor):

  @inject IConfiguration Config
  
  ...
  
  <HeadContent>
      <base href="/@(Config.GetValue<string>("AppBasePath"))" />
  </HeadContent>
  

Jeśli nie ma wartości konfiguracji do załadowania, na przykład w środowiskach innych niż przejściowe, powyższe rozwiązanie jest rozpoznawane href jako ścieżka /główna .

Przykłady w tej sekcji koncentrują się na dostarczaniu ścieżki podstawowej aplikacji z ustawień aplikacji, ale podejście odczytu ścieżki z IConfiguration jest prawidłowe dla dowolnego dostawcy konfiguracji. Aby uzyskać więcej informacji, zobacz następujące zasoby:

• Konfiguracja Blazor na platformie ASP.NET Core
• Konfiguracja w usłudze ASP.NET Core