Introdução à condução de operações globais com o objeto Xrm da API do cliente

  • 8 minutos

A API do Cliente fornece o objeto Xrm, que está disponível globalmente em seu código, habilitando várias atividades sem depender do contexto de execução. Em alto nível, o diagrama a seguir ilustra cada uma das propriedades e métodos disponíveis. Para obter uma visão detalhada desse objeto, veja Objeto Xrm da API do Cliente.

Captura de tela dos namespaces do modelo de objeto da API de script de cliente, Xrm, App, device, Encoding, Navigation, Panel, Utility, WebAPI.

Objeto Aplicativo

Usando addGlobalNotification por meio do objeto Aplicativo, você pode exibir notificações de erro, informações, avisos ou êxito para um aplicativo e especificar ações a serem executadas com base na notificação. Essa notificação é semelhante às notificações de formulário, mas você pode usá-la fora do contexto de um formulário. Por exemplo, um script de barra de comando pode notificar um usuário sobre uma ação concluída. Use o método clearGlobalNotification para limpar uma notificação no aplicativo.

Objeto Dispositivo

O objeto Xrm.Device expõe recursos nativos de dispositivo relacionados a interações de dispositivo móvel, com exceção do método pickFile, que também pode ser acessado por clientes Web. Os aplicativos de tela também fornecem uma estrutura extensível para desenvolvimento móvel e devem ser considerados nesses cenários. A tabela a seguir é um resumo dos métodos disponíveis no objeto Xrm.Device.

Método Descrição
captureAudio Invoca o microfone do dispositivo para gravar o áudio.
captureImage Invoca a câmera do dispositivo para capturar uma imagem.
captureVideo Invoca a câmera do dispositivo para gravar um vídeo.
getBarcodeValue Invoca a câmera do dispositivo para ler as informações de código de barras, como um número de produto.
getCurrentPosition Retorna o local atual usando o recurso de geolocalização do dispositivo.
pickFile Abre uma caixa de diálogo para selecionar arquivos do seu computador (cliente Web) ou dispositivo móvel (clientes móveis).

Dependendo da configuração do dispositivo, algumas funcionalidades não estarão disponíveis. O consentimento do usuário também pode ser necessário para que o aplicativo acesse recursos específicos do dispositivo. Por exemplo, o usuário pode ter desabilitado globalmente os recursos de localização do dispositivo ou recusado o acesso à câmera do aplicativo. Ao desenvolver um aplicativo, tenha cuidado, pois esses métodos podem falhar devido aos recursos, à configuração, à falta de permissões ou ao consentimento do dispositivo.

Objeto Codificação

Você pode usar o objeto Xrm.Encoding para codificar e decodificar strings XML e HTML. Essa codificação e decodificação poderão ser valiosas ao:

  • Interagir com recursos da Web HTML,

  • Codificar e decodificar parâmetros de cadeia de caracteres de consulta,

  • Interagir com FetchXML que contém caracteres especiais como '&' ou '<' em uma cadeia de pesquisa.

O objeto Navigation fornece métodos relacionados à navegação que você pode usar em um aplicativo baseado em modelo. Devido a sua natureza de bloqueio, atividades como mostrar caixas de diálogo de alerta, confirmação e erro não são consideradas uma experiência de usuário ideal, mas ainda estão disponíveis. Nesses cenários, recomendamos considerar notificações de formulário ou outros mecanismos sem bloqueio para alertar os usuários sobre um problema. Aqui está um resumo dos métodos disponíveis no objeto Xrm.Navigation.

Método Descrição
openAlertDialog Exibe uma caixa de diálogo de alerta com uma mensagem e um botão.
openConfirmDialog Exibe uma caixa de diálogo de confirmação com uma mensagem e dois botões.
openErrorDialog Exibe uma caixa de diálogo de erro.
openFile Abre um arquivo.
openForm Abre um formulário de tabela ou um formulário de criação rápida.
openUrl Abre uma URL, incluindo URLs de arquivo.
openWebResource Abre um recurso da Web HTML.

Objeto de painel

O objeto Xrm.Panel fornece um método para exibir uma página da Web no painel lateral de um formulário de aplicativo baseado em modelo. Esse recurso está atualmente em versão preliminar e não será abordado em detalhes aqui. Para obter mais informações, veja Xrm.Panel.

Objeto Utilitário

O objeto Xrm.Utility é um contêiner para vários métodos úteis. A tabela a seguir apresenta um resumo dos métodos disponíveis no objeto Xrm.Utility. Para obter mais informações, veja Xrm.Utility (referência da API do Cliente)

Método Descrição
closeProgressIndicator O indicador fecha uma caixa de diálogo de progresso que foi aberta usando showProgressIndicator.
getAllowedStatusTransitions Retorna as transições de estado válidas para a tabela e o código de estado especificados.
getEntityMetadata Retorna os metadados da entidade especificada.
getGlobalContext Recupera o contexto global, fornecendo informações de runtime, como configurações da organização, configurações do usuário, detalhes do aplicativo e informações do cliente.
getLearningPathAttributeName Retorna o nome do atributo DOM que é esperado pelo designer de conteúdo do roteiro de aprendizagem (ajuda guiada) para identificar controles da interface do usuário nos formulários de aplicativos baseados em modelo.
getResourceString Retorna a cadeia de caracteres localizada para determinada chave associada ao recurso da Web especificado.
invokeProcessAction Invoca uma ação com base nos parâmetros especificados. Este método também pode ser usado para invocar APIs personalizadas criadas por seus desenvolvedores.
lookupObjects Abre um controle de pesquisa para selecionar um ou mais itens.
refreshParentGrid Atualiza a grade pai que contém o registro especificado.
showProgressIndicator Exibe uma caixa de diálogo de progresso com a mensagem especificada.

Também existem vários métodos que não estão listados aqui, mas que você pode encontrar em um código mais antigo, que foram preteridos porque foram transferidos para o namespace Xrm.Navigation. Se você encontrar esses métodos, deverá atualizar o código para usar os novos métodos Xrm.Navigation.

Objeto Xrm.WebApi

O objeto Xrm.WebApi fornece propriedades e métodos para usar a API Web em operações CRUD tradicionais em um script de cliente. Quando você usa Xrm.WebAPI em seu script, as operações são executadas automaticamente no contexto do usuário do aplicativo atual. Você pode usar a API Web quando o aplicativo estiver online e offline (se você configurar o ambiente para offline). O namespace inclui um conjunto específico de métodos online e offline; entretanto, o uso desses métodos requer o acompanhamento do estado do cliente. Se você usar Xrm.WebAPI, Xrm.WebAPI.createRecord, a API determinará se deve usar os métodos de namespace online ou offline.

A tabela a seguir apresenta um resumo dos métodos disponíveis no objeto Xrm.WebApi. Para obter mais informações, veja Xrm.WebApi (referência da API do Cliente).

Método Descrição
createRecord Cria uma linha de tabela.
deleteRecord Exclui uma linha de tabela usando a ID da linha.
retrieveRecord Recupera uma linha usando sua ID.
retrieveMultipleRecords Recupera uma coleção de linhas de tabela que correspondem às opções de consulta ou ao FetchXML fornecido.
updateRecord Atualiza uma linha de tabela.
isAvailableOffline Retorna um valor booliano que indica se uma tabela está presente no perfil de um usuário e disponível no modo offline.
execute Executa uma única ação, função ou operação CRUD.
executeMultiple Executa uma coleção de ações, funções ou operações CRUD.

Usando propriedades e métodos do objeto Xrm, você pode automatizar os processos empresariais e melhorar a experiência geral do usuário.