Umbraco - Razor Class library packages - Pt4

A while back now. I wrote a three-part series on using Razor Class libraries (RCLs) for Umbraco packages.

I recently had cause to read them again, and while I think they still stand up and are generally correct i.e. doing what the original posts say still works and is valid.

But there are a couple of things I now do differently/in addition that I thought it would be worth adding.

---

1. set StaticWebAssetBasePath to '/'

So originally I suggest you should set StaticWebAssetBasePath to be something like App_Plugins/myPackage and then your package files that live in wwwroot would automagically be re-routed to /app_plugins/myPackage by the RCL code.

however, since then I've slowly decided to ditch this. at first I simple started setting the value to 'App_Plugins' so that wwwroot/myPackage became the folder. but recently I've moved to setting it to '/' so it just points to the wwwroot folder..

With the StaticWebAssetBasePath value set to '/'. you need to place your package files in wwwroot/App_Plugins/MyPackage

  <StaticWebAssetBasePath>/</StaticWebAssetBasePath>

So, this is a little change, but for me it makes it simpler to understand as this is ultimately where the files will end up (or appear to end up) in a website project. when you publish all your razor files end up in wwwroot/App_Plugins/MyPackage anyway. so why not keep them there.

It also has the second advantage in that should you need to you can include files now in App_Plugins - now at the moment that might not be a big deal, but say for example a new version of Umbraco comes along that uses a totally different front-end framework....

---

2. Use the assembly version for the package version.

Now in Umbraco v11 - you don't have to use the ManifestFilter anymore - but if you want your package to be compatible with Umbraco 10 you still do - and it has some other advantages - one being you can dynamically inject things like package version into your package at runtime.

Looking at our previous example for the manifest filter.

internal class MyManifestFilter: IManifestFilter
{
 public void Filter(List<PackageManifest> manifests)
 {
   manifests.Add(new PackageManifest
   {
     PackageName = "MyPackage",
     Scripts = new []
     {
       "/App_Plugins/MyPackage/my.controller.js"
     },
     Stylesheets = new []
     {
       "/App_Plugins/MyPackage/mystyles.css"
     }
  });
 }
}

What we can do is add the Version property to our package manifest, but take the version from the current assembly.

Version = typeof(MyManifestFilter).Assembly
             .GetName().Version.ToString(3),

This line means get the assembly version but only return the first 3 parts of the version (e.g., 10.3.4.5 returns 10.3.4).

With this in place the version of your package will always be reported as the version you built the NuGet package at.

extra hint: to stamp the version number on a package file pack with dotnet pack -c release -o outfolder /p:version=version where outfolder and version are things you change

---

3. Add your own schema.

this one is a much bigger one, so will likely need its own post. but as of Umbraco v11 - you can add your own appsettings.json schema files to a project by adding values to the UmbracoJsonSchemaFiles property in a .targets file.

e.g - in uSync we have this.

<Project>
    <ItemGroup>
        <UmbracoJsonSchemaFiles Include="$(MSBuildThisFileDirectory)..\appsettings-schema.usync.json" Weight="-80" />
    </ItemGroup>
</Project>

Now you also need to build your schema - which you can do from the settings (again this is how we build the appsettings schema in uSync).

I think there might be an Umbraco way to do this second step now, but i haven't had time to fully investigate. when I have. I will write a full run down on how to do this.