Reguły projektowania

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

W tej sekcji

Reguła	Opis
CA1000: Nie deklaruj statycznych elementów członkowskich dla typów ogólnych	Gdy jest wywoływany statyczny element członkowski typu ogólnego, argument typu musi być określony dla typu. Jeśli wywoływany jest ogólny członek instancji, który nie obsługuje wnioskowania, argument typu musi być określony dla tego członka. W tych dwóch przypadkach składnia określania argumentu typu jest inna i łatwo może prowadzić do pomyłek.
CA1001: Typy, które posiadają pola jednorazowe, powinny być jednorazowe	Klasa deklaruje i implementuje pole instancji typu System.IDisposable, ale sama nie implementuje interfejsu IDisposable. Klasa, która deklaruje pole IDisposable pośrednio jest właścicielem niezarządzanego zasobu i powinna zaimplementować interfejs IDisposable.
CA1002: Nie ujawniaj list ogólnych	System.Collections.Generic.List<(Of <(T>)>) to kolekcja ogólna zoptymalizowana pod kątem wydajności, a nie pod kątem dziedziczenia. W związku z tym Lista nie zawiera żadnych wirtualnych członków. Kolekcje ogólne przeznaczone do dziedziczenia powinny być udostępnione.
CA1003: Użyj ogólnych wystąpień programu obsługi zdarzeń	Typ zawiera delegata, który nie zwraca wartości, a którego podpis zawiera dwa parametry (pierwszy to obiekt, a drugi to typ, który można przypisać do klasy EventArgs), a zawierający go zestaw jest zgodny ze środowiskiem .NET Framework 2.0.
CA1005: Unikaj nadmiernych parametrów dla typów ogólnych	Tym bardziej parametry typu zawiera typ ogólny, tym trudniej jest wiedzieć i zapamiętać, co reprezentuje każdy parametr typu. Zwykle jest to oczywiste z jednym parametrem typu, jak w list<T>, a w niektórych przypadkach z dwoma parametrami typu, jak w słowniku<TKey, TValue>. Jeśli jednak istnieje więcej niż dwa parametry typu, trudność staje się zbyt duża dla większości użytkowników.
CA1008: Wyliczenia powinny mieć wartość zerową	Wartość domyślna niezainicjowanego wyliczenia, podobnie jak inne typy wartości, wynosi zero. Wyliczenie, które nie używa atrybutu flag, powinno definiować element członkowski przy użyciu wartości zero, aby wartość domyślna była prawidłową wartością wyliczenia. Jeśli wyliczenie z zastosowanym atrybutem FlagsAttribute definiuje element członkowski o wartości zerowej, jego nazwa powinna być "None", aby wskazać, że w wyliczeniu nie ustawiono żadnych wartości.
CA1010: Kolekcje powinny implementować interfejs ogólny	Aby poszerzyć użyteczność kolekcji, zaimplementuj jeden z ogólnych interfejsów kolekcji. Następnie można użyć kolekcji do wypełniania typów kolekcji ogólnych.
CA1012: Typy abstrakcyjne nie powinny mieć publicznych konstruktorów	Konstruktory w typach abstrakcyjnych mogą być wywoływane tylko przez typy pochodne. Ponieważ konstruktory publiczne tworzą wystąpienia typu i nie można tworzyć wystąpień typu abstrakcyjnego, typ abstrakcyjny, który ma konstruktor publiczny, jest niepoprawnie zaprojektowany.
CA1014: Oznacz zestawy atrybutem CLSCompliantAttribute	Specyfikacja języka wspólnego (CLS) definiuje ograniczenia nazewnictwa, typy danych i reguły, z którymi zestawy muszą być zgodne, jeśli będą używane w różnych językach programowania. Dobra praktyka projektowa wymaga, aby wszystkie zestawy w sposób jawny wskazywały zgodność z CLS za pomocą CLSCompliantAttribute. Jeśli ten atrybut nie jest obecny w zestawie, zestaw nie jest zgodny.
CA1016: Oznacz zestawy za pomocą atrybutu AssemblyVersionAttribute	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 wersjonowania i polityki wydawniczej. Domyślnie aplikacje są uruchamiane tylko z wersją zestawu, z którą zostały skompilowane.
CA1017: Oznaczanie zestawów z użyciem atrybutu ComVisibleAttribute	ComVisibleAttribute określa, jak klienci COM uzyskują dostęp do kodu zarządzanego. Dobry projekt określa, że zestawy jawnie wskazują widoczność modelu COM. Widoczność COM można ustawić dla całego zestawu, a następnie zastąpić ją dla poszczególnych typów i członków typu. Jeśli ten atrybut nie jest obecny, zawartość zestawu jest widoczna dla klientów COM.
CA1018: Oznacz atrybuty za pomocą AttributeUsageAttribute	Podczas definiowania atrybutu niestandardowego oznacz go za pomocą atrybutu AttributeUsageAttribute, aby wskazać, gdzie w kodzie źródłowym można zastosować atrybut niestandardowy. Znaczenie i zamierzone użycie atrybutu określi prawidłowe lokalizacje w kodzie.
CA1019: Definiowanie akcesorów dla argumentów atrybutów	Atrybuty mogą definiować obowiązkowe argumenty, które należy określić podczas stosowania atrybutu do elementu docelowego. Są one również nazywane argumentami pozycyjnymi, ponieważ są one dostarczane do konstruktorów atrybutów jako parametry pozycyjne. Dla każdego obowiązkowego argumentu atrybut powinien również podać odpowiednią właściwość tylko do odczytu, aby można było pobrać wartość argumentu w czasie wykonywania. Atrybuty mogą również definiować opcjonalne argumenty, nazywane również nazwami argumentów. Te argumenty są dostarczane do konstruktorów atrybutów według nazwy i powinny mieć odpowiednią właściwość odczytu/zapisu.
CA1021: Unikaj parametrów	Przekazywanie typów według odwołania (przy użyciu out lub ref) wymaga doświadczenia ze wskaźnikami, zrozumienia różnic typów wartości i typów odwołań oraz obsługi metod z wieloma wartościami zwracanymi. Ponadto różnica między parametrami out i ref nie jest powszechnie rozumiana.
CA1024: użyj właściwości tam, gdzie jest to odpowiednie	Metoda publiczna lub chroniona ma nazwę rozpoczynającą się od "Get", nie przyjmuje parametrów i zwraca wartość, która nie jest tablicą. Metoda może być dobrym kandydatem do stania się atrybutem.
CA1027: oznaczanie wyliczenia za pomocą FlagsAttribute	Wyliczenie to typ wartości, który definiuje zestaw powiązanych nazwanych stałych. Zastosuj atrybut FlagsAttribute do wyliczenia, gdy można sensownie łączyć jego nazwane stałe.
CA1028: Magazyn wyliczenia powinien mieć wartość 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 stałej wartości. Mimo że można zmienić ten typ bazowy, nie jest to wymagane ani zalecane w przypadku większości scenariuszy.
CA1030: Korzystaj ze zdarzeń, tam gdzie to odpowiednie	Ta reguła wykrywa metody, które mają nazwy, które zwykle będą używane dla zdarzeń. Jeśli metoda jest wywoływana w odpowiedzi na jasno zdefiniowaną zmianę stanu, metoda powinna być wywoływana przez program obsługi zdarzeń. Obiekty wywołujące metodę powinny zgłaszać zdarzenia zamiast bezpośrednio wywoływać metodę.
CA1031: Nie przechwytuj ogólnych typów wyjątków	Wyjątki ogólne nie powinny być przechwytywane. Przechwyć bardziej szczegółowy wyjątek lub ponownie wprowadź ogólny wyjątek jako ostatnią instrukcję w bloku catch.
CA1032: Implementowanie standardowych konstruktorów wyjątków	Brak zapewnienia pełnego zestawu konstruktorów może utrudnić poprawną obsługę wyjątków.
CA1033: Metody interfejsu powinny być wywoływane przez typy podrzędne	Niezapieczętowany typ widoczny zewnętrznie dostarcza jawną implementację metody interfejsu publicznego i nie dostarcza alternatywnej metody widocznej zewnętrznie o tej samej nazwie.
CA1034: Typy zagnieżdżone nie powinny być widoczne	Typ zagnieżdżony to taki, który jest zadeklarowany w obrębie innego typu. Typy zagnieżdżone są przydatne do hermetyzacji prywatnych szczegółów implementacji typu, który zawiera. W tym celu zagnieżdżone typy nie powinny być widoczne zewnętrznie.
CA1036: Nadpisywanie metod dla porównywalnych typów	Typ publiczny lub chroniony implementuje interfejs System.IComparable. Nie zastępuje metody Object.Equals ani nie przeciąża operatora specyficznego dla języka w zakresie równości, nierówności, mniejszości lub większości.
CA1040: Unikaj pustych interfejsów	Interfejsy definiują członków, którzy określają zachowanie lub kontrakt użycia. Funkcjonalność opisana przez interfejs może zostać przyjęta przez dowolny typ, niezależnie od tego, gdzie typ pojawia się w hierarchii dziedziczenia. Typ implementuje interfejs, zapewniając implementacje dla składowych interfejsu. Pusty interfejs nie definiuje żadnych elementów członkowskich; w związku z tym nie definiuje kontraktu, który można wdrożyć.
CA1041: podaj komunikat ObsoleteAttribute	Typ lub człon jest oznaczony za pomocą atrybutu System.ObsoleteAttribute bez 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żyj argumentu całkowitego lub ciągu dla indeksatorów	Indeksatory (czyli właściwości indeksowane) powinny używać typów całkowitych lub ciągów dla indeksu. Te typy są zwykle używane do indeksowania struktur danych i zwiększają użyteczność biblioteki. Użycie typu obiektu powinno być ograniczone do tych przypadków, w których nie można określić określonego typu całkowitego lub ciągu w czasie projektowania.
CA1044: Właściwości nie powinny być zapisywane tylko	Chociaż dopuszczalne i często konieczne jest posiadanie właściwości tylko do odczytu, wytyczne projektowe zabraniają używania właściwości tylko do zapisu. Jest to spowodowane tym, że umożliwienie użytkownikowi ustawienia wartości, a następnie uniemożliwienie użytkownikowi wyświetlania tej wartości nie zapewnia żadnych zabezpieczeń. Ponadto bez dostępu do odczytu nie można wyświetlić stanu obiektów udostępnionych, co ogranicza ich użyteczność.
CA1045: Nie przekazuj typów przez referencję	Przekazywanie typów według odwołania (przy użyciu out lub ref) wymaga doświadczenia ze wskaźnikami, zrozumienia różnic typów wartości i typów odwołań oraz 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 dla typów odwołań	W przypadku typów referencyjnych 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 chronionych elementów członkowskich w typach zapieczętowanych	Typy deklarują chronione elementy członkowskie, aby dziedziczone typy mogły uzyskiwać dostęp do elementów członkowskich lub je przesłaniać. Z definicji nie można dziedziczyć zapieczętowanych typów, co oznacza, że nie można wywoływać metod chronionych w typach zapieczętowanych.
CA1050: deklarowanie typów w przestrzeniach nazw	Typy są deklarowane w przestrzeniach nazw, aby zapobiec kolizjom nazw i jako sposób organizowania powiązanych typów w hierarchii obiektów.
CA1051: nie deklaruj widocznych pól instancji	Podstawowym zastosowaniem pola powinno być pełnienie funkcji szczegółu implementacyjnego. Pola powinny być prywatne lub wewnętrzne i powinny być uwidocznione za pomocą właściwości.
CA1052: Typy statycznych uchwytów powinny być zapieczętowane	Typ publiczny lub chroniony zawiera tylko statyczne elementy członkowskie i nie jest zadeklarowany przy użyciu modyfikatora sealed (C#) lub NotInheritable (Visual Basic). Typ, który nie ma być dziedziczony, powinien być oznaczony przy użyciu modyfikatora zapieczętowanego, aby zapobiec jego użyciu jako typ podstawowy.
CA1053: Statyczne typy nie powinny mieć konstruktorów	Publiczny lub zagnieżdżony typ publiczny deklaruje tylko statyczne składniki i ma konstruktor domyślny, który jest publiczny lub chroniony. Konstruktor jest niepotrzebny, ponieważ wywoływanie statycznych członków nie wymaga instancji tego typu. Przeciążenie ciągu powinno wywołać przeciążenie identyfikatora URI (Uniform Resource Identifier) przy użyciu argumentu ciągu dla bezpieczeństwa i zabezpieczeń.
CA1054: parametry identyfikatora URI nie powinny być ciągami	Jeśli metoda przyjmuje reprezentację ciągu identyfikatora URI, należy podać odpowiednie przeciążenie, które przyjmuje wystąpienie klasy URI, która zapewnia te usługi w bezpieczny i bezpieczny sposób.
CA1055: zwracane wartości identyfikatora URI nie powinny być ciągami	Ta reguła zakłada, że metoda zwraca identyfikator URI. Reprezentacja łańcucha URI jest podatna na błędy analizy i kodowania, co może prowadzić do luk w zabezpieczeniach. Klasa System.Uri zapewnia te usługi w bezpieczny i 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 znaków URI jest podatna na błędy analizowania i kodowania, co może prowadzić do luk w zabezpieczeniach. Klasa System.Uri zapewnia te usługi w bezpieczny i bezpieczny sposób.
CA1058: Typy nie powinny rozszerzać niektórych typów bazowych	Typ widoczny zewnętrznie rozszerza niektóre typy podstawowe. Użyj jednej z alternatyw.
CA1060: Przenieś P/Invokes do klasy NativeMethods	Metody wywołania platformy, takie jak te oznaczone za pomocą System.Runtime.InteropServices.DllImportAttribute lub zdefiniowane przy użyciu słowa kluczowego Declare w Visual Basic, uzyskują dostęp do niezarządzanego kodu. Te metody powinny być klasy NativeMethods, SafeNativeMethods lub UnsafeNativeMethods.
CA1061: Nie ukrywaj metod klas bazowych	Metoda w typie podstawowym jest ukryta przez identycznie nazwaną metodę w typie pochodnym, gdy podpis parametru metody pochodnej różni się tylko od typów, które są bardziej słabo pochodne niż odpowiadające im typy w podpisie parametru metody podstawowej.
CA1062: Weryfikowanie argumentów metod publicznych	Wszystkie argumenty odwołania przekazywane do metod widocznych zewnętrznie powinny być sprawdzane pod kątem wartości null.
CA1063: Zaimplementuj interfejs IDisposable poprawnie	Wszystkie typy IDisposable powinny poprawnie zaimplementować wzorzec Dispose.
CA1064: Wyjątki powinny być publiczne	Wyjątek wewnętrzny jest widoczny tylko wewnątrz własnego zakresu wewnętrznego. Gdy wyjątek wystąpi poza zakresem wewnętrznym, można użyć tylko wyjątku podstawowego, aby go przechwycić. 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, która nie powinna zgłaszać wyjątków, zgłasza wyjątek.
CA1066: Implementowanie funkcji IEquatable podczas zastępowania wartości Equals	Typ wartości zastępuje metodę Equals, ale nie implementuje IEquatable<T>.
CA1067: Nadpisz Equals podczas implementowania IEquatable	Typ implementuje IEquatable<T>, ale nie zastępuje metody Equals.
CA1068: Parametry CancellationToken muszą znajdować się na końcu	Metoda ma parametr CancellationToken, który nie jest ostatnim parametrem.
CA1069: Wyliczenia nie powinny mieć zduplikowanych wartości	Wyliczenie ma wiele elementów, które są jawnie przypisane tej samej wartości stałej.
CA1070: Nie deklaruj pól zdarzeń jako wirtualne	Zdarzenie podobne do pola zostało zadeklarowane jako wirtualne.