Roteamento e navegação do Blazor Hybrid do ASP.NET Core

Este artigo explica como gerenciar o roteamento de solicitações e a navegação em aplicativos Blazor Hybrid.

Comportamento de roteamento de solicitação de URI

Comportamento de roteamento de solicitação de URI padrão:

• Um link será interno se o nome do host e o esquema corresponderem entre o URI de origem do aplicativo e o URI da solicitação. Quando os nomes e esquemas de host não correspondem ou se o link definir target="_blank", o link será considerado externo.
• Se o link for interno, o link será aberto no BlazorWebView pelo aplicativo.
• Se o link for externo, o link será aberto por um aplicativo determinado pelo dispositivo com base no manipulador registrado do dispositivo para o esquema do link.
• Para links internos que parecem solicitar um arquivo porque o último segmento do URI usa notação de ponto (por exemplo, /file.x, /Maryia.Melnyk, /image.gif), mas não apontam para nenhum conteúdo estático:
  • WPF e Windows Forms: o conteúdo da página host é retornado.
  • .NET MAUI: uma resposta 404 é retornada.

Para alterar o comportamento de manipulação de link para links que não definem target="_blank", registre o evento UrlLoading e defina a propriedade UrlLoadingEventArgs.UrlLoadingStrategy. A enumeração UrlLoadingStrategy permite definir o comportamento de tratamento de link para qualquer um dos seguintes valores:

• OpenExternally: carregue a URL usando um aplicativo determinado pelo dispositivo. Essa é a estratégia padrão para URIs com um host externo.
• OpenInWebView: carregue a URL dentro do BlazorWebView. Essa é a estratégia padrão para URLs com um host que corresponde à origem do aplicativo. Não use essa estratégia para links externos, a menos que você possa garantir que o URI de destino seja totalmente confiável.
• CancelLoad: cancela a tentativa de carregamento de URL atual.

A propriedade UrlLoadingEventArgs.Url é usada para obter ou definir dinamicamente a URL.

Aviso

Por padrão, os links externos são abertos em um aplicativo determinado pelo dispositivo. Abrir links externos em um BlazorWebView pode introduzir vulnerabilidades de segurança e não devem ser habilitados, a menos que você possa garantir que os links externos sejam totalmente confiáveis.

Documentação da API:

• .NET MAUI: BlazorWebView.UrlLoading
• WPF: BlazorWebView.UrlLoading
• Windows Forms: BlazorWebView.UrlLoading

O namespace Microsoft.AspNetCore.Components.WebView é necessário para os seguintes exemplos:

using Microsoft.AspNetCore.Components.WebView;

Adicione o manipulador de eventos a seguir ao construtor do Page em que o BlazorWebView é criado, que é MainPage.xaml.cs em um aplicativo criado a partir do modelo de projeto .NET MAUI.

blazorWebView.UrlLoading += 
    (sender, urlLoadingEventArgs) =>
    {
        if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
        {
            urlLoadingEventArgs.UrlLoadingStrategy = 
                UrlLoadingStrategy.OpenInWebView;
        }
    };

Adicione o atributo UrlLoading="Handle_UrlLoading" ao controle BlazorWebView no arquivo .xaml:

<blazor:BlazorWebView HostPage="wwwroot\index.html" 
    Services="{StaticResource services}" 
    x:Name="blazorWebView" 
    UrlLoading="Handle_UrlLoading">

Adicione o manipulador de eventos no arquivo .xaml.cs:

private void Handle_UrlLoading(object sender, 
    UrlLoadingEventArgs urlLoadingEventArgs)
{
    if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
    {
        urlLoadingEventArgs.UrlLoadingStrategy = 
            UrlLoadingStrategy.OpenInWebView;
    }
}

No construtor do formulário que contém o controle BlazorWebView, adicione o seguinte registro de evento:

blazorWebView.UrlLoading += 
    (sender, urlLoadingEventArgs) =>
    {
        if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
        {
            urlLoadingEventArgs.UrlLoadingStrategy = 
                UrlLoadingStrategy.OpenInWebView;
        }
    };

Obter ou definir um caminho para a navegação inicial

Use a propriedade BlazorWebView.StartPath para obter ou definir o caminho para a navegação inicial no contexto de navegação Blazor quando o componente Razor tiver concluído o carregamento. O caminho padrão de início é o caminho relativo da URL raiz (/).

Na marcação MainPage XAML (MainPage.xaml), especifique o caminho inicial. O exemplo a seguir define o caminho para uma página de boas-vindas em /welcome:

<BlazorWebView ... StartPath="/welcome" ...>
    ...
<BlazorWebView>

Como alternativa, o caminho inicial pode ser definido no construtor MainPage (MainPage.xaml.cs):

