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=”” 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 ‘’ 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 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 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 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 MajorPCF MinorPCF PatchSolution

Remember that these combinations are needed only when using the 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 was unmanaged. But if the 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!

6 thoughts on “All about PCF-Versioning

Add yours

  1. Hi Diana, thank you for this post! It’s been super helpful! I was able to update a solution, but all the PowerApps that referenced the PCF are still using the old code – would you have any suggestions?

    1. So sorry I’ve missed this one, David! In the meanwhile you must have fixed it, but just for have it listed here: for Canvas Apps or CustomPages you need to open the app; then you should be asked ti upgrade the component. AFter you save and publish the App (Canvas) or the Custom Pages and the App (Model-Driven), the update should be done.

  2. Thanks a lot for this post Diana! I was trying this one out, but while importing the solution built with
    msbuild /t:build /restore, I am not getting the option to upgrade the existing solution. I am only shown the update option, which like you have mentioned has no effect. Could you please help?

    1. If you’ve incremented the PCF version, an import should work (using the new solution designer you should be able to see the options under “Advanced settings”- which might be collapsed at beginning.
      Remember that after importing an unmanaged solution, you need to publish. With the new Solution designer, we are not reminded of that, so it’s easy to forget.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Website Powered by

Up ↑

%d bloggers like this: