Menu Górne
web.config

Dziś słów kilka o tym czym są transformacje XML czyli zmiany plików web.config dla określonych konfiguracji w solucji. Jeżeli nie wiesz o czym pisze to ten post jest dla Ciebie. Jeżeli już to robiłeś to… ten post jest również dla Ciebie 😉

Paaanie, a na co to komu? 😉

Cześć osób może stwierdzić: „nie używam, bo nie potrzebuje„. Tu na myśl przychodzi mi od razu powiedzenie mojego kolegi: „ludzie dzielą się na tych którzy robią backupy i na tych którzy będą je robić…” 😀 Tak samo jest z transformacjami, możesz twierdzić że nie potrzebujesz do momentu gdy na produkcję wyślesz konfigurację z adresem bazy testowej lub odwrotnie. Nie życzę tego nikomu, ale niestety ignorowanie mechanizmów takich jak transformacje do tego prowadzi. Mechanizm transformacji konfiguracji ma na celu utrzymanie higieny ustawień poszczególnych konfiguracji. Zamiast utrzymywać kilka plików konfiguracyjnych z różnymi adresami baz, ustawieniami aplikacji, konfiguracją sieciową, dostajemy możliwość stworzenia jednego pliku a w dodatkowych plikach zawarcia jedynie zmiennych które są związane bezpośrednio ze środowiskiem.

Od czego zacząć przygotowanie do transformacji plików web.config?

… od przeczytania tego posta! 😀 A tak całkiem poważnie, to zależy… Jeżeli problem dotyczy nowego projektu to jedyne co powinieneś zrobić to przeczytać ten artykuł i stosować się do rad w nim zawartych. Jeżeli natomiast mamy już jakiś duży projekt który jest w użyciu to polecam zrobić kopię plików poszczególnych środowisk i usunięcie ich z projektu. Następnie przygotujmy pliki tak aby podgląd transformacji wygenerował plik identyczny z pierwotnie zapisaną kopią. Podstawą każdej transformacji są dwie informacje: „co” i „z czym” mechanizm konfiguracji ma zrobić. Bardzo dobrym zwyczajem jest to, że w plikach pochodnych (transformujących) nie powinno być ŻADNYCH powtarzających się elementów. Powinniśmy przenieść te elementy do pliku podstawowego.

Określ „co” należy zrobić

To co należy zrobić określa tzw. „Transform Attribute”. Atrybut ten określa dokładnie to co ma się stać z danym „nodem” w pliku XML. Mamy różne atrybuty zależnie od akcji:

Replace

Jak sama nazwa wskazuje zamienia on zawartość elementu na nową. Przykładowo gdybyśmy chcieli ZAMIENIĆ element connection string w pliku konfiguracji:

<add name="MainDatabase"
        connectionString="Production Database Connection String"
        xdt:Transform="Replace" xdt:Locator="Match(name)"/>

Insert

W sytuacji gdy chcemy DODAĆ element mamy do dyspozycji atrybut Insert. Składnia jest analogiczna, jednak w tej sytuacji powodujemy dodanie a nie podmianę elementu:

  <add name="MainDatabase"
    connectionString="Release Database Connection String"
    xdt:Transform="Insert""/>

Tutaj należy zwrócić uwagę na to iż polecenie insert nie waliduje czy element o danej nazwie już istnieje, więc bez problemu doda duplikat. Warto również zauważyć że w tym przypadku zbędny staje się Locator ponieważ nie robimy nic z istniejącymi elementami, tylko dodajemy kolejny.

InsertBefore, InsertAfter

InsertBefore oraz InsertAfter pozwala nam wstawić element zdefiniowany bezpośrednio przed lub po elemencie określonym przez wyrażenie XPath w pliku XML. Musimy użyć wyrażenia bezwzględnego, ponieważ jest ono stosowane do całego źródłowego pliku Web.config. Bardzo rzadko używany. Przykładowa składnia:

<allow roles="Admins"
xdt:Transform="InsertBefore(/configuration/system.web/authorization/deny[@users='*'])" />

Remove

Zgodnie z nazwą, usuwa element. Uwaga: jeżeli elementów będzie więcej (o tej samej nazwie) polecenie usunie pierwszy napotkany element. Jeżeli chcesz usunąć wszystkie elementy można użyć RemoveAll.

RemoveAttributes, SetAttributes

Działają tylko na atrybutach. Przydatne w sytaucji gdy mamy kilka atrybutów w ramach jednego elementu – gdy atrybut jest tylko jeden to SetAttribute działa analogicznie do Replace. Np. biorąc pod lupę pierwszy przykład z posta:

        connectionString="Release Database Connection String"
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>

W tym przypadku kod zadziała tak samo jak replace. Jednak jeżeli dodali byśmy nowy atrybut, to używając Replace atrybut zostałby usunięty, a w powyższym zachowany.

Określ „z czym” należy coś zrobić

To który element należy poddać transformacji określa „Locator Attribute”. Atrybut ten określa dokładnie który element w pliku XML ma zostać edytowany. Mamy różne atrybuty, np.:

Condition

To polecenie warunkuje wykonanie transformacji spełnieniem wyrażenia Xpath. Wybierze on elementy pasujące do połączonego wyrażenia XPath. Przykładowa składnia wygląda następująco:

<add name="SomeName" connectionString="New connection string"
       providerName="newprovider"
       xdt:Transform="Replace" 
       xdt:Locator="Condition(@name='oldname'
         or @providerName='oldprovider')" />
  </connectionStrings>

Powyższy przykład pokazuje, jak wybrać elementy connection string których nazwa to oldname lub atrybut providerName ma wartość oldprovider. W transformowanym pliku Web.config określone wyżej elementy będą zastąpione elementem który umieścimy w pliku transformacji.

Match

Wybiera element lub elementy, które mają pasującą wartość dla określonego atrybutu lub atrybutów. Jeśli podano wiele nazw atrybutów, wybierane są tylko elementy pasujące do wszystkich określonych atrybutów. Czyli w naszym przykładzie:

 <add name="MainDatabase"
        connectionString="Release Database Connection String"
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>

Wybieramy wszystkie elementy które mają nazwę „MainDatabase”. Atrybutów możemy podawać wiele oddzielając je przecinkami.

XPath

Określa bezwzględne wyrażenie XPath, które jest stosowane do rozwojowego pliku Web.config. W naszym przypadku może to być np.:

    <add name="MainDatabase" connectionString="Release Database Connection String"
       providerName="someprovider"
       xdt:Transform="Replace"        xdt:Locator="XPath(configuration/connectionStrings[@name='MainDatabase'
         or @providerName='System.Data.SqlClient'])" />

Poniższy przykład pokazuje, jak wybrać te same elementy, które zostały wybrane w poprzednim przykładzie dla słowa kluczowego Condition.

Podsumowanie

Transformacje XML na pierwszy rzut wyglądają na skomplikowane, ale w gruncie rzeczy takie nie są. Zachęcam do nauki ponieważ znajomość mechanizmu zaowocuje bardzo dobrą higieną plików konfiguracyjnych.

Źródła:
Transformacje MSDN
Dokumentacja MSDN

O autorze

Niepoprawny optymista. 100 pomysłów na sekundę, wielbiciel nowych technologii, nie tylko z rodziny .Net. Często nosi przy sobie jabłko, takie nadgryzione... ;)

1 Comment

  1. Fajny wpis! Dobrze przygotowane pliki konfiguracyjne wraz z transformacjami pozwalają zaoszczędzić sporo czasu i troszkę nerwów 🙂 żal nie skorzystać

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *

Możesz używać znaczników języka HTML i ich atrybutów: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Zamknij