pcf

Debugging PCF in Typescript

/ Dynamics Ninja / 1 Comment

I see a lot of people lately started debugging PCFs by using Fiddler Autoresponder which is awesome and it’s definitely a way to do it.

If you are still one of those that are not using Fiddler when debugging your controls you should definitely need to read a deep-dive article by Diana Birkelbach which will guide you on how to set up Fiddler for the first time.

Debugging with Fiddler is a huge time saver for every developer out there, but what happens when it’s not enough.

Issues

You have that is using modern features like async/await pattern that is almost unreadable when translated to Javascript.

You separated complex control logic across multiple TypeScript files to make it more readable, but in the end, it’s bundled in a single file and you lost that readability when debugging.

You have a critical data related issue on the production environment and you need to debug it there, but there is only production ready minified code that can’t be debugged.

Solution

All the issues mentioned abouve can cause a lot of headaches when you are developing complex controls, but luckily there is always a tool that can help you with all the problems.

The answer to your problems is TypeScript’s feature called Source Map.

Source Map

Source Map is a feature that allows us to debug through our TypeScript files rather than generated JavaScript.

Those files basically contain all the code from your TypeScript files inside one bundled file which is pretty much unreadable for a human, but machines can do some magic with them.

An important thing to mention here is that your whole TypeScript code is copied to the source map file inside sourcesContent node.

When using Source Maps you can easily open your TypeScript files in dev tools of your choice and set breakpoints in them to start the much easier debugging session through much more readable TypeScript code.

Generate Source Map file

Now when we know what we need it’s time to make it work with the PCF project.

The first thing we need to do is instruct the compiler to generate source maps for us every time we make a change in our code.

This is a pretty straightforward process and it requires only one simple property in the tsconfig.json file located in the root folder of our project.

We need to add sourceMap property to the compilerOptions object inside the JSON file and set the value to true.

Your JSON should look something like this:

This was the easy part, but most of the people are stuck here because after the build source map file is not generated.

We need to do one more thing to make it work.

Modify the webpack config

Since PCF is using webpack as a bundler tool, we need to instruct it too that we want to use source maps because it’s not initially set up there.

Webpack configuration is quite hard to find in your project and that’s why most people fail in this step.

Configuration is hidden deep in the node_modules folder.

Path to the configuration file is:

node_modules/pcf-scripts/webpackConfig.js

Once you found the file open it and locate the oobConfig object.

You need to define new property inside this object called devtool and set the value to source-map like it’s shown in line number 5.

After that you are ready to generate the source map file.

Run a simple npm run build command and you should see that the bundle.js.map file is generated in command line output.

You can find those files in out/controls/<CONTROL_NAME> folder.

One more thing to check after the build is bundle.js file and search for one line at the end of the file.

//# sourceMappingURL=bundle.js.map

This line indicates a reference to the source map file that will be used in this JavaScript file.

Now we have everything to start debugging with the TypeScript files, but there is again a catch before we can actually do it.

If you try to pack the control and deploy it as a solution to the environment you will fast realize that you can’t find TypeScript files in the dev tools inside the browser.

The answer is because the source map was not packed inside the solution and deployed to the environment. There is an option called inline source map that will basically pack the whole source map file inside the bundle.js file.

That’s not a good practice because the size of the source map is most of the time larger than the original code size.

This is where Fiddler comes to the rescue and if you didn’t use Fiddler before please take a look at the post mentioned in the first section before you proceed with this article.

Fiddler Configuration

We need to inject the bundle.js.map file inside the browser to make everything work.

You need to create a simple new rule in Auto Responder rule.

Matchregex:(?inx).+bundle.js.map$
Action<LOCAL_PATH_TO_bundle.js.map>

With this, you are finally ready to jump to the browser and test the source maps.

Make sure that Fiddler’s Auto Responder is running and clear the browser cache before opening the form that has PCF control on it.

Once you open Dev Tools (Ctrl + Shift + I on Chrome/Edgium) you should navigate to the Sources tab.

You should see pcf_tools_<RANDOM-GUID> node there. When you expand it you should find all your TypeScript files there.

Open one of those files set a breakpoint and trigger the action that will hit that breakpoint.

Well done, you are finally debugging your TypeScript files.

Conclusion

This article showed you one more trick with Fiddler’s Auto Responder feature that will help you to speed up your development process, but also save your time when debugging when trying to find what causes the bug in the production environment in a more continent way.

Important things to remember are that source maps are not there with the default project configuration, but can be easily added when you get used to it.

I mentioned an inline source map that can be used without Fiddler, but it’s not a good idea to pack code one more time to the bundle.js file, definitely not in a production environment since the file size of the control is doubled.

I hope that from now on you will most likely stick with Fiddler debugging and use debugging harness less frequently.

Keep making great PCF controls!

PCF Preview Image

/ Dynamics Ninja

Almost every day we see a new control or two developed by the community and available as open source. Controls that are published as open-source are generally developed and published in a really short period of time and lack some of the best practices. My last few posts around PCF were just about that.

How to make our controls better by following simple steps?

This time the topic is preview image that is most of the time first impression about the control when we see it in the controls tab.

Today our general source of PCF controls is PCF Gallery where we can find more than 200 controls that are open source. Most of the controls have some kind of screenshot that shows us the interface of this control. Those images are a great way to get our first impression of the control and can easily make us download it and try it at the end.

More than 80% of the controls out there stick with the preview image that is by default. It’s time to change that!

Problem

The problem here is that people don’t add some kind of picture to their controls to make them more visually attractive in the first place.

Maybe people are not that responsible for not including the preview image to the control because in the official examples there are no preview images at all. I personally think that those examples are really good in general, but of course, it should be included there at least in one example control that people see it on the road.

Next is that it’s not presented in the template so people just skip that part.

Everyone can find it in the official docs but is it’s kinda overlooked because it’s one of the last parameters mentioned in the control node section.

How to add

Adding it to your control is really simple.

There is a preview-image attribute in the control node that needs to be defined. Prerequisite is, of course, that image is stored somewhere in the control folder so it can be caught by the webpack.

Let’s have a look at the example!

The example shows us how we can add a preview.png image that is located in the img folder inside a root control directory. Simply add a preview-image attribute and assign img/preview.png value to it.

Easy as that and you have your preview image added.

Another misconception here is that you need to add it also to the resources node with all the other files. Actually, you don’t need to add it there and it will render just fine if you add it just in the control node. The resource node is used only for the images that will be used inside your code.

Model-Driven Apps

Model-Driven App is a place where you will be able to see your preview image.

The preview image can only be seen when you are picking the control for your field/dataset in the form editor.

If you look at the preview image container when you set up your control it feels small and there is a catch in it. That container has fixed size and it will not scale with your image.

Container size is 170 x 130 pixels.

That’s the biggest issue with it in my opinion. Why?

You must be really careful when designing the preview image if you don’t want to be surprised by the weird shape at the end when you see it in the configuration page.

If you don’t keep the 17:13 ratio you will eventually be surprised because the image will stretch in both directions horizontally and vertically to match the size of the container.

The key takeaway here is as long as you keep that strange 17:13 ratio you will have the expected result shown at the end.

The best way to present what your control is capable to do is by using a GIF as a preview image. Yes, it’s possible to add it and I strongly encourage you to use it that way because it’s really eye-catching to see the control is some action.

Canvas Apps

When it comes to canvas apps it’s mentioned in the documentation somehow. A quick look over the Available for column gives you an answer that it’s not available for those kinds of apps, but who knows what future will bring.

The other problem with canvas apps is that controls with preview images cause really critical issues while importing to the app.

When you try to import the PCF control that has preview image included it will just fail to import to the app.

I hope that it’s just a temporary issue and that it will be fixed soon by the Microsoft guys and until then all you need to do is avoid using the preview images in your control.

Conclusion

Images are a great way of showing the features of the control in a quick and effective way. Saying that let’s start including them in our control to help the makers easily choose the right control from the list.

Keep the 17:13 ratio to avoid unnecessary image stretching!

Use GIFs because they the best way of showing the features!

It’s a shame that this feature limits our controls only to model-driven apps because of the issue with the canvas apps. If your control is supposed to be used on both types of apps try to include the preview image and comment that code for now, but hopefully, soon you’ll be able to uncomment it release it the way it should be done.