Reguły projektowania

Reguły projektowania obsługują przestrzeganie wytycznych dotyczących projektowania programu .NET Framework.

W tym obszarze

Reguła	opis
CA1000: Nie deklaruj składowych statycznych w typach ogólnych	Po wywołaniu statycznego elementu członkowskiego typu ogólnego dla typu trzeba określić argument typu. Po wywołaniu wystąpienia ogólnego elementu członkowskiego, które nie obsługuje wnioskowania, dla elementu członkowskiego musi zostać określony argument typu. W tych dwóch przypadkach składnia określająca argument typu jest różna i łatwo o pomyłkę.
CA1001: Typy z polami możliwymi do likwidacji powinny być możliwe do likwidacji	Klasa deklaruje i implementuje pole wystąpienia, które jest typem System.IDisposable, a klasa nie implementuje interfejsu IDisposable. Klasa, która deklaruje pole IDisposable, pośrednio posiada niezarządzany zasób i powinna implementować interfejs IDisposable.
CA1002: Nie ujawniaj list ogólnych	System.Collections.Generic.List<(Of <(T>)>) to kolekcja ogólna przeznaczona do wydajności, a nie dziedziczenia. Dlatego też lista nie zawiera wirtualnych elementów członkowskich. Zamiast powyższych powinny zostać zastosowane kolekcje ogólne, zaprojektowane do obsługi dziedziczenia.
CA1003: Użyj wystąpień ogólnej procedury obsługi zdarzeń	Typ zawiera delegata zwracającego wartość void, którego podpis zawiera dwa parametry (pierwszy obiekt i drugi typ, który można przypisać do klasy EventArgs) oraz zawierające obiekty docelowe zestawu .NET Framework 2.0.
CA1005: Unikaj nadużywania parametrów w typach ogólnych	Im więcej parametrów typu zawiera typ ogólny, tym trudniej poznać i zapamiętać, co reprezentuje każdy z nich. Zwykle jest to oczywiste z jednym parametrem typu, jak w liście<T>, a w niektórych przypadkach z dwoma parametrami typu, jak w słowniku<TKey, TValue>. Jeśli jednak istnieją więcej niż dwa parametry typu, poziom trudności staje się zbyt wysoki dla większości użytkowników.
CA1008: Wyliczenia powinny zawierać wartość zero	Wartość domyślna niezainicjowanego typu wyliczeniowego, podobnie jak inne typy wartości, wynosi zero. Wyliczenie atrybutu nonflags powinno definiować element członkowski przy użyciu wartości zero, aby wartość domyślna jest prawidłową wartością wyliczenia. Jeśli wyliczenie, w którym zastosowano atrybut FlagsAttribute, definiuje element członkowski o wartości zero, powinno być nazwane „Brak”, aby wskazać, że żadne wartości nie zostały ustawione w wyliczeniu.
CA1010: Kolekcje powinny implementować interfejs ogólny	Aby poszerzyć użyteczność kolekcji, zaimplementuj jeden z interfejsów kolekcji generycznej. Następnie kolekcja może zostać użyta, aby wypełnić typy generyczne kolekcji.
CA1012: Typy abstrakcyjne nie powinny mieć publicznych konstruktorów	Konstruktory dla typów abstrakcyjnych mogą być wywoływane tylko przez typy pochodne. Ze względu na to, że publiczne konstruktory tworzą wystąpienia typu, a nie można utworzyć wystąpienia typu abstrakcyjnego, publiczny konstruktor typu abstrakcyjnego został niepoprawnie zaprojektowany.
CA1014: Oznacz zestawy atrybutem CLSCompliant	The Common Language Specification (CLS) definiuje ograniczenia nazw, typów danych i reguł, z którymi muszą być zgodne zestawy, jeśli zostaną użyte w językach programowania. Dobry projekt określa, że wszystkie zestawy jawnie wskazują zgodność CLS przy użyciu CLSCompliantAttribute. Jeśli ten atrybut nie jest obecny w zestawie, oznacza to, że zestaw jest niezgodny.
CA1016: Oznacz zestawy atrybutem AssemblyVersion	Platforma .NET używa numeru wersji w celu unikatowego zidentyfikowania zestawu i powiązania z typami w silnie nazwanych zestawach. Numer wersji jest używany razem z zasadami wersji i wydawcy. Domyślnie aplikacje są uruchamiane tylko z wersji zestawu, z którego zostały zbudowane.
CA1017: Oznacz zestawy atrybutem ComVisibleAttribute	ComVisibleAttribute określa, w jaki sposób klienci COM otrzymują dostęp do kodu zarządzanego. Zasada dobrego projektowania nakazuje, aby zestawy jawnie wskazywały widoczność COM. Widoczność COM można ustawić dla całego zestawu, a następnie zastąpić dla poszczególnych typów i elementów członkowskich typu. Jeśli ten atrybut jest nieobecny, zawartość zestawu jest widoczna dla klientów COM.
CA1018: Oznacz atrybuty atrybutem AttributeUsage	Podczas definiowania atrybutu niestandardowego należy go oznaczyć przy użyciu elementu AttributeUsageAttribute, aby wskazać, w którym miejscu kodu źródłowego ma być on zastosowany. Znaczenie i zamierzone użycie atrybutu określi jego prawidłowe lokalizacje w kodzie.
CA1019: Zdefiniuj metody dostępu dla argumentów atrybutu	Atrybuty mogą definiować obowiązkowe argumenty, które trzeba określić, aby móc zastosować atrybut do obiektu docelowego. Znane są również jako argumenty pozycyjne, ponieważ są one dostarczane do konstruktorów atrybutu jako parametry pozycyjne. Dla każdego obowiązkowego argumentu atrybut powinien również dostarczyć odpowiadającą właściwość tylko do odczytu, dzięki której można pobrać wartość argumentu w czasie wykonywania. Atrybuty mogą też definiować argumenty opcjonalne, które są znane również jako argumenty nazwane. Argumenty te są dostarczane do konstruktorów atrybutu poprzez nazwę i powinny mieć odpowiadającą właściwość umożliwiającą odczyt i zapis.
CA1021: Unikaj parametrów out	Przekazywanie typów przez odwołanie (używając out lub ref) wymaga doświadczenia w zakresie wskaźników, rozumienia różnicy między typami wartości i typami odwołania oraz umiejętności obsługi metod z wieloma wartościami zwracanymi. Ponadto różnica między parametrami out i ref nie jest powszechnie zrozumiała.
CA1024: Używaj właściwości wszędzie tam, gdzie jest to odpowiednie	Metody publiczne lub chronione mają nazwę zaczynającą się od „Get”, nie posiadają parametrów i zwracają wartość, która nie jest tablicą. Metoda ta może być dobrym kandydatem na właściwość.
CA1027: Oznacz typy wyliczeniowe atrybutem Flags	Wyliczenie to typ wartości, który definiuje zestaw powiązanych, nazwanych stałych. Zastosuj atrybut FlagsAttribute do wyliczenia, gdy jego stałe nazwane mogą zostać sensownie połączone.
CA1028: Magazyn typu wyliczeniowego powinien być typu Int32	Wyliczenie to typ wartości, który definiuje zestaw powiązanych, nazwanych stałych. Domyślnie typ danych System.Int32 jest używany do przechowywania wartości stałej. Mimo że można zmienić ten typ bazowy, nie jest to wymagane ani zalecane w przypadku większości scenariuszy.
CA1030: Używaj zdarzeń wszędzie tam, gdzie jest to odpowiednie	Ta reguła wykrywa metody o nazwach, które normalnie mogą być używane dla zdarzeń. Jeśli metoda jest wywoływana w odpowiedzi na jasno określoną zmianę stanu, powinna ona zostać wywołana przez program obsługi zdarzeń. Obiekty, które wywołują tę metodę, powinny wywoływać zdarzenia, a nie bezpośrednio metodę.
CA1031: Nie przechwytuj ogólnych typów wyjątków	Ogólne wyjątki nie powinny być przechwytywane. Przechwyć bardziej szczegółowy wyjątek lub ponownie wprowadź ogólny wyjątek jako ostatnią instrukcję w bloku catch.
CA1032: Zaimplementuj standardowe konstruktory wyjątku	Niepowodzenie podczas dostarczenia pełnego zestawu konstruktorów może utrudnić poprawną obsługę wyjątków.
CA1033: Typy podrzędne powinny móc wywoływać metody interfejsu	Niezapieczętowany typ widoczny na zewnątrz zapewnia jawną implementację metody interfejsu publicznego i nie dostarcza alternatywnej metody widocznej z zewnątrz o tej samej nazwie.
CA1034: Typy zagnieżdżone nie powinny być widoczne	Typ zagnieżdżony to typ, który jest zadeklarowany wewnątrz zakresu innego typu. Typy zagnieżdżone są przydatne w przypadku hermetyzacji szczegółów implementacji prywatnej typu zawierającego. Używane w tym celu typy zagnieżdżone nie powinny być widoczne na zewnątrz.
CA1036: Przesłoń metody dla typów obsługujących porównywanie	Typ publiczny lub chroniony implementuje interfejs System.IComparable. Nie zastępuje on metody Object.Equals ani nie przeciąża specyficznego dla języka operatora równości, nierówności, mniejsze lub większe niż.
CA1040: Unikaj pustych interfejsów	Interfejsy definiują elementy członkowskie, które zapewniają zachowanie lub użycie kontraktu. Funkcjonalność opisana przez interfejs może zostać przyjęta przez dowolny typ, niezależnie od tego, gdzie ten typ się pojawia w hierarchii dziedziczenia. Typ implementuje interfejs, dostarczając implementacje dla jego elementów członkowskich. Pusty interfejs nie definiuje żadnych elementów członkowskich; dlatego też nie definiuje kontraktu, który można zaimplementować.
CA1041: Określ komunikat ObsoleteAttribute	Typ lub element członkowski jest oznaczony za pomocą atrybutu System.ObsoleteAttribute, który nie ma określonej właściwości ObsoleteAttribute.Message. Gdy typ lub element członkowski oznaczony przy użyciu przestarzałego atrybutu jest kompilowany, zostanie wyświetlona właściwość Message atrybutu, która daje użytkownikowi informacje o przestarzałym typie lub elemencie członkowskim.
CA1043: Używaj argumentu integral lub string dla indeksatorów	Indeksatory (właściwości indeksowane) powinny używać dla indeksu typów całkowitych lub ciągu. Typy te są zwykle używane do indeksowania struktur danych i zwiększają one użyteczność biblioteki. Użycie typu Object powinno zostać ograniczone do przypadków, w których nie może zostać określony typ całkowity lub ciąg w czasie projektowania.
CA1044: Właściwości nie powinny być tylko do zapisu	Chociaż posiadanie właściwości tylko do odczytu jest dopuszczalne i często konieczne, wytyczne projektowania zabraniają używania właściwości tylko do zapisu. Dzieje się tak dlatego, że umożliwienie użytkownikowi ustawienia wartości, a następnie uniemożliwianie przeglądania tej wartości nie zapewnia żadnych zabezpieczeń. Poza tym bez dostępu do odczytu nie można przeglądać stanu obiektów udostępnionych, co ogranicza ich przydatność.
CA1045: Nie przekazuj typów przez odwołanie	Przekazywanie typów przez odwołanie (używając out lub ref) wymaga doświadczenia w zakresie wskaźników, rozumienia różnicy między typami wartości i typami odwołania oraz umiejętności obsługi metod z wieloma wartościami zwracanymi. Architekci bibliotek, którzy projektują dla odbiorców ogólnych, nie powinni oczekiwać, że użytkownicy będą biegłi w pracy z parametrami out lub ref.
CA1046: Nie przeciążaj operatora równości w typach referencyjnych	Dla typów odwołań domyślna implementacja operatora równości jest prawie zawsze poprawna. Domyślnie dwa odwołania są równe tylko wtedy, gdy wskazują ten sam obiekt.
CA1047: Nie deklaruj składowych chronionych w typach zapieczętowanych	Chronione elementy członkowskie są zadeklarowane w typach tak, aby typy dziedziczące miały dostęp do elementu członkowskiego i mogły go zastąpić. Z definicji po typach zapieczętowanych nie można dziedziczyć, co oznacza, że nie można wywołać metody chronionej na typach zapieczętowanych.
CA1050: Deklaruj typy w przestrzeniach nazw	Typy są zadeklarowane w przestrzeniach nazw, aby zapobiec kolizjom nazw oraz jako sposób organizowania typów powiązanych w hierarchii obiektów.
CA1051: Nie deklaruj widocznych pól wystąpienia	Głównym zastosowaniem pola powinno być to, co szczegółowo opisuje implementacja. Pola powinny być prywatne lub wewnętrzne i dostępne przy użyciu właściwości.
CA1052: Statyczne typy przechowujące powinny być zapieczętowane	Typ publiczny lub chroniony zawiera tylko statyczne elementy członkowskie i nie jest zadeklarowany przy użyciu modyfikatora zapieczętowanego (C#) lub NotInheritable (Visual Basic). Typ, po którym nie będzie dziedziczenia, powinien być oznakowany przy użyciu modyfikatora sealed, aby zapobiec użyciu go jako typu podstawowego.
CA1053: Statyczne typy przechowujące nie powinny mieć konstruktorów	Typ publiczny lub publiczny zagnieżdżony deklaruje tylko statyczne elementy członkowskie i ma publiczny lub chroniony konstruktor domyślny. Konstruktor jest zbędny, ponieważ wywołanie statycznego elementu członkowskiego nie wymaga wystąpienia tego typu. Przeciążenie typu ciąg powinno wywoływać, dla bezpieczeństwa, przeciążenie jednolitego identyfikatora zasobów (URI) przy użyciu argumentu typu ciąg.
CA1054: Parametry identyfikatora URI nie powinny być ciągami	Jeśli metoda pobiera reprezentację ciągu identyfikatora URI, powinno zostać dostarczone odpowiadające przeciążenie, pobierające wystąpienie klasy URI, które dostarcza te usługi w bezpieczny sposób.
CA1055: Wartości zwracane identyfikatora URI nie powinny być ciągami	Reguła ta zakłada, że metoda zwraca identyfikator URI. Reprezentacja ciągu identyfikatora URI jest podatna na analizowanie i kodowanie błędów i może prowadzić do powstawania luk w zabezpieczeniach. Klasa System.Uri udostępnia te usługi w bezpieczny sposób.
CA1056: Właściwości identyfikatora URI nie powinny być ciągami	Ta reguła zakłada, że właściwość reprezentuje identyfikator URI. Reprezentacja ciągu identyfikatora URI jest podatna na analizowanie i kodowanie błędów i może prowadzić do powstawania luk w zabezpieczeniach. Klasa System.Uri udostępnia te usługi w bezpieczny sposób.
CA1058: Typy nie powinny rozszerzać pewnych typów podstawowych	Typ widoczny na zewnątrz rozszerza niektóre typy podstawowe. Użyj jednej z alternatyw.
CA1060: Przenieś wywołania P/Invoke do klasy NativeMethods	Metody wywołania platformy, takie jak metody oznaczone System.Runtime.InteropServices.DllImportAttribute za pomocą metod lub zdefiniowane za pomocą słowa kluczowego Declare w języku Visual Basic, uzyskują dostęp do niezarządzanych kodów. Metody te powinny być klasami NativeMethods, SafeNativeMethods lub UnsafeNativeMethods.
CA1061: Nie ukrywaj metod klasy podstawowej	Metoda w typie podstawowym jest ukryta przez metodę o identycznej nazwie typu pochodnego, gdy sygnatura parametru metody pochodnej różni się tylko typami, które są słabiej dziedziczone niż odpowiadające typy w sygnaturze parametru metody podstawowej.
CA1062 Zweryfikuj argumenty metod publicznych	Wszystkie argumenty odwołania, które są przekazywane do metody widocznej na zewnątrz, powinny być sprawdzane pod kątem wartości null.
CA1063: Zaimplementuj poprawnie interfejs IDisposable	Wszystkie typy IDisposable powinny poprawnie implementować wzorzec Dispose.
CA1064: Wyjątki powinny być publiczne	Wyjątek wewnętrzny jest widoczny tylko wewnątrz własnego zakresu wewnętrznego. W przypadku wystąpienia wyjątku poza zakresem wewnętrznym tylko wyjątek podstawowy może zostać użyty do jego przechwycenia. Jeśli wyjątek wewnętrzny jest dziedziczony z System.Exception, System.SystemExceptionlub System.ApplicationException, kod zewnętrzny nie będzie miał wystarczających informacji, aby wiedzieć, co zrobić z wyjątkiem.
CA1065: Nie zgłaszaj wyjątków w nieoczekiwanych lokalizacjach	Metoda, od której nie oczekiwano zgłaszania wyjątków, zgłasza wyjątek.
CA1066: Implementowanie funkcji IEquatable podczas zastępowania wartości Equals	Typ wartości zastępuje metodę, ale nie implementuje EqualsIEquatable<T>metody .
CA1067: Zastępowanie równości podczas implementowania funkcji IEquatable	Typ implementuje metodę IEquatable<T>, ale nie zastępuje Equals metody.
CA1068: Parametry CancellationToken muszą być ostatnie	Metoda ma parametr CancellationToken, który nie jest ostatnim parametrem.
CA1069: Wyliczenia nie powinny mieć zduplikowanych wartości	Wyliczenie ma wiele elementów członkowskich, które są jawnie przypisane do tej samej wartości stałej.
CA1070: Nie deklaruj pól zdarzeń jako wirtualne	Zdarzenie podobne do pola zostało zadeklarowane jako wirtualne.