---
source_url: https://itmustbecode.com/customapi-manager-for-xrmtoolbox/
title: Custom API Manager for XrmToolBox
date: 2021-01-04T02:46:01+00:00
categories:
  - blog
tags:
  - custom-api
  - dataverse
  - xrmtoolbox
word_count: 1288
reading_time_minutes: 7
type: posts
---

Like most Power Platform developers, I am a heavy user of the [**XrmToolBox**](https://www.xrmtoolbox.com/) a community project led by **[Tanguy Touzard](https://mvp.microsoft.com/en-us/PublicProfile/4028956)**. The myriad of tools it surfaces just makes my day to day job a lot less painful. I also **secretly** been wanting to write a tool of my own to contribute to this amazing project for a long time.

## **The wait is over** 🎉

Today, I'm proud to release my first tool called **[Custom API Manager](https://www.xrmtoolbox.com/plugins/XTB.CustomApiManager/)**, and I really think that it will fill a gap in the current Custom API authoring experience.


{{< linkcard url="https://www.xrmtoolbox.com/plugins/XTB.CustomApiManager/" title="Dataverse Custom API Manager · XrmToolBox" summary="Management tool that provides 360° View of Dataverse Custom APIs. Provides CRUD operations on Custom API, Request Parameters (Inputs) and Response Properties (Outputs)." image="/linkcards/c8fc55f7b936c3af.png" domain="www.xrmtoolbox.com" new_tab="true" nofollow="true" >}}

If you want to **skip the details**, you can fire up your XrmToolBox application and install the Tool from the Tool Library. You will then have access to it in the **Tools section**.

{{< figure src="./image-35.png" alt="" caption="" >}}

{{< figure src="./image-11.png" alt="" caption="" >}}

> If you need some APIs to play around with, you can install my collection of generic [**Dataverse Custom API**](/2021/01/02/dataverse-custom-api-collection/) ( _Shameless plug_ 😏)


{{< linkcard url="https://github.com/drivardxrm/Dataverse-CustomApis" title="drivardxrm/Dataverse-CustomApis" summary="Collection of Dataverse Custom Apis. Contribute to drivardxrm/Dataverse-CustomApis development by creating an account on GitHub." image="/linkcards/e9ffe6985986dfe4.png" domain="github.com" new_tab="true" nofollow="true" >}}

## **What's a Custom API anyway?**

> At the time of writing, Dataverse Custom APIs are still considered a _preview feature_. If you want more information please look at [Microsoft official documentation](https://docs.microsoft.com/en-us/powerapps/developer/data-platform/custom-api)

I will blog more deeply into Dataverse Custom APIs but, In a nutshell, they give developers the ability to define their own REST messages to encapsulate business logic written in C# (using **IPLugin interface** from the Xrm SDK) with a set of Inputs ( **Request parameters**) and Outputs ( **Response properties**).

These messages are then exposed by the **Dataverse WebApi** and can be consumed by any method that can connect to it (Plugins, Power Automate, PCF, Modern-Driven Form javascript, External programs, etc...). The use cases are unlimited.

{{< figure src="./image-10.png" alt="" caption="" >}}

A current limitation of the Custom API is the **lack of an editor** for authoring and management purposes (like the Custom Action/Workflow Editor). Instead, the APIs, Inputs, and Outputs need to be managed separately and it can be hard to get the full picture of the APIs that are defined in a system. This is where the **Custom API Manager** comes in handy.

> This is where the **Custom API Manager** comes in handy.

## **360° View of Custom API**

The goal of the tool is to provide **full visibility** of the Dataverse Custom APIs and related components like request parameters (inputs) and response properties (outputs) that are registered in your Dataverse environment.

You can **(1)** select existing APIs or **(2)** Create new ones from scratch.

{{< figure src="./image-22.png" alt="" caption="" >}}

Once an API is selected, you have access to all the relevant information about the API at your fingertips. You can perform all **CRUD operations** on the API, Request Parameters (inputs), and Response Properties (outputs) very **efficiently** in the **same UX**.

{{< figure src="./image-26.png" alt="" caption="" >}}

{{< figure src="./image-33.png" alt="" caption="" >}}

{{< figure src="./image-27.png" alt="" caption="" >}}

{{< figure src="./image-32.png" alt="" caption="" >}}

## **Integration with Custom API Tester**


{{< linkcard url="https://www.xrmtoolbox.com/plugins/Rappen.XrmToolBox.CustomAPITester/" title="Custom API Tester · XrmToolBox" summary="Browse Custom APIs, enter input parameters, execute the action, investigate output parameters." image="/linkcards/7963c972123cfedd.png" domain="www.xrmtoolbox.com" new_tab="true" nofollow="true" >}}

My favorite feature is that the tool is integrated (both ways) with the **Custom API Tester** from [**Jonas Rapp**](https://jonasr.app/). I had the opportunity to speak with him lately and we decided to make our tools communicate, I personally think that this **joint-venture** provides added value to both tools. 1️⃣ + 1️⃣ = 3️⃣

With this integration, you can **Define** your API in the Custom API Manager, and **Test** it right away using the Custom API Tester. ( **Bonus**! You can even **Monitor** the test execution using the **Plugin Trace Viewer** that is integrated with the API _tester... how cool is that_ 🤯)

{{< figure src="./Integration3.gif" alt="" caption="" >}}

On a technical side, I found it quite easy to implement tool integration and I encourage every XrmToolBox Tool author to **find synergies** with other existing tools in order to provide better experiences to the end-users.

### **Follow these 3 simple steps to leverage tools integration.**

### **1-** Implement the **IMessageBusHost** interface

First, you need your control to implement the **IMessageBusHost** interface contained in **XrmToolBox.Extensibility.Interfaces** Library.

{{< figure src="./image-12.png" alt="" caption="" >}}

{{< figure src="./image-28.png" alt="" caption="" >}}

The interface need the following methods and event to be defined on your plugin class.

- **OnOutgoingMessage**: Event that will send request from your tool to another tool
- **OnIncomingMessage**: Method that will accept a request from another tool to fire up your tool

### **2- Define Outgoing Message**

To send a request to another Tool from your own tool, you will need to define an event called **OnOutgoingMessage**. ( _this line of code will be added automatically in your class when you implement the interface_)

{{< figure src="./image-17.png" alt="" caption="" >}}

Once defined, you can call the event from your business logic. Here I'm calling the **OnOutgoingMessage** event when the user clicks on the **Open With Custom API Tester** button.

When calling the event you need to specify the following in the arguments ( **MessageBusEventArgs**)

- **Name** of the tool to call
- **TargetArgument**: this is the **object** that the receiving tool is expects (Context). In our case, we send a string that contains the GUID of the Custom API to Open in the **Custom API Tester**

{{< figure src="./image-29.png" alt="" caption="" >}}

### **3- Define Incoming Message**

To receive a request from another tool, we need to implement the **OnIncomingMessage** method from the interface.

Here we can get the Context information from the **TargetArgument** object contained in **MessageBusEventArgs** received from the caller. It's then up to you to do what you need with this information in your code. For example, get the GUID of the Custom API that we want to display in the form.

{{< figure src="./image-20.png" alt="" caption="" >}}

> As a side-note **Jonas Rapp** just released a tool called **XrmToolBox Integration Tester** to test these kinds of inter-tools integrations, it really helped me during the development.


{{< linkcard url="https://jonasr.app/2020/12/xit/" title="XrmToolBox Integration Tester ⋆ The Power Platform Trenches" summary="The XrmToolBox Integration Tester tool helps tool developers validate any integration scenarios where other tools call their own tools." image="/linkcards/ab0600b787688f8f.png" domain="jonasr.app" new_tab="true" nofollow="true" >}}

## **Lessons learned**

Looking back on my XrmToolBox Tool authoring experience, I have to say that it is a personal challenge I am happy to have accomplished.

There is definitely a learning curve and you need to dust up your _good'ol_ **WinForm skills** which is the stack that the ToolBox is built on. There are a lot of good resources to get you started ( _see link section at the end of the post_ ). I also found a lot of inspiration looking at some of the top Tools GitHub repos (ain't that what open-source is all about).

One of the **hidden gems** 💎 I found that saved me tons of time ( **and lines of code**) was this collection of WinForm controls adapted to Dataverse: **xrmtb.XrmToolBox.Controls**. Particularly the **CDSDataTextBox** and the **CDSLookupDialog** that used extensively in my tool. Just install the NuGet package in your project.


{{< linkcard url="https://github.com/jamesnovak/xrmtb.XrmToolBox.Controls" title="jamesnovak/xrmtb.XrmToolBox.Controls" summary="Repository of shared controls that can be used for building XrmToolBox Tools - jamesnovak/xrmtb.XrmToolBox.Controls" image="/linkcards/082a497c3e6e8fdf.png" domain="github.com" new_tab="true" nofollow="true" >}}

{{< figure src="./image-15.png" alt="" caption="" >}}

{{< figure src="./image-16.png" alt="" caption="" >}}

## **Going forward**

This is the first release of the **Custom API Manager**, I hope it will help some of you adopt and enjoy this new Power Platform extensibility option.

I would greatly appreciate any **feedback** so I can improve the user experience. Also if you have any ❓ **questions** or 💡 **feature requests** don't hesitate to contact me in the [discussion](https://github.com/drivardxrm/XTB.CustomApiManager/discussions) area of the GitHub repo.


{{< linkcard url="https://github.com/drivardxrm/XTB.CustomApiManager" title="drivardxrm/XTB.CustomApiManager" summary="Dataverse Custom Api Manager for XrmToolBox. Contribute to drivardxrm/XTB.CustomApiManager development by creating an account on GitHub." image="/linkcards/5f73033359771e6e.jpg" domain="github.com" new_tab="true" nofollow="true" >}}

## **Useful links and references**

{{< linkcard url="https://youtu.be/qb5308sW4vc" title="25 Nov 2020 | Let’s build an XrmToolBox tool! by Jonas Rapp" summary="Autoplay" image="/linkcards/xrmtoolbox-jonas-rapp.jpg" domain="youtu.be" new_tab="true" nofollow="true" >}}


{{< linkcard url="https://jonasr.app/2018/05/xtbvsts/" title="Use Azure DevOps to publish XrmToolBox tools ⋆ The Power Platform Trenches" summary="In this article I demonstrate how to create a complete CI/CD pipeline for your XrmToolBox tools using GitHub, Visual Studio Team Services, and NuGet." image="/linkcards/d79e18232e304dce.jpg" domain="jonasr.app" new_tab="true" nofollow="true" >}}


{{< linkcard url="https://learn.microsoft.com/en-us/power-apps/developer/data-platform/custom-api?WT.mc_id=DX-MVP-5004959" title="Create and use Custom APIs (Microsoft Dataverse) - Power Apps" summary="Custom API is a new code-first way to define custom messages for the Microsoft Dataverse" image="/linkcards/34be76da44fadf0c.png" domain="learn.microsoft.com" new_tab="true" nofollow="true" >}}