Dataverse Developer Reference

Fundamentals

Dataverse is a managed, relational data platform — tables, typed columns, relationships, keys, rich metadata, and a role-based security model, all served over a uniform OData v4 Web API and a .NET SDK. It is the native store for model-driven apps and Dynamics 365, and the most scalable source for canvas apps and cloud flows.

• Tables hold rows (records) made of typed columns. Every row has a GUID primary key (e.g. accountid) and a primary name column.
• Table types: *Standard* (normal), *Activity* (time-bound, e.g. tasks/emails), *Virtual* (data sourced from an external system at runtime), and *Elastic* (NoSQL-backed, for very high volume / variable schema).
• Ownership is chosen at table creation and is permanent: *User/Team-owned* rows participate in the full access-level hierarchy; *Organization-owned* rows are on/off only.
• Alternate keys let you address a row by a business value (e.g. an order number) instead of its GUID — essential for upsert and integration.

Column data types

Relationships

Relationships are first-class metadata, not just foreign keys. A 1:N relationship adds a lookup column on the “many” (child) table; an N:N relationship creates a hidden intersect table. In the Web API you traverse them as navigation properties with $expand.

Cascade behavior (1:N relationship behavior)

• Parental — actions on the parent cascade to children (delete the parent, delete the children). Use sparingly; it is the strongest coupling.
• Referential — children survive; the lookup is simply cleared or blocked. *Referential, Restrict Delete* blocks deleting a parent that still has children.
• Configurable cascade — set each action independently: *Assign*, *Share/Unshare*, *Reparent*, *Delete*, and *Merge* can each be Cascade All / Active / User-owned / None.

Web API basics

The Web API is an OData v4 service at https://<org>.crm.dynamics.com/api/data/v9.2/. Everything is JSON over HTTPS with an OAuth 2.0 bearer token (Microsoft Entra ID). You address a table by its entity set name — usually the logical name pluralized (account → accounts, contoso_widget → contoso_widgets).

POST [Organization URI]/api/data/v9.2/accounts
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json
Prefer: return=representation

{
  "name": "Contoso Ltd",
  "creditlimit": 50000,
  "primarycontactid@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)"
}

PATCH [Organization URI]/api/data/v9.2/contoso_orders(contoso_ordernumber='SO-1042')
If-None-Match: "*"
Content-Type: application/json

{ "contoso_total": 1299.00, "contoso_status": 1 }

Querying with OData

GET [Organization URI]/api/data/v9.2/accounts?
  $select=name,revenue,statuscode&
  $filter=revenue gt 100000 and statecode eq 0&
  $orderby=revenue desc&
  $expand=primarycontactid($select=fullname,emailaddress1)&
  $top=25
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

FetchXML

FetchXML is Dataverse’s XML query language. It backs saved views and the SDK’s RetrieveMultiple, and it does a few things OData does more awkwardly — aggregates/grouping, deep link-entity joins, and distinct. Many makers author it in the FetchXML Builder (XrmToolBox) and paste the result.

<fetch top="50">
  <entity name="account">
    <attribute name="name" />
    <attribute name="revenue" />
    <filter type="and">
      <condition attribute="statecode" operator="eq" value="0" />
      <condition attribute="revenue" operator="gt" value="100000" />
    </filter>
    <link-entity name="contact" from="contactid" to="primarycontactid" alias="pc">
      <attribute name="fullname" />
    </link-entity>
    <order attribute="revenue" descending="true" />
  </entity>
</fetch>

<fetch aggregate="true">
  <entity name="opportunity">
    <attribute name="estimatedvalue" alias="total" aggregate="sum" />
    <attribute name="opportunityid" alias="cnt" aggregate="count" />
    <attribute name="ownerid" alias="owner" groupby="true" />
    <filter>
      <condition attribute="statecode" operator="eq" value="0" />
    </filter>
  </entity>
</fetch>

Plug-ins & the SDK

A plug-in is a sandboxed .NET class implementing `IPlugin` that the platform runs when a message (Create, Update, Delete, a custom API…) fires against a table. You register it on a stage of the event pipeline with the Plugin Registration Tool or pac plugin. Inside, you reach the platform through the IServiceProvider.

public class AccountPreOperation : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider
            .GetService(typeof(IPluginExecutionContext));
        var tracing = (ITracingService)serviceProvider
            .GetService(typeof(ITracingService));
        var factory = (IOrganizationServiceFactory)serviceProvider
            .GetService(typeof(IOrganizationServiceFactory));
        var service = factory.CreateOrganizationService(context.UserId);

        // Guard against re-entrancy (our own Update re-triggering us).
        if (context.Depth > 1) return;

        if (context.InputParameters.TryGetValue("Target", out var t) && t is Entity account)
        {
            tracing.Trace("Validating account " + account.Id);
            var name = account.GetAttributeValue<string>("name");
            if (string.IsNullOrWhiteSpace(name))
                throw new InvalidPluginExecutionException("Account name is required.");

            // PreOperation: set values on the inbound row — no extra Update needed.
            account["contoso_normalizedname"] = name.Trim().ToLowerInvariant();
        }
    }
}

• Sync vs async: synchronous steps run inline (10/20/40) and block the caller; asynchronous steps run after commit via the system-job queue and may only register on PostOperation (40).
• Cancel an operation by throwing InvalidPluginExecutionException — ideally in PreValidation, before the transaction and security checks.
• Images beat re-reading: register a Pre/Post image to get old/new values instead of calling Retrieve inside the plug-in.
• Sandbox isolation: no file system or registry, outbound HTTP/HTTPS only, and a ~2-minute execution limit — keep plug-ins fast and side-effect-light.

Security roles & access

Dataverse uses role-based access control. A security role grants a privilege (an action) at an access level (how far it reaches) per table — together those are the user’s *access rights*. A user can hold several roles, and access is the least-restrictive union of them all — you cannot subtract access with another role.

• Business units form the hierarchy that Local/Deep/Global are measured against; every user and team belongs to exactly one.
• Teams carry roles too: *Owner* teams can own rows; *Access* teams grant per-row access at scale; Microsoft Entra group teams sync membership from a security group — the cleanest way to manage access.
• Field-level security secures individual columns (e.g. salary, national ID) via Field Security Profiles that grant Read / Update / Create on the secured column — independent of table privileges.
• Hierarchy security layers Manager or Position hierarchies on top of roles so managers see their reports’ rows without a custom role.

Web API patterns

Recipes that combine the pieces above — each is a copy-and-adapt request for real integration work.

Atomic multi-write with a $batch changeset

POST [Organization URI]/api/data/v9.2/$batch
Content-Type: multipart/mixed; boundary=batch_AAA

--batch_AAA
Content-Type: multipart/mixed; boundary=changeset_BBB

--changeset_BBB
Content-Type: application/http
Content-ID: 1

POST /api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json

{ "name": "Contoso Ltd" }

--changeset_BBB
Content-Type: application/http
Content-ID: 2

POST /api/data/v9.2/contacts HTTP/1.1
Content-Type: application/json

{ "lastname": "Reed", "parentcustomerid_account@odata.bind": "$1" }
--changeset_BBB--
--batch_AAA--

Optimistic concurrency (don’t clobber a newer write)

PATCH [Organization URI]/api/data/v9.2/accounts(<id>)
If-Match: W/"1234567"
Content-Type: application/json

{ "creditlimit": 75000 }

Associate / disassociate an N:N

POST [Organization URI]/api/data/v9.2/accounts(<id>)/contoso_account_contact_set/$ref
Content-Type: application/json

{ "@odata.id": "[Organization URI]/api/data/v9.2/contacts(<contactid>)" }

Impersonate another user for a delegated write

POST [Organization URI]/api/data/v9.2/tasks
MSCRMCallerID: 7b1f8a90-0000-0000-0000-000000000abc
Content-Type: application/json

{ "subject": "Follow up", "regardingobjectid_account@odata.bind": "/accounts(<id>)" }

Choosing an access path

Tip