Depurar recursos Web em JavaScript usando Local Overrides

Ao desenvolver e depurar recursos Web JavaScript que você usa como um manipulador de eventos em um aplicativo controlado por modelos, você normalmente precisa fazer várias alterações e testar como elas funcionam. Fazer upload e publicar o recurso da Web após cada alteração retarda esse processo.

As ferramentas de desenvolvedor do navegador moderno fornecem recursos para salvar uma cópia local do recurso da Web. Quando o aplicativo controlado por modelo solicita o recurso da Web, o navegador carrega sua cópia local em vez do arquivo do servidor. Você pode editar a cópia local, atualizar a página e testar suas alterações sem carregar e publicar repetidamente o recurso da Web. Você não precisa instalar software proxy, extensões de navegador ou certificados.

Saiba mais sobre como os navegadores modernos fornecem esses recursos.

Important

Uma sobrescrita local altera apenas o recurso carregado pelo navegador. Ele não atualiza o recurso Web JavaScript no Microsoft Dataverse e outros usuários não veem suas alterações. Depois de concluir a solução de problemas, copie as alterações que deseja manter no arquivo de origem e use o processo normal para atualizar e publicar o recurso da Web. Este artigo não descreve esse processo.

Prerequisites

Antes de começar:

  • Você precisa de um aplicativo baseado em modelo que tenha um recurso Web JavaScript usado para fornecer manipuladores de eventos para um formulário.

    Este artigo usa o recurso Web JavaScript descrito em Escreva seu primeiro script de cliente. Esse passo a passo cria um recurso Web JavaScript chamado example_form-script.js, adiciona-o ao formulário Account e registra funções para os eventos On Load e On Save do formulário e o evento On Change da coluna Name.

    Note

    Você pode baixar o JavaScriptWebResourceExampleSolution_1_0_managed.zip. Instale essa solução gerenciada e você encontrará um aplicativo controlado por modelo que representa o resultado concluído do artigo passo a passo Escrever seu primeiro script do cliente.

  • Este artigo usa Microsoft Edge, mas as ferramentas de desenvolvedor do Google Chrome, Firefox e Safari têm recursos semelhantes.

  • Crie uma pasta vazia no computador para Microsoft Edge DevTools para armazenar substituições locais. Não use uma pasta que contenha arquivos de origem, credenciais, certificados ou outras informações confidenciais. O DevTools cria a estrutura de pastas de que precisa nessa pasta. Este artigo usa, C:\temp\overrides mas talvez você queira usar C:\Users\<your user name>\overrides.

Este artigo usa este script de Escreva seu primeiro script de cliente:

// Define a unique namespace for the sample library.
window.Example ??= {};

(() => {
    const notificationId = "_myUniqueId";
    const currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName;
    const message = `${currentUserName}: Your JavaScript code in action!`;

    // Code to run in the form OnLoad event
    window.Example.formOnLoad = (executionContext) => {
        const formContext = executionContext.getFormContext();

        // Display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", notificationId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(
            () => formContext.ui.clearFormNotification(notificationId),
            5000
        );
    };

    // Code to run in the column OnChange event
    window.Example.attributeOnChange = (executionContext) => {
        const formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        const accountName = formContext.getAttribute("name").getValue();
        if (accountName?.toLowerCase().includes("contoso")) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    };

    // Code to run in the form OnSave event
    window.Example.formOnSave = () => {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    };
})();

Este recurso Web JavaScript fornece três funções registradas para os seguintes eventos:

Função Event
Example.formOnLoad Form OnLoad
Example.attributeOnChange OnChange do campo
Example.formOnSave Form OnSave

As etapas também funcionam com qualquer recurso Web JavaScript registrado como um manipulador de eventos de formulário. Use o nome do recurso da Web e dispare seu evento quando as etapas se referirem ao exemplo.

Confirme se o script publicado funciona

Antes de criar uma substituição, confirme o comportamento atual do recurso da Web publicado:

  1. Abra o aplicativo baseado em modelo no Microsoft Edge.

  2. Abra um registro de conta existente ou crie um novo.

  3. Confirme se uma notificação de formulário semelhante à seguinte mensagem aparece por cinco segundos:

    <Your Name>: Your JavaScript code in action!

Esta etapa confirma que o formulário carrega o recurso da Web e chama o manipulador de eventos Example.formOnLoad.

Configurar sobrescritas locais

Você só precisa selecionar uma pasta de overrides na primeira vez que usar Local Overrides em um perfil do navegador Microsoft Edge.

  1. Com o formulário de conta aberto, pressione F12 ou Ctrl+Shift+I para abrir o DevTools.

  2. Selecione a ferramenta Fontes .

  3. No painel Navegador, selecione a guia Substituições. Se a guia não estiver visível, selecione Mais guias e selecione Substituições.

  4. Selecione Selecionar pasta para sobrescritas.

  5. Selecione a pasta vazia que você criou para substituições de configuração e, em seguida, selecione Selecionar Pasta.

  6. Quando DevTools solicitar acesso completo à pasta, selecione Permitir.

    Captura de tela do prompt DevTools solicitando acesso completo à pasta Substituições Locais.

  7. Confirme se Habilitar Substituições Locais está selecionado.

    Captura de tela da guia Substituições locais da ferramenta Origens depois que uma pasta de substituições é selecionada, mostrando Habilitar Substituições Locais selecionada.

Habilitar o bypass da rede para service workers

Important

Habilitar o Bypass para rede garante que as substituições locais de DevTools sejam aplicadas, impedindo que os Service Workers forneçam respostas em cache. Se você não fizer essa etapa, as substituições locais não funcionarão com aplicativos baseados em modelo.

  1. Em DevTools, selecione a guia Aplicativo .

    Se a guia não estiver visível, selecione + (Mais guias) e, em seguida, Application.

  2. No painel de navegação esquerdo, selecione Service Workers.

  3. Selecione Ignorar para a rede para forçar solicitações a ignorar o Service Worker e usar a rede.

    Captura de tela do painel Service Workers com Bypass para rede selecionada.

  4. Atualize a página para aplicar a alteração.

Criar uma substituição forçada para o recurso da Web

Use a ferramenta Network para localizar o arquivo JavaScript carregado pelo formulário da conta:

  1. Selecione a ferramenta Rede .

  2. Se a atividade de rede não estiver sendo registrada, selecione Registrar log de rede.

  3. Atualize a página para que o formulário carregue o recurso da Web novamente.

  4. Na caixa Filtrar , comece a digitar o nome do recurso da Web, como: example_form-script.js.

  5. Na lista de solicitações de rede, clique com o botão direito do mouse example_form-script.js e, em seguida, selecione Substituir conteúdo.

    Captura de tela da ferramenta Rede filtrada para example_form-script.js com o comando Substituir conteúdo selecionado.

  6. Selecione a ferramenta Fontes e, em seguida, selecione a guia Substituições .

  7. Expanda as pastas que o DevTools criou e selecione example_form-script.js.

    Captura de tela de example_form-script.js na guia Overrides com o indicador de substituição roxo.

    O DevTools copia o recurso da Web para a pasta Overrides. Um ponto roxo no ícone de arquivo indica que o DevTools substituiu o recurso.

Tip

Você também pode criar a sobrescrita na guia Página na ferramenta Fontes. Encontre o recurso da Web, clique com o botão direito do mouse nele e selecione Substituir o conteúdo.

Verifique se Microsoft Edge abre a cópia local

Faça uma alteração fácil de reconhecer para que você possa confirmar se a sobrescrita está funcionando:

  1. No editor do DevTools, localize a seguinte linha:

    const message = `${currentUserName}: Your JavaScript code in action!`;

  2. Substitua-o por esta linha:

    const message = `${currentUserName}: Local override in action!`;

    Note

    Se você tentar colar o código no editor de DevTools, verá essa caixa de diálogo. Você precisa digitar allow pasting e selecionar Permitir para continuar. Essa caixa de diálogo não será exibida se você digitar alterações diretamente.

    Captura de tela da caixa de diálogo de aviso de colagem do DevTools com o botão Permitir.

  3. Altere a duração da notificação de 5000 para 15000.

  4. Pressione Ctrl+S para salvar o arquivo local.

  5. Atualize o formulário da conta.

  6. Confirme se a notificação exibe a substituição local em ação! e permanece visível por 15 segundos.

    Captura de tela da notificação do formulário da conta mostrando a substituição local em ação.

A mensagem e a duração alteradas confirmam que Microsoft Edge carregou a substituição local em vez do recurso da Web publicado.

Depurar os manipuladores de eventos

Depois de confirmar que a substituição funciona, use o depurador DevTools para investigar o script.

