Własna reguła do check-inów: praktyczny przykład

signsJedną z mocno przydatnych mechanizmów TFSa jest podstawowa kontrola jakości umieszczanych zmian PRZED ich faktycznym zaistnieniem w repozytorium. Mechanizm ten nazywa się Check in policies (luźne tłumaczenie: reguły check-inów) i standardowo z instalacją dostarczone mamy implementacje takich zasad jak np. “wymagany komentarz do check ina”, czy też “wymagane podpięcie work itema”.
Co jednak, gdy chcemy zaimplementować własny algorytm, weryfikujący specyficzne wymagania naszego zespołu? Wtedy z pomocą przychodzi TFS API i klasa abstrakcyjna PolicyBase, po której dziedzicząc i wypełniając implementacje dosłownie kilku metod, wprowadzamy do naszego zespołu automat spełniający nasze konkretne wymagania dotyczące check-inów.
W poniższym przykładzie pokazuję, jak sprawić, przy wszystkie umieszczane w repozytorium pliki projektowe z rozszerzeniem .csproj zawierały w sobie konkretną frazę(często firmy wprowadzają konkretną konwencję nazewniczą dla projektów, przeważnie jednym z członów jest nazwa firmy).

1.) Tworzymy projekt…

…typu Class Library i dodajemy w nim referencje do biblioteki Microsoft.TeamFoundation.VersionControl.Client. Następnie proponuję zmienić nazwę klasy Class1 na naszą, np. ProjectNameValidator i oznaczyć ją jako serializowalną.

2.) Dziedziczymy i implementujemy…

Klasę ProjectNameValidator odziedziczmy po klasie PolicyBase. Gdy poprosimy Visual Studio o “zaimplementowanie” wymaganych metod i właściwości, zobaczymy dosłownie kilka miejsc do wypełnienia. Najważniejsza metoda to Evaluate, zawierająca logikę naszego sprawdzenia. Poniżej wklejam przykładową implementację(na końcu posta jest też link do kompletnej solucji):
[Serializable]
    public class ProjectNameValidator : PolicyBase
    {
        /// <summary>
        /// fraza do weryfikacji w plikach o rozszerzeniu .csproj
        /// </summary>
        private const string _requiredString = "CompanyName";

        /// <summary>
        /// Opis reguły - pojawi się w oknie dodawania reguły
        /// </summary>
        public override string Description
        {
            get { return string.Format("Dokonujemy sprawdzenia, czy wszystkie pliki .csproj zawierają w sobie fragment \"{0}\"", _requiredString); }
        }

        /// <summary>
        /// Informacja pokazana użytkownikowi, gdy nie ma zainstalowanej biblioteki z regułą na swojej maszynie
        /// </summary>
        public override string InstallationInstructions
        {
            get { return "Nie masz zainstalowanej reguły sprawdzenia nazw projektów - proszę pobrać z http://..."; }
        }

        /// <summary>
        /// Wykorzystywane, gdy chcemy edytować istniejącą regułę.
        /// </summary>
        /// <param name="policyEditArgs"></param>
        /// <returns></returns>
        public override bool Edit(IPolicyEditArgs policyEditArgs)
        {
            return true;
        }

        /// <summary>
        /// Główna metoda dokonująca walidacji
        /// </summary>
        /// <returns></returns>
        public override PolicyFailure[] Evaluate()
        {
            var failures = new List<PolicyFailure>();

            // iterujemy po każdym ZAZNACZONYM pliku
            foreach (var file in base.PendingCheckin.PendingChanges.CheckedPendingChanges)
            {
                if(file.FileName.EndsWith(".csproj") && file.FileName.IndexOf(_requiredString) == -1)
                    failures.Add(new PolicyFailure(string.Format("Plik {0} nie zawiera w sobie fragmentu {1}!", 
                                                        file.FileName, 
                                                        _requiredString), 
                                                    this));
            }

            return failures.ToArray();
        }

        /// <summary>
        /// Pokazana administratorowi podczas dodawania reguły dla danego projektu w TFS
        /// </summary>
        public override string Type
        {
            get { return "ProjectNameValidator"; }
        }

        /// <summary>
        /// Szczegółowy opis pokazany administratorowi podczas dodawania reguły dla danego projektu w TFS
        /// </summary>
        public override string TypeDescription
        {
            get { return string.Format("ProjectNameValidator - dokonuje sprawdzenia, czy wszystkie pliki .csproj zawierają w sobie fragment \"{0}\"", _requiredString); }
        }
    }

3.) Instalujemy…

Instalacji możemy dokonać na dwa sposoby:
A. ręcznie dodać wpis do rejestru(najłatwiej wyszukać klucza “Checkin policies”, bo z tego co zauważyłem, ścieżka może być różna w zależności od konfiguracji. U mnie jest to np. HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\TeamFoundation\SourceControl\Checkin Policies).
Dodajemy nową wartość stringową, gdzie nazwa to prostu nazwa naszej zasady, a wartość to pełna ścieżka do wynikowej dllki naszego projektu z implementacją z powyższych punktów.
B. stworzyć projekt VSIX(Visual Studio SDK wymagane do jego obsługi!) i za jego pośrednictwem umieścić wpis w rejestrze – załączony na końcu posta projekt uwzględnia właśnie instalację z VSIXa.
 
Po instalacji, restarcie VS i przejściu do właściwości Source Control dla danego projektu(Team –> Team project settings –> Source Control –> [zakładka] Check-in Policy –> Add), na liście powinniśmy zobaczyć naszą nową zasadę.
dodanycheckin
Od chwili jej dodania jako obowiązującej, wszyscy programiści będą musieli się do niej stosować. Gdy którykolwiek z programistów nie będzie posiadał zainstalowanej na swojej maszynie biblioteki z naszą zasadą, otrzyma komunikat, jaki wypełniliśmy we właściwości InstallationInstructions. Tak więc check in zostanie uniemożliwiony każdemu, kto nie przeszedł zadanego przez nas warunku lub zwyczajnie nie ma zainstalowanej naszej reguły 🙂

4.) Wymagamy! 😉

Jak widać poniżej, reguła faktycznie wymusza, aby wszystkie pliki .csproj zawierały fragment z nazwą firmy. Naturalnie zaproponowana implementacja jest dość podstawowa, mamy możliwość wytworzenia bardzo wyszukanych algorytmów. Pamiętajmy tylko, że wprowadzanie odpowiednich zasad ma nam pomóc w codziennej pracy! Nakładanie zbyt rygorystycznych albo zwyczajnie upierdliwych restrykcji może obniżyć wydajność zespołu, albo spowodować, że check iny będą dokonywane znaczniej rzadziej(co nie zawsze jest pożądanym efektem).
eval
 
Kompletna solucja: ProjectNameValidator.zip

No Comments

Post a Comment

Time limit is exhausted. Please reload CAPTCHA.