As funções Error, IfError, IsError, IsBlankOrError
Aplica-se a:
Aplicativos de tela Colunas de fórmula do Dataverse Fluxos da área de trabalho Aplicativos baseados em modelo Power Platform CLI
Detecta erros e fornece um valor alternativo ou executa ação. Crie um erro personalizado ou passe um erro.
Nota
- O comportamento que este artigo descreve está disponível apenas quando a versão prévia do recurso Gerenciamento de erros no nível da fórmula em Configurações > Próximos recursos > Versão prévia está ativado.
IfError
A função IfError testa um ou mais valores até encontrar um resultado de erro. Se a função encontrar um erro, a função avaliará e retornará um valor de substituição correspondente e interromperá a avaliação. Um valor padrão também pode ser fornecido quando nenhum erro for encontrado. A estrutura de IfError é semelhantes à da função If: IfError testa a presença de erros, enquanto If testa para true.
Use IfError para substituir valores de erro por valores válidos, para que os cálculos de downstream possam continuar. Por exemplo, use essa função se a entrada do usuário puder resultar em uma divisão por zero:
IfError( 1/x, 0 )
A fórmula retornará 0 se o valor de x for zero, pois 1/x produzirá um erro. Se x for diferente de zero, 1/x será retornado.
Interrompendo o processamento adicional
Ao encadear fórmulas em fórmulas de comportamento, como:
Patch( DS1, ... );
Patch( DS2, ... )
A segunda função Patch para DS2 será executada mesmo se o Patch para DS1 falhar. O escopo de um erro é limitado a cada fórmula encadeada.
Use IfError para executar uma ação e somente continue o processamento se a ação tiver sido bem-sucedida. Como aplicar IfError a este exemplo:
IfError(
Patch( DS1, ... ), Notify( "problem in the first action" ),
Patch( DS2, ... ), Notify( "problem in the second action" )
)
Se o Patch do DS1 tiver um problema, a primeira Notificação será executada. Nenhum outro processamento é executado, incluindo o segundo Patch de DS2. Se o primeiro Patch obtiver êxito, o segundo Patch será executado.
Se fornecido, o argumento opcional DefaultResult será retornado se nenhum erro for descoberto. Sem esse argumento, o último argumento Valor será retornado.
Com base no último exemplo, o valor de retorno do IfError pode ser verificado para determinar se houve algum problema:
IfError(
Patch( DS1, ... ), Notify( "problem in the first action" ); false,
Patch( DS2, ... ), Notify( "problem in the second action" ); false,
true
)
Compatibilidade de tipo
IfError retornará o valor de um de seus argumentos. Os tipos de todos os valores que podem ser retornados por IfError devem ser compatíveis.
No último exemplo, Patch retornará um registro não compatível com os boolianos usados para as fórmulas Replacement ou DefaultResult. O que não é um problema, pois não há uma situação na qual o valor de retorno dessas chamadas de Patch seja retornado por IfError.
Nota
Enquanto o comportamento está em processo de alteração, os tipos de todos os argumentos para IfError devem ser compatíveis no momento.
No exemplo simples descrito anteriormente:
IfError( 1/x, 0 )
Os tipos de 1/x e 0 eram compatíveis pois ambos eram números. Caso contrário, o segundo argumento será imposto para corresponder ao tipo do primeiro argumento.
O Excel vai exibir #DIV/0! quando ocorre uma divisão por zero.
Considerar IfError com o seguinte:
IfError( 1/x, "#DIV/0!" )
A fórmula acima não funcionará. A cadeia de texto "#DIV/0!" será imposta para o tipo do primeiro argumento de IfError, que é um número. O resultado de IfError ainda será outro erro, pios a cadeia de texto não pode ser imposta. Como correção, converta o primeiro argumento em uma cadeia de texto, de forma que IfError sempre retorne uma cadeia de texto:
IfError( Text( 1/x ), "#DIV/0!" )
Conforme visto anteriormente, IfError pode retornar um erro se Replacement ou DefaultResult for um erro.
FirstError/AllErrors
Dentro das fórmulas de substituição, as informações sobre os erros encontrados estão disponíveis por meio do registro FirstError e da tabela AllErrors. AllErrors é uma tabela de registros de informações de erro com FirstError sendo um atalho para o primeiro registro desta tabela. FirstError sempre retornará o mesmo valor do que First( AllErrors ).
Os registros Error incluem:
| Campo | Tipo | Descrição |
|---|---|---|
| Kind | Enumeração ErrorKind (número) | Categoria do erro. |
| Message | Cadeia de caracteres de texto | Mensagem sobre o erro, apropriado para ser exibido para o usuário final. |
| Origem | Cadeia de caracteres de texto | Local de origem do erro, usado para relatórios. Por exemplo, para uma fórmula vinculada a uma propriedade de controle, isso estará no formato ControlName.PropertyName. |
| Observed | Cadeia de caracteres de texto | Location em que o erro é exibido ao usuário, usado para relatórios. Por exemplo, para uma fórmula vinculada a uma propriedade de controle, isso estará no formato ControlName.PropertyName. |
| Detalhes | Registro | Detalhes sobre o erro. Atualmente, os detalhes são fornecidos apenas para erros de rede. Este registro inclui HttpStatusCode, que contém o código de status HTTP e HttpResponse, que contém o corpo da resposta do conector ou serviço. |
Por exemplo, considere a seguinte fórmula como uma propriedade OnSelect do controle Button:
Set( a, 1/0 )
Adicione esta fórmula na propriedade OnSelect de um segundo controle Button:
IfError( a, Notify( "Internal error: originated on " & FirstError.Source & ", surfaced on " & FirstError.Observed ) )
A fórmula de exemplo acima exibe o seguinte banner quando os dois botões são ativados em sequência:
Normalmente, haverá apenas um erro que FirstError pode trabalhar suficientemente. No entanto, há cenários em que vários erros podem ser retornados. Por exemplo, ao usar um operador de encadeamento de fórmulas ou a função Concurrent. Mesmo nessas situações, relatar FirstError pode ser suficiente para revelar um problema em vez de sobrecarregar um usuário com vários erros. Se você ainda precisar trabalhar com cada erro individualmente, poderá usar a tabela AllErrors.
IsError
A função IsError testa um valor de erro.
O valor de retorno é um booliano true ou false.
Usar IsError impedirá qualquer processamento adicional do erro.
IsBlankOrError
A função IsBlankOrError testa um valor em branco ou um valor de erro e é o equivalente a Or( IsBlank( X ), IsError( X ) ).
Ao habilitar o tratamento de erros para aplicativos existentes, considere substituir IsBlank por IsBlankOrError para preservar o comportamento do aplicativo existente. Antes da adição de tratamento de erros, um valor em branco foi usado para representar valores nulos de bancos de dados e valores de erro. O tratamento de erros separa essas duas interpretações de em branco, o que pode mudar o comportamento de aplicativos existentes que continuam a usar IsBlank.
O valor de retorno é um booliano true ou false.
O uso de IsBlankOrError impedirá qualquer processamento posterior do erro.
Use a função Error para criar e relatar um erro personalizado. Por exemplo, você pode ter lógica para determinar se um determinado valor é válido para seu contexto ou não, algo não verificado para um problema automaticamente. Você pode criar e retornar seu próprio erro, completo com Kind e Message, usando o mesmo registro descrito acima para a função IfError.
No contexto de IfError, use a função Error para relançar ou passar por um erro. Por exemplo, sua lógica em IfError pode decidir que em alguns casos um erro pode ser ignorado com segurança, mas em outros casos é importante enviar o erro. Em IfError ou App.OnError, use Error( FirstError ) para passar um erro.
A função Error também pode receber uma tabela de erros, como seria encontrado na tabela AllErrors. Use Error( AllErrors ) para relançar todos os erros e não apenas o primeiro.
Um registro em branco ou uma tabela vazia passado para Error resulta em nenhum erro.
Sintaxe
Error( ErrorRecord )
Error( ErrorTable )
- ErrorRecord - obrigatório. Registro de informações de erro, incluindo Kind, Message e outros campos. Kind é obrigatório. FirstError pode ser passado diretamente.
- ErrorTable - obrigatório. Tabela de registros de informações de erro. AllErrors pode ser passado diretamente.
IfError( Value1, Replacement1 [, Value2, Replacement2, ... [, DefaultResult ] ] )
- Value(s) - obrigatório. Fórmulas para testar quanto a um valor de erro.
- Replacement(s) - obrigatório. As fórmulas a serem avaliadas e os valores a serem retornados se os argumentos Valor correspondentes retornarem um erro.
- DefaultResult - opcional. As fórmulas para avaliar se a fórmula não encontra erros.
IsError( Value )
IsBlankOrError( Value )
- Value - obrigatório. Fórmula para testar.
Exemplos
IfError simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| IfError( 1, 2 ) | O primeiro argumento não é um erro. A função não possui outros erros para verificar e nenhum valor de retorno padrão. A função retorna o último argumento de valor avaliado. | 1 |
| IfError( 1/0, 2 ) | O primeiro argumento retorna um valor de erro (por causa da divisão por zero). A função avalia o segundo argumento e o retorna como resultado. | 2 |
| IfError( 10, 20, 30 ) | O primeiro argumento não é um erro. A função não possui outros erros para verificar, mas possui um valor de retorno padrão. A função retorna o argumento DefaultResult. | 30 |
| IfError( 10, 11, 20, 21, 300 ) | O primeiro argumento 10 não é um erro, portanto, a função não avalia a substituição correspondente desse argumento 11. O terceiro argumento 20 também não é um erro, portanto, a função não avalia a substituição correspondente desse argumento 21. O quinto argumento 300 não tem substituição correspondente e é o resultado padrão. A função retorna esse resultado porque a fórmula não contém erros. | 300 |
| IfError( 1/0, Notify( "There was an internal problem" ) ) | O primeiro argumento retorna um valor de erro (devido à divisão por zero). A função avalia o segundo argumento e exibe uma mensagem ao usuário. O valor retornado de IfError é o valor retornado de Notify, forçado para o mesmo tipo do primeiro argumento de IfError (um número). | 1 |
IsError simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| IsError( 1 ) | O argumento não é um erro. | false |
| IsError( Blank() ) | O argumento é um espaço em branco, mas não é um erro. | false |
| IsError( 1/0 ) | O argumento é um erro. | true |
| If( IsError( 1/0 ), Notify( "There was an internal problem" ) ) | O argumento para IsError retorna um valor de erro (por causa da divisão por zero). Esta função retorna true, o que faz com que If exiba uma mensagem ao usuário com a função Notify. O valor retornado de If é o valor retornado de Notify, forçado para o mesmo tipo do primeiro argumento de If (um booliano). | true |
IsBlankOrError simples
| Fórmula | Descrição | Resultado |
|---|---|---|
| IsBlankOrError( 1 ) | O argumento não é um erro ou está em branco. | false |
| IsBlankOrError( Blank() ) | O argumento está em branco. | true |
| IsBlankOrError( 1/0 ) | O argumento é um erro. | true |
Erro simples
Neste exemplo, as datas são validadas uma em relação à outra, resultando em um erro se houver um problema.
If( StartDate > EndDate,
Error( { Kind: ErrorKind.Validation, Message: "Start Date must be before End Date" } ) )
Neste exemplo, alguns erros podem passar enquanto outros são suprimidos e substituídos por um valor. No primeiro caso, b estará em um estado de erro porque a função Value tem um argumento inválido. Como isso é inesperado pelo redator da fórmula, ele é passado para que o usuário o veja. No segundo caso, com a mesma fórmula, b terá o valor 0, resultando em uma divisão por zero. Nesse caso, o redator da fórmula pode saber que isso é aceitável para essa lógica, suprimir o erro (nenhuma faixa é exibida) e retornar -1.
With( {a: 1, b: Value("a")},
IfError( a/b, If( FirstError.Kind <> ErrorKind.Div0, Error( FirstError ), -1 ) ) )
// returns an error with Kind = ErrorKind.InvalidArgument
With( {a: 1, b: 0} )
IfError( a/b, If( FirstError.Kind <> ErrorKind.Div0, Error( FirstError ), -1 ) ) )
// returns -1
A tabela AllErrors pode ser filtrada como qualquer outra tabela. Usada com a função Error, os erros esperados podem ser removidos e os erros restantes retidos e relatados. Por exemplo, se soubéssemos que a divisão por zero não seria um problema em um contexto específico, esses erros poderiam ser filtrados, deixando todos os outros erros intactos com a seguinte fórmula:
Error( Filter( AllErrors, Kind <> ErrorKind.Div0 ) )
Passo a passo
Adicione um controle Text input e nomeie-o como TextInput1 se ele não tiver esse nome por padrão.
Adicione um controle Label e nomeie-o como Label1 se ele não tiver esse nome por padrão.
Defina a fórmula da propriedade Text de Label1 como:
IfError( Value( TextInput1.Text ), -1 )Em TextInput1, insira 1234.
Label1 mostrará o valor 1234 pois essa é uma entrada válida para a função Value.
Em TextInput1, insira ToInfinity.
Label1 mostrará o valor -1 pois essa não é uma entrada válida para a função Value. Sem encapsular a função Value com IfError, o rótulo não mostraria nenhum valor, pois o valor de erro é tratado como blank.