DisassociateRequest Class

  • Reference

Definition

Namespace:
Microsoft.Xrm.Sdk.Messages
Assembly:
Microsoft.Xrm.Sdk.dll
Package:
Microsoft.PowerPlatform.Dataverse.Client v1.1.17

Contains the data that is needed to remove associations between records. 

public ref class DisassociateRequest sealed : Microsoft::Xrm::Sdk::OrganizationRequest
[System.Runtime.Serialization.DataContract(Namespace="http://schemas.microsoft.com/xrm/2011/Contracts")]
public sealed class DisassociateRequest : Microsoft.Xrm.Sdk.OrganizationRequest
[<System.Runtime.Serialization.DataContract(Namespace="http://schemas.microsoft.com/xrm/2011/Contracts")>]
type DisassociateRequest = class
    inherit OrganizationRequest
Public NotInheritable Class DisassociateRequest
Inherits OrganizationRequest
Inheritance
Object
OrganizationRequest
DisassociateRequest
Attributes
DataContractAttribute

Examples

The following example shows how to use this message. For this sample to work correctly, you must be connected to the server to get an IOrganizationService interface instance.

The following example disassociates some task records from an account with optional parameters: 

/// <summary>
/// Demonstrates the DisassociateRequest class
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void DisassociateRequestExample(IOrganizationService service)
{
    // The account record
    Guid accountId = new("ace7042d-1871-ee11-9ae7-000d3a993550");
    EntityReference primaryRecordReference = new("account", accountId);

    // Task records associated with the account
    EntityReferenceCollection recordsToDisassociate = new() {
        { new EntityReference("task", new Guid("bbe7042d-1871-ee11-9ae7-000d3a993550")) },
        { new EntityReference("task", new Guid("b1a65033-1871-ee11-9ae7-000d3a993550")) }
    };

    // The relationship SchemaName
    string relationshipName = "Account_Tasks";

    // Prepare the request
    DisassociateRequest request = new()
    {
        RelatedEntities = recordsToDisassociate,
        Relationship = new Relationship(relationshipName),
        Target = primaryRecordReference
    };

    // Set a shared variable that a plug-in can access
    request["tag"] = "RecordsDissasociatedBySampleCode";
    // Bypass plug-in logic if caller has prvBypassCustomPlugins privilege
    request["BypassCustomPluginExecution"] = true;
    // Don't trigger any flows for this operation
    request["SuppressCallbackRegistrationExpanderJob"] = true;

    // Send the request
    service.Execute(request);
}

Sample code on GitHub

Associate and disassociate table rows

Remarks

Usage

Pass an instance of this class to the Execute(OrganizationRequest) method, which returns an instance of DisassociateResponse.

Privileges and Access Rights

To perform this action, the caller must have privileges on the tables and access rights for records specified by the Target and RelatedEntities properties.

Notes for Callers

Generally, it is easier to use the IOrganizationService.Disassociate method rather than this class. Use this class if you want to apply optional parameters.

This operation removes multiple associations in one transaction between the record specified by the Target property and each record in the RelatedEntities property for the relationship specified in the Relationship property.

You don't need to know the details about the relationship to use this message. You only only need to know the relationship SchemaName property value.

Both one-to-many and many-to-many relationships inherit their SchemaName property from RelationshipMetadataBase.SchemaName. By specifying the unique name of the relationship, Dataverse understands the type of relationship and removes the appropriate data.

For a one-to-many relationship, this operation removes the lookup column values specified by the OneToManyRelationshipMetadata.ReferencingAttribute property in the related record for the relationship you specify. You don't need to know the name of the lookup column.

For a many-to-many relationship, this operation deletes a record in the intersect table for the relationship. You don't need to know the name of the intersect table, Dataverse will know to use the intersect table specified by the ManyToManyRelationshipMetadata.IntersectEntityName property for the relationship you specify.

Supported Tables

You can use this method to disassociate any records that participate in a relationship. You can find the default relationships for common Dataverse tables listed in the Dataverse table/entity reference. For all tables and relationships in your environment, you can use a table definition browser like the one described in Browse table definitions in your environment.

Constructors

DisassociateRequest()

Initializes a new instance of the DisassociateRequest class.

Properties

ExtensionData

Gets or sets the structure that contains extra data. Optional.

(Inherited from OrganizationRequest)
Item[String]

Gets or sets the indexer for the Parameters collection.

(Inherited from OrganizationRequest)
Parameters

Gets or sets the collection of parameters for the request. Required, but is supplied by derived classes.

(Inherited from OrganizationRequest)
RelatedEntities

Gets or sets the collection of entity references (references to records) to be disassociated. Required.

Relationship

Get or sets the name of the relationship to be used for the disassociation. Required.

RequestId

Gets or sets the ID of the request. Optional.

(Inherited from OrganizationRequest)
RequestName

Gets or sets the name of the request. Required, but is supplied by derived classes.

(Inherited from OrganizationRequest)
Target

Gets or sets the record from which the related records will be disassociated. Required.

Applies to

See also