.NET Conf

System szablonów .NET to jedno z najpotężniejszych i jednocześnie niedostatecznie wykorzystywanych narzędzi w ekosystemie .NET, oferujące deweloperom zaawansowane możliwości szkieletowania projektów, generowania kodu i standaryzacji zespołów. Kluczowym narzędziem do pracy z szablonami jest polecenie dotnet new, które umożliwia nie tylko korzystanie z istniejących szablonów, ale też tworzenie i zarządzanie własnymi. To rozwiązanie może znacząco przyspieszyć rozwój oprogramowania oraz wyegzekwować standardy kodowania w organizacjach.

Spis treści [odkryj]

Zrozumienie ekosystemu polecenia dotnet new

Polecenie dotnet new pełni rolę głównego interfejsu do obsługi systemu szablonów .NET. Od .NET 7 SDK architektura tej komendy została usprawniona poprzez wprowadzenie podkomend, zwiększając przejrzystość i ułatwiając codzienne użycie.

Najczęściej wykonywana operacja to instancjonowanie szablonu, czyli uruchomienie polecenia z wybranym identyfikatorem oraz ewentualnymi parametrami, na przykład:

dotnet new mvc --name MyApp --framework net8.0

Podczas tego procesu silnik szablonów analizuje definicje, przetwarza parametry użytkownika i generuje wynikowe pliki na dysku. System korzysta z zaawansowanych mechanizmów pattern matching i transformacji plików, dzięki czemu wyjście jest precyzyjnie dostosowane do potrzeb.

Do zarządzania szablonami służą dedykowane podkomendy:

  • list – wyświetlanie dostępnych szablonów z opcjami filtrowania;
  • search – przeszukiwanie szerszego ekosystemu NuGet pod kątem szablonów społeczności;
  • install – instalacja szablonów z różnych źródeł (np. NuGet, lokalny katalog, plik .nupkg);
  • uninstall – usuwanie niepotrzebnych lub przestarzałych szablonów;
  • update – sprawdzanie i wdrażanie aktualizacji do nowych wersji.

System szablonów .NET zapewnia obsługę wielu źródeł instalacji i aktualizacji szablonów – zarówno publicznych, jak i prywatnych repozytoriów. To pozwala organizacjom na wdrażanie własnych szablonów przy jednoczesnym zachowaniu centralizacji zarządzania.

Architektura i konfiguracja szablonów

Trzonem każdego szablonu jest plik template.json, w którym znajdują się metadane i definicje zachowania szablonu. W praktyce szablon składa się z:

  • plików źródłowych i folderów, czyli zawartości projektu,
  • konfiguracji w folderze .template.config opisującej parametry, symbole i sposoby działania szablonu.

Plik template.json zawiera krytyczne dane: identyfikator, nazwy, autora, klasyfikacje i parametry podstawowe. Klasyfikacja grupuje szablony tematycznie, a identyfikator gwarantuje unikalność w ekosystemie.

System symboli szablonów pozwala na zaawansowaną parametryzację. Dostępne typy symboli to:

  • parametry z wejściem użytkownika,
  • symbole pochodne (przekształcenia na bazie innych wartości),
  • symbole logiczne (warunki),
  • symbole generowane automatycznie (np. GUID, timestamp).

Pozwala to budować złożone szablony, dostosowujące się dynamicznie do scenariusza użytkownika.

Proces generowania szablonu przebiega etapowo:

  1. Gromadzenie parametrów oraz ich walidacja,
  2. Rozwiązywanie symboli zależnych,
  3. Przetwarzanie plików i generowanie finalnych artefaktów.

System obsługuje zarówno proste podstawienia tekstu, jak i skomplikowane operacje warunkowe na całej strukturze projektu.

Systemy parametrów i personalizacja

Szablony .NET udostępniają rozbudowany system parametrów. Personalizacja polega na zdefiniowaniu typów parametrów, określaniu ich powiązań i wpływu na generowane projekty. Oto najważniejsze typy parametrów:

  • Bool (logiczne) – pozwalają włączać i wyłączać funkcje szablonu;
  • Choice (wybór) – ograniczają wybór do dozwolonych wartości, np. wybór frameworka;
  • String (łańcuchy tekstowe) – pozwalają użytkownikowi podać własne nazwy, teksty lub ustawienia.

Dzięki tej architekturze nawet skomplikowane szablony mogą być całkowicie konfigurowalne, pozostając spójne i zgodne ze standardami.

Realizacja zaawansowanych zależności i warunkowości pomiędzy parametrami pozwala np. ukrywać pewne opcje do czasu spełnienia określonych warunków. Warto też wspomnieć, że system obsługuje różne strategie podstawiania tekstu, pozwalające automatycznie stosować konwencje typu PascalCase czy camelCase.

Tworzenie własnych szablonów

Proces tworzenia własnego szablonu .NET dzieli się na kilka kluczowych etapów:

  • wybór lub zbudowanie projektu wzorcowego, najlepiej realnie uruchamialnego,
  • dodanie folderu .template.config z plikiem template.json,
  • zdefiniowanie metadanych, klasyfikacji, skrótów, tagów oraz parametrów,
  • dostosowanie plików do dynamicznej zamiany nazw, przestrzeni nazw czy struktury katalogów,
  • testowanie przy pomocy polecenia dotnet new <szablon> --dry-run,
  • przygotowanie dokumentacji i przykładów użycia.

Odpowiednie opisanie parametrów, wzorców zamiany oraz spójność nazewnictwa są kluczowe dla uzyskania powtarzalnych i profesjonalnych efektów końcowych.

Zaawansowane funkcje szablonów

Współczesne szablony .NET oferują wiele zaawansowanych opcji wykraczających poza podstawowe podstawianie tekstu. Oto przykładowe możliwości:

  • warunkowa obecność plików i folderów w zależności od wartości parametrów,
  • generowanie unikalnych wartości typu GUID, timestamp, losowe ciągi,
  • dynamiczne przełączanie scenariuszy przetwarzania (mechanizm switch),
  • post-processing – uruchamianie akcji po wygenerowaniu projektu, takich jak przywrócenie pakietów czy pierwsza kompilacja,
  • obsługa plików konfiguracyjnych (JSON, XML, YAML),
  • tworzenie złożonych hierarchii katalogów lub struktur rozwiązań.

To sprawia, że szablony mogą generować kompletne architektury gotowe do natychmiastowej pracy.

Dystrybucja i zarządzanie szablonami

Szablony najwygodniej dystrybuować w paczkach NuGet, które oferują:

  • wersjonowanie i śledzenie wydań,
  • centralne repozytoria publiczne oraz prywatne feedy organizacyjne,
  • integrację z narzędziami CI/CD i automatyzację wdrożeń,
  • mechanizmy powiadamiania o aktualizacjach i obsługę autoupdate.

Dzięki temu szablony są zawsze dostępne, zgodne z polityką wersjonowania oraz łatwe do zarządzania w dużych zespołach. Możliwa jest także dystrybucja poprzez udostępnianie plików .nupkg lub korzystanie z katalogów lokalnych – szczególnie przydatne w fazie testów i rozwoju.

Przykłady zastosowań szablonów w praktyce

W zależności od potrzeb i skali organizacji, szablony mogą spełniać różne role:

  • generowanie kompletnej architektury korporacyjnej dla aplikacji biznesowych,
  • szybka produkcja usług API z gotowymi mechanizmami autoryzacji i konfiguracji,
  • tworzenie zestawów mikroserwisów oraz powiązanych projektów w spójny sposób,
  • standardyzacja konfiguracji CI/CD, plików Dockerfile, pipelines,
  • modernizacja projektów legacy poprzez automatyczną migrację oraz generowanie wrapperów,
  • budowanie szablonów edukacyjnych z przykładami kodu i materiałami pomocniczymi,
  • generowanie projektów testowych z gotowym zestawem testów jednostkowych i integracyjnych.

Każde z tych zastosowań przyspiesza wdrażanie nowych rozwiązań i podnosi spójność kodu.

Utrzymanie i rozwój szablonów

Sprawne zarządzanie szablonami wymaga regularnych działań z zakresu rozwoju, monitoringu oraz dokumentowania. Najważniejsze zadania obejmują:

  • monitorowanie użycia i zbieranie informacji zwrotnej od użytkowników;
  • prowadzenie konsekwentnego wersjonowania według zasad semver;
  • aktualizację zależności oraz testy przed publikacją nowych wydań;
  • utrzymanie kompatybilności wstecznej oraz wsparcia starszych wersji;
  • wdrażanie automatycznych testów i walidacji szablonów;
  • stałe aktualizacje dokumentacji;
  • aktywna komunikacja z społecznością poprzez feedback, ankiety i roadmapy;
  • tworzenie narzędzi oraz instrukcji migracyjnych dla starszych projektów.

Dzięki tym działaniom szablony stają się długofalowym narzędziem standaryzacji i automatyzacji rozwoju w organizacji.