Enum w C# - jak używać go bezpiecznie?

Gdy w kodzie pojawia się kilka dozwolonych stanów, łatwo wpaść w pułapkę przypadkowych liczb albo trudnych do kontrolowania napisów. Enum w C# pozwala nazwać taki zamknięty zestaw wartości, dzięki czemu kod staje się czytelniejszy, bezpieczniejszy i łatwiejszy w utrzymaniu. Pokażę, czym jest typ wyliczeniowy, jak go definiować, kiedy używać flag oraz na jakie problemy uważać przy konwersji, walidacji i serializacji.

Czym jest enum w C#

Enum, czyli typ wyliczeniowy, opisuje zamknięty zestaw nazwanych stałych. Zamiast przechowywać w kodzie wartości takie jak 1, 2 i 3, nadajemy im znaczenie, na przykład Pending, Paid i Cancelled.

public enum OrderStatus
{
    Pending,
    Paid,
    Shipped,
    Cancelled
}

Od tej chwili zmienna typu OrderStatus może opisywać status zamówienia. Kod if (status == OrderStatus.Paid) mówi znacznie więcej niż warunek porównujący status z liczbą 1. W praktyce właśnie ta czytelność intencji jest największą zaletą enumów.

OrderStatus status = OrderStatus.Paid;

if (status == OrderStatus.Paid)
{
    Console.WriteLine("Zamówienie zostało opłacone.");
}

Enum jest typem wartościowym, a wszystkie typy wyliczeniowe w .NET dziedziczą po System.Enum. Nie oznacza to jednak, że każda dowolna liczba jest automatycznie poprawną wartością biznesową. Można utworzyć enum zawierający liczbę, dla której nie zdefiniowano żadnej nazwanej pozycji, dlatego przy danych z zewnątrz potrzebna jest dodatkowa walidacja.

Jak definiować wartości i typ bazowy

W pokazanym przykładzie pierwsza wartość otrzymuje liczbową reprezentację 0, a każda następna jest zwiększana o jeden. Można jednak przypisać wartości jawnie, co przydaje się między innymi wtedy, gdy enum odwzorowuje kody zapisane w bazie danych albo kontrakcie API.

public enum PaymentStatus
{
    Unknown = 0,
    Pending = 10,
    Completed = 20,
    Failed = 30
}

Jeśli nie podasz typu bazowego, C# użyje int. W razie potrzeby można wybrać inny całkowity typ liczbowy, na przykład byte, short albo long.

public enum AccessLevel : byte
{
    Guest = 1,
    User = 2,
    Administrator = 3
}

Zmiana typu bazowego ma sens głównie wtedy, gdy enum jest częścią konkretnego formatu danych lub trzeba ograniczyć rozmiar struktury. Nie wybierałbym byte tylko dlatego, że wygląda oszczędniej. W większości aplikacji biznesowych domyślny int jest prostszy i wystarczający, a rozmiar pojedynczej wartości nie będzie realnym problemem.

Dlaczego warto zdefiniować wartość zero

Domyślna wartość każdego enum wynosi zero. Jeśli pierwsza pozycja ma inną liczbę, zmienna utworzona bez przypisania otrzyma wartość, która może nie mieć nazwy.

public enum JobState
{
    Queued = 1,
    Running = 2,
    Finished = 3
}

JobState state = default;
Console.WriteLine(state); // 0

Z tego powodu często dodaję pozycję Unknown, None albo NotSet z wartością 0. Nie rozwiązuje to wszystkich problemów, ale sprawia, że stan początkowy jest jawny i można go świadomie obsłużyć.

Enum a liczby i napisy

W pamięci enum przechowuje wartość liczbową, ale w kodzie posługujemy się nazwą. C# nie pozwala bezpośrednio przypisać zwykłego int do enum bez konwersji, ponieważ taka operacja mogłaby ukryć błąd typu.

int value = 2;
OrderStatus status = (OrderStatus)value;

Rzutowanie działa technicznie, nawet jeśli liczba 2 nie ma odpowiadającego jej elementu w deklaracji. Dlatego przy wartościach z formularza, parametrów URL, pliku lub API najpierw sprawdzam, czy dane mieszczą się w dozwolonym zakresie.

if (Enum.IsDefined(typeof(OrderStatus), value))
{
    var status = (OrderStatus)value;
}

W nowoczesnym C# wygodniejsza jest metoda generyczna Enum.IsDefined, a do bezpiecznego parsowania napisów służy Enum.TryParse.

string input = "Paid";

if (Enum.TryParse(input, ignoreCase: true, out var status)
    && Enum.IsDefined(status))
{
    Console.WriteLine(status);
}

To rozróżnienie jest ważne, bo samo TryParse może zaakceptować również liczbę odpowiadającą wartości, której nie nazwano w enum. Przy danych z zewnątrz stosuję więc parsowanie razem z walidacją, a nie samo rzutowanie.

Konwersja do tekstu

Wywołanie ToString() zwykle zwróci nazwę elementu, na przykład "Paid". Nie traktowałbym jednak tej nazwy jako stabilnego kontraktu dla użytkownika. Zmiana nazwy w kodzie może zmienić dane zapisywane w logach, bazie lub komunikatach API.

OrderStatus status = OrderStatus.Paid;

string name = status.ToString();
int number = (int)status;

Jeżeli tekst ma być widoczny w interfejsie, lepiej użyć osobnej warstwy prezentacji, lokalizacji albo atrybutów opisowych. Nazwa programistyczna Cancelled nie zawsze powinna być wyświetlana użytkownikowi jako angielski komunikat.

Kiedy używać enum z atrybutem Flags

Zwykły enum opisuje jedną wartość z zestawu. Czasami potrzebujemy jednak zaznaczyć kilka niezależnych opcji jednocześnie, na przykład uprawnienia użytkownika albo cechy pliku. Do tego służy enum oznaczony [Flags].

[Flags]
public enum Permission
{
    None = 0,
    Read = 1,
    Write = 2,
    Delete = 4,
    Share = 8
}

Każda flaga powinna mieć własny bit, dlatego wartości zwykle są kolejnymi potęgami dwójki: 1, 2, 4, 8. Dzięki temu można je łączyć operatorem bitowym | bez nakładania się poszczególnych uprawnień.

Permission permissions = Permission.Read | Permission.Write;

bool canWrite = (permissions & Permission.Write) == Permission.Write;
bool canDelete = permissions.HasFlag(Permission.Delete);

Atrybut [Flags] nie zmienia sposobu przechowywania wartości i nie pilnuje poprawności liczb. Pomaga głównie w czytelnym formatowaniu wyniku oraz komunikuje innym programistom, że elementy można łączyć. Jeśli flagi nie mają sensu biznesowego, nie używałbym ich na siłę.

Przeczytaj również: Generyki w C# i .NET - jak pisać bezpieczniejszy kod?

Najczęstszy błąd przy flagach

Wartości takie jak Read = 1, Write = 2 i Delete = 3 są złym wyborem dla niezależnych flag. Liczba 3 oznacza już połączenie bitów 1 i 2, więc nie reprezentuje osobnej opcji.

[Flags]
public enum FileAccessMode
{
    None = 0,
    Read = 1,
    Write = 2,
    ReadWrite = Read | Write
}

Pozycja ReadWrite może być przydatna jako nazwany skrót, ale jej wartość powinna wynikać z połączenia istniejących flag. Taki zapis od razu pokazuje, że nie jest to trzeci niezależny bit.

Enum w API, bazie danych i serializacji

W aplikacji .NET enum często przekracza granicę procesu. Trafia do JSON-a, bazy danych, komunikatu kolejki albo publicznego API. Wtedy trzeba ustalić, czy kontrakt ma przechowywać liczby, czy nazwy.

Domyślna konfiguracja serializacji może zapisać enum jako liczbę. Jeśli API ma być czytelne dla innych systemów lub ludzi, często wybieram zapis tekstowy, ale pilnuję stabilności nazw. Zmiana Completed na Done może być zmianą łamiącą kontrakt, nawet jeśli dla kodu wewnętrznego wygląda niewinnie.

using System.Text.Json;
using System.Text.Json.Serialization;

var options = new JsonSerializerOptions();
options.Converters.Add(new JsonStringEnumConverter());

string json = JsonSerializer.Serialize(
    OrderStatus.Paid,
    options);

Przy bazie danych podobna decyzja zależy od używanego ORM-a i wymagań systemu. Liczby są kompaktowe, ale nazwy ułatwiają ręczną analizę danych. W systemach, które mają działać przez wiele lat, szczególnie uważałbym na zmienianie istniejących wartości liczbowych, bo stare rekordy mogą zacząć oznaczać coś innego.

Enum czy stałe i stringi

Enum najlepiej sprawdza się wtedy, gdy zestaw wartości jest znany, ograniczony i kontrolowany przez kod. Status płatności, poziom dostępu, rodzaj dokumentu czy tryb pracy to naturalne przykłady.

Nie używałbym enumu dla danych, które użytkownik może dynamicznie dodawać, na przykład listy kategorii produktów zarządzanej z panelu administracyjnego. W takim przypadku lepsza będzie tabela w bazie albo zwykła klasa domenowa. Enum jest wygodny właśnie dlatego, że jego wartości są częścią modelu aplikacji, a nie danymi zmienianymi bez wdrażania kodu.

Trzeba też pamiętać, że enum nie przechowuje dodatkowych właściwości. Jeśli każdy status ma opis, kod zewnętrzny, kolor i reguły biznesowe, prosty typ wyliczeniowy może szybko stać się zbyt ciasnym rozwiązaniem.

Jak rozsądnie stosować enum w codziennym kodzie

Najbezpieczniejszy schemat jest prosty. Definiuję wartości z jednoznacznymi nazwami, zostawiam świadomą wartość zero, nie zmieniam istniejących kodów używanych w trwałych danych i waliduję wszystko, co pochodzi spoza aplikacji.

• Używaj nazw opisujących znaczenie, na przykład PaymentStatus, a nie Type1.
• Dodaj None albo Unknown jako zero, jeśli obiekt może powstać bez ustawionej wartości.
• Nie porównuj enumów z magicznymi liczbami, gdy możesz użyć nazwanej wartości.
• Nie zmieniaj numerów elementów, które zostały zapisane w bazie lub wysłane do innych usług.
• Przy danych wejściowych korzystaj z TryParse i dodatkowej walidacji.
• Używaj [Flags] wyłącznie dla niezależnych opcji, które rzeczywiście można łączyć.

W mojej praktyce największą różnicę robi nie sama deklaracja enumu, ale konsekwencja na granicach systemu. Wewnątrz aplikacji nazwy poprawiają pracę z kodem, natomiast przy API i bazie trzeba jeszcze zadbać o stabilny kontrakt danych.

Od pierwszego enumu do bezpiecznego modelu domeny

Najkrócej mówiąc, enum w C# zastępuje nieczytelny zestaw liczb lub przypadkowych napisów nazwanym typem. Zyskujesz lepszą dokumentację kodu, podpowiedzi w IDE i większą ochronę przed pomyłkami, ale nadal musisz świadomie obsłużyć wartości domyślne, konwersje oraz kompatybilność.

Na początek wystarczy prosty enum statusu. Gdy zaczynasz przesyłać go przez API, zapisywać w bazie albo łączyć flagi, potraktuj go już jako część projektu danych, a nie wyłącznie wygodny skrót składniowy. To właśnie wtedy poprawne wartości, walidacja i stabilne nazewnictwo decydują o tym, czy rozwiązanie pozostanie czytelne także po kilku latach rozwoju.