Wprowadzę sobie PESEL o długości 15 znaków, a co, niech programiści sobie if’ują!
W wielu projektach, jak nie w każdym, zachodzi konieczność sprawdzenia, czy dane pole spełnia określone reguły narzucone przez potrzeby biznesowe, czy po prostu przez zdrową ludzką logikę. W prostych przypadkach dozwolony zakres danych narzucony jest przez typy zmiennych w typowanym języku programowania, jakim jest np. C#. Przez to nie możemy przypisać dowolnego tekstu do zmiennej całkowitoliczbowej. Co jednak jeżeli chcielibyśmy narzucić bardziej złożone ograniczenie, czy wtedy wszystko musimy sprawdzać ręczenie?
W tym wpisie przedstawię, czym jest DataAnnotations oraz gdzie znajduje zastosowanie przy budowaniu aplikacji internetowych w ASP.NET (MVC, czy też Core).
Co to DataAnnotations?
Data Annotations to zestaw atrybutów, które można przyporządkować do danego pola, najczęściej właściwości, w celu zdefiniowania warunku, jakie musi spełniać to pole. Dzięki temu możemy wymagać, aby jedno pole miało wartość z odpowiedniego przedziału (liczby od 1 do 100), albo wyraz miał dokładnie 11 cyfr, co zapobiegłoby problemowi opisanemu na samym początku wpisu. Platforma .NET dostarcza nam kilka wybranych atrybutów, jednak zawsze możemy stworzyć swoje własne, co opiszę w osobnym artykule.
Samo DataAnnotations to przestrzeń nazw (ang. namespace), ale potocznie tak samo nazywa się atrybuty, które definiują warunki pól. Podstawowe atrybuty znajdują się właśnie w tym namespace’się, tzn. w System.ComponentModel.DataAnnotations lub jego “odnóżach”.
Przykłady użycia DataAnnotations
Krótka demonstracja, jak używać DataAnnotations. Na początku zdefiniuję model klasy detektywa, który będzie składał się z podstawowych pól, takich jak wiek, imię i nazwisko, płeć oraz inne.
namespace PostDataAnnotations
{
public class Detective
{
public string FullName{ get; set; }
public string Email { get; set; }
public string Phone { get; set; }
public string Gender { get; set; }
public int Age { get; set; }
}
}
Dodam DataAnnotations, tak aby:
- FullName był wymagany (nie może przyjmować wartości null) oraz nie mógł być dłuższy od 100 znaków.
- Phone odpowiadał formatem numerowi telefonu.
- Email odpowiadał formatem adresowi e-mail oraz był wymagany.
- Gender mógł zawierać tylko dwie frazy: male oraz female.
- Age przyjmowało wartości od 1 do 120.
Po dodaniu atrybutów całość wygląda tak:
using System.ComponentModel.DataAnnotations;
namespace PostDataAnnotations
{
public class Detective
{
[Required]
[StringLength(100)]
public string FullName { get; set; }
[Required, EmailAddress]
public string Email { get; set; }
[Phone]
public string Phone { get; set; }
[Required]
[RegularExpression("male|female")]
public string Gender { get; set; }
[Range(1, 120)]
public int Age { get; set; }
}
}
Atrybuty można wpisywać jeden pod drugim (co w moim odczuciu jest bardziej przejrzyste), lub też po przecinku jeden za drugim, jak zostało pokazane przy polu Email. Atrybuty odnoszą się do pola znajdującego się poniżej. Do jednego pola może być przypisanych wiele atrybutów.
Gdy wprowadzamy dane poprawienie model zachowuje zgodność zdefiniowanych warunków.
"FullName": "Bolek Wąski", "Email": "adress@email.com", "Phone": "434123456", "Gender": "male", "Age": 12
Gdy wprowadzimy dane nieprawidłowo:
public Detective Get()
{
var detective = new Detective
{
Age = 121,
Gender = "fmale",
Phone = "123123aaa",
Email = "asdasd.com",
};
return detective;
}
np. przy przesyłaniu danych żądaniem HTTP POST w celu zapisu, otrzymujemy wiadomości o błędach oraz niepoprawny kod HTTP:
"Age": [ "The field Age must be between 1 and 120." ], "Email": [ "The Email field is not a valid e-mail address." ], "Phone": [ "The Phone field is not a valid phone number." ], "Gender": [ "The field Gender must match the regular expression 'male|female'." ], "FullName": [ "The FullName field is required." ]
Uwaga
Należy zauważyć, że platforma .NET nie uniemożliwia przypisania do obiektu nieprawidłowych danych. Wartości mogą zostać przypisane w sposób nieodpowiedni, jednak atrybuty te są bardzo przydatne w sytuacjach opisanych poniżej w zastosowaniach.
Zastosowania
DataAnnotations warto stosować w przypadku:
- Wstępnej walidacji modelu przesyłanego do kontrolera w żądaniach HTTP. Używa się tutaj ModelState, co opisałem w poprzednim wpisie.
- Definiowania węzłów integralnościowych (np. kluczy, unikalnej wartości, not null, itp. ) bazy danych w Entity Framework Code First. Tutaj często stosuje się przestrzeń nazw System.ComponentModel.DataAnnotations.Schema.
- Wyświetlania wiadomości błędów niepoprawnych pól modelu w widokach napisanych za pomocą silnika Razor.
Podsumowanie
Niemal zawsze sprawdza się poprawność danych. Dzięki wykorzystaniu atrybutów pozbywamy się w kodzie niepotrzebnego sprawdzania wartości. Dodatkowo istniej możliwość tworzenia własnych warunków, co jeszcze bardziej uporządkowuje kod. Korzystanie z DataAnnotations nie powoduje, że nie możemy przypisać złych danych, dzięki czemu mamy możliwość ich przetwarzania, jeżeli tego potrzebujemy, gdy np. chcielibyśmy analizować najczęściej popełniane błędy przez użytkowników.
