Create a better way for registering package resources through C#

[abjerner]

Create a better way for registering package resources through C#

Today Umbraco provides a few different ways for registering resources and components.

Many resources can be registered by creating a package.manifest file - eg. CSS and JavaScript assets, but also things like property editors, dashboards, content apps or similar. This may be great for smaller packages, but not super flexibly for larger and more complex packages.

Most resources and components can also be registered from C#, but with a few different approaches for doing so - some not super friendly. For instance with backoffice assets, these can be registered in the example below:

builder.BackOfficeAssets()
    .Append<ModelsBuilderCssAsset>()
    .Append<ModelsBuilderDashboardAsset>();

So to add a new CSS asset, I had to create the ModelsBuilderCssAsset class implementing the IAssetFile interface - eg. like:

namespace Limbo.Umbraco.ModelsBuilder.BackOffice.Assets {
    
    public class ModelsBuilderCssAsset : IAssetFile {
        
        public string FilePath { get; set; }

        public AssetType DependencyType { get; }

        public ModelsBuilderCssAsset() {
            DependencyType = AssetType.Css;
            FilePath = $"/App_Plugins/Limbo.Umbraco.ModelsBuilder/Styles/Default.css?v={ModelsBuilderPackage.SemVersion}";
        }

    }

}

This seems like a bit more work than should be necessary. #11308 is an open PR that also works on improving the developer experience.

umbraco/rfcs#27 also proposes creating a JavaScript first approach to registering components in Umbraco. Both as a package developer and a solution implementer, I feel this is a step in the wrong direction (reasons for thinking this are well describe in the RFC).

So my proposal is to introduce a new interface serving as a C# euquivalent of the package.manifest file. It oculd be defined like in the example below:

public interface IPackageManifest {

        /// <summary>
        /// Gets the friendly name of the package.
        /// </summary>
        public string Name { get; }

        /// <summary>
        /// Gets the version of the package.
        /// </summary>
        public string Version { get; }

        /// <summary>
        /// Gets whether telemetry should be enabled for the package.
        /// </summary>
        public bool AllowPackageTelemetry { get; }
        
        /// <summary>
        /// Returns an array of asset files for the package.
        /// </summary>
        /// <returns>An array of <see cref="IAssetFile"/>.</returns>
        public IAssetFile[] GetAssets();

}

Umbraco could automatically look for classes implementing the IPackageManifest interface, and make sure the instances are properly registered with Umbraco. For starters, the interface describes the name and version of the package, along with the AllowPackageTelemetry property recently introduced for package.manifest.

The GetAssets method could be used for returning the CSS and JavaScript assets that should be loaded for this particular package. IMO this would make setting this up much easier that it is today.

Registering a NuGet package so that it shows up in the Packages section isn't super friendly either - eg. via a package migration. With the IPackageManifest interface, it could also mean that instances of this interface are automatically shown in the list of installed packages - maybe even with more information than is shown today (eg. package version, package author information etc.).

XML files are also a bit old school, so the IPackageManifest interface could likely describe a method that would return all the keys/phrases for a package. This would introduce an "API" for registering translations through C# like Jason suggests.

---

So to sum this up, my the proposal is that the IPackageManifest interface could be the preferred approach for registering resources and components via C#. The interface should likely have lots of other options as well - or perhaps it should be an abstract base class instead so it's easier to later introduce new options without it resulting in breaking changes.

[KevinJump]

Just to say there is already a PackageManifest class used in the Packaging Services, and that can be used programmatically to add manifest to at boot time.

you can add a IManifestFiler which defines your package:

 public class uSyncManifestFilter : IManifestFilter
    {
        public void Filter(List<PackageManifest> manifests)
        {
            var manifest = new PackageManifest()
            {
                PackageName = "uSync",
                BundleOptions = BundleOptions.Independent,
                Scripts = new string[]
                {
                    "/App_Plugins/uSync/usync.9.2.0.min.js"
                },
                Stylesheets = new string[]
                {
                    "/App_Plugins/uSync/usync.9.2.0.min.css"
                }
            };

            manifests.Add(manifest);            
        }
    }

and you append this in the composer:

    public class uSyncAssetsComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.ManifestFilters().Append<uSyncManifestFilter>();
        }
    }

(i have some of this sitting in branch for a RCL version of uSync)

It would of course be WAY better for this to be an interface that was discovered, although i am not sure what the current stance on Type discovery at boot time is (i think its considered slow).

but I think builder.packages().append<MyPackageManifest>(); would equally be a big improvement on the current situation.

And it would certainly get my vote if we could also include lang files and/or language entries this way.

[abjerner]

I didn't know this. Thanks for sharing 👍

Umbraco it self seems to have different approaches to auto discovery. I think you have to register most things manually, but for instance IDashboard's are registered automatically. But whether it happens automatically or I should do it manually isn't my primary concern.

The PackageManifest class is in the direction of what I was thinking on, so maybe the best option is to extend that.

Anyways. I'd also like to hear HQs thoughts on this, as the RFC suggests a different direction from what I'm proposing and looking for.