IOrganizationService.Retrieve(String, Guid, ColumnSet) Method

Definition

Namespace:

Microsoft.Xrm.Sdk

Assembly:

Microsoft.Xrm.Sdk.dll

Package:

Microsoft.PowerPlatform.Dataverse.Client v1.1.32

Retrieves a record.

public:
 Microsoft::Xrm::Sdk::Entity ^ Retrieve(System::String ^ entityName, Guid id, Microsoft::Xrm::Sdk::Query::ColumnSet ^ columnSet);

[System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))]
[System.ServiceModel.OperationContract]
public Microsoft.Xrm.Sdk.Entity Retrieve (string entityName, Guid id, Microsoft.Xrm.Sdk.Query.ColumnSet columnSet);

[<System.ServiceModel.FaultContract(typeof(Microsoft.Xrm.Sdk.OrganizationServiceFault))>]
[<System.ServiceModel.OperationContract>]
abstract member Retrieve : string * Guid * Microsoft.Xrm.Sdk.Query.ColumnSet -> Microsoft.Xrm.Sdk.Entity

Public Function Retrieve (entityName As String, id As Guid, columnSet As ColumnSet) As Entity

Parameters

entityName

String

The logical name of the table for the record that is specified in the id parameter.

id

Guid

The ID of the record that you want to retrieve.

columnSet

ColumnSet

A query that specifies the set of columns, or attributes, to retrieve.

Returns

Entity

The requested entity.

Attributes

FaultContractAttribute OperationContractAttribute

Examples

The following example shows four different ways to set the parameters for the Retrieve(String, Guid, ColumnSet) method depending on common ways you might reference a record that you want to retrieve.

• When using the generated early-bound Account class, you can use the EntityLogicalName property or the Entity.LogicalName property to set the entityName parameter. Learn more about generating early-bound classes for the SDK for .NET

• When using the late-bound Entity class, you can use the Entity.LogicalName property to set the entityName parameter.

• When using a reference to a record defined with the EntityReference class, you can use the EntityReference.LogicalName property to set the entityName parameter.

• If you only have the ID value and know the type of record, you can set the entityName parameter to a string value that corresponds to the EntityMetadata.LogicalName property. In this case, that value is 'account'.

For this sample to work correctly, you must be connected to the server to get an IOrganizationService interface instance.

/// <summary>
/// Demonstrates the Retrieve method
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
/// <param name="earlyBoundAccount">An early bound Account instance.</param>
/// <param name="lateBoundAccount">A late bound account Entity record.</param>
/// <param name="accountReference">A reference to an account record.</param>
/// <param name="accountId">The ID of an account record to delete.</param>
static void RetrieveAccountsExample(IOrganizationService service,
      Account earlyBoundAccount,
      Entity lateBoundAccount,
      EntityReference accountReference,
      Guid accountId)
{

      ColumnSet columns = new("name", "primarycontactid", "createdby", "createdon");

      // Early bound example
      Account retrievedAccount1 = (Account)service.Retrieve(entityName: Account.EntityLogicalName, 
         id: earlyBoundAccount.Id, 
         columnSet: columns);
      // Late bound example
      Entity retrievedAccount2 = service.Retrieve(entityName: lateBoundAccount.LogicalName, 
         id: lateBoundAccount.Id, 
         columnSet: columns);
      // Account reference 
      Entity retrievedAccount3 = service.Retrieve(entityName: accountReference.LogicalName, 
         id: accountReference.Id, 
         columnSet: columns);
      // Guid ID
      Entity retrievedAccount4 = service.Retrieve(entityName: "account", 
         id: accountId, 
         columnSet: columns);
}

You can find more samples on GitHub:

• Sample: Late-bound table operations

• Sample: Early-bound table operations

Remarks

Learn how to retrieve a table row using the SDK for .NET.

Privileges and Access Rights

To perform this action, the caller must have Read privileges on the table that is specified in the entityName parameter and Read access rights on the record that is specified in the id parameter. Learn more about how to verify access with code.

Notes for Callers

The returned record contains values for the specified properties in the columnSet parameter for which the calling user has access rights.

Pass null for the columnSet parameter to retrieve only the primary key. If the columnSet includes attributes where IsValidForRead is false, they are ignored.

To retrieve a record and its related records in a single transaction, use the RetrieveRequest class. Learn how to retrieve records with related rows.

For more information about the exceptions that can be thrown when this method is called, see Handle exceptions in your code.

Supported tables

You can use this method to create any record of a table that supports the Retrieve message. Learn more about Table support for messages and Message support for tables.

See also

• RetrieveResponse
• RetrieveRequest