Adventures with the SharePoint Framework (SPFx): Part 3 – Solution Configuration Settings

Before we get on to building something that might actually be useful, I want to cover off a few things that I believe you should be aware of and consider for all SPFx projects. I know that this is detail stuff but it will make all the difference between your work looking like just another amateur effort and it standing out as the professional offering that it no doubt deserves to be.

In part 1 of this series, I looked at how to set the up a development environment and provided a quick walk through on how to create a simple test client-side web part using the SPFx.

In part 2, I covered how to package and deploy an SPFx solution using the in-built capabilities of your O365 tenancy to provide its own Content Deliver Network (CDN) which is where we elected to save the artefacts and assets required for the solution to work – these files have got to be stored somewhere.

In this 3^rd part of the series I will dive into the configuration settings that are at your disposal at the solution level. Specifically, I’ll be covering:

• Title and Filename: Where and how and why you should set the title and filename for your solution package
• Versioning: How and why you need to apply version numbers
• App Icon: How to customise the App Icon associated with your solution

Solution Title, Name and Filename

By default, the SPFx provides some pretty generic and lacklustre values for the solution name and filename and I am dismayed at the number of developers who never put this right straightaway (or at all).

If you’ve been following along with this series or the official Microsoft tutorials then you will no doubt have noticed that the default solution title is somewhat vague and formatted in an ugly way using hyphenated words as can be seen below:

We could put this right by editing the name element of the solution object in the package-solution.json file in the config folder of the project directory.

But you don’t need to. Instead you should, add in a title element to the solution object and assign it an appropriate text value. The title is optional and will accept a localised text string value whereas the name element is required and will not accept a localised value. We’ll leave localisation for another day but it works like this:

• If a title value is set (whether it be a localised or non-localised text value) then that value is used as the Title of the solution in the App Catalog and in rest of the web UI such as in the “Your Apps” page when adding your app to a site.
• If a title value is not set then use the name value as the title.

I also recommend changing the filename, but not the location, of the .sppkg file to something a little more meaningful by editing the zippedPackage element of the paths object. This is because the filename will actually get shown in the Name column of App Catalog, less the file extension.

Note that the name and zippedPackage properties are tolerant of spaces but they don’t like special characters. If you tried to set the name to “Kaboodle Software – Test Solution #1” for example, SharePoint will throw a hissy-fit at the use of the ‘#’ character. However, the title doesn’t mind special characters at all and this provides yet another reason why you should explicitly set the title instead of relying on name as the default.

I’ll come back to what my solution properties look like in just a minute but first I want to address version numbering.

Version Numbers

Once you start deploying your solution to an App Catalog, I recommend that you get into the habit of incrementing the version number or else you will likely run into version control issues when installing newer solution package files. Basically, you can’t add a solution to a site with the same or a lower version number has previously be installed on that site without having to not only remove the app from Site Contents but also purge it from both stages of the Recycle Bin. This gets to be really painful when you have installed the solution on several sites. Incrementing the version number side-steps this issue. Please see Part 2 in this series for more information on how to delete and upgrade solution packages.

Microsoft use a standard 4-number element scheme with each number separated by a period/decimal point. However, there are no hard and fast rules on how you are to use this scheme, except that:

• Elements are read from left-to-right, so version 1.0.0.0 is higher than version 0.9999.9999.9999
• Unlike in some other technologies where you are often constrained to 4 digits per element, it seems that SharePoint will allow more than 4 digits if you like.
• There has to be exactly 4 elements and they must be numeric integer digits, no alpha-characters allowed.
• If you set any leading zeros they will get removed from what it shown in the App Catalog, so you might specify 1.0.0.07 but that will get displayed as 1.0.0.7 when the solution package gets uploaded to the Catalog.

If you follow the Semantic Versioning pattern then the first 3 elements should be for Major Version, Minor Version and Patch numbers with the 4^th element most often being used to specify a build number. But this pattern is not enforced and because there is nowhere (that I have found) to set a release date for the solution I tend to adopt a Major-Version.Year.Month.Build pattern. So, in my versioning scheme, 2.2018.9.24 would indicate to me that this is the the 24^th build iteration of the solution in September, 2018 for the second major release of the product.

Purists will no doubt berate me for such a contrivance but I don’t much care because my scheme is supported, simple, it works and it gives me some added insight on when the solution was released. Let’s move on and talk about the App Icon.

App Icon

When developing solutions for the Cloud App Model you can include an App Icon in the package which provides some branding for your solution. The App Icon is a 96px square graphic (and it has to be exactly that size) used to distinguish your solution on the “Your Apps” and “Site Contents” pages when viewed in Classic mode. If you don’t provide a custom App Icon, all is not lost, as SharePoint will just use the default “hexagon inside a hexagon” image that you can see in the first screenshot in this article, above. But if we are developing a pukka professional solution then we’d like to associate it to our brand or at least give a pictorial clue as to what the solution does.

However, currently with the SPFx there doesn’t seem to be a way to include such an App Icon automatically. However, what you can do is:

• Manually set App Icon URL for the solution in the App Catalog
• Set an iconPath property in the solution object in the package-solution.json file.

Actually, you will want to do both of the above. If you don’t do the former then your App Icon will be the default hexagons when your solution is viewed from the “Your Apps” page and while the solution is being installed (or removed) from a SharePoint site. If you don’t do the latter then you’ll be stuck with the hexagons when your solution is viewed from the Site Contents page after it has been installed on a site.

Before we dig into these options, I should stress that this only applies when in Classic mode. If you are viewing Site Contents in Modern then you’re stuck with a miniature version of the hexagons as highlighted below:

In some ways that give developers an easy way out as there’s nothing much to be done if there is nothing that can be done. But Classic is still with us and, at the time of writing, the only way to remove an App is by switching to Classic mode, so let’s not be lazy and do things properly shall we.

Set the App Icon URL in the App Catalog

As there is no App Icon URL property of the solution object which can be set within the SPFx solution and then mapped to the properties of solution in the App Catalog, we are left with no option other than to treat this as a post-deployment step. What you have to do here is host an App Icon file somewhere externally (a CDN or web site somewhere) and paste in the hyperlink to that file in the Icon URL property of the solution’s profile in the App Catalog as shown below:

Just be aware that your Icon URL column is limited to a maximum of 255 characters in length.

Whilst we are at it we should probably set the Description and Short Description for the solution with appropriate values as well, more on that in a moment.

Assuming you have set a valid URL to a compliant graphic then the App Icon will now show up in “Apps you can add”.

But if you install the app, the App Icon reverts to the default hexagons, not what we want at all!

Just before we go and sort that one out, I should point out that the Short Summary text, along with the version number, gets displayed when you click on the ellipsis for the app as highlighted below:

To see the full Description, you need to click on the About link and from the linked page you can see a more complete set of solution details as shown below:

Notice also that our version number is shown here as well as a release date value which actually only shows the month and year of when the package was gulped. I presume that this property is automatically set because I can find no place to set a release date explicitly (which would have been nice). Notice also that our App Icon is back in play here!

As we can’t use the SPFx to set these properties automatically, this means we have to provide specific instructions and trust that the Tenancy Administrator will follow them. Ok, so it’s just pasting in some text values but in my experience, admins tend to avoid reading instructions and take the path of least resistance and basically can’t be relied upon to follow simple guidance. I’m now expecting some serious incoming hate-mail.

Back to our inconsistency with the App Icon. As things are now, it shows up when we are about to add the app to a site and in the app About page (above) and it even shows up whilst the app is being loaded (or removed) as well.

But it does not show up on the Site Contents page when the app has actually been successfully installed. Consistency in the UI is overrated in my opinion. Fortunately, we can do something to bring back some law and order.

Set the iconPath Property

The solution object in the package-solution.json file provides us with what we need in the form or an iconPath property. Unfortunately, the iconPath property in does not accept an absolute URL it only accepts a relative path and so the App Icon graphic file needs to be copied into the solution folder structure somewhere – directly in the /sharepoint folder is place of least resistance. Then set the iconPath property to the file name of the App Icon as highlighted below:

Oddly, what this means is that you could (if so inclined) provide a different App Icon for when the app is actually installed and viewable from Site Contents as to when it is viewed from just about everywhere else. That makes no sense to me and would be at odds with how Cloud App model solutions work and would only cause confusion in my book. I therefore recommend that you use the same graphic in both places even though they will be distinct and separate copies of that graphic file.

Anyway, the above screenshot shows my finished package-solution.json file.

Increment the version number, gulp bundle and gulp package-solution the and solution and upload the new .sppkg file the App Catalog, not forgetting to check-in the file if you are upgrading a previous instance.

As you can see, the title element has been carried through to the Title column and the file name of the solution package (without the .sppkg extension) has been set to the Name column and the version element has been applied to the App Version column.

Then add it to a site and everything should be harmonised and the same App Icon is now displayed in Site Contents – yay!

In Summary

So just to recap:

• You apply configuration settings for your solution in the package-solution.json file located in the config folder of your solution directory.
• I recommend setting a value in the title element of the solution object rather than defaulting to the name property value as you can localise this string if you like and use special characters.
• Come up with a consistent approach for versioning and remember to expect trouble if you don’t increment version numbers between deployment upgrades to the App Catalog of a test tenancy.
• You need to undertake manual post installation steps of your solution package to set the Icon URL, Short Description and Description properties as they cannot be set by the SPFx solution package automatically.
• The Icon URL property needs to link to a graphic that is exactly 96px square and must be in some globally accessible location such as a CDN.
• The Icon URL is not used for apps that have been installed and so does not show up on the Site Content page.
• To get a consistent App Icon you also need to set the iconPath property that identifies the location of a graphic that has to be included within the solution package.
• You now have to deal with 2 separate files but which share a single function and that is to brand or somehow indicate the purpose of the solution and as such it recommended that an instance of the same graphic be used in both locations.
• Setting an App Icon only has an impact for Classic pages as Modern does not support this capability currently.

I can’t help but conclude that Microsoft could have done a bit of a better job here.

In the next article I will look at a similar set of properties at you disposal when configuring client web parts developed using the SPFx.