.NET Conf

Tworzenie szablonów repozytoriów dla projektów .NET to kluczowy element nowoczesnego developingu, pozwalający na standaryzację struktury projektów, automatyzację konfiguracji oraz znaczące przyspieszenie startu nowych inicjatyw programistycznych. Deweloperzy mogą korzystać zarówno z natywnych mechanizmów .NET, jak i funkcjonalności GitHub, by łączyć szablony kodu z gotową infrastrukturą CI/CD. Nowoczesne szablony wykorzystują template.json, automatyzację przez GitHub Actions i pełną integrację z dystrybucją NuGet, oferując elastyczną personalizację projektów dzięki systemowi symboli i transformacjom tekstu.

Spis treści [odkryj]

Podstawy szablonów projektów .NET

Architektura systemu szablonów

System szablonów .NET korzysta z modularnego silnika templating engine (dotnet/templating). Pozwala on na tworzenie szablonów dla projektów, plików i zasobów, znacząco ułatwiając start nowych aplikacji o jednolitej strukturze.

Szablon projektowy .NET składa się z:

  • plików i folderów źródłowych,
  • pliku konfiguracyjnego template.json,
  • opcjonalnych zasobów multimedialnych lub dodatkowych narzędzi,
  • instrukcji i dokumentacji dla użytkownika,
  • automatyzacji (np. workflow czy skryptów postinstalacyjnych).

Plik template.json odpowiada za metadane, parametry i logikę personalizacji szablonu. Dzięki temu możliwe jest generowanie gotowych rozwiązań z dopasowaniem struktur kodu i nazw do wymagań projektu.

Struktura pliku template.json

