Recarga Dinâmica de XAML para .NET MAUI

A Recarga Dinâmica de XAML do .NET MAUI é um recurso do Visual Studio que permite exibir o resultado de alterações de XAML em seu aplicativo em execução, sem precisar compilar novamente seu projeto. Sem a Recarga Dinâmica de XAML, você precisará compilar e implantar seu aplicativo sempre que quiser exibir o resultado de uma alteração de XAML.

Quando seu aplicativo .NET MAUI está em execução na configuração de depuração, com o depurador anexado, a Recarga Dinâmica de XAML analisa suas edições de XAML e envia essas alterações para o aplicativo em execução. Ele preserva o estado da interface do usuário, pois não recria a interface do usuário para a página inteira e atualiza as propriedades alteradas nos controles afetados por edições. Além disso, seu estado de navegação e dados serão mantidos, permitindo que você itere rapidamente na interface do usuário sem perder sua localização no aplicativo. Portanto, você gastará menos tempo compilando novamente e implantando seus aplicativos para validar alterações na interface do usuário.

Por padrão, você não precisa salvar seu arquivo XAML para ver os resultados de suas edições. Em vez disso, as atualizações são aplicadas imediatamente à medida que você digita. No entanto, no Windows, você pode alterar esse comportamento para atualizar somente ao salvar o arquivo. Isso pode ser feito marcando a caixa de seleção Aplicar a Recarga Dinâmica de XAML ao salvar o documento nas configurações de IDE de Recarga Dinâmica disponíveis selecionando Depurar > Opções > Recarga Dinâmica de XAML na barra de menus do Visual Studio. Às vezes, somente atualizar ao salvar o arquivo pode ser útil se você fizer atualizações de XAML maiores e não quiser que elas sejam exibidas até que sejam concluídas.

Observação

Se você estiver escrevendo um aplicativo UWP ou WPF nativo sem usar o .NET MAUI, consulte O que é a Recarga Dinâmica de XAML para aplicativos WPF e UWP?.

A Recarga Dinâmica XAML está disponível no Visual Studio 2022 e no Visual Studio Code. No Windows, a Recarga Dinâmica de XAML está disponível no Android, iOS e WinUI em emuladores, simuladores e dispositivos físicos. No Mac, a Recarga Dinâmica de XAML está disponível no Android, iOS e Mac Catalyst em emuladores, simuladores e dispositivos físicos. Em todos os casos, a Recarga Dinâmica de XAML requer que sua configuração de depuração se chame Debug.

Importante

A Recarga Dinâmica de XAML não recarrega o código C#. Se você adicionar um novo manipulador de eventos no código, ele só poderá ser usado em XAML depois que o código for recarregado. Além disso, se você adicionar um novo elemento XAML com um x:Name, o nome não poderá ser usado no código até que o código seja recarregado.

Recarregamento de página inteira

Pode haver casos em que a Recarga Dinâmica XAML não atualiza o aplicativo em execução conforme o esperado. Por exemplo, você pode alterar uma propriedade de cor em um controle .NET MAUI, mas não pode ver a alteração de cor no aplicativo em execução. Para contornar esses problemas, você pode recarregar totalmente o arquivo XAML clicando no botão da barra de ferramentas Recarga Dinâmica ou pressionando Alt+F10. Somente os arquivos XAML que foram editados serão recarregados. A exceção a isso é se você alterar um arquivo de dicionário de recursos, caso em que todos os arquivos XAML serão recarregados para aplicar os novos recursos.

Importante

Quando o XAML é recarregado, algum estado da interface pode ser perdido, como o foco e a seleção atuais.

Habilitar Recarga Dinâmica de XAML

A Recarga Dinâmica de XAML é habilitada por padrão no Visual Studio 2022. Se ela tiver sido desabilitada anteriormente, poderá ser habilitada selecionando Depurar > Opções > Recarga Dinâmica de XAML na barra de menus do Visual Studio. Em seguida, na caixa de diálogo Opções, verifique se as opções Habilitar a Recarga Dinâmica de XAML, WinUI (incluindo .NET MAUI) e Android e iOS (.NET MAUI) estão marcadas:

Em seguida, no iOS, em suas configurações de compilação, verifique se o Vinculador está definido como “Não vincular”.

Recarregar em várias plataformas

A Recarga Dinâmica de XAML dá suporte à depuração simultânea de várias plataformas no Visual Studio, desde que você tenha projetos principais separados por plataforma, em vez de um único aplicativo de projeto. Por exemplo, você pode implantar um destino do Android e um do iOS ao mesmo tempo para ver suas alterações refletidas em ambas as plataformas ao mesmo tempo. Para depurar em várias plataformas no Windows, consulte Como: Definir vários projetos de inicialização.

Solução de problemas

A saída da Recarga Dinâmica de XAML exibe mensagens de status que podem ajudar na solução de problemas. No Visual Studio, elas podem ser exibidas selecionando Exibir > Saída na barra de menus e escolhendo Recarga Dinâmica no menu suspenso Mostrar saída de:.

Se a Recarga Dinâmica de XAML falhar ao inicializar, você deve garantir que está usando a versão mais recente do .NET MAUI, a versão mais recente do IDE e que as configurações do vinculador de iOS estão definidas como Não Vincular nas configurações de compilação do projeto.

A Recarga Dinâmica de XAML requer que sua configuração de depuração se chame Debug. Se uma configuração de compilação personalizada for usada, a Recarga Dinâmica de XAML deixará de funcionar se a configuração de compilação não se chamar Debug.

Se nada acontecer ao salvar o arquivo XAML, verifique se a Recarga Dinâmica de XAML está habilitada no IDE. Para obter mais informações, consulte Habilitar a Recarga Dinâmica de XAML.

Se você fizer uma alteração que o analisador da Recarga Dinâmica de XAML vê como inválida, ele mostrará o erro sublinhado no editor e o incluirá na janela Lista de Erros. Os erros de Recarga Dinâmica têm um código de erro que começa com “XHR” (para Recarga Dinâmica de XAML). Se houver erros desse tipo na página, a Recarga Dinâmica de XAML não aplicará alterações ao seu aplicativo em execução até que os erros sejam corrigidos.

Não é possível adicionar, remover ou renomear arquivos ou pacotes NuGet durante uma sessão de Recarga Dinâmica de XAML. Se você adicionar ou remover um arquivo ou pacote NuGet, compile e implante novamente seu aplicativo para continuar usando a Recarga Dinâmica de XAML.

Não há suporte para desabilitar a compilação de XAML com [XamlCompilation(XamlCompilationOptions.Skip)] e pode causar problemas com a árvore visual dinâmica. Para obter mais informações sobre a árvore visual dinâmica, consulte Inspecionar a árvore visual de um aplicativo .NET MAUI.