Solução de problemas das funções personalizadas

Ao desenvolver funções personalizadas, você poderá encontrar erros no produto durante a criação e testes das funções.

Para resolver problemas, habilite o log do tempo de execução para capturar erros e consultar mensagens de erro do Excel. Alem disso, verifique se há erros comuns, como deixar promessas não resolvidas.

Depuração de funções personalizadas

Para depurar suplementos de funções personalizadas que usam um tempo de execução compartilhado, consulte Visão geral da depuração de Suplementos do Office.

Para depurar suplementos de funções personalizadas que não usam um runtime compartilhado, consulte Depuração de funções personalizadas.

Habilitar o log de tempo de execução

Se estiver testando o suplemento do Office no Windows, você deverá habilitar o log do tempo de execução. O log de tempo de execução entrega instruções console.log a um arquivo de log separado criado para ajudar você a descobrir problemas. As instruções abrangem uma variedade de erros, incluindo erros relacionados ao arquivo de manifesto do suplemento, condições de tempo de execução ou instalação de suas funções personalizadas. Para saber mais sobre o log do tempo de execução, confira Depurar seu suplemento com o log do tempo de execução.

Verificar se há mensagens de erro do Excel

O Excel tem diversas mensagens de erro internas que serão retornadas para uma célula se houver um erro de cálculo. As funções personalizadas usam apenas as seguintes mensagens de erro: #NULL!, #DIV/0!, #VALUE!, #REF!, #NAME?, #NUM!, #N/A e #BUSY!.

Geralmente, estes erros correspondem aos erros que você já deve estar familiarizado no Excel. Existem apenas algumas exceções específicas para funções personalizadas, listadas aqui:

• Um erro #NAME? geralmente significa que houve um problema ao registrar as suas funções. Para obter informações adicionais, consulte Funções personalizadas mostrando #NAME? erro.
• Um erro #N/A também pode ser um sinal de que esta função, embora registrada, não pode ser executada. Isto é normalmente devido à um comando CustomFunctions.associate em falta.
• Um #VALUE! erro normalmente indica um erro no arquivo de script das funções.
• Um erro #REF! pode indicar que o nome da sua função é o mesmo nome de uma função em um suplemento já existente.

Limpar o cache do Office

Informações sobre funções personalizadas são armazenadas em cache pelo Office. Às vezes, ao desenvolver e recarregar repetidamente um suplemento com funções personalizadas, as suas alterações podem não aparecer. Isso pode ser corrigido limpando o cache do Office. Para saber mais, confira Limpar o cache do Office.

Limpar o cache de funções personalizadas quando o suplemento for executado

Pode haver momentos em que você precise limpar o cache de funções personalizadas de um suplemento implantado para os usuários finais, para que as atualizações do suplemento e as alterações de configuração de funções personalizadas sejam incorporadas ao mesmo tempo. Sem disparar uma limpeza de cache de funções personalizadas, as alterações nos arquivos de functions.json e functions.js podem levar até 24 horas para chegar aos usuários finais, enquanto as alterações no taskpane.html chegam aos usuários finais mais rapidamente.

Para garantir que o cache de funções personalizadas seja limpo pelo suplemento, adicione o código a seguir ao arquivo functions.js e chame o setForceRefreshOn método em sua Office.onReady chamada ou outra lógica de inicialização do suplemento.

// To enable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOn` method in your `Office.onReady` call.
function setForceRefreshOn() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        true  
    );  
    Office.context.document.settings.saveAsync();  
}

Para desabilitar a limpeza de cache de funções personalizadas em seu suplemento, defina Office.ForceRefreshCustomFunctionsCache como false e chame o método em sua Office.onReady chamada. O exemplo de código a seguir mostra um exemplo com um setForceRefreshOff método.

// To disable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOff` method in your `Office.onReady` call.
function setForceRefreshOff() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        false  
    );  
    Office.context.document.settings.saveAsync();  
}

Problemas comuns e soluções

Funções personalizadas mostrando #NAME? de erro

Ao abrir uma pasta de trabalho que usa um suplemento de funções personalizadas, às vezes um #NAME? erro é exibido em células de função personalizadas em vez do resultado da fórmula. O IntelliSense para funções personalizadas também pode não aparecer na pasta de trabalho ao criar novas fórmulas. A causa provável desse problema é que o suplemento de funções personalizadas não foi registrado com êxito.

Para resolver o problema, tente as seguintes abordagens:

• Atualize o suplemento selecionando o ícone do suplemento. Selecione Suplementos Domésticos>,>Meus Suplementos e, em seguida, o ícone do suplemento.
• Siga as orientações para limpar automaticamente o cache do Office quando o Office for aberto e reinicie o Excel.

Não é possível abrir o suplemento do host local: use uma isenção de loopback local

Se você vir o erro "Não é possível abrir este suplemento do localhost", você precisará habilitar uma isenção de loopback local. Para obter detalhes sobre como fazer isso, confira este artigo de suporte da Microsoft.

Relatórios de log de tempo de execução "TypeError: Falha na solicitação de rede" no Excel para Windows

Se você ver o erro "TypeError: Falha na solicitação de rede" em seu log de tempo de execução enquanto faz chamadas para seu servidor localhost, você precisará habilitar uma exceção de loopback local. Para mais detalhes sobre como fazer isso, confira Opção #2 neste artigo de suporte da Microsoft .

Garantir que as promessas retornem resultados

Quando o Excel está aguardando a conclusão de uma função personalizada, ela é exibida #BUSY! na célula. Se o código da função personalizada retornar uma promessa, mas a promessa não retornar um resultado, o Excel continuará exibindo #BUSY!. Verifique suas funções para garantir que as promessas estejam retornando corretamente um resultado para uma célula.

Erro: O servidor de desenvolvimento já está em execução na porta 3000

Às vezes, ao executar npm start você poderá ver um erro que o servidor de desenvolvimento já está executando na porta 3000 (ou qualquer outra porta que o seu suplemento use). Você pode parar o servidor de desenvolvimento executando npm stop ou fechando a janela Node.js. Em alguns casos, pode levar alguns minutos para que o servidor de desenvolvimento pare de ser executado.

Minhas funções não carregam: associar funções

Nos casos em que seu JSON não tiver sido registrado e você tiver criado os seus próprios metadados JSON, talvez receba um #VALUE!erro ou receba uma notificação de que o seu suplemento não pode ser carregado. Geralmente, isso significa que você precisa associar cada função personalizada a idpropriedade especificada no arquivo de metadados JSON. Isso é feito usando a CustomFunctions.associate() função. Normalmente, essa chamada de função é feita após cada função ou no final do arquivo de script. Se uma função personalizada não estiver associada, ele não funcionará.

O exemplo a seguir mostra uma função add, seguida pelo nome add da função que está sendo associada a ADD da id JSON correspondente.

/**
 * Add two numbers.
 * @customfunction
 * @param {number} first First number.
 * @param {number} second Second number.
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

Para obter mais informações sobre esse processo, consulte Associar nomes de função a metadados JSON.

Problemas conhecidos

Os problemas conhecidos são rastreados e relatados no repositório GitHub de Funções Personalizadas do Excel.

Fornecer comentários

Se você tiver problemas que não estão descritos aqui, fale conosco. Há duas maneiras de relatar problemas.

No Excel no Windows ou no Mac

Se estiver usando o Excel no Windows ou no Mac, você poderá relatar comentários à equipe de extensibilidade do Office diretamente do Excel. Para fazer isso, selecione Arquivo>Comentário>Enviar um Rosto Triste. Enviando um Rosto Triste, você fornece os registros necessários para entendermos o problema que você está enfrentando.

No Github

Sinta-se à vontade para enviar problemas encontrados através do recurso "Comentários do conteúdo" na parte inferior de todas as páginas de documentação ou informe um novo problema diretamente no repositório de funções personalizadas.

Próximas etapas

Saiba como tornar as suas funções personalizadas compatíveis com as funções definidas pelo usuário de XLL.

Confira também

• Gerar metadados JSON automaticamente para funções personalizadas
• Criar funções personalizadas no Excel
• Depuração de funções personalizadas