Množství konfiguračních souborů nepředstavuje neprostupnou džungli ale spíše příjemnou procházku lesem.

<sitecore>

Základní konfigurace Sitecore je definována v souboru Sitecore.config v adresáři App_Config. Jeho obsah je vložen do sekce <sitecore> souboru web.config a obsahuje veškeré nastavení související se Sitecore.

Dále se v adresáři App_Config nalézá adresář Include obsahující množství konfiguračních souborů, jež rozšiřují a mění základní konfiguraci. To znamená, že je nejen možné přidávat další konfigurační nastavení, ale také měnit základní konfiguraci souboru Sitecore.config, aniž bychom jej museli upravit. To platí i pro další konfigurační soubory umístěné v Include adresáři.
To je důležité především v okamžiku, kdy je potřeba aktualizovat Sitecore instalací nového update nebo při přechodu na novou verzi Sitecore. Pro změnu konfigurace je proto vždy nejlepší vytvořit si vlastní .config soubory.

Mechanismus úprav konfigurace

Sitecore při startu aplikace zpracuje konfigurační soubory, přičemž pro soubory s koncovkou .config v adresáři App_Config/Include provede takzvané patchování. Takový soubor musí především obsahovat patřičný XML namespace v konfiguračním elementu a dále element <sitecore>.

Include adresář obsahuje .config soubory, které již mohou upravovat originální konfiguraci sitecore, proto je důležité znát pořadí v jakém se změny provádí. Častou chybou totiž je, že upravujeme konfiguraci ve více souborech a změny se poté neprojeví jak očekáváme, protože poslední změna vyhrává.

Sitecore zpracovává .config soubory podle abecedy a poté pokračuje podadresáři opět dle abecedy. Běžnou praxí je použít v názvu souboru předponu Z, Z., Zzz apod.. Ovšem ideální je vytvořit si vlastní adresář v Include adresáři, který bude zpracován až po všech souborech v Include adresáři.

Výsledná konfigurace

Výslednou konfiguraci zobrazuje stránka /sitecore/admin/showconfig.aspx. To je důležité pro zjištění aktuální konfigurace a ověření změn.

XML namespace

Mechanismus změn konfigurace v Include adresáři využívá XML namespace patch a set.

Patch

Patch namespace obsahuje atributy after, before pro vkládání elementů na určené místo v konfiguraci a instead pro nahrazení celého elementu včetně podřízených elementů. Atributy obsahují XPath výraz pro nalezení elementu. Dále obsahuje elementy delete pro mazání elementů a attribute pro nahrazení atributu v elementu.

Příklady použití patch namespace
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
	<sitecore>
		<pipelines>
			<initialize>
				<processor type="Sitecore.Cintel.Endpoint.Plumbing.InitializeRoutes, Sitecore.Cintel" patch:after="*[last()]" />
			</initialize>
			<ces.geoIp.parseResponse>
				<processor type="Sitecore.CES.GeoIp.LegacyLocation.Pipelines.ParseResponse.SetRegionToLegacyValue, Sitecore.CES.GeoIp.LegacyLocation" patch:after="processor[@type='Sitecore.CES.GeoIp.Pipelines.ParseResponse.MapGeoIpResponse, Sitecore.CES.GeoIp']">
					<param ref="LegacyLocationSource" />
				</processor>
			</ces.geoIp.parseResponse>
			<httpRequestEnd>
				<processor patch:before="*[1]" type="Sitecore.FXM.Pipelines.HttpRequest.IgnoreBundleEntries, Sitecore.FXM" />
			</httpRequestEnd>
		</pipelines>
		<processors>
			<uiDragItemTo>
				<processor mode="off" type="Sitecore.Shell.Framework.Pipelines.DragItemTo,Sitecore.Kernel" method="CheckPermissions" patch:instead="*[@type='Sitecore.Shell.Framework.Pipelines.DragItemTo,Sitecore.Kernel' and @method='CheckPermissions']" />
			</uiDragItemTo>
		</processors>
	</sitecore>
</configuration>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
	<sitecore>
		<settings>
			<setting name="FastQueryDescendantsDisabled">
				<patch:attribute name="value">true</patch:attribute>
			</setting>
		</settings>
	</sitecore>
</configuration>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
	<sitecore>
		<tracking>
			<contactManager type="Sitecore.Analytics.Tracking.ContactManager, Sitecore.Analytics" singleInstance="true">
				<param desc="sharedSessionStateManager" ref="tracking/sharedSessionState/manager" />
				<param desc="contactRepository">
					<patch:delete />
				</param>
			</contactManager>
		</tracking>
	</sitecore>
</configuration>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
	<sitecore>
		<pipelines>
			<initialize>
				<processor type="Sitecore.Pipelines.Initialize.PrecompileSpeakViews, Sitecore.Speak.Client">
					<patch:delete />
				</processor>
			</initialize>
		</pipelines>
	</sitecore>
</configuration>

Set

Set namespace funguje obdobně jako patch:attribute s tím rozdílem, že pokud atribut neexistuje, tak jej vytvoří. Není nutné specifikovat hodnotu atributu, jehož hodnota se má nastavit, ovšem pokud by existovalo více elementů stejného názvu s různými hodnotami atributu, pak je nutné atribut s jeho hodnotou specifikovat.

Příklad použití set namespace
<configuration xmlns:set="http://www.sitecore.net/xmlconfig/set/">
	<sitecore>
		<settings>
			<setting name="FastQueryDescendantsDisabled" set:value="true" />
		</settings>
	</sitecore>
</configuration>

Shrnutí

  • Neměňte originální Sitecore.config ani .config soubory v App_Config/Include adresáři. Originální soubory ani nevkládejte do .NET solution a verzovacího systému, aby nikoho nelákalo tyto soubory měnit. Tam patří pouze vaše vlastní konfigurační soubory.
  • Pro povolení/zakázání konfiguračního souboru použijte příponu .disabled.
  • Pro vaše konfigurační soubory si vytvořte nový adresář v adresáři App_Config/Include.
  • Kontrolujte si každý zásah do konfigurace na stránce /sitecore/admin/showconfig.aspx. Ideální je, uložit si stránku showconfig.aspx před změnou konfigurace, poté ji uložit po změně a změny porovnat.
  • Pro snažší orientaci pojmenujte vaše vlastní konfigurační soubory podobně jako originální, vhodné je použít nějakou předponu. Soubor showconfig.aspx obsahuje změněné elementy atribut patch:source, kde je jméno skriptu, který změnu provedl. Tím snadno odhalíte příčinu případných problémů.
  • Nezapomeňte kontrolovat logy. Při chybě načtení konfiguračního souboru se tato chyba objeví hned na začátku logu a konfigurační soubor sitecore ignoruje a aplikace se spustí i bez jeho zpracování.
  • V pipeline je důležité pořadí procesorů. Navíc jsou často měněny více konfiguračními soubory. Zkontrolujte si proto v showconfig.aspx aktuální podobu pipeline než ji začnete měnit.
  • Pro změny atributů dávejte přednost patch:attribute nebo set namespace, než aby jste celý element nahrazovali nebo mazali a znovu vytvářeli.

Odkazy

Originální dokumentace v angličtině
XPath na Wikipedii
XML Path Language (XPath)