Appsettings og JSON schema

Essentials-pakkerne leverer JSON schemaer med felttyper og standardværdier til editorens IntelliSense i appsettings.json.

Installation og opsætning

Installer de pakker, projektet bruger, og byg Umbraco-projektet:

dotnet add package Ecreo.Essentials
dotnet build

Hver pakke med egne options indeholder appsettings-schema.<PackageId>.json og en buildTransitive/<PackageId>.targets-fil. Targets-filen registrerer schemaet i UmbracoJsonSchemaFiles. Umbraco kopierer filen til projektets rod og tilføjer en lokal reference i appsettings-schema.json. Det virker også, når pakken er en transitiv NuGet dependency.

Angiv schemaet øverst i appsettings.json:

{
  "$schema": "appsettings-schema.json",
  "Ecreo": {
    "Essentials": {
      "Meta": {
        "TitleSeparator": "|"
      },
      "ResponsivePicture": {
        "EnableAvif": true
      },
      "HtmlSnippets": {
        "DefaultPropertyAlias": "scripts"
      },
      "ImageSizeCache": {
        "DatabaseRetention": "30.00:00:00",
        "AccessFlushInterval": "00:05:00"
      }
    }
  }
}

Schemaernes standardværdier er forslag i editoren. Options-klasserne bestemmer værdierne ved runtime.

Alle options-felter har en beskrivelse af deres funktion og relevante afhængigheder i schemaet. De samme forklaringer findes som XML-doc på options-klasserne og leveres med NuGet-pakkerne, så de også vises i C# IntelliSense.

Sektioner

Alle sektioner ligger under Ecreo:Essentials.

Pakke	Sektioner	Binding
Ecreo.Essentials	ImageSizeCache, Meta, ResponsivePicture, HtmlSnippets, SelfHost	Registreres automatisk af pakkens composers.
SEO	Seo	Brug builder.AddEcreoEssentialsSeo(builder.Config).
Azure AD Login	AzureADLogin	Brug builder.AddEcreoEssentialsAzureADLogin(builder.Config).
Frontpage URL	FrontpageUrl	Brug builder.AddEcreoEssentialsFrontpageUrl(builder.Config).
PageNotFound	PageNotFound	Brug builder.AddEcreoEssentialsPageNotFound(builder.Config).

Kald builder-metoderne fra projektets Umbraco composer med pakkens Extensions namespace. Et schema aktiverer ikke i sig selv pakkens funktionalitet.

TimeSpan-værdier skrives som strenge, fx "00:05:00" eller "30.00:00:00". ImageSizeCache.DatabaseRetention kan sættes til null for at deaktivere oprydning efter alder.

Meta.DefaultMetaViewModel indeholder standardværdier for meta tags, ikoner og farver. HtmlSnippets.PlaceStringValues bruger enum-navnene HeadStart, HeadEnd, BodyStart og BodyEnd som nøgler.

Default meta-komponenten kopierer modellen og overskriver derefter de sideafhængige felter, blandt andet titler, beskrivelser, URL’er, HrefLangs og Open Graph-billedet. De felter fungerer derfor ikke som fallback-værdier fra appsettings. Ikonstier, farver, Open Graph-type og billedets crop-dimensioner kan bruges som defaults.

Image-cache-jobbet kører med AccessFlushInterval og kontrollerer ved hver kørsel, om CleanupInterval er nået. Oprydning kan derfor ske senere end det angivne cleanup-interval. Retention gælder databaseposter efter deres senest registrerede adgang og fjerner ikke poster, der allerede er indlæst i hukommelsen.

Meta.DefaultViewComponent er en System.Type, og Meta.DefaultMetaViewModel.Content er et IPublishedContent. De sættes i C# og indgår derfor ikke som JSON-felter i schemaet:

builder.Services.Configure<MetaOptions>(options =>
{
    options.DefaultViewComponent = typeof(MyDefaultMetaViewComponent);
});

Pakker uden egne options leverer ikke et schema. Umbracos og andre pakkers options dækkes af deres egne schemaer.

Kontrol af schemaer

Kør pwsh -File tools/Verify-AppSettingsSchemas.ps1 fra repository-roden for at kontrollere, at alle egne options og deres JSON-felter er dækket.

Med -PackageDirectory <mappe> kontrolleres også schema, build-target og XML-dokumentation i de fem pakkers NuGet-filer.