Depurar o evento OnLoad do formulário

  1. Na ferramenta Fontes, abra o arquivo sobrescrito example_form-script.js.

  2. Selecione o número de linha desta instrução para definir um ponto de interrupção:

    Captura de tela do editor DevTools com um ponto de interrupção no manipulador de eventos Example.formOnLoad.

  3. Atualize o formulário da conta.

  4. Quando a execução do script for pausada, use o painel Escopo para inspecionar executionContext e formContext.

    Captura de tela do painel Escopo de DevTools mostrando valores executionContext e formContext.

  5. Percorra a função e observe a chamada para setFormNotification.

  6. Selecione Retomar a execução do script para continuar.

Depurar o evento OnChange do nome da conta

  1. Defina um ponto de interrupção nesta instrução Example.attributeOnChange:

    const accountName = formContext.getAttribute("name").getValue();

  2. No formulário da conta, altere o Nome da Conta e, em seguida, mova o foco para longe da coluna para disparar o evento On Change .

  3. Quando a execução for pausada, inspecione o valor de accountName.

    Captura de tela do DevTools pausado no manipulador de eventos Example.attributeOnChange enquanto inspeciona o accountName.

  4. Utilize um nome de conta que contenha Contoso e percorra a função para observar como o script define os valores Site, Telefone Principal e Descrição.

Depurar o evento OnSave do formulário

  1. Defina um ponto de interrupção na instrução Xrm.Navigation.openAlertDialog em Example.formOnSave.

  2. Salve o registro.

  3. Quando a execução for pausada, inspecione a pilha de chamadas para confirmar se o evento On Save do formulário chamou a função esperada.

    Captura de tela da pilha de chamadas do depurador DevTools pausada no manipulador de eventos Example.formOnSave.

  4. Retome a execução do script e confirme se a caixa de diálogo de alerta é aberta.

Você pode editar e salvar o override sempre que quiser testar uma possível correção. Atualize o formulário para testar as alterações no código que são executadas quando o formulário é carregado. Acione o formulário relevante ou o evento da coluna para testar outros manipuladores de eventos. Use a ferramenta Console para examinar erros e saída de log.

Comparar a substituição forçada com o recurso da Web publicado

Para confirmar se um problema é causado por suas alterações locais:

  1. Na ferramenta Fontes , selecione a guia Substituições .
  2. Desmarque "Habilitar substituições locais".
  3. Atualize o formulário da conta e teste o evento novamente.

Microsoft Edge agora carrega o recurso web publicado do servidor. Selecione Ativar substituições locais e atualize o formulário para retomar usando a cópia local.

Finalizar a solução de problemas

Os arquivos de substituição local não estão conectados ao recurso da Web no Dataverse ou aos arquivos de origem da solução.

  1. Copie as alterações que você deseja manter do arquivo de substituição para o arquivo de origem que você usa para manter o recurso da Web.
  2. Use seu processo normal de desenvolvimento e implantação para atualizar e publicar o recurso Web em JavaScript.
  3. Teste o recurso da Web publicado com Habilitar Substituições Locais desmarcada.
  4. Quando você não precisar mais da configuração de sobrescrição, selecione Limpar a configuração na guia Sobrescrições.

Caution

Não trate o arquivo na pasta de substituições como o arquivo de origem para o recurso da Web. Mantenha as alterações que você deseja manter antes de limpar a configuração ou excluir arquivos de substituição local.

Solucionar problemas com sobrescritas locais

Veja a seguir os problemas que você pode encontrar ao usar Local Overrides.

O recurso da Web não aparece na ferramenta Rede

Confirme se a ferramenta Network está registrando, desmarque todos os filtros e atualize o formulário. O formulário deve carregar o recurso da Web antes de ser exibido. Confirme também se a biblioteca JavaScript foi adicionada ao formulário e se as personalizações do formulário foram publicadas.

O comando conteúdo Override não está disponível

Retorne à ferramenta Sources e confirme se você selecionou uma pasta de substituições, permitiu que o DevTools a acessasse e selecionou Habilitar Substituições Locais. Em seguida, atualize o formulário e tente novamente.

O formulário ainda usa o script publicado

Mantenha o DevTools aberto, confirme se Habilitar Substituições Locais está selecionado e verifique se o recurso da Web tem um ponto roxo na ferramenta Rede ou Fontes . Salve a substituição forçada e atualize o formulário.

Um ponto de interrupção não é atingido

Confirme se você definiu o ponto de interrupção no arquivo sobrescrito e se ele aparece habilitado. Dispare o evento associado a essa função: atualize o formulário para On Load, altere a coluna configurada para On Change ou salve o registro para On Save. Verifique também a ferramenta Console para verificar se há um erro de sintaxe que impeça o carregamento do script.

  • Última atualização a