FetchXMLBuilder

The FetchXMLBuilder class provides a fluent API for building and manipulating FetchXML queries programmatically. Instead of constructing raw XML strings, you can use strongly-typed methods to define entities, columns, filters, conditions, sort orders, and link-entities.

Creating a Query

Create a new FetchXMLBuilder with an empty query, or parse an existing FetchXML string.

// Create an empty query
var builder = new FetchXMLBuilder();
builder.Fetch.Entity.TableName = "contact";

// Or parse an existing FetchXML string
var builder = new FetchXMLBuilder(existingFetchXml);

Selecting Columns

Add individual columns with AddColumn, or set AllColumns = true to retrieve all columns. Setting AllColumns removes any individually added columns.

// Add specific columns
builder.Fetch.Entity.AddColumn("fullname");
builder.Fetch.Entity.AddColumn("emailaddress1");

// Or retrieve all columns
builder.Fetch.Entity.AllColumns = true;

Adding Filters

Add filters to an entity or link-entity with AddFilter, then add conditions to the filter. Each condition specifies a column, operator, and value.

var filter = builder.Fetch.Entity.AddFilter(LogicalOperator.And);

var condition = filter.AddCondition();
condition.Column = "statecode";
condition.Operator = ConditionOperator.Equal;
condition.Value = "0";

// Add an OR condition group
var orFilter = builder.Fetch.Entity.AddFilter(LogicalOperator.Or);

var nameCondition = orFilter.AddCondition();
nameCondition.Column = "fullname";
nameCondition.Operator = ConditionOperator.Like;
nameCondition.Value = "%smith%";

var emailCondition = orFilter.AddCondition();
emailCondition.Column = "emailaddress1";
emailCondition.Operator = ConditionOperator.Like;
emailCondition.Value = "%smith%";

Joining Related Tables

Use AddLinkEntity to join a related table. Set the TableName, From, To, and Operator properties to define the join. Filters can be added to link-entities just like the main entity.

var linkEntity = builder.Fetch.Entity.AddLinkEntity();
linkEntity.TableName = "account";
linkEntity.From = "accountid";
linkEntity.To = "parentcustomerid";
linkEntity.Operator = JoinOperator.LeftOuter;
linkEntity.Alias = "acct";

// Add columns from the linked table
linkEntity.AddColumn("name");

// Add filters to the linked table
var linkFilter = linkEntity.AddFilter();
var linkCondition = linkFilter.AddCondition();
linkCondition.Column = "statecode";
linkCondition.Operator = ConditionOperator.Equal;
linkCondition.Value = "0";

Sorting Results

Use AddSortOrder to define the sort order. You can specify the column name and whether to sort in descending order.

// Sort by fullname ascending
builder.Fetch.Entity.AddSortOrder("fullname");

// Sort by createdon descending
builder.Fetch.Entity.AddSortOrder("createdon", descending: true);

Paging

Control paging with the Count, Page, and PagingCookie properties on the Fetch element. Set ReturnRecordCount = true to include the total record count in the results.

builder.Fetch.Count = 50;
builder.Fetch.Page = 1;
builder.Fetch.ReturnRecordCount = true;

// For subsequent pages, set the paging cookie from the previous result
builder.Fetch.Page = 2;
builder.Fetch.PagingCookie = previousPagingCookie;

Parsing Existing FetchXML

Pass an existing FetchXML string to the constructor to parse and manipulate it. This is useful for modifying queries from views or other sources.

var fetchXml = @"<fetch>
    <entity name='contact'>
        <attribute name='fullname' />
        <filter>
            <condition attribute='statecode' operator='eq' value='0' />
        </filter>
    </entity>
</fetch>";

var builder = new FetchXMLBuilder(fetchXml);

// Modify the parsed query
builder.Fetch.Entity.AddColumn("emailaddress1");
builder.Fetch.Entity.AddSortOrder("fullname");

Generating the FetchXML String

Call ToString() to generate the FetchXML string. The output is deterministically ordered: attributes, then sort orders, then filters, then link-entities. Within each group, elements are sorted alphabetically.

var fetchXmlString = builder.ToString();