Główną rolę odgrywa plik template.json, który znajduje się w katalogu .template.config:

  • $schema – lokalizacja schematu pliku (typowo: „http://json.schemastore.org/template”);
  • identity – unikalny identyfikator szablonu;
  • name – czytelna nazwa wyświetlana użytkownikom;
  • shortName – skrócona nazwa dla dotnet new;
  • author – autor szablonu;
  • classifications – kategorie/działanie szablonu;
  • tags – dodatkowe metadane (np. typ szablonu, język, docelowa platforma).

Poprawna konfiguracja tych pól pozwala użytkownikom oraz narzędziom na szybkie filtrowanie, wyszukiwanie i wykorzystanie szablonu .NET.

System symboli i personalizacja

Szablony .NET pozwalają na głęboką personalizację poprzez symbole:

  • parameter – wartości wprowadzane przez użytkownika przy generowaniu projektu;
  • derived – symbole pochodne, bazujące na innych symbolach (np. przekształcenia nazw);
  • computed – wartości logiczne wyliczane dynamicznie;
  • generated – generowane przez silnik (np. identyfikatory GUID, losowe ciągi znaków).

Zaawansowane szablony wykorzystują generatory takie jak casing, umożliwiające automatyczną zmianę wielkości liter, czy też warunkowe wstawianie fragmentów kodu.

Szablony repozytoriów GitHub

Koncepcja i funkcjonalności

Szablony repozytoriów GitHub pozwalają błyskawicznie zakładać nowe repozytoria, kopiując strukturę plików, dokumentację, workflow CI/CD i konfigurację bez historii commitów. Idealnie nadają się do startu nowych projektów na sprawdzonym szkielecie.

Podstawowe zastosowania szablonów repozytoriów obejmują:

  • utrwalanie dobrych praktyk w strukturze katalogów,
  • automatyczne dołączanie polityk bezpieczeństwa i licencji,
  • replikowanie gotowych workflow CI/CD,
  • wykorzystanie w programach edukacyjnych oraz GitHub Classroom,
  • szybkie wdrażanie nowych inicjatyw projektowych.

Warunkiem korzystania z mechanizmu szablonów jest aktywacja funkcji „Template repository” w ustawieniach repozytorium na GitHub.

Proces tworzenia szablonu repozytorium

Procedura wygląda następująco:

  1. Przygotuj repozytorium zawierające strukturę, pliki startowe, .gitignore, README, licencje i workflow CI;
  2. W ustawieniach zaznacz „Template repository”;
  3. Korzystaj z przycisku „Use this template”, by generować kolejne repozytoria-klony;
  4. Opcjonalnie zainicjuj nowy projekt na bazie szablonu w Codespace lub wybraną gałęzią;
  5. Dostosuj nowoutworzone repozytorium do własnych potrzeb.

Zaawansowane konfiguracje i automatyzacja

Szablony repozytoriów mogą zawierać zaawansowaną automatyzację dzięki GitHub Actions – od instalacji zależności po generowanie kodu aplikacji.

Typowe elementy automatyzacji, które warto dodać do szablonu repozytorium:

  • workflow generujące kod (np. init.yml z wywołaniem dotnet new),
  • Dependabot do aktualizacji zależności,
  • workflow CI/CD z automatyczną publikacją artefaktów,
  • skrypty do zarządzania środowiskiem developerskim,
  • monitoring oraz integracje z narzędziami bezpieczeństwa.

Integracja szablonów .NET z GitHub

Łączenie dwóch podejść

Połączenie szablonów projektów .NET i szablonów repozytoriów GitHub pozwala uzyskać pełną automatyzację procesu startu projektu programistycznego. Po utworzeniu repozytorium szablon generuje kompletny projekt .NET, konfiguruje workflow oraz ustawia podstawowe zależności.

Najlepszy rezultat uzyskasz, tworząc szablon repozytorium z:

  • minimalną konfiguracją startową (README, .gitignore, etc.),
  • workflow init.yml generującym projekt .NET po utworzeniu repozytorium,
  • automatycznym wykorzystaniem nazwy repozytorium dla projektu (spójność nazewnictwa),
  • predefiniowanymi workflow CI/CD oraz dependabotem.

Efekt końcowy to gotowy projekt .NET, gotowy do pracy bez manualnej interwencji dewelopera.

Konfiguracja automatyzacji

Przykładowy workflow automatyzujący inicjalizację projektu .NET:

  • etap instalacji środowiska .NET (actions/setup-dotnet),
  • generowanie projektu z wykorzystaniem dotnet new oraz nazwy repozytorium,
  • możliwość wygenerowania kilku projektów naraz (np. klasy głównej i testów),
  • commit i push wygenerowanej struktury projektu do repozytorium.

Zarządzanie zależnościami i konfiguracją

Każdy szablon powinien zawierać plik dependabot.yml zarządzający aktualizacjami zależności oraz workflow CI/CD umożliwiające ciągłą integrację. Dodatkowe zalety:

  • gotowa konfiguracja środowisk developerskich (Dev Container, Codespaces),
  • eliminacja konieczności lokalnej konfiguracji po stronie użytkownika,
  • szybki start nowych developerów bezpośrednio z repozytorium.

Tworzenie i zarządzanie pakietami szablonów

Tworzenie pakietów szablonów NuGet

Pakiety szablonów .NET to wygodna forma zarządzania i dystrybucji szablonów do wielu projektów jednocześnie. Tworzysz pakiet .nupkg zawierający komplet szablonów, gotowy do instalacji i publikacji.

Procedura obejmuje:

  • instalację szablonu projektu templatepack – dotnet new install Microsoft.TemplateEngine.Authoring.Templates;
  • utworzenie projektu szablonu – dotnet new templatepack;
  • dodanie plików szablonowych do folderu content;
  • konfigurację pliku .csproj z parametrami pakietu (PackageType, id, wersja, etc.);
  • budowanie pakietu poleceniem dotnet pack.

Konfiguracja i budowanie pakietów

Konieczne ustawienia w pliku projektu szablonu:

  • IncludeContentInPack=true – pakuje cały folder content,
  • IncludeBuildOutput=false – nie pakuje binarek,
  • osobny template.json dla każdego podszablonu.

Po zbudowaniu instalacja lokalna wykonuje się przez: dotnet new install ścieżka-do-pakietu. Publikację realizujesz przez wrzucenie do repozytorium NuGet.

Dystrybucja i instalacja

Szablony możesz dystrybuować poprzez:

  • publiczne repozytoria NuGet (instalacja: dotnet new install nazwa-pakietu),
  • prywatne repozytoria/kanaliki NuGet (dotnet nuget add source),
  • dystrybucję lokalną jako plik .nupkg.

Wbudowane polecenia dotnet new list i dotnet new uninstall pozwalają błyskawicznie zarządzać zainstalowanymi szablonami.

Zaawansowane funkcje i personalizacja

Mechanizmy transformacji tekstu

Mechanizmy dynamicznej modyfikacji wygenerowanych plików to:

  • generator switch – logika warunkowa wstawiająca/wykluczająca fragmenty kodu,
  • generator constant – stałe wartości wykorzystywane w projekcie,
  • możliwość używania dyrektyw preprocesorowych (#if, #else, #endif) w szablonie.

Zaawansowane konfiguracje symboli

Symbole typu bind umożliwiają automatyczne pobieranie parametrów od hosta, środowiska lub użytkownika, bez konieczności ręcznego ich podawania. System pilnuje cyklicznych zależności symboli, zgłaszając błędy już na etapie generowania szablonu.

Personalizacja nazw plików i folderów

Możliwa jest automatyczna zmiana nazw plików/folderów, warunkowe kopiowanie lub wykluczanie ich w zależności od opcji wybranych przez użytkownika. Dzięki temu szablony mogą być uniwersalne (multi-platformowe, obsługujące różne style architektoniczne itp.).

GitHub Actions i automatyzacja

Projektowanie workflow dla szablonów

GitHub Actions pozwala budować workflow automatyzujące każdy aspekt inicjalizacji projektu .NET – od pobrania zależności po generowanie kodu i konfigurację narzędzi.

Typowy workflow rozpoczyna się od zdarzenia push lub workflow_dispatch. Składa się z etapów:

  • konfiguracja środowiska (np. instalacja Dotnet SDK),
  • generowanie projektu (dotnet new),
  • commit oraz push do repozytorium,
  • opcjonalnie – konfiguracja narzędzi, szablonów czy monitoring.

Zaawansowana automatyzacja i integracja

Workflow mogą instalować dodatkowe narzędzia, generować pliki konfiguracyjne, inicjować pull requesty aktualizacyjne lub dynamicznie konfigurować repozytorium za pomocą GitHub API. Synchronizacja szablonów z projektami i monitorowanie zmian poprawia aktualność środowiska deweloperskiego.

Monitorowanie i debugging workflow

Monitoring workflow polega na analizie logów, testów i zachowania repozytorium po automatycznym uruchomieniu workflow. Idempotentność, właściwa obsługa błędów oraz przejrzyste logowanie ułatwiają identyfikację i szybkie naprawianie problemów.

Najlepsze praktyki i wzorce

Organizacja struktury szablonów

Prawidłowa organizacja elementów szablonów (oddzielenie treści od konfiguracji, modularność projektów, konsekwentne nazewnictwo tokenów) zapewnia łatwy rozwój szablonu i możliwość jego późniejszej rozbudowy. Warto stosować oddzielne szablony/sekcje dla określonych ról np. testów, infrastruktury Docker itp.

Zarządzanie wersjami i kompatybilnością

Szablony należy versionować semantycznie, przygotowując osobne warianty dla nowych wersji .NET. Minimalne wymagania platformy ustawiamy w TFM i parametrach szablonu. Wszystkie zmiany breaking wymagają wyraźnej sygnalizacji użytkownikom.

Testowanie i walidacja szablonów

Rekomendujemy automatyczne testy wygenerowanych projektów, sprawdzenie poprawności symboli oraz kompilacji. Testowanie wykonuj na różnych wersjach .NET, systemach operacyjnych i środowiskach IDE.

Rozwiązywanie problemów i debugging

Typowe problemy z szablonami .NET

  • niepoprawna składnia template.json,
  • złe zależności lub cykliczne powiązania symboli,
  • nieprawidłowe formatowanie bądź encoding plików,
  • problemy z nazwami plików i ich prawidłową personalizacją na etapie generowania.

Walidację szablonu rozpocznij od sprawdzenia składni, następnie przetestuj symbole i zależności.

Debugging workflow GitHub Actions

Najczęstsze błędy dotyczą niedostatecznych uprawnień workflow oraz braku dostępu do zasobów zewnętrznych. Kluczem jest analiza logów, poprawne wykorzystanie tokenów i stosowanie cache/retry dla zwiększania niezawodności pipeline.

Narzędzia diagnostyczne i monitoring

Przydatne polecenia do diagnostyki szablonów:

  • dotnet new list --verbose – szczegółowa lista dostępnych szablonów,
  • dotnet new --dry-run – testowe wygenerowanie projektu bez zapisu na dysku,
  • skrypty automatycznie testujące poprawność symboli i plików w procesie CI/CD.

Monitoring użytkowania szablonów i statystyk adopcji umożliwia lepszy rozwój i standaryzację narzędzi organizacji.

Przyszłość i trendy rozwoju

Ewolucja systemu szablonów .NET

Szablony .NET muszą nadążać za rozwojem technologii – minimal APIs, source generators, hot reload oraz praktyki cloud-native to kluczowe trendy. Wzrost znaczenia automatyzacji, AI czy uczenia maszynowego otwiera nowe możliwości dla dynamicznej personalizacji i poprawy jakości kodu generowanego przez szablony.

Integracja z ekosystemem DevOps

Coraz większa integracja z praktykami DevOps i IaC pozwala szablonom generować nie tylko kod aplikacji, lecz także gotową infrastrukturę (Terraform, ARM, Kubernetes). Bezpieczeństwo, monitoring i automatyczna zgodność z politykami stają się standardem, zwłaszcza w projektach enterprise.

Społeczność i współpraca

Współtworzone przez społeczność szablony oraz sektorowe standardy stają się coraz ważniejsze. Możliwe są programy certyfikacji i branżowa standaryzacja szablonów, a inicjatywy edukacyjne pomagają popularyzować dobre praktyki i narzędzia do efektywnej pracy.