Architecture - vue d'ensemble

Principe general

Ce repo est un gabarit Umbraco minimal et reutilisable. src/Web/ heberge Umbraco 17 et reste le seul projet executable (Microsoft.NET.Sdk.Web), mais la logique intranet propre au projet est extraite dans deux bibliotheques de classes (src/Intranet.Core/, src/Intranet.Connectivity/) que Web reference : il y a donc bien une couche separee du reste du template, meme si ce n'est pas une architecture en couches classique (Application/Domain/Persistence, toujours absentes du template et a la charge des projets aval si besoin).

Le projet hote contient l'echafaudage commun : composition Umbraco, points d'extension (content finder, controllers techniques), SEO, consentement cookies, personnalisations backoffice, pipeline frontend Vite et deploiement Docker.

Structure de solution

Sentinelle.sln (a renommer dans chaque projet aval) regroupe 5 projets :

Projet	Dossier	Role
Intranet.Connectivity	src/Intranet.Connectivity/	Clients d'annuaire (LDAP). Aucune dependance Umbraco - bibliotheque de classes pure.
Intranet.Core	src/Intranet.Core/	Logique intranet. Depend d'Umbraco (Umbraco.Cms.Web.Website/Web.Common) mais d'aucun modele genere ; reference Intranet.Connectivity.
Web	src/Web/	Seul projet executable (Microsoft.NET.Sdk.Web). Application Umbraco : vues, controllers, modeles ModelsBuilder, services types dessus ; reference Intranet.Core et Intranet.Connectivity.
Tests.Common	tests/Common/	Base de test partagee (TestBase). Le csproj s'appelle Tests.Common mais le dossier est Common - decalage intentionnel (voir README).
Tests.Web	tests/Web/	Tests du projet Web ; reproduit l'arborescence de src/Web/. Contient un DummyTest d'exemple.

Sens des references, strict : Web -> Intranet.Core -> Intranet.Connectivity. Jamais l'inverse ; le compilateur l'impose (ProjectReference a sens unique dans chaque .csproj).

Critere de placement d'un nouveau type (par provenance/dependance, pas par couche fonctionnelle) :

• sans aucune dependance Umbraco -> Intranet.Connectivity (ex. LdapDirectoryService, LdapFilterHelper) ;
• avec une dependance Umbraco mais sans dependre d'un modele ModelsBuilder genere -> Intranet.Core (ex. MemberProvisioningService, MemberGateMiddleware, DirectorySyncJob) ;
• des qu'un type est type sur un modele ModelsBuilder genere (IPageSettings, EventPage, ...) ou sur des controllers/vues -> Web.

Voir ../architecture/patterns.md pour la regle appliquee a un enregistrement DI.

Pourquoi trois projets et pas juste des dossiers dans Web : Web.csproj et SiteComposer.cs appartiennent au template et sont mis a jour via le remote upstream ; y laisser vivre du code metier multiplie les conflits de merge. En isolant la logique intranet dans deux projets nouveaux (proprietes du projet aval, jamais touches par upstream), SiteComposer.cs se reduit a deux appels (builder.AddIntranet(); builder.AddIntranetWeb();) au lieu d'une vingtaine d'enregistrements DI directs - la surface de conflit avec le template redevient minimale.

Bootstrap (src/Web/Program.cs)

Modele top-level statements (pas de classe Startup). Ordre :

1. En Development, charge appsettings.local.json (optionnel, git-ignore).
2. Bind CookieConsentOptions (section CookieConsent).
3. Configure StaticFileOptions.OnPrepareResponse : /css et /js sont fingerprintes (asp-append-version), donc Cache-Control: public,max-age=31536000,immutable ; les autres assets ont max-age=604800. ImageSharp gere ses propres en-tetes pour /media.
4. builder.CreateUmbracoBuilder().AddBackOffice().AddWebsite().AddDeliveryApi().AddComposers().Build().
5. Sentry : charge uniquement si Staging/Production ET SentryUrl non vide. Prod : 10% trace sampling ; Staging : ajoute ProfilingIntegration (500 ms).
6. Page d'exception dev si Development ou ForceDisplayDeveloperExceptionPage=true, sinon UseExceptionHandler("/error").
7. UseRewriter (rewrites IIS rewriteRules.xml) uniquement en Staging/Production.
8. BootUmbracoAsync() puis UseUmbraco() (middleware + endpoints backoffice et website).

Composition (src/Web/SiteComposer.cs)

IComposer unique, decouvert par AddComposers(). SiteComposer.cs appartient au template : Compose se limite a builder.AddIntranet() + builder.AddIntranetWeb() (les deux methodes d'extension qui portent tous les enregistrements du projet, voir ../modules/extensibility.md) et au provider 2FA du template (UmbracoUserAppAuthenticator). Ne pas ajouter d'enregistrement directement dans SiteComposer : ajouter dans AddIntranet() (src/Intranet.Core/Extensions/IntranetBuilderExtensions.cs) ou AddIntranetWeb() (src/Web/Extensions/IntranetWebBuilderExtensions.cs) selon ou vit le type enregistre.

Flux de requete

1. Page editoriale : Umbraco route vers le template correspondant au document type (HomePage.cshtml, etc.) qui rend via _MasterLayout.cshtml.
2. 404 : aucun contenu trouve -> NotFoundContentFinder resout la racine du site (match du host sur les domaines Umbraco) puis cherche un enfant de type notFoundPage ; rend NotFoundPage.cshtml.
3. 500 / erreurs : UseExceptionHandler("/error") -> ErrorController (~/error/, chemin reserve) ; un 500 redirige vers le noeud internalServerErrorPage, sinon vers /.
4. Endpoints techniques : SitemapController (/sitemap, XML multilingue), RobotsController (/robots.txt), DevLoginController (/l, DEBUG uniquement).

Detail des extensions : ../modules/extensibility.md.

Acces aux donnees

Le template n'a pas de couche d'acces aux donnees custom ni d'ORM additionnel : tout passe par l'API Umbraco (IPublishedContent + modeles ModelsBuilder) et la base Umbraco (SQL Server). Un projet aval qui a besoin de tables propres ajoutera un projet Persistence.

ModelsBuilder

Mode SourceCodeAuto (appsettings.json) : Umbraco genere des classes C# typees dans src/Web/umbraco/Models (namespace Web.umbraco.Models) a partir des document types. Ces fichiers *.generated.cs ne doivent pas etre edites a la main. Les extensions (PageExtensions) castent IPublishedContent vers les interfaces generees (IPageSettings) ; elles ne compilent qu'une fois les modeles produits.

Fichiers cles

Sujet	Fichier
Bootstrap / pipeline HTTP	src/Web/Program.cs
Composition / DI	src/Web/SiteComposer.cs (template), src/Intranet.Core/Extensions/IntranetBuilderExtensions.cs (AddIntranet), src/Web/Extensions/IntranetWebBuilderExtensions.cs (AddIntranetWeb)
Content finder 404	src/Web/ContentFinders/NotFoundContentFinder.cs
Controller d'erreur	src/Web/Controllers/ErrorController.cs
Helpers SEO	src/Web/Extensions/PageExtensions.cs
Layout principal	src/Web/Views/Layouts/_MasterLayout.cshtml
Config	src/Web/appsettings.json

Contributors

No contributors

Changelog

No recent changes