Minimum Version: 2.3.0 / 3.3.0
Similarly to Custom Actions, we can generate early bound messages for custom apis, the difference with Custom Actions is how we would register them in middleware as they need a plugin to be executed.
They are part of the FakeXrmEasy.Plugins.v* packages, because they need a plugin assembly to run.
Please have a look at the video below to get an overview of how Custom Api’s are implemented in FakeXrmEasy.
A custom api acts like a custom message: it receives some input parameters and can potentially return output parameters. Custom Apis are implemented via a plugin type. Said plugin type will be in charge of implementing any necessary business logic for each relevant input, and will return any necessary output parameters as well.
When the custom api is executed, it will pass any input parameters into your plugin context’s InputParameters, and likewise, any output parameters that the plugin populates in the OutputParameters property, will be returned in the custom api response.
There are different levels of dev and testing you can do with with FakeXrmEasy with regards to Custom Apis.
Given custom apis are implemented with plugins, the dev process of custom apis would typically follow these steps:
You would create a plugin that implements the api, with any necessary unit tests for it. There won’t be any major differences between this custom api plugin and other types of plugins. Main difference being that rather than maybe using the Target input parameter, you would instead be using the parameters that were received in the api directly, and so these would be passed into the InputParameters property.
You would deploy the plugin type to your Dataverse dev environment.
You would, then, create a custom api in Dataverse, with any necessary input and output parameters, using the new plugin type that was deployed.
If you’re just developing a custom api (steps 1 to 3 above), then probably doesn’t make much sense to use pipeline simulation for these and unit testing custom apis like other plugins is probably enough.
If, however, you’re consuming custom apis in .net applications or if you need to register further plugin steps against these custom apis, using pipeline simulation and the documentation in this post might be beneficial. These would be situations like:
If you’re developing .net applications that consume a custom api (like an Azure function), or,
A custom api was setup so that it allows further plugin registrations (to allow 3rd parties to register their own business logic against it), and you need to test the interaction between said custom api implementation and these other plugins.
If you’re consuming a custom api, it might be a good idea to generate a strongly-typed message for it. You can do so with crmsvcutil and similar tools.
The steps needed to setup FakeXrmEasy so it knows how to handle that custom api, given it has strongly-typed requests and responses generated, it’s very straight-forward.
Generate the strongly-typed request and response for that custom api. Check the Generate strongly-typed messages section in the docs.
Add a CustomApi executor like the following:
public class CustomApiSumFakeMessageExecutor :
CustomApiFakeMessageExecutor<CustomApiSumPlugin, dv_SumRequest, dv_SumResponse>, ICustomApiFakeMessageExecutor
{
}
In this example, we’re implementing a custom api executor that will execute the dv_SumRequest api, and will return a sv_SumResponse using the CustomApiSumPlugin implementation.
_context = MiddlewareBuilder
.New()
.AddCrud()
.AddFakeMessageExecutors(Assembly.GetAssembly(typeof(AddListMembersListRequestExecutor)))
//This is the important bit
.AddCustomApiFakeMessageExecutors(Assembly.GetAssembly(typeof(CustomApiSumFakeMessageExecutor)))
.AddPipelineSimulation(new PipelineOptions() { UsePluginStepAudit = true })
.UsePipelineSimulation()
.UseCrud()
.UseMessages()
.SetLicense(FakeXrmEasyLicense.RPL_1_5)
.Build();
In this example, we’re telling FakeXrmEasy to search for custom api executors in the assembly where CustomApiSumFakeMessageExecutor was defined. If there where any other custom api executors in that assembly, FakeXrmEasy will also know about these, there’s no need to add them again. If you had custom api executors spread across different assemblies, you can call this same method many times.
With these 3 steps, FakeXrmEasy will be able to search if there is a given custom api executor for any given combination of custom api request and response, and execute the plugin filling in the InputParameters and OutputParameters for you.
Magic!
Feel free to check a live running example in the samples repo.
If you need to register a plugin step so that it would fire when the custom api is executed, you can register said plugins like any other type of message, just use the name of the Custom Api in the RequestName as follows:
var request = new dv_SumRequest()
{
Prop1 = 7,
Prop2 = 3
};
_context.RegisterPluginStep<SomePlugin>(new PluginStepDefinition()
{
MessageName = request.RequestName,
Stage = ProcessingStepStage.Postoperation
});
In the above example, SomePlugin will fire in PreOperation when dvSumRequest is executed.
Feel free to check a live running example in the samples repo for examples like this an many others