Compartir a través de

Crear columnas de autonumeración

  • Artículo

Con Microsoft Dataverse, puede agregar una columna de autonumeración para cualquier tabla. Para crear columnas de autonumeración en Power Apps, consulte Columnas de autonumeración.

El artículo explica cómo puede crear mediante programación un atributo de autonumeración y establecer un valor de semilla para los elementos de la secuencia. Además, el artículo muestra cómo establecer el número de secuencia del registro siguiente si necesita restablecer el valor de semilla en cualquier momento más adelante.

Nota

El establecimiento de un valor de semilla es opcional. No es necesario llamar a la semilla si no es necesario volver a sembrar el valor.

Puede crear una columna de numeración automática del mismo modo que se crea una columna de cadena mediante la clase StringAttributeMetadata excepto que en este caso se usa la nueva propiedad AutoNumberFormat. Utilice AutoNumberFormat property para definir un modelo que incluya números secuenciales y cadenas aleatorias mediante la composición de marcadores de posición, que indica la longitud y el tipo de valores que se generan. Las cadenas aleatorias le ayudan a evitar duplicados o colisiones, en especial cuando los clientes sin conexión intentan crear números automáticamente.

Cuando crea una columna de numeración automática, los valores de la propiedad FormatName o Property deben ser Text. Puesto que valores son los valores predeterminados, normalmente no será necesario definir esta propiedad. No puede crear una columna de autonumeración que use cualquier otro tipo de formato especial como Email, Phone, TextArea, Url o cualquier otro formato existente.

SQL genera el segmento secuencial que garantiza la unicidad.

Nota

Puede modificar una columna de texto de formato existente para que sea un formato de autonumeración.

En aplicaciones basadas en modelos que usan interfaz unificada, los controles vinculados a una columna de numeración automática deben configurarse explícitamente como deshabilitados. Si no establece el valor de la columna inicial en el formulario, el valor se establece solo después de guardar la tabla. La numeración automática se puede aplicar a valores de columna en vistas, cuadrículas, etc.

Ejemplos

Los siguientes ejemplos muestran cómo crear una nueva columna de autonumeración llamada new_SerialNumber para una tabla personalizada llamada new_Widget que tendrá un valor parecido al siguiente: WID-00001-AB7LSFG-20170913070240 usando la API Web y el SDK de Dataverse para .NET.

Puede crear y actualizar definiciones de tabla mediante la API web. Más información: Crear y actualizar definiciones de tabla mediante la API web.

Solicitud:

POST [Organization URI]/api/data/v9.0/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
}

Respuesta:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/EntityDefinitions(402fa40f-287c-e511-80d2-00155d2a68d2)/Attributes(f01bef16-287c-e511-80d2-00155d2a68d2)

Nota

Los valores de autonumeración son preseleccionados por la base de datos al iniciar el registro. Si se inicia un registro pero se cancela, el número que se asignó no se usa. Si, durante este tiempo, otro registro se completa con el número secuencial siguiente, los huecos estarán presentes en la numeración automática de registros.

Opciones de AutoNumberFormat

Estos ejemplos muestran cómo puede configurar la propiedad AutoNumberFormat para obtener resultados diferentes:

Valor de AutoNumberFormat Valor de ejemplo
CAR-{SEQNUM:3}-{RANDSTRING:6} CAR-123-AB7LSF
CNR-{RANDSTRING:4}-{SEQNUM:4} CNR-WXYZ-1000
{SEQNUM:6}-#-{RANDSTRING:3} 123456-#-R3V
KA-{SEQNUM:4} KA-0001
{SEQNUM:10} 1234567890
QUO-{SEQNUM:3}#{RANDSTRING:3}#{RANDSTRING:5} QUO-123#ABC#PQ2ST
QUO-{SEQNUM:7}{RANDSTRING:5} QUO-0001000P9G3R
CAS-{SEQNUM:6}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss} CAS-002000-S1P0H0-20170913091544
CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMMddhh}-{RANDSTRING:6} CAS-002002-2017091309-HTZOUR
CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMM}-{RANDSTRING:6}-{DATETIMEUTC:hhmmss} CAS-002000-201709-Z8M2Z6-110901

Los marcadores de posición de cadena aleatoria son opcionales. Puede incluir más de un marcador de posición de cadena aleatorio. Utilice cualquiera de los valores de formato de marcadores de posición de datetime de Cadenas con formato de fecha y hora estándar.

Longitud de cadena

En la tabla se muestra el valor de la longitud de cadena para los marcadores de posición aleatorios y secuenciales.

Marcador de posición Longitud de cadena Escenario de salida
{RANDSTRING:MIN_LENGTH} El valor de MIN_LENGTH está entre 1 y 6. Cuando se guarda la fila, la columna de autonumeración genera la cadena aleatoria con la longitud definida si el valor está entre 1 y 6. Si usa un MIN_LENGTH value de 7 o más, obtendrá un error de argumento no válido.
{SEQNUM:MIN_LENGTH} El valor mínimo de MIN_LENGTH es 1. El número sigue aumentando más allá de la longitud mínima. Cuando se guarda la fila, la columna de autonumeración funciona bien y sigue funcionando correctamente para valores mayores de MIN_LENGTH.

