Criar linhas de tabela usando o SDK para .NET

Este artigo inclui exemplos usando estilos de programação com vinculação tardia e com vinculação antecipada. Mais informações:

Criação básica

Os exemplos a seguir mostram como criar uma linha de tabela usando o estilo de programação com associação tardia e com vinculação antecipada.

Cada um dos exemplos usa uma svc variável que representa uma instância de uma classe que implementa os métodos na interface IOrganizationService. Para obter informações sobre as classes que dão suporte a essa interface, consulte IOrganizationService Interface.

Observação

Cada tabela tem uma coluna de chave primária de identificador exclusivo que você pode especificar ao criar uma linha. Na maioria dos casos, você deve permitir que o sistema defina isso para você porque os valores gerados pelo sistema são otimizados para melhor desempenho.

O Dataverse armazena dados de chave primária na telemetria para ajudar a manter o serviço. Se você especificar valores de chave primária personalizados, não use informações confidenciais nesses valores.

Com tabelas elásticas, você pode criar registros com valores de chave primária duplicados e valores partitionid diferentes. No entanto, esse padrão não é compatível com Power Apps de tela ou orientadas por modelo. Saiba mais sobre como definir o valor da chave primária com tabelas elásticas

O exemplo a seguir mostra como usar a classe Entity para criar uma conta usando o método IOrganizationService.Create.

//Use Entity class with entity logical name
var account = new Entity("account");

// set attribute values
    // string primary name
    account["name"] = "Contoso";
    // Boolean (Two option)
    account["creditonhold"] = false;
    // DateTime
    account["lastonholdtime"] = new DateTime(2017, 1, 1);
    // Double
    account["address1_latitude"] = 47.642311;
    account["address1_longitude"] = -122.136841;
    // Int
    account["numberofemployees"] = 500;
    // Money
    account["revenue"] = new Money(new decimal(5000000.00));
    // Picklist (Option set)
    account["accountcategorycode"] = new OptionSetValue(1); //Preferred customer

//Create the account
Guid accountid = svc.Create(account);

Usar a classe CreateRequest

Em vez de usar o método IOrganizationService.Create, você pode usar a classe Entity com limite tardio ou as classes de entidade geradas com o CreateRequest definindo a instância da entidade como a propriedade CreateRequest.Target e, em seguida, usando o método IOrganizationService.Execute para obter uma CreateResponse instância. O ID da linha da tabela de conta criada está no valor da propriedade CreateResponse.id.

var request = new CreateRequest() { Target = account };
var response  = (CreateResponse)svc.Execute(request);
Guid accountid = response.id;

Quando usar a classe CreateRequest

Você deve usar a classe CreateRequest se quiser passar parâmetros opcionais. Há dois casos em que você pode precisar de parâmetros especiais.

Usar a classe CreateMultipleRequest

Quando você precisa criar vários registros do mesmo tipo, a classe CreateMultipleRequest é a maneira mais performativa. Mais informações: Mensagens de Operação em Massa

Para tabelas padrão, ao criar uma nova linha de tabela, você também pode criar linhas relacionadas na mesma operação. Isso é chamado deep insert.

Os exemplos de associação tardia e de associação inicial a seguir criam um Account e um Contact relacionados a essa conta usando a relação um-para-muitos contact account_primary_contact, em que a pesquisa account primarycontactid é a ReferencingAttribute.

Os exemplos também criam três linhas relacionadas de Task usando a relação um-para-muitos account Account_Tasks, em que o campo de pesquisa task regardingobjectid é o ReferencingAttribute.

No estilo de associação tardia, você deve adicionar explicitamente uma ou mais entidades relacionadas (linhas) a uma EntityCollection e, em seguida, usar a classe Relationship para especificar a relação usando o/a SchemaName da relação antes de adicioná-las à propriedade Entity.RelatedEntities.

// Use Entity class with entity logical name
var account = new Entity("account");

// Set attribute values
    // string primary name
    account["name"] = "Sample Account";

// Create Primary contact
var primaryContact = new Entity("contact");
primaryContact["firstname"] = "John";
primaryContact["lastname"] = "Smith";

// Add the contact to an EntityCollection
EntityCollection primaryContactCollection = new EntityCollection();
primaryContactCollection.Entities.Add(primaryContact);

// Set the value to the relationship
account.RelatedEntities[new Relationship("account_primary_contact")] = primaryContactCollection;

// Add related tasks to create
var taskList = new List<Entity>() {
            new Entity("task") { ["subject"] = "Task 1" },
            new Entity("task") { ["subject"] = "Task 2" },
            new Entity("task") { ["subject"] = "Task 3" }
        };

// Add the tasks to an EntityCollection
EntityCollection tasks = new EntityCollection(taskList);

// Set the value to the relationship
account.RelatedEntities[new Relationship("Account_Tasks")] = tasks;

// Create the account
Guid accountid = svc.Create(account);

Associar linhas de tabela ao criar

Você pode associar qualquer nova linha a uma linha existente ao criá-la da mesma maneira que faria ao atualizá-la. Você deve usar um EntityReference para definir o valor de uma coluna de pesquisa relacional (atributo).

Essa atribuição de consulta é a mesma para estilos de vinculação antecipada e tardia.

//Use Entity class with entity logical name
var account = new Entity("account");

// set attribute values
    //string primary name
    account["name"] = "Sample Account";

Guid primarycontactid = new Guid("e6fa5509-2582-e811-a95e-000d3af40ae7");

account["primarycontactid"] = new EntityReference("contact", primarycontactid);

//Create the account
Guid accountid = svc.Create(account);

Usar chaves alternativas

Se você não souber a ID da linha da tabela e as seguintes condições forem verdadeiras:

  • Você configurou chaves alternativas para a tabela
  • Você conhece os valores-chave

Você pode usar os construtores alternativos EntityReference usando os parâmetros keyValue e keyName.

account["primarycontactid"] = new EntityReference("contact", "sample_username", "john.smith123");

Observação

As chaves alternativas geralmente são usadas apenas para cenários de integração de dados

Mais informações:

Verificar se há registros duplicados

Mais informações: detectar dados duplicados usando o SDK para .NET

Definir valores padrão com base na linha da tabela primária

Quando as pessoas criam novos registros no aplicativo, eles geralmente são criados no contexto de outro registro. Por exemplo, você pode criar um novo registro de contato no contexto de uma conta. Quando isso acontece, determinados valores de coluna da conta são copiados para o formulário de contato. Isso agiliza a criação da nova linha relacionada porque a nova linha tem alguns valores padrão definidos para que a pessoa que edita a linha a ser criada não precise inserir esses valores. Eles podem alterar os valores se quiserem antes de salvar.

Os valores que são copiados quando uma nova linha é criada dessa forma são controlados por configurações aplicadas ao ambiente Microsoft Dataverse, portanto, isso pode variar entre ambientes.

Mais informações:

Como desenvolvedor, você pode usar a classe InitializeFromRequest para gerar uma instância de entidade com valores padrão já definidos.

O código a seguir cria um novo contato associado a uma conta existente. O contato está associado à conta especificada e determinados valores de atributo, como Telephone1 e vários valores de endereço compartilhados entre a conta e o contato são definidos por padrão.

//The account that the contact will be associated with:
var parentAccount = new EntityReference("account", new Guid("a976763a-ba1c-e811-a954-000d3af451d6"));

// Initialize a new contact entity with default values from the account.
var request = new InitializeFromRequest()
{
    EntityMoniker = parentAccount,
    TargetEntityName = "contact"

};

var response = (InitializeFromResponse)svc.Execute(request);
//Get the Entity from the response
Entity contact = response.Entity;

// Set values that are not from the account
contact["firstname"] = "Joe";
contact["lastname"] = "Smith";

// Create the contact
Guid contactid = svc.Create(contact);

Usar Upsert

Outra maneira de criar uma linha de tabela é usando a classe UpsertRequest. Um upsert criará uma nova linha quando não houver nenhuma linha existente que tenha os identificadores exclusivos incluídos na linha passada com a solicitação.

Mais informações: Usar Upsert

Criar documentos em partições de armazenamento

Se você estiver criando um grande número de linhas de tabela elástica que contêm dados não relacionais, poderá criar as linhas em partições de armazenamento para acelerar o acesso a essas linhas. Mais informações: Particionamento e escalabilidade horizontal

Consulte também

Recuperar uma linha de tabela usando o SDK para .NET
Atualizar e excluir linhas de tabela usando o SDK para .NET
Associar e desassociar linhas de tabela usando o SDK para .NET