blazorWebView.StartPath = "/welcome";

No designer MainWindow (MainWindow.xaml), especifique o caminho inicial. O exemplo a seguir define o caminho para uma página de boas-vindas em /welcome:

<blazor:BlazorWebView ... StartPath="/welcome" ...>
    ...
</blazor:BlazorWebView>

Dentro do construtor Form1 do arquivo Form1.cs, especifique o caminho inicial. O exemplo a seguir define o caminho para uma página de boas-vindas em /welcome:

blazorWebView1.StartPath = "/welcome";

Navegação entre páginas e componentes do Razor

Esta seção explica como navegar entre páginas de conteúdo do .NET MAUI e componentes do Razor.

O modelo de projeto híbrido .NET MAUIBlazor não é um aplicativo baseado em Shell, portanto, portanto, a navegação baseada em URI para aplicativos baseados em Shell não é adequada para um projeto baseado no modelo de projeto. Os exemplos nesta seção usam um NavigationPage para executar a navegação sem modelo ou modal.

No exemplo a seguir:

• O namespace do aplicativo é MauiBlazor, que corresponde ao nome do projeto sugerido do tutorial Criar um aplicativo .NET MAUIBlazor Hybrid.
• Um ContentPage é colocado em uma nova pasta adicionada ao aplicativo chamado Views.

No App.xaml.cs, crie o MainPage como um NavigationPage fazendo a seguinte alteração:

- MainPage = new MainPage();
+ MainPage = new NavigationPage(new MainPage());

Views/NavigationExample.xaml:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MauiBlazor"
             x:Class="MauiBlazor.Views.NavigationExample"
             Title="Navigation Example"
             BackgroundColor="{DynamicResource PageBackgroundColor}">
    <StackLayout>
        <Label Text="Navigation Example"
               VerticalOptions="Center"
               HorizontalOptions="Center"
               FontSize="24" />
        <Button x:Name="CloseButton" 
                Clicked="CloseButton_Clicked" 
                Text="Close" />
    </StackLayout>
</ContentPage>

No arquivo de código a seguir NavigationExample, o manipulador de eventos CloseButton_Clicked para o botão fechar chama PopAsync para tirar o ContentPage da pilha de navegação.

Views/NavigationExample.xaml.cs:

namespace MauiBlazor.Views;

public partial class NavigationExample : ContentPage
{
    public NavigationExample()
    {
        InitializeComponent();
    }

    private async void CloseButton_Clicked(object sender, EventArgs e)
    {
        await Navigation.PopAsync();
    }
}

Em um componente Razor:

• Adicione o namespace para as páginas de conteúdo do aplicativo. No exemplo a seguir, o namespace é MauiBlazor.Views.
• Adicione um elemento HTML button com um @onclick manipulador de eventos para abrir a página de conteúdo. O método manipulador de eventos é chamado OpenPage.
• No manipulador de eventos, chame PushAsync para efetuar push do ContentPage, NavigationExample, para a pilha de navegação.

O exemplo a seguir tem base no componente Index no modelo de projeto .NET MAUIBlazor.

Pages/Index.razor:

@page "/"
@using MauiBlazor.Views

<h1>Hello, world!</h1>

Welcome to your new app.

<SurveyPrompt Title="How is Blazor working for you?" />

<button class="btn btn-primary" @onclick="OpenPage">Open</button>

@code {
    private async void OpenPage()
    {
        await App.Current.MainPage.Navigation.PushAsync(new NavigationExample());
    }
}

Para alterar o exemplo anterior para navegação modal:

• No método CloseButton_Clicked (Views/NavigationExample.xaml.cs), altere PopAsync para PopModalAsync:

  - await Navigation.PopAsync();
  + await Navigation.PopModalAsync();
  

• No método OpenPage (Pages/Index.razor), altere PushAsync para PushModalAsync:

  - await App.Current.MainPage.Navigation.PushAsync(new NavigationExample());
  + await App.Current.MainPage.Navigation.PushModalAsync(new NavigationExample());
  

Para saber mais, consulte os recursos a seguir:

• Artigo NavigationPage (documentação de .NET MAUI)
• NavigationPage (Documentação da API)

Vinculação de aplicativos (links diretos)

Muitas vezes é desejável conectar um site e um aplicativo móvel para que os links em um site iniciem o aplicativo móvel e exibam conteúdo no aplicativo móvel. A vinculação de aplicativos, também conhecido como vinculação profunda, é uma técnica que permite que um dispositivo móvel responda a um URI e inicie conteúdo em um aplicativo móvel representado pelo URI.

Para obter mais informações, consulte os seguintes artigos na documentação .NET MAUI:

• Links de aplicativo do Android
• Links universal da Apple