Para marcadores de posición de valores secuenciales, MIN_LENGTH es una longitud mínima. Si establece el valor en 2, el valor inicial será 01 y el valor de la fila número 100 será 100. El número sigue aumentando más allá de la longitud mínima. El valor en la configuración de la longitud de los valores secuenciales sirve para establecer una longitud coherente para el valor generado automáticamente agregando ceros adicionales al valor inicial. Esto no limitará el valor absoluto. Los marcadores de posición de valores aleatorios siempre serán la misma longitud.

Como los valores secuenciales pueden ser mayores que la longitud mínima asignada, no debería ajustar la propiedad StringAttributeMetadata.MaxLength para que coincida con la longitud del valor con formato. Establecer esta propiedad tiene poco valor porque podría producir un error en el futuro si el valor supera el valor de MaxLength. Asegúrese de que queda suficiente espacio para un intervalo realista de valores de la secuencia.

Nota

No se necesita ninguna validación de los valores de marcador de al crear la columna. El error aparece solo cuando intenta guardar una tabla que utiliza un AutoNumberFormat value configurado incorrectamente. Por ejemplo, si especifica la longitud de la cadena aleatoria como mayor de 6, la primera persona en crear una nueva instancia de tabla obtendrá un error Argumento no válido al intentar guardar por primera vez la tabla que contiene la nueva columna de numeración automática.

Actualizar columnas de autonumeración

Si crea una columna de autonumeración con una configuración incorrecta o desea modificar una columna de autonumeración existente, puede actualizar en la columna el AutoNumberFormat value.

El siguiente fragmento de código explica cómo recuperar, modificar y actualizar la columna de autonumeración usando el SDK para .NET:

Para modificar una columna de numeración automática existente, debe recuperar la columna mediante la clase RetrieveAttributeRequest.

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

Después de recuperar la columna de autonumeración, debe modificar y actualizar la columna.

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

// Update the autonumber column            
var updateRequest = new UpdateAttributeRequest
  {
    Attribute = retrievedAttributeMetadata,
    EntityName = "newWidget",
  };
// Execute the request
_serviceProxy.Execute(updateRequest);

Establecer un valor de semilla

De forma predeterminada, todos los valores de la secuencia de numeración automática comienzan con 1000 y utilizan 0 como prefijo según la longitud. De este modo, la longitud del valor siempre es el misma. Si desea cambiar el valor inicial, debe cambiar el valor de semilla inicial mediante el mensaje SetAutoNumberSeed para establecer el número siguiente que se usará para el segmento de la secuencia.

Por ejemplo, cuando la longitud del número de secuencia es 5, es posible que desee comenzar con un valor inicial de 10 000 en lugar del valor predeterminado de 00001. Si desea elegir un valor inicial diferente después de crear la columna de autonumeración, utilice el mensaje SetAutoNumberSeed. Utilice la clase SetAutoNumberSeedRequest cuando use los ensamblados de SDK y la acción SetAutoNumberSeed cuando use la API de web.

El mensaje AutoNumberSeed tiene los siguientes parámetros:

Nombre Tipo Descripción
EntityName cadena El nombre lógico de la tabla que contiene la columna en el que desea establecer el valor de semilla.
AttributeName cadena El nombre lógico de la columna en la que desea establecer el valor de semilla.
Value entero Siguiente valor de autonumeración para la columna.

Nota

Establecer el valor de inicialización solo cambia el valor numérico actual para la columna especificada en el entorno actual. No implica un valor de inicio común para la columna. El valor de inicialización no se incluye en una solución cuando se instala en diferentes entornos. Para establecer el número de inicio después de una importación de solución, use el mensaje SetAutoNumberSeed en el entorno de destino.

Ejemplos de SetAutoNumberSeed

Los siguientes ejemplos establecen el valor de semilla en 10000 para una columna de autonumeración llamada new_SerialNumber para una tabla personalizada llamada new_Widget.

Con la API web SetAutoNumberSeed Action.

Solicitud:

POST [Organization URI]/api/data/v9.0/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
}

Respuesta:

HTTP/1.1 204 No Content
OData-Version: 4.0

Más información: Use las acciones de API de web > Acciones sin enlazar

Herramientas de la Comunidad

Administrador de número automático

Administrador de numeración automática para XrmToolBox es una herramienta impulsada por la comunidad para Dataverse que proporciona una interfaz de usuario para configurar, actualizar y quitar el formato de numeración automática en columnas nuevas y existentes.

Consulte el artículo Herramientas del desarrollador para ver las herramientas desarrolladas por la comunidad y anm.xrmtoolbox.com para obtener más información sobre Auto Number Manager.

Nota

Las herramientas de la comunidad no son un producto de Dataverse y no se incluyen en el soporte técnico. Si tiene alguna duda relacionada con la herramienta, póngase en contacto con el Editor. Más información: XrmToolBox.

Consulte también

Trabajar con definiciones de tabla mediante código
Personalizar definiciones de tablas

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).