Use estos mensajes con el SDK para .NET

  • Artículo

Es importante comprender que todas las operaciones de datos en Dataverse se definen como mensajes y las definiciones de estos mensajes se almacenan en Dataverse.

Cada mensaje tiene:

  • Un nombre único
  • Una colección de parámetros de entrada
  • Una colección de parámetros de salida

Hay tres formas diferentes de usar un mensaje con el SDK para .NET, como se explica en las siguientes secciones:

método Descripción
Clases OrganizationRequest y OrganizationResponse Utilice estas clases cuando no tenga clases de solicitud y respuesta de SDK. Es posible que prefiera utilizar este enfoque en lugar de generar clases de solicitud y respuesta SDK cuando conoce el nombre del mensaje y los detalles de los parámetros de entrada y salida.
Clases de solicitud y respuesta SDK El uso de estas clases es la forma más común de usar los mensajes. Muchos mensajes ya tienen clases definidas en el SDK para .NET. Para las acciones personalizadas, puede generar clases.
Métodos de IOrganizationService El IOrganizationService proporciona algunos métodos para operaciones de datos comunes. Estos métodos son las formas más rápidas y fáciles de realizar las operaciones de datos más comunes.

Clases OrganizationRequest y OrganizationResponse

Nota

El uso de las clases OrganizationRequest t OrganizationResponse no es la forma más común de usar los mensajes en Dataverse. Sin embargo, estas clases demuestran cómo se implementan los mensajes. Comprender esto es importante para entender cómo funcionan otras partes de Dataverse.

Puede usar un mensaje sin clases de solicitud y respuesta de SDK.

  1. Usar la clase OrganizationRequest.

  2. Envíe la solicitud mediante el método IOrganizationService.Execute, que devuelve una instancia OrganizationResponse.

    Los elementos de la colección OrganizationResponse.Results contienen los resultados.

Por ejemplo, si desea crear un registro de cuenta, puede hacerlo de esta manera:

public static Guid OrganizationRequestExample(IOrganizationService service) {

   // Instantiate an Entity instance of type 'account'
    var account = new Entity("account");
    account["name"] = "Test account";

   // Instantiate a collection of parameters with one item 'Target',
   // set to the account entity instance
    ParameterCollection parameters = new ParameterCollection
    {
        { "Target", account }
    };

   // Instantiate an OrganizationRequest instance setting the
   // RequestName and Parameters
    OrganizationRequest request = new OrganizationRequest()
    {
        RequestName = "Create",
        Parameters = parameters
    };

   // Send the request using the IOrganizationService.Execute method
    OrganizationResponse response = service.Execute(request);

   // Parse the output parameter 'id' from the Results
    return (Guid)response.Results["id"];
}

Para crear un registro de cuenta usando este método, necesita saber:

  • El nombre del mensaje: Create.
  • El nombre y el tipo de datos de cada parámetro de entrada: un único parámetro denominado Target que es una Entidad.
  • El nombre y el tipo de datos de cada parámetro de salida: un único parámetro denominado id que es una Guid.

Esta información se almacena en Dataverse. La tabla SdkMessage contiene información sobre todos los mensajes.

Dataverse gestiona información sobre los parámetros de entrada y salida en tablas privadas. No necesita recuperarlo porque hay una manera más fácil: usar las clases de solicitud y respuesta del SDK.

Clases de solicitud y respuesta SDK

Las clases de solicitud y respuesta del SDK reducen la complejidad del uso de las clases OrganizationRequest y OrganizationResponse. No necesitas saber el nombre del mensaje y los parámetros de entrada y salida porque las clases los tienen incluidos.

El SDK para .NET contiene definiciones para mensajes comunes Dataverse en estos espacios de nombres:

Espacio de nombres Descripción
Microsoft.Xrm.Sdk.Messages Mensajes para operaciones de datos comunes y mensajes utilizados para crear y modificar datos de esquema, también conocidos como metadatos.
Microsoft.Crm.Sdk.Messages Mensajes para lógica de negocios y operaciones para admitir capacidades especiales para admitir ALM y aplicaciones. Algunos mensajes en este espacio de nombres admiten capacidades que solo se encuentran en Microsoft Dynamics 365 Business Applications.

Estas clases contienen propiedades para todos los parámetros de entrada y salida.

  • Las clases que terminan en *Request contienen las propiedades de los parámetros de entrada.

    Estas clases heredan de la clase OrganizationRequest.

  • Las clases que terminan en *Response contienen las propiedades de los parámetros de salida.

    Estas clases heredan de la clase OrganizationResponse.

Por ejemplo, para crear un registro, puede usar la clase Microsoft.Xrm.Sdk.Messages.CreateRequest para preparar la solicitud. Use IOrganizationService.Execute para enviar la solicitud y los resultados tendrán la forma de una instancia de clase Microsoft.Xrm.Sdk.Messages.CreateResponse.

El siguiente ejemplo usa la clase Microsoft.Xrm.Sdk.Messages.CreateRequest con una clase de enlace anticipado generada para la entidad de cuenta:

public static Guid CreateRequestExample(IOrganizationService service)
{
    // Instantiate an Account using generated early-bound class
    var account = new Account
    {
        Name = "Test account"
    };

    // Instantiate a CreateRequest
    var request = new CreateRequest
    {
        // Set the Target property
        Target = account
    };

    // Send the request using the IOrganizationService.Execute method
    // Cast the OrganizationResponse into a CreateResponse
    var response = (CreateResponse)service.Execute(request);

    // Return the id property value
    return response.id;
}

Generar clases para las acciones personalizadas

Hay otros mensajes que no tienen clases en el SDK. Por ejemplo, las soluciones que se instalan con frecuencia incluyen nuevas definiciones de mensajes definidas como acciones personalizadas (API personalizada o acciones de proceso personalizadas). Más información: Crear sus propios mensajes

Los desarrolladores pueden generar clases de solicitud y respuesta para los mensajes que se encuentran en su entorno utilizando las siguientes herramientas:

Herramienta Descripción
Power Platform CLI
pac modelbuilder build
comando		 Genera clases .NET (Core) multiplataforma para aplicaciones que usan Microsoft.PowerPlatform.Dataverse.Client.ServiceClient.
Utilice el parámetro --generateActions para generar clases de solicitud y respuesta.
Comando de Power Platform CLI pac modelbuilder build Genera clases de .NET Framework para admitir aplicaciones que usan .NET Framework, como complementos Dataverse.

Más información: Generar clases de enlace en tiempo de compilación para el SDK para .NET

Pasar parámetros opcionales con una solicitud

Hay varios parámetros opcionales que puede pasar para aplicar comportamientos especiales a los mensajes. No puede usar los métodos IOrganizationService cuando usa parámetros opcionales. Debe utilizar las clases de solicitud SDK o la clase OrganizationRequest.

Más información: Usar parámetros opcionales

Métodos de IOrganizationService

Además de IOrganizationService.Execute método, el Interfaz IOrganizationService especifica que también se deben implementar los siguientes métodos. Estos métodos encapsulan las clases de Solicitud y Respuesta correspondientes:

método Clases de solicitud y respuesta
Create CreateRequest / CreateResponse
Retrieve RetrieveRequest / RetrieveResponse
RetrieveMultiple RetrieveMultipleRequest / RetrieveMultipleResponse
Update UpdateRequest / UpdateResponse
Delete DeleteRequest / DeleteResponse
Associate AssociateRequest / AssociateResponse
Disassociate DisassociateRequest / DisassociateResponse

Estos métodos simplifican la realización de estas operaciones con menos líneas de código. El siguiente ejemplo usa el método IOrganizationService.Create para crear un registro de cuenta:

public static Guid CreateMethodExample(IOrganizationService service)
{
   // Instantiate an Account using generated early-bound class
    var account = new Account
    {
        Name = "Test account"
    };

    // Use the Create method to get the id of the created account.
    return service.Create(account);
}

Como puede ver, las operaciones de datos comunes se han agilizado usando los métodos IOrganizationService y otros mensajes son más fáciles de usar con las clases Solicitud y Respuesta en los ensamblados del SDK o generados con las herramientas. La mayoría de las veces no necesita usar las clases subyacentes OrganizationRequest y OrganizationResponse, pero es importante comprender las diferentes opciones disponibles para usar mensajes, especialmente cuando se trabaja con complementos y API personalizados.

Trabajar con mensajes en complementos

Los datos que describen una operación en un complemento tienen la forma de IExecutionContext.InputParameters y IExecutionContext.OutputParameters.

En las etapas PreValidation y PreOperation antes de la operación main de la canalización de eventos, IExecutionContext.InputParameters contiene OrganizationRequest.Parameters.

Con una API personalizada, su complemento leerá IExecutionContext.InputParameters y contiene lógica para establecer IExecutionContext.OutputParameters como parte de la etapa de operación main.

Después de la etapa de operación main, en el escenario PostOperation, IExecutionContext.OutputParameters contiene OrganizationResponse.Results.

Conocer la estructura de los mensajes ayuda a comprender dónde encontrar los datos que desea comprobar o cambiar en el complemento.

Más información:

Mensajes privados

Microsoft Dataverse contiene algunos mensajes que no están pensados para que las utilicen desarrolladores de terceros. Microsoft agrega estos mensajes para habilitar la funcionalidad de la característica, pero también pueden agregarlos soluciones de terceros con la característica API personalizada. Los mensajes privados se indican mediante la propiedad SdkMessage.IsPrivate.

Precaución

No debe utilizar mensajes privados a menos que los haya creado como una API personalizada. Al marcar un mensaje como privado, el editor de soluciones está diciendo explícitamente que no son compatibles con otras aplicaciones para usar el mensaje. Pueden quitar el mensaje o introducir cambios importantes en cualquier momento. No se admite el uso de estos mensajes por nadie que no sea editor de soluciones. No se admite la llamada a mensajes privados desde complementos.

Más información: Crear y usar API personalizadas

Soporte de tabla para mensajes

Algunos mensajes se pueden utilizar con varias tablas. Por ejemplo, los mensajes Create, Update, y Delete se pueden usar para la mayoría de las tablas, pero es posible que algunas tablas no admitan todos los mensajes comunes.

Esta información se almacena en la Tabla SdkMessageFilter. Puede consultar esta tabla para determinar si puede usar un mensaje para una tabla.

Utilice este método estático para obtener una lista de nombres de mensajes que pueden funcionar con una tabla:

/// <summary>
/// Write the names of messages for a table to the console
/// </summary>
/// <param name="service">The authenticated IOrganizationService to use</param>
/// <param name="tableName">The logical name of the table</param>
static void OutputTableMessageNames(IOrganizationService service, string tableName)
{
    var query = new QueryExpression(entityName: "sdkmessagefilter")
    {
        Criteria =
        {
            Conditions =
            {
                new ConditionExpression(
                    attributeName:"primaryobjecttypecode",
                    conditionOperator: ConditionOperator.Equal,
                    value: tableName)
            }
        },
        // Link to SdkMessage to get the names
        LinkEntities =
        {
            new LinkEntity(
                linkFromEntityName:"sdkmessagefilter",
                linkToEntityName: "sdkmessage",
                linkFromAttributeName: "sdkmessageid",
                linkToAttributeName: "sdkmessageid",
                joinOperator: JoinOperator.Inner)
            {
                EntityAlias = "sdkmessage",
                Columns = new ColumnSet("name"),
                LinkCriteria =
                {
                    Conditions =
                    {
                        // Don't include private messages
                        new ConditionExpression("isprivate", ConditionOperator.Equal, false)
                    }
                }
            }
        }
    };

    EntityCollection results = service.RetrieveMultiple(query);

        foreach (var entity in results.Entities)
        {
            Console.WriteLine(((AliasedValue)entity["sdkmessage.name"]).Value);
        }
}

Si usa este método configurando el parámetro tableName en account, obtendrá resultados que incluyen estos nombres de mensaje:

Salida:

Assign
Create
Delete
GrantAccess
Merge
ModifyAccess
Retrieve
RetrieveMultiple
RetrievePrincipalAccess
RetrieveSharedPrincipalsAndAccess
RevokeAccess
SetState
SetStateDynamicEntity
Update

Nota

Algunos de estos mensajes están en desuso. SetState y SetStateDynamicEntity todavía existen, pero debe usar Update en su lugar.

Soporte de mensaje para tablas

Algunos mensajes solo se pueden utilizar con tablas específicas. Por ejemplo, solo puede usar el mensaje RetrieveUnpublishedMultiple con un conjunto específico de tablas que contienen datos que se pueden publicar

Esta información se almacena en la Tabla SdkMessageFilter. Puede consultar esta tabla para determinar qué tablas pueden usarse para un mensaje específico.

Utilice este método estático para obtener una lista de nombres de tablas que pueden usarse con un mensaje:

/// <summary>
/// Write the names of tables for a message to the console
/// </summary>
/// <param name="service">The authenticated IOrganizationService to use</param>
/// <param name="messageName">The name of the message</param>
static void OutputTablesForMessage(IOrganizationService service, string messageName) {

    var query = new QueryExpression(entityName: "sdkmessage")
    {
        Criteria = { 
            Conditions =
            {
                new ConditionExpression(
                        attributeName: "name",
                        conditionOperator: ConditionOperator.Equal,
                        value: messageName)
            }
        },
        LinkEntities = {
            new LinkEntity(
                linkFromEntityName:"sdkmessage",
                linkToEntityName: "sdkmessagefilter",
                linkFromAttributeName: "sdkmessageid",
                linkToAttributeName: "sdkmessageid",
                joinOperator: JoinOperator.Inner)
            {
                EntityAlias = "sdkmessagefilter",
                Columns = new ColumnSet("primaryobjecttypecode"),
            }
        }
    };

            EntityCollection results = service.RetrieveMultiple(query);
            List<string> names = new List<string>();

            foreach (var entity in results.Entities)
            {
                names.Add(((AliasedValue)entity["sdkmessagefilter.primaryobjecttypecode"]).Value as string);
            }

            names.Distinct().ToList().ForEach(name => Console.WriteLine(name));
}

Si usa este método configurando el parámetro messageName en RetrieveUnpublishedMultiple, obtendrá resultados que incluyen estos nombres de tabla:

Salida:

organizationui
systemform
savedquery
savedqueryvisualization
sitemap
hierarchyrule
appmodule
appconfig
appconfiginstance
webresource
mobileofflineprofile
mobileofflineprofileitem
mobileofflineprofileitemassociation
navigationsetting
appelement
appsetting
teammobileofflineprofilemembership
usermobileofflineprofilemembership

Nota

  • Para ciertos mensajes, puede encontrar que se devuelven valores de marcador de posición, como DeletedEntity for objectTypeCode=11478 o new_system_donotuseentity_rp53fd1p1ekxpa_t12_b71d6344c5. Estos no son nombres de tabla válidos. Ignore estos valores.

  • Esta consulta también devolverá tablas privadas. En el ejemplo anterior: organizationui,hierarchyrule, appelement y appsetting son tablas privadas y no se admiten para su uso.

Consulte también

Operaciones de tabla con el SDK para .NET
Uso ExecuteAsync para ejecutar mensajes forma asincrónica
Ejecutar mensajes en una sola transacción de la base de datos
Ejemplo: ejecutar varias solicitudes usando SDK para .NET

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).