TransformXml - MSBuild task pro transformaci XML souborů ála web.config transformace (XDT)

  • Article

Uff, dalo mi hodně práce vymyslet titulek tohoto článku, aby alespoň trochu vyjadřoval, co článek popisuje - tedy jak pomocí nové techniky Visual Studia 2010 pro web.config transformace, tedy pomocí transformačních XDT souborů (XML Document Transformation Engine), transformovat libovolný jiný XML soubor jako součást běžného buildu.

Pokud nevíte, jak fungují ve Visual Studiu 2010 transformace web.config souborů při deploymentu, podívejte se na můj screencast na MSTV (12:48 minut) nebo na materiály z prezentací (vč. demokódu). Pokud Vás zajímá, jak tímto způsobem transformovat libovolný jiný XML soubor (ať už .config, .sitemap, nebo jakýkoliv jiný .xml), potom čtěte dále.

TransformXml MSBuild task

Celé kouzlo spočívá ve využití připraveného TransformXml MSBuild tasku, který je použit i v připraveném targetu TransformWebConfig používaném při deploymentu webových aplikací (vytváření Package). Task TransformXml je prostý, má tři parametry a vypadá takto:

<TransformXml Source="path/original.xml" Transform="path/transformation.xml" Destination="path/transformed.xml" />

Abyste však tento task mohli použít v libovolném projektovém (.csproj, .vbproj, ...) souboru (nejenom tedy webu, ale i ConsoleApplication, ClassLibrary, či čehokoliv jiného mimo WebSite), musíte jej importovat instrukcí using z assembly webového deploymentu:

<UsingTask TaskName="TransformXml" AssemblyFile="$(MSBuildExtensionsPath)MicrosoftVisualStudiov10.0WebMicrosoft.Web.Publishing.Tasks.dll"/>

No použít task můžete samozřejmě v rámci libovolného targetu, celé to pak může v .csproj souboru vypadat takto:

<UsingTask TaskName="TransformXml" AssemblyFile="$(MSBuildExtensionsPath)MicrosoftVisualStudiov10.0WebMicrosoft.Web.Publishing.Tasks.dll"/><Target Name="AfterBuild"> <TransformXml Source="Menudefault.xml" Transform="MenuMyTransform.xml" Destination="MenuMyMenu.xml" /></Target>

Target AfterBuild je připravený a automaticky spouštěný po základním buildu projektu. Znáte-li fungování projektových souborů a MSBuildu, dále číst nemusíte.

Editace projektových souborů (.csproj/.vbproj/.*proj)

Projektové soubory, jak je znáte z Visual Studia, nejsou ve skutečnosti nic jiného, než MSBuild instrukční soubory, které nejenom drží pohromadě konfiguraci Vašeho projektu, ale představují především zadání pro MSBuild, jak má Vás projekt v různých situacích buildovat.

Nebojte se tedy s těmito soubory pracovat a editovat je! Nejedná se o žádné hackování Visual Studia, ale o zamýšlený způsob ovládání Microsoftího build-procesu. Visual Studio pro Vás tyto soubory typicky založí, během práce s projektem je aktualizuje, nicméně je nepřegenerovává, ale pouze edituje a je opravdu na Vás, pokud chcete buildování Vašeho projektu nějak obohatit, abyste s těmito XML soubory pracovali.

Podrobnější popis fungování těchto souborů je mimo rozsah tohoto článku, pro začátek Vám však značí znát pojmy jako target a task.

MSBuild task je primitivní úkon, který má MSBuild během své práce vykonat. Např. něco zkompilovat, smazat, zkopírovat, založit složku, zkomprimovat do ZIP souboru, transformovat XML, atp. V projektovém souboru se zapisuje jako XML emelent a jeho nastavení se provádí pomocí atributů, viz např. výše uvedený TransformXml task. Základní sada tasků je v MSBuild integrována, další lze připojit jako doplňky (viz výše uvedený Using, který zavádí task TransformXml z .NET assembly).

MSBuild target je něco jako procedura, sada tasků nebo jiných targetů, které se mají vykonat. Pokud např. Visual Studio builduje Váš projekt, volá target "Build", při publishingu webových aplikací se používají targety jako "CreatePackage" nebo "TransformWebConfig". Výchozí konfigurace zahrnuje speciální template-targety "BeforeBuild", "AfterBuild" a podobné, kam se snadno můžete zapojit se svými tasky při běžných buildech.

No a to co my ve skutečnosti při výše uvedených transformacích XML souborů děláme, je ve skutečnosti to, že do targetu AfterBuild přidáme task TransformXml (před tím zavedený pomocí Using), který v patřičné fází buildu transformaci provede.

Jak na editaci projektových souborů z Visual Studia:

  1. Projekt, do jehož projektového souboru budete zasahovat, je zpravidla potřeba "unloadovat" (jen málokterý projektový soubor lze editovat, pokud je projekt zaveden, např. u .wdproj Web Deployment Projectu to lze). V Solution Exploreru tedy pravým tlačítkem klikneme na projekt a dáme "Unload project" (unloadovaný project se sbalí a zašedne).
  2. Nyní můžeme v Solution Exploreru pravým tlačítkem na projekt a dát "Edit project file"
  3. V typickém projektovém souboru najdete targety AfterBuild a BeforeBuild jako připravené zakomentované XML elementy (odkomentujte!), obvykle někde ke konci souboru (na začátku je zpravidla nastavení projektu, uprostřed používané soubory, ke konci buildové věci):
    <!-- To modify your build process, add your task inside one of the targets below and uncomment it. Other similar extension points exist, see Microsoft.Common.targets.<Target Name="BeforeBuild"></Target><Target Name="AfterBuild"></Target>-->
  4. Po potřebných úpravách souboru a jeho uložení stačí opět dát pravým na projekt v Solution Exploreru a "Reload Project".
  5. Nyní můžete buildovat...

Pokud zapomenete udělat Reload Project, projekt se Vám bude při buildu ignorovat, což nemusí být hned zjevné

Robert Haken (ASP.NET MVP)