Ever since Umbraco stepped away from using .NET Framework at its' core, the new way of handing configs is (primarily) through the appsettings.json files. To help users/developers set up their settings and configurations, Umbraco ships with an appsettings-schema.json file allowing for autocompletion and intellisense on the appsettings.json files within most IDE's. But did you know you are able to extend this appsettings schema to include your own intellisense, e.g. when creating an Umbraco Package that has its' own settings options?!
Getting Started
The first step to extending Umbraco's default appsettings-schema.json file is by creating our own appsettings schema. There are two routes we can take here, either being the creation of our schema file by hand, or by taking the evil-genius approach like uSync creator Kevin Jump has done and create a Schema Generator project to generate said schema for you! I won't be going over the details on how to do said generation, but you can take a look at Kevin's source-code if you wish to do so, as I'm lazy like that! 😉
An example of what an appsettings-schema.{your-project-name}.json file looks like is as follows:
The schema above corresponds to the following appsettings.json entry, as shown in the JetBrains Rider IDE:
Attachment 1. Example of the appsettings.json structure based on the provided example schema
By adding this appsettings-schema.{your-project-name}.json to your solution or package, we will notice that it won't automatically cause the intellisense on your appsettings.json to work. That is because the default appsettings-schema.json file provided by Umbraco does not yet contain a reference to our own schema file! Luckily for us, Umbraco includes a way for us to add said reference automatically when the project is being build!
To have our schema file be copied, referenced and use-able, we have to specify the UmbracoJsonSchemaFiles in our msbuild targets file. When working on a package, you will most likely already be shipping your package with a msbuild targets file to perform certain actions when a solution that includes your package is being build, like copying over files and assets. You can find out more about building packages and the provided msbuild targets on the Umbraco Documentation.
In our case, we will be including our file in our package's main msbuild targets file, and include the following line in the targets file that will be included in our package itself:
Note that the rest of the contents of the targets file have been stripped for demonstration purposes
And that's it already! ✨ As soon as your solution is being build, Umbraco will pick up on the various referenced Schema Files throughout the included build targets, copy them over from their location to the project directory, and add a reference to them in the default appsettings-schema.json ready for your IDE to use and make your life a lot easier! For more details on what's happening during the build process, you can take a look at the part responsible for the copying & referencing in the Umbraco CMS source-code over on GitHub. Huge shout-out to Kevin Jump for helping me find out about all this Umbraco wizardry! 🪄
If you have any further questions, feel free to contact me over at my socials available at the Contact page, and I'd love to hear about either your success stories, or further troubles to help improve this blog! 😄
