Gerar classes de associação antecipada para o SDK para .NET

Criando classes associadas antecipadamente para os projetos .NET:

  • Melhora a legibilidade e a manutenção do código.
  • Diminui o risco de erros porque elas oferecem verificação do tipo em tempo de compilação.
  • Melhora a produtividade do desenvolvedor porque os desenvolvedores podem descobrir tabelas, colunas e opções de escolha usando o IntelliSense.
  • Fornece a classe OrganizationServiceContext para que você possa escrever consultas do Dataverse usando LINQ e outros recursos que funcionam com dados.

Saiba mais:

Use o comando de criação pac modelbuilder da CLI do Power Platform para gerar classes de código de associação antecipada. Você também pode usar a CrmSvcUtil.exe ferramenta de geração de código, mas para o Dataverse é recomendável usar o pac modelbuilder build comando. Aprenda a usar o CrmSvcUtil.exe a fim de gerar classes associadas antecipadamente para o SDK para .NET

Como muitos comandos da CLI do Power Platform, pac modelbuilder build tem muitos parâmetros que você pode usar para controlar o resultado. Neste artigo, recomendamos que você comece usando o parâmetro --settingsTemplateFile para a maioria dos casos de uso. Use esse parâmetro para fazer referência a um arquivo JSON em que você pode controlar todas as outras configurações disponíveis. Dessa forma, você não precisa compor uma longa lista de parâmetros e pode atualizar a configuração apropriada para seu projeto para permitir a regeneração das classes quando precisar delas.

Você ainda pode usar o comando de build com parâmetros, se preferir. Consulte Usando parâmetros.

Introdução

Antes de começar:

  1. Instalar o Microsoft Power Platform CLI.
  2. Conecte-se ao seu ambiente usando comandos de autenticação pac da CLI do Power Platform.

Para começar, use as seguintes etapas:

  1. No seu projeto .NET, adicione uma referência a um pacote NuGet de um dos seguintes:

  2. Criar uma pasta chamada model.

  3. model Na pasta, adicione um builderSettings.json arquivo com as seguintes configurações:

    {
"emitentityetc-comment": "Generate a constants structure that contains all of the field names by entity at the time of code generation.",
"emitEntityETC": false,
"emitfieldsclasses-comment": "Generate a constants structure that contains all of the field names by entity at the time of code generation.",
"emitFieldsClasses": false,
"emitvirtualattributes-comment": "When set, includes the Virtual Attributes of entities in the generated code.",
"emitVirtualAttributes": false,
"entitynamesfilter-comment": "Filters the list of entities are retrieved when reading data from Dataverse.",
"entityNamesFilter": [
   "account",
   "contact"
],
"entitytypesfolder-comment": "Folder name that contains entities.",
"entityTypesFolder": "Entities",
"generateGlobalOptionSets-comment": "Emit all Global OptionSets. Note: If an entity contains a reference to a global optionset, it is emitted even if this switch is not present.",
"generateGlobalOptionSets": false,
"generatesdkmessages-comment": "When set, emits Sdk message classes as part of code generation",
"generateSdkMessages": true,
"language-comment": "The language to use for the generated proxy code. This value can be either 'CS' or 'VB'. The default language is 'CS'.",
"language": "CS",
"logLevel-comment": "Log level. The default value is 'Off'.",
"logLevel": "Off",
"messagenamesfilter-comment": "Filters the list of messages that are retrieved when reading data from Dataverse.",
"messageNamesFilter": [
   "searchautocomplete",
   "searchquery",
   "sample_*"
],
"messagestypesfolder-comment": "Folder name that contains messages.",
"messagesTypesFolder": "Messages",
"namespace-comment": "The namespace for the generated code.",
"namespace": "ExampleProject",
"optionsetstypesfolder-comment": "Folder name that contains option sets.",
"optionSetsTypesFolder": "OptionSets",
"serviceContextName-comment": "The name for the generated service context. If a value is passed in, it's used for the Service Context. If not, no Service Context is generated.",
"serviceContextName": "OrgContext",
"suppressGeneratedCodeAttribute-comment": "When set, this suppress all generated objects being tagged with the code generation engine and version",
"suppressGeneratedCodeAttribute": true,
"suppressINotifyPattern-comment": "When enabled, doesn't write the INotify wrappers for properties and classes.",
"suppressINotifyPattern": true
}

    Note

    Esse arquivo é uma versão modificada do arquivo que você pode gerar usando pac modelbuilder build com o --writesettingsTemplateFile parâmetro. Saiba como gerar o arquivo sem comentários em Usar parâmetros.

  4. Use o comando a seguir a fim de gerar classes de associação antecipada para o ambiente conectado usando as configurações definidas em builderSettings.json. O C:\projects\exampleproject\ caminho representa o caminho para seu projeto e model é a pasta que você criou.

    PS C:\projects\exampleproject\model> pac modelbuilder build -o . -stf .\builderSettings.json

    Este comando usa estes parâmetros:

    • atalho -o para o parâmetro --outdirectory necessário com um valor de ., para indicar o diretório atual.
    • -stf abreviação do parâmetro --settingsTemplateFile com o valor .\builderSettings.json, para indicar o diretório atual builderSettings.json.

    Você também pode usar esse comando no exampleproject diretório:

    PS C:\projects\exampleproject>pac modelbuilder build -o model -stf model\builderSettings.json

Entenda quais arquivos são gravados

Com qualquer um dos comandos, você recebe a seguinte saída:

Connected to... Your Organization
Connected as you@yourorganization.onmicrosoft.com
Begin reading metadata from MetadataProviderService
      Begin Reading Metadata from Server
      Read 2 Entities - 00:00:00.732
      Read 0 Global OptionSets - 00:00:00.000
      Read 12 SDK Messages - 00:00:00.889
      Completed Reading Metadata from Server - 00:00:01.694
Completed reading metadata from MetadataProviderService - 00:00:01.697
Begin Writing Code Files
      Processing 2 Entities
      Wrote 2 Entities - 00:00:00.0625873
      Processing 12 Messages
      Wrote 3 Message(s). Skipped 9 Message(s) - 00:00:00.0091589
      Processing 0 Global OptionSets
      Wrote 0 Global OptionSets - 00:00:00.0000045
      Code written to C:\projects\exampleproject\model\Entities\account.cs.
      Code written to C:\projects\exampleproject\model\Entities\contact.cs.
      Code written to C:\projects\exampleproject\model\Messages\searchquery.cs.
      Code written to C:\projects\exampleproject\model\Messages\searchautocomplete.cs.
      Code written to C:\projects\exampleproject\model\OrgContext.cs.
      Code written to C:\projects\exampleproject\model\EntityOptionSetEnum.cs.
Completed Writing Code Files - 00:00:00.116
Generation Complete - 00:00:01.815
PS C:\projects\exampleproject\model>

Ao inspecionar a saída, você verá que ela gera apenas classes para as tabelas especificadas por entityNamesFilter e apenas as mensagens especificadas em messageNamesFilter. Especifique quais tabelas (entidades) e mensagens você usa em seu projeto. Caso contrário, o comando gerará classes para todas as tabelas e mensagens.

Para messageNamesFilter, use * como um caractere curinga nesses valores. Esse filtro é útil quando as mensagens em sua solução compartilham um prefixo de personalização comum.

pac modelbuilder build grava os arquivos em pastas com nomes que você controla no arquivo de configurações:

  • As classes de entidade vão para a pasta especificada pela configuração entityTypesFolder .
  • As classes de mensagem vão para a pasta especificada pela configuração messagesTypesFolder .
  • A classe OrganizationServiceContext vai para um arquivo com o nome especificado pela serviceContextName configuração.
  • Todas as classes fazem parte do namespace definido na namespace configuração.

Note

Se você estiver gerando classes de mensagens, inclua sempre um nome para a serviceContextName configuração. Consulte Incluir serviceContextName ao gerar classes de mensagem.

É assim que os arquivos e pastas aparecem no Visual Studio:

Exemplo de saída do comando pac modelbuilder build no Visual Studio Explorer

Com esses arquivos gravados no projeto, agora está tudo pronto para usar classes associadas antecipadamente.

Se você quiser alterá-los, exclua os arquivos na model pasta diferente de builderSettings.json, altere as configurações builderSettings.jsone gere-os novamente.

Usando parâmetros

Você não precisa usar o arquivo de configurações builderSettings.json nem o parâmetro --settingsTemplateFile com pac modelbuilder build. Você pode invocar o comando usando parâmetros diretamente. Para obter documentação de referência e exemplos, consulte a documentação de referência do pac modelbuilder build.

Se você usar o builderSettings.json arquivo de configurações e o --settingsTemplateFile parâmetro, poderá usar parâmetros de linha de comando para substituir essas configurações.

Aqui está um exemplo que mostra como gerar arquivos usando as mesmas configurações do exemplo na seção Introdução usando parâmetros:

PS C:\>pac modelbuilder build `
   --outdirectory C:\projects\exampleproject\model `
   --entitynamesfilter 'account;contact' `
   --generatesdkmessages `
   --messagenamesfilter 'searchautocomplete;searchquery;sample_*' `
   --namespace ExampleProject `
   --serviceContextName OrgContext `
   --suppressGeneratedCodeAttribute `
   --suppressINotifyPattern `
   --writesettingsTemplateFile

Este exemplo não inclui todas as configurações porque usa as opções padrão. Se você usar o parâmetro --writesettingsTemplateFile para gerar um arquivo builderSettings.json, ele não incluirá os comentários do exemplo na seção Primeiros passos deste artigo. O exemplo que usa parâmetros grava o seguinte builderSettings.json arquivo na model pasta:

{
  "suppressINotifyPattern": true,
  "suppressGeneratedCodeAttribute": true,
  "language": "CS",
  "namespace": "ExampleProject",
  "serviceContextName": "OrgContext",
  "generateSdkMessages": true,
  "generateGlobalOptionSets": false,
  "emitFieldsClasses": false,
  "entityTypesFolder": "Entities",
  "messagesTypesFolder": "Messages",
  "optionSetsTypesFolder": "OptionSets",
  "entityNamesFilter": [
    "account",
    "contact"
  ],
  "messageNamesFilter": [
    "searchautocomplete",
    "searchquery",
    "sample_*"
  ],
  "emitEntityETC": false,
  "emitVirtualAttributes": false
}

Incluir serviceContextName ao gerar classes de mensagem

Se você estiver gerando classes de mensagem, inclua sempre um nome para o serviceContextName parâmetro para que uma classe OrganizationServiceContext seja gerada com seu código. Essa classe inclui uma propriedade importante para habilitar o uso de classes de mensagens geradas. Se você não incluir um OrganizationServiceContext, receberá o seguinte erro ao tentar usar as classes de mensagem geradas.

The formatter threw an exception while trying to deserialize the message: 
There was an error while trying to deserialize parameter http://schemas.microsoft.com/xrm/2011/Contracts/Services:request. 
The InnerException message was 'Error in line 1 position 700. Element 'http://schemas.microsoft.com/xrm/2011/Contracts/Services:request' contains data from a type that maps to the name 'http://schemas.microsoft.com/xrm/2011/new/:<your generated class name>'. 
The deserializer has no knowledge of any type that maps to this name. 
Consider changing the implementation of the ResolveName method on your DataContractResolver to return a non-null value for name '<your generated class name>' and namespace 'http://schemas.microsoft.com/xrm/2011/new/'.'.  
Please see InnerException for more details.

Site da comunidade

O Early Bound Generator V2 é um plug-in do XrmToolBox criado pela comunidade para fornecer uma interface de usuário que gera o arquivo builderSettings.json correto e executa o comando pac modelbuilder build para o usuário. Como a interface do usuário gera apenas o arquivo builderSettings.json e chama o comando pac modelbuilder build, você ainda pode executar o comando em um pipeline sem depender do XrmToolBox. O plug-in também oferece opções de configuração que o pac modelbuilder não oferece. Por exemplo, ele fornece a capacidade de controlar explicitamente a classe e a caixa de propriedade e a transliteração de caracteres específicas da linguagem. O Early Bound Generator V2 pode fazer isso por meio dos recursos de extensibilidade do pac modelbuilder.

Note

Microsoft não estende o suporte a ferramentas desenvolvidas pela comunidade. Se você tiver dúvidas sobre a ferramenta, entre em contato com o editor. Para obter mais informações, consulte XrmToolBox.

Para Dynamics 365 Customer Engagement on-premises

A CLI do Power Platform não está disponível para Dynamics 365 Customer Engagement local. Você precisa usar a ferramenta para geração de códigos CrmSvcUtil.exe a fim de gerar classes associadas antecipadamente. Aprenda a usar o CrmSvcUtil.exe a fim de gerar classes associadas antecipadamente para o SDK para .NET

Programação limitada tardia e limitada antecipada
Exemplo: operações de tabela com vinculação antecipada
Ferramentas e recursos para desenvolvedores
Ferramentas de desenvolvimento do Dataverse
Aprenda a usar o CrmSvcUtil.exe a fim de gerar classes associadas antecipadamente para o SDK para .NET

  • Última atualização em