Setting Sub-Grid FilterXml In The Unified Interface And Other Naughty Things

This post started as a twitter poll where I asked if I should blog about an unsupported solution I developed for a rather unusual business requirement dealing with adding option set values to a control that didn’t actually exist in the Option Set of the system.  Because 5 more people voted for me to blog the solution than not, the code for that twitter poll is at the end of this blog post.  But, the real reason I suspect that most of you are here is to be able to set the fetchXml/filterXml of a sub-grid in the new Unified Interface of Dynamics CE / CDS, so let’s get started…

Most JS devs are capable enough to start snooping into the JS Dom of the grid control and find the setFilterXml function.  One would think calling this undocumented function would do what one desires, but nope, it does not.  There have even been attempts to re-write the function that may have worked at one time, but have never worked for me ( https://medium.com/@meelamri23/dynamically-set-fetchxml-to-subgrid-on-dynamics-365-v9-uci-a4a531200e73, https://community.dynamics.com/crm/f/microsoft-dynamics-crm-forum/299697/dynamics-365-unified-interface-inject-fetchxml-into-subgrid).  There is also the supported method of writing a plugin to edit the FetchXml on the server in a Retrieve Multiple plugin, (https://community.dynamics.com/crm/f/microsoft-dynamics-crm-forum/216881/how-to-set-up-custom-fetchxml-for-subgrid-in-dynamics-crm, https://sank8sinha.wordpress.com/2020/01/07/adding-filtered-views-in-uci-in-dynamics-365-crm-finally-achieved/) but unfortunately there is no client context and this may not be possible in some situations and requires a lot of extra effort.  

So what is the solution?  After hitting my head against the brick wall that is the setFilterXml function of the grid control, I decided to focus on figuring out how the fetch xml for the grid was getting determined in the first place.  When attempting to edit the metadata of an option set, as mentioned above, I discovered a function to access the global page state: “Xrm.Utility.getGlobalContext()._clientApiExecutor._store.getState()”.  This function returns a state object that contains the entire page model (metadata, ribbon rules, business process flows, etc).  I had used it to edit option set metadata to allow for dynamic values to be added to it (Picture a payment screen where customer’s previous payment information was in the option set drop down, which is way easier to select from rather than a lookup control.  The resultant function “resetOptions” is in the code block at the bottom of this page.) and I decided to see if I could find the metadata used to generate the Rest call to the server for the option set.

I fired up the Debugger window once more and dived into the call hierarchy used to generate the rest call to the server and discovered that the query was being built from the same metadata cache on the page.  “metadata.views” was an object with GUID properties of view metadata.  A couple quick edits in the debugger console and a refresh of the grid later, and I was in luck!  Editing the fetch xml in the metadata of the page state resulted in directly updating the fetch xml used to query and populate the grid results!  

I’ve since gone through and created a function to do the heavy lifting of finding the view id for the grid by the name of the grid control, and replacing any filters from the view with the filter xml provided as a parameter.  (Please note, this is unsupported.  It could break at any point so use it at your own risk.  With that being said everything I see points to that being unlikely for the foreseeable future)  The function is located below as TypeScript, because TypeScript is awesome and it’s not too hard to remove the typing if you’re just using plain old JS.  I’ve also gone through and documented the entirety of the GlobalState object returned from the “getState()” function as a TypeScript definition file, in the hopes that in the future I can use it to do more  “naughty” unsupported customizations.  You can access it here and is designed to go in your npm “node_modules/@types” folder.  (If someone wants to add it do the work of uploading it to GitHub and making it an npm package, be my guest!)

Call setSubgridFilterXml to set the sub-grid control fetch xml.  Since the metadata is shared at the page level, each grid will require a unique view to keep form interfering with other grids.

/**
 * Updates the Fetch XML of the Metadata which is used to generate the OData Query.
 * Since the metadata is shared at the page level, each grid will require a unique view to keep from interfering with other grids.
 * @param context Global Context
 * @param formContext Form Context
 * @param gridName Name of the Grid
 * @param filterXml Fetch Xml to set the Grid to
 */
export function setSubgridFilterXml(context: Xrm.GlobalContext, formContext: Xrm.FormContext, gridName: string, filterXml: string): void {
    console.info("Unsupported.setSubgridFilterXml(): Executing for grid: ", gridName, ", fetchXml: ", filterXml);
    const gridControl = formContext.getControl(gridName) as Xrm.Controls.GridControl;
    if (!gridControl) {
        console.warn(`No subgrid control found found name ${gridName} in Unsupported.setSubgridFilterXml()`);
        return;
    }
    try {
        const viewId = gridControl.getViewSelector().getCurrentView().id
            .toLowerCase()
            .replace("{", "")
            .replace("}", "");
        const view = getState(context).metadata.views[viewId];
        if (!view) {
            console.warn(`No view was found in the metadata for grid ${gridName} and viewId ${viewId}.`);
            return;
        }
        const originalXml = view.fetchXML;
        const fetchXml = removeFilters(removeLinkedEntities(originalXml));
        const insertAtIndex = fetchXml.lastIndexOf("</entity>");
        // Remove any white spaces between XML tags to ensure that different filters are compared the same when checking to refresh
        view.fetchXML = (fetchXml.substring(0, insertAtIndex) + filterXml + fetchXml.substring(insertAtIndex)).replace(/>\s+</g, "><");

        if (view.fetchXML !== originalXml) {
            // Refresh to load the new Fetch            
            gridControl.refresh();
        }

    } catch (err) {
        CommonLib.error(err);
        alert(`Error attempting unsupported method call setSubGridFetchXml for grid ${gridName}`);
    }
}

function getState(context: Xrm.GlobalContext) {
    return (context as XrmUnsupportedGlobalContext.Context)._clientApiExecutor._store.getState();
}

function removeFilters(fetchXml: string): string {
    return removeXmlNode(fetchXml, "filter");
}

function removeLinkedEntities(fetchXml: string) {
    return removeXmlNode(fetchXml, "link-entity");
}

function removeXmlNode(xml: string, nodeName: string) {
    // Remove Empty tags i.e. <example /> or <example a="b" />
    xml = xml.replace(new RegExp(`<[\s]*${nodeName}[^/>]*\\/>`, "gm"), "");

    const startTag = "<" + nodeName;
    const endTag = `</${nodeName}>`;
    let endIndex = xml.indexOf(endTag);

    // use first end Tag to do inner search
    while (endIndex >= 0) {
        endIndex += endTag.length;
        const startIndex = xml.substring(0, endIndex).lastIndexOf(startTag);
        xml = xml.substring(0, startIndex) + xml.substring(endIndex, xml.length);
        endIndex = xml.indexOf(endTag);
    }
    return xml;
}

This code can be used to allow for dynamically defining the option set values in an option set.  It will still fail on save if the integer value is not actually defined in the system

/**
 * Crm only supports filtering option sets.  This supports resetting the options, although it will still fail on save unless other precautions are taken.
 * It will allow for setting the value.
 * @param context Global Context
 * @param formContext Form Context
 * @param attributeName The name of the attribute
 * @param options The options to reset the Option Sets to
 */
export function resetOptions(context: Xrm.GlobalContext, formContext: Xrm.FormContext, attributeName: string, options: Xrm.OptionSetValue[]) {
    console.warn("Unsupported.resetOptions(): Executing for attribute: " + attributeName);
    const att = formContext.getAttribute(attributeName);
    if (!att) {
        console.warn(`No Attribute found for ${attributeName} in resetOptions.`);
        return;
    }

    const metadata = getState(context).metadata.attributes[att.getParent().getEntityName()][attributeName];
    const nonExistingValues = options.filter(v => {
        return metadata.OptionSet.findIndex(o => {
            return o.Value === v.value as any;
        }) < 0;
    }).map(osv => {
        return {
            Color: "#0000ff",
            DefaultStatus: undefined,
            InvariantName: undefined,
            Label: osv.text,
            ParentValues: undefined,
            State: undefined,
            TransitionData: null,
            Value: osv.value
        } as XrmUnsupportedGlobalContext.Metadata.OptionSetMetadata;
    });

    metadata.OptionSet = nonExistingValues.concat(metadata.OptionSet);
}

Happy Coding!

Handle All Your Plugin Exceptions In One Place, And Then Hide It!

One of the simplest to understand, best practice of writing code (outside of maybe limiting # of lines in a method) is don’t create duplicate code.  Having duplicate code leads to tons of maintenance issues as bugs are fixed in some places, and not others.  Following this best practice, it’s very common recommended best practice to let your Plugin Base class logic handle catching and logging exceptions.

*Important Side Bar* Before going any farther, there are 101 ways to setup debugging in Visual Studio and in certain situations this doesn’t apply, but for the most part, I will assume that your Visual Studio Debugger is setup with most default settings still in place, including the “Enable Just My Code” option.  Also, I don’t know everything about the VS debugger or C# debugger attributes, so if there is a better way, please let us all know.  Alright, lets continue…

One of the problems this creates for those that have unit tests, is (more than likely) that when debugging a unit test, if the plugin itself throws an exception (NullRef anyone?) the debugger will stop execution at the throw statement in the plugin base, since that’s the last place that the exception is caught, before surfacing it to the application, normally CRM, in this case, it would be your test harness.  This is rather annoying, since you don’t see the actual like of code the error occurred at since it was caught by the plugin base class when thrown.  As the picture below shows, this gives 0 context as to where the exception has actually occurred without digging into the stack trace within the exception (as opposed to the Call Stack in VS)

With the equally less than helpful call stack:

So how do we get VS to stop debugging where the error happens, rather than at the plugin base exception handler logic?  Enter “Debugger Attributes” to the Rescue!

There are quite a few “Debugger Attribute” classes in the System.Diagnostics namespace, but the one that makes most sense here is the DebuggerStepThroughAttribute (Or, if you have an open source project that is distributed as code (code gists, source only nuget packages, submodules, etc) or if you want to use the “Enable Just My Code” debugger option to be able to control if you can set a break point and debug or not, then the DebuggerNonUserCodeAttribute makes more sense.).  By adding this attribute to your base plugin class that contains the throw (or method level if you so desire)

[DebuggerNonUserCode]
public abstract class DLaBGenericPluginBase<T> : IRegisteredEventsPlugin where T: IExtendedPluginContext
{

this will force VS to give the desired result:

Since the method handling the exception is “hidden” from the debugger, now the call site of the method that throws the exception, will be where the debugger stops.  Above we can see the actual method call that resulted in the null ref exception was GetByName(), and below the exception call site is shown in the calls stack, so the path to the exception is easily navigated to:

But wait, what happened to the base plugin call site?  Where did it go?  It’s represented by the [External Code] line.  It can’t be stepped into, or debugged without changing your debug settings or removing the attributes but it still shows up in the actual exception stack trace.  So spend less time diving into the exception stack trace, and instead, allowing VS to put you on the actual line where the exception is actually occurring.

 

Happy Coding!

How To Determine If Your Canvas App Is In Studio Or Play Mode

Sometimes, you want to run different logic if you’re editing a canvas app, vs “playing” a canvas app.  There is no out of the box function to call, but there is a fairly small work around for it:

/*********************************
 * Determine Studio or Play mode *
 *********************************/
SaveData([true], "IsMobileApp"); // SaveData only works in the Power Apps App, not the web player
Clear(IsMobileApp);
LoadData(IsMobileApp, "IsMobileApp", true);
// TenantId is required for the web player SaveData only works in the Power Apps App, 
// not the web player so if both are blank/empty then it's studio mode
Set(AppMode, If(IsBlank(Param("tenantId")) && IsEmpty(IsMobileApp), "Studio", "Play"));

 

Since the TenantId is included in the URL for the play web page, and you can’t open the studio from the PowerApps Mobile App, the function should cover all bases for determining if you’re in Studio or Play mode.  This makes it possible to automatically change how the app behaves if it is opened in Studio mode.  I personally use it to show certain hidden sections of the app that are helpful when debugging/creating.

 

Enjoy!