December 17, 2021

Dataverse REST Builder and XrmToolBox

The XrmToolBox version of Dataverse REST Builder is out, you can download it from the Tool Library inside XrmToolBox.

When creating a new tool for Dynamics 365/Dataverse, XrmToolBox is usually the first choice. It's a well known application, there are already several essential tools for it, you connect to your instance and you are ready.

When I created Dataverse REST Builder I went for a different path, a classic Managed Solution, but why?

Main reason is Xrm.WebApi, the client api created by Microsoft to deal with Web API is available only inside a Dynamics 365/Power Apps instance, it makes sense (at least for me) to create a tool running inside the instance in order to test this correctly.

Second reason is Windows Forms, although it's possible to recreate the same functionalities using the Windows Forms controls they would not have the same look and feel, (and I know I stressed others about this in the past, sorry) the dropdown library used inside DRB it's very convenient for me, I like to use it.

There are other reasons why you may prefer a Managed Solution (you use a Mac or you can't use XrmToolBox for a specific customer) and if you need the functionality you can't be too much picky on how you can get it.

This doesn't mean I don't care about people demanding an XrmToolBox version, I also prefer to have it if possible, however of one thing I was sure: I would not create a different codebase just for XrmToolBox.

There is another tool released as Managed Solution with an XrmToolBox version, Ribbon Workbench by Scott Durow. He may not recall this, but when we first met in London (June 2016) he anticipated me that he was working on the XrmToolBox version, and quickly described me the "bridge" required to make it works. I have fond memories of that trip, can't believe already 5 years passed.

Back to DRB, I knew it is technically possible to load a webpage inside XrmToolBox but it isn't the main problem. DRB is written using JavaScript + jQuery libraries, when I write some code I try to find a syntax available also for IE 11 but sometimes is not possible for everything (like some external libraries I use) and this is the case for DRB, it doesn't work inside IE 11.

Not big deal if you use the Managed Solution (just use a supported browser) but it's a big issue inside a Windows Forms application. Windows Forms has a control to display a webpage but uses the Internet Explorer engine, not the new Edge/Chromium one.

After doing some testing with WebView2 control and able to run DRB inside XrmToolBox, I shared my findings with Tanguy Touzard, he also needed this control for other functionalities and included it inside the release 1.2021.12.53.
If you are curious on how it works, the code of the tool is available inside this repository, inside DRB the code checks if the object coming from XrmToolBox is present.

I suggest this approach if you are planning to create a new tool? Absolutely not:

  • You are limited only to connections using a token based authentication, nowadays it should be the most common way to connect but isn't always the case.
  • You are forced to use the REST endpoint and not the official SDK, if you have the possibility to use the official SDK you should always prefer it, the new version of the SDK is still on public preview but it's mature enough in my opinion.

The XrmToolBox version of DRB comes with limitations, main one is of course the inability to execute Xrm.WebApi requests (but the code is generated), jQuery/XHR requests can be executed because behind the scenes I inject the authentication token.

One thing I expect is that probably more people will use DRB because is available inside XrmToolBox, this means more bugs discovered and more requests asked. If this is the case, please open a GitHub issue, comments in my blog or direct contact requests may be lost and if I receive them I will still ask you to open a GitHub issue.

I hope you find this tool useful.

December 11, 2021

File Columns and Web API

One of the recent and useful additions inside Dataverse is the File column. Prior to this type, files inside Dataverse were usually stored as a Note (annotation table) and having Notes is an option that customizers may prefer to don't enable (or you are dealing with a table like systemuser where you can't enable Notes).

You can find the official documentation regarding File columns here: link.

The page contains also some examples on how to deal with this type, both with REST requests and C# examples.

The latest version of Dataverse REST Builder (1.0.0.13) now includes a new request type called "Manage File Data" to deal with File Columns.

Note: This request is only available with jQuery and XMLHttpRequest, it should work also with Portals (and the safeAjax method) but I didn't test this scenario.

There are three operations available: Retrieve, Upload and Delete.
Retrieve and Delete are quite simple, they are just a GET and a DELETE request to the specific endpoints, the Upload one (it uses a PATCH) is quite tricky.
When Upload is selected a new textbox to specify the file name appears, there are two ways to pass the name using this operation, by url parameter or by header. I decided to use the url parameter, I encode the string before adding it to the main url and I implemented some checks to avoid special characters.
The content is another story, there are no REST examples inside the documentation so I did some tests.
First of all the expected format is binary, other types inside Dataverse, like the annotation table I mentioned above with the column documentbody or an Image column, require a Base 64 string.

Note: DRB allows the upload of images when dealing with Image columns, you can see this behavior also inside the demo with a Create/Update request to Custom Table and Image column.

I did some tests with a Base 64 string as source and converting the content to binary (with atob and other approaches) but the binary was always different from the original one (the Base 64 string was obtained with the FileReader object) probably due to encoding, so now DRB just shows an empty string, if in the future I can find a solution to this conversion I can add a Load button inside this request.

Note: With Postman you can select a file when the body is set to "Binary", the export from DRB handles this setting.

One of the reasons I had when I created DRB was to handle the new column types (choices, image, file), this version is another step forward to deal with them.