All about PCF-Versioning

One of the most common question asked in the Power Apps Pro Dev Community Forum is about the PCF version. In some cases, the PCF doesn’t seem to get updated, which creates a lot of frustration. So here is everything I know (until now) about this.

PCF Version

First things first. What is the PCF version? The PCF version is specified in the PCF manifest, as an attribute for the “control” node.

How should a PCF-Version look like? The SDK says that the version has to follow the rules of “Semantic Versioning”. This means that it has three parts: <MAJOR>.<MINOR>.<PATCH>. The specification of “Sematic Versioning” allows also some aditional labels for pre-release and build. Some examples are: 1.0.0-beta, 1.0.0-rc, 1.0.0-rc.1. Can we use all that for the PCF-Version?

Well, my tests showed that only <MAJOR>.<MINOR>.<PATCH> is allowed. Examples of valid versions are

• 0.0.1
• 8.0.5
• 9.5.20201223

So eventually we could think of patterns using the date, if we need to.

I’ve tried the version=”9.0.3-beta“, but I’ve got an error during the build:

[1:06:00 PM] [build]  Failed:
[pcf-1014] [Error] Manifest validation problem: instance.manifest.control[0].$.version does not match pattern “^[\\^=>]*\\d+(\\.\\d+)*$”

I’ve tried version=”9.0.0.1” and I could build the solution, but I couln’t import the solution in my Dataverse instance, getting the following error.

Solution “Solution” failed to import: Import Solution Failed: CustomControl with name failed to import with error: The import manifest file is invalid. XSD validation failed with the following error: ‘The import manifest file is invalid. XSD validation failed with the following error: ‘The ‘version’ attribute is invalid – The value ‘9.0.0.1’ is invalid according to its datatype ‘versionType’ – The Pattern constraint failed.’.”‘.”

Solution version

The solution version is not related to the PCF version. There are a few ways to create solutions containing PCFs. In case you create it using the Power Apps CLI “pac solution init”, you find the solution in the folder “src\Other\Solution.xml”

The format of the solution version can also include a four numbers, so it can contain <MAJOR>.<MINOR>.<PATCH>.<BUILD>.

Even if the PCF and the Solution version are not linked, it makes sense to come up with a versioning strategy for both PCF and Solution; just to have them clean.

Reading the version in a Dataverse instance

Ok, so we’ve imported the solution.zip containing PCFs. How can we find the PCF version in the Dataverse environment? Then answer is “Solution Layer“. Using the Power Apps Maker Portal, navigate inside a solution, select the “Custom Control” (PCF) that you want to inspect, and select from the menu the “Solution Layers”

You can find there the manifest. The version is also extracted in a separate field.

The impact of the PCF version

To upload a PCF to a Dataverse environment, we have two ways:

1. use “pac pcf push” to upload a debug version of the PCF. This will upload a debug version of the PCF to a solution called “PowerAppsTools_<prefix>” (unmanaged)
2. make a “.cdsproj” for the solution (“pac solution init”), add a reference to the “.pcfproj” (pac solution add-reference) and generate the Solution.zip using “msbuild”. This solution can be then imported to any Dataverse instance.

For the way 1 (pac pcf push), the version of the pcf doesn’t need to be incremented. This is intended to be used for development reasons only. This will skip the version checks, and just update the content.

The normal deployment should be made using way 2 (with a .cdsproj). When you import a solution.zip generated this way, the manifest (PCF) version need to be incremented. Otherwise you won’t get an error, but the content of the PCF won’t be upgraded. But there are some cases where, even if the manifest version was changed, the PCF won’t change.

Incrementing <Major> or <Minor>

Incrementing the last part of the PCF Version (Patch) is always safe. The changes will be reflected, the PCF content will be upgraded. But after changing one of the first two numbers (Major or Minor), the PCF won’t be upgraded… unless you increment the solution version too. It doesn’t matter what part of the Solution version you change.

So if you started with the PCF version “0.0.1” (like the most of the PCFs does), and want to go to “0.1.0” or “1.0.0” you need to change the solution version too.

The table below tries to show which combination of PCF version and Solution versions needs an incrementation.

PCF Major	PCF Minor	PCF Patch	Solution
		+1
	+1		+1
+1			+1

Remember that these combinations are needed only when using the solution.zip generated with msbuild (based on a “cdsproj” project). “pac pcf push” doesn’t need any incrementation.

It’s also important to import the solution choosing to “upgrade”. An “update” won’t have any effect.

Using the old customizing experience is the same: the “Update” or “Overwrite customizations” won’t have any effect.

Importing ways – Mix and Match

We have the two ways of importing the solution “pac pcf push” and “cdsproj solution zip”. But what if we imported once a “cdsproj solution zip” and want to go back to “pac pcf push”? Maybe we work to a new feature and need again a debug version. Will that work?

The answer is … you guessed: “it depends”.

The good news is: it does work when the solution.zip was unmanaged. But if the solution.zip was managed, we see both versions inside the “Solutions Layers”:

Even if we customize the PCF on the form only now, we will get to choose the managed version of the PCF. Any change to the unmanaged layer, so any change using “pac pcf push” won’t be seen on the form (at least that was the case today in my test).

So if you want to go back to “pac pcf push” you need to remove the PCF from the form, uninstall the managed solution, and start over with “pac pcf push” and register the PCF again on the form.

Note: Using “pac pcf push” might help to develop, but the better way to debug PCFs is using the Fiddler AutoResponder, as shown in my other blog.

Hope it helps!

Advertisement