Criar atributos de numeração automática

Com a versão 9 do Dynamics 365 Customer Engagement (on-premises), você pode adicionar um atributo de numeração automática para qualquer entidade. Atualmente, você pode adicionar o atributo programaticamente. Não há interface do usuário para adicionar esse tipo de atributo. Este artigo explica como você pode criar programaticamente um atributo de numeração automática e definir um valor inicial para elementos sequenciais. Além disso, este artigo mostra como definir o número de sequência para o próximo registro se você precisar redefinir a semente a qualquer momento no futuro.

Você pode criar um atributo de numeração automática da mesma forma que cria um atributo de cadeia de caracteres usando a classe StringAttributeMetadata, exceto que você usa a nova propriedade AutoNumberFormat . Use a propriedade AutoNumberFormat para definir um padrão que inclua números seqüenciais e cadeias de caracteres aleatórias compondo espaços reservados, que indicam o comprimento e o tipo de valores gerados. As strings aleatórias ajudam a evitar duplicatas ou colisões, especialmente quando clientes offline tentam criar números automáticos.

Ao criar um atributo de numeração automática, a propriedade StringAttributeMetadata.FormatName ou os valores da propriedade StringAttributeMetadata.Format devem ser Text. Como esses são os valores padrão, você normalmente não definirá essa propriedade. Você não pode criar um atributo de numeração automática que use qualquer outro tipo especial de formato, como Email, Phone, TextArea, Url ou qualquer outro formato existente.

O sequenciamento de numeração automática é gerenciado pelo SQL e é garantido ser único.

No cliente Web herdado, ao adicionar um controle em um formulário associado a um atributo de numeração automática, o controle é desabilitado automaticamente e se comporta como somente leitura no formulário em que os usuários finais não podem editar o controle. Na Interface Unificada, os controles associados a um atributo de numeração automática precisam ser definidos explicitamente como desabilitados. Se você não definir o valor do atributo inicial no formulário, o valor será definido somente depois que você salvar a entidade. A numeração automática pode ser aplicada a valores de campo de atributo em exibições, grades e assim por diante.

Exemplos

Os exemplos a seguir mostram como criar um novo atributo de numeração automática chamado new_SerialNumber para uma entidade personalizada chamada new_Widget, que terá um valor semelhante a este: WID-00001-AB7LSFG-20170913070240. Usando o serviço da organização com assemblies do SDK CreateAttributeRequest e classes StringAttributeMetadata:

CreateAttributeRequest widgetSerialNumberAttributeRequest = new CreateAttributeRequest
            {
                EntityName = "newWidget",
                Attribute = new StringAttributeMetadata
                {
                    //Define the format of the attribute
                    AutoNumberFormat = "WID-{SEQNUM:5}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}",
                    LogicalName = "new_serialnumber",
                    SchemaName = "new_SerialNumber",
                    RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                    MaxLength = 100, // The MaxLength defined for the string attribute must be greater than the length of the AutoNumberFormat value, that is, it should be able to fit in the generated value.
                    DisplayName = new Label("Serial Number", 1033),
                    Description = new Label("Serial Number of the widget.", 1033)
                }
            };
            _serviceProxy.Execute(widgetSerialNumberAttributeRequest);

Usar a API Web

Você pode criar e atualizar definições de entidade usando a API Web.

Mais informações: Criar e atualizar definições de entidade usando a API Web > Criar atributos.

Solicitação

POST [Organization URI]/api/data/v9.1/EntityDefinitions(LogicalName='new_widget')/Attributes HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "AttributeType": "String",
 "AttributeTypeName": {
  "Value": "StringType"
 },
 "Description": {
  "@odata.type": "Microsoft.Dynamics.CRM.Label",
  "LocalizedLabels": [
   {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Serial Number of the widget.",
    "LanguageCode": 1033
   }
  ]
 },
 "DisplayName": {
  "@odata.type": "Microsoft.Dynamics.CRM.Label",
  "LocalizedLabels": [
   {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Serial Number",
    "LanguageCode": 1033
   }
  ]
 },
 "RequiredLevel": {
  "Value": "None",
  "CanBeChanged": true,
  "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
 },
 "SchemaName": "new_SerialNumber",
 "AutoNumberFormat": "WID-{SEQNUM:5}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}",
 "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
 "FormatName": {
  "Value": "Text"
 },
 "MaxLength": 100
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.1/EntityDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/Attributes(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

Opções de AutoNumberFormat

Estes exemplos mostram como você pode configurar a propriedade AutoNumberFormat para obter resultados diferentes:

Os espaços reservados da cadeia de caracteres aleatórios são opcionais. Você pode incluir mais de um espaço reservado de cadeias de caracteres aleatórias. Use qualquer um dos valores de formato para espaços reservados de data e hora de Cadeias de Caracteres de Formato de Data e Hora Padrão.

Tamanho da cadeia de caracteres

A tabela mostra o valor do comprimento da cadeia de caracteres para os espaços reservados aleatórios e sequenciais.

Para espaços reservados de valor sequencial, o MIN_LENGTH é um comprimento mínimo. Se você definir o valor como 2, o valor inicial será 01 e o valor da 100ª entidade será 100. O número continuará a aumentar além do comprimento mínimo. O valor na definição do comprimento para valores sequenciais é estabelecer um comprimento consistente para o valor gerado automaticamente adicionando 0s adicionais ao valor inicial. Não limitará o valor absoluto. Os placeholders de valores aleatórios sempre terão o mesmo tamanho.

Como os valores sequenciais podem ficar maiores do que o comprimento mínimo alocado para eles, você não deve ajustar a propriedade StringAttributeMetadata.MaxLength para corresponder ao comprimento do valor formatado. Há pouco valor em fazer isso e isso pode causar um erro no futuro se o valor exceder o valor MaxLength . Certifique-se de deixar espaço suficiente para um intervalo realista de valores sequenciais.

Atualizar atributos de numeração automática

Se criar um atributo de numeração automática com uma configuração incorreta ou quiser modificar um atributo de numeração automática existente, você poderá atualizar o atributo o valor AutoNumberFormat.

O snippet de código a seguir explica como recuperar, modificar e atualizar o atributo de numeração automática.

Para modificar um atributo de numeração automática existente, você deve recuperar o atributo usando a classe RetrieveAttributeRequest .

// Create the retrieve request
RetrieveAttributeRequest attributeRequest = new RetrieveAttributeRequest
            {
                EntityLogicalName = entityName.ToLower(),
                LogicalName = "new_serialnumber",
                RetrieveAsIfPublished = true
            };
// Retrieve attribute response
RetrieveAttributeResponse attributeResponse = (RetrieveAttributeResponse)_serviceProxy.Execute(attributeRequest);

Depois de recuperar o atributo de numeração automática, você precisa modificar e atualizar o atributo.

//Modify the retrieved auto-number attribute
AttributeMetadata retrievedAttributeMetadata = attributeResponse.AttributeMetadata;
retrievedAttributeMetadata.AutoNumberFormat = "CAR-{RANDSTRING:5}{SEQNUM:6}"; //Modify the existing attribute by writing the format as per your requirement 

// Update the auto-number attribute            
UpdateAttributeRequest updateRequest = new UpdateAttributeRequest
                        {
                            Attribute = retrievedAttributeMetadata,
                            EntityName = "newWidget",
                        };
// Execute the request
_serviceProxy.Execute(updateRequest);

Definir um valor gerador

Por padrão, todos os valores sequenciais de numeração automática começam com 1000 e usam 0 como prefixo, dependendo do comprimento. Dessa forma, o comprimento do valor é sempre o mesmo. Se você quiser alterar o valor inicial, precisará alterar o valor da semente inicial usando a API abaixo para definir os próximos números usados para o segmento sequencial.

Por exemplo, se você não usou um valor de semente ou se definiu o valor de semente como um único dígito, seu primeiro número seria um único dígito com um prefixo de zeros adicionado para igualar o comprimento do número. Uma semente de um único dígito com um comprimento de exibição de 5 resultaria na exibição de "5" como "00005". O uso de um valor de semente permite que você comece com um valor inicial maior, portanto, se você definir sua semente como "10000", um valor de 5 será exibido como "10005".

Se você quiser escolher um valor inicial diferente depois de criar o atributo de numeração automática, use a mensagem SetAutoNumberSeed . Use a classe SetAutoNumberSeedRequest ao usar os assemblies do SDK e a ação SetAutoNumberSeed ao usar a API Web.

A mensagem AutoNumberSeed tem os seguintes parâmetros:

Exemplos

Os exemplos a seguir definem a semente como 10000 para um atributo de numeração automática chamado new_SerialNumber para uma entidade personalizada chamada new_Widget.

Usando o serviço Organização com assemblies SDK da classe SetAutoNumberSeedRequest:

//Define the seed 
SetAutoNumberSeedRequest req = new SetAutoNumberSeedRequest();
req.EntityName = "newWidget";
req.AttributeName = "newSerialnumber";
req.Value = 10000;
_serviceProxy.Execute(req);

Usando a ação SetAutoNumberSeed da API Web.

Para mais informações: Uso de ações da API Web > Ações não associadas

Solicitação

POST [Organization URI]/api/data/v9.1/SetAutoNumberSeed HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "EntityName": "new_Widget",
 "AttributeName": "new_Serialnumber",
 "Value": 10000
} 

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0

Ferramentas da comunidade

Gerenciador de números automáticos

O Gerenciador Automático de Números para XrmToolBox é uma ferramenta orientada pela comunidade para o Dynamics 365 Customer Engagement (on-premises) que fornece uma interface do usuário para definir, atualizar e remover o formato de número automático em atributos novos ou existentes. Consulte o artigo Ferramentas do desenvolvedor para obter ferramentas desenvolvidas pela comunidade e anm.xrmtoolbox.com para obter mais informações sobre o Auto Number Manager.

Consulte Também

Metadados e modelos de dados
Personalizar metadados de atributo de entidade