Ostrzeżenia projektu
Ostrzeżenia projektu wspierające przestrzeganie Wytycznych Projektu .NET Framework.
W tej sekcji
Reguła |
Opis |
|---|---|
CA1000: Nie deklaruj statycznych elementów członkowskich na typach generycznych |
Po wywołaniu statycznego elementu członkowskiego typu generycznego, argument typu musi zostać określony dla typu.Po wywołaniu wystąpienia generycznego elementu członkowskiego, który nie obsługuje wnioskowania, argument typu musi zostać określony dla elementu członkowskiego.W tych dwóch przypadkach składnia określająca argument typu jest różna i łatwo o pomyłkę. |
CA1001: Typy, które posiadają pola usuwalne, powinny być usuwalne |
Klasa deklaruje i implementuje pole wystąpienia typu System.IDisposable i klasa ta nie implementuje interfejsu IDisposable.Klasa, która deklaruje pole IDisposable pośrednio posiada niezarządzany zasób i powinna implementować interfejs IDisposable. |
System.Collections.Generic.list<(Z <(T>)>) jest kolekcją generyczną, zaprojektowaną z myślą o wydajności, nie dziedziczeniu.Dlatego też element List nie zawiera wirtualnych elementów członkowskich.Zamiast powyższych powinny zostać zastosowane kolekcje generyczne, które zostały zaprojektowane do obsługi dziedziczenia. |
|
Typ zawiera pełnomocnika zwracającego wartość typu void, którego podpis zawiera dwa parametry (pierwszy typu obiekt i drugi typu, który można przypisać do EventArgs) i zawierający zestaw odwołujący się do Program .NET Framework 2,0. |
|
Wnioskowanie to ustalenie argumentu typu metody generycznej poprzez typ argumentu przekazanego do metody, zamiast użycia jawnej specyfikacji argumentu typu.Aby włączyć wnioskowanie, podpis parametru metody generycznej musi zawierać parametr, który jest tego samego typu co parametr typu dla metody.W tym przypadku argument typu nie musi zostać określony.W przypadku użycia wnioskowania dla wszystkich parametrów typu składnia wywołania wystąpień metody generycznej i niegenerycznej jest identyczna; upraszcza to użycie metod generycznych. |
|
CA1005: Unikaj nadużywania parametrów na typach generycznych |
Im więcej parametrów typu zawiera typ generyczny, tym trudniej jest poznać i zapamiętać co reprezentuje każdy parametr typu.Zwykle jest wszystko jasne w przypadku jednego parametru typu, jak w List<T>, oraz w niektórych przypadkach zawierających dwa parametry typu, jak słownik <TKey, TValue>.Jednakże, jeśli istnieją więcej niż dwa parametry typu, poziom trudności staje się zbyt wysoki dla większości użytkowników. |
CA1006: Nie zagnieżdżaj typów generycznych w podpisach elementu członkowskiego |
Argument typu zagnieżdżonego jest argumentem typu, który jest również typem generycznym.Aby wywołać element członkowski, którego podpis zawiera argument typu zagnieżdżonego, użytkownik musi zainicjować wystąpienie pierwszego typu generycznego i przekazać go do konstruktora drugiego typu generycznego.Wymagana procedura oraz składnia jest złożona i powinno się jej unikać. |
CA1007: Używaj danych generycznych wszędzie, gdzie jest to odpowiednie |
Metoda widoczna z zewnątrz zawiera parametr przekazany przez odwołanie do typu System.Object.Użycie metody generycznej umożliwia przekazanie wszystkich typów podlegających ograniczeniom do metody, bez uprzedniego rzutowania typu do typu parametru przekazanego przez odwołanie. |
Wartość domyślna niezainicjowanego typu wyliczeniowego, podobnie jak inne typy wartości, wynosi zero.Wyliczanie przypisane bez flag powinno definiować element członkowski przy użyciu wartości zero tak, że wartość domyślna jest prawidłową wartością wyliczenia.Jeśli wyliczenie, które posiada zastosowany 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. |
|
Metody obsługi zdarzeń przyjmują dwa parametry.Pierwszy jest typu System.Object i nosi nazwę "nadawca".Jest to obiekt, który wywołał zdarzenie.Drugi parametr jest typu System.EventArgs i nosi nazwę "e".To dane, które są skojarzone ze zdarzeniem.Metody obsługi zdarzeń nie powinny zwracać wartości; w języku programowania C# to jest wskazywane przez zwrócony typ void. |
|
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. |
|
CA1011: Należy rozważyć przekazywanie typów bazowych jako parametrów |
Jeśli typ podstawowy jest określony jako parametr w deklaracji metody, dowolny typ, który pochodzi od typu podstawowego może zostać przekazany jako odpowiadający argument do metody.Jeśli dodatkowa funkcjonalność, która jest dostarczana przez typ parametru pochodnego nie jest wymagana, użycie typu podstawowego umożliwia szersze wykorzystanie metody. |
Konstruktory dla typów abstrakcyjnych mogą być wywoływane tylko przez typy pochodne.Ponieważ publiczne konstruktory tworzą wystąpienia typu, a nie można utworzyć wystąpienia typu abstrakcyjnego, publiczny konstruktor typu abstrakcyjnego został niepoprawnie zaprojektowany. |
|
CA1013: Przeciąż operator equals przeciążając operatory add i subtract |
Typ publiczny lub chroniony implementuje operator dodawanie lub odejmowanie bez stosowania implementacji operatora równości. |
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.Zasada dobrego projektowania nakazuje, aby wszystkie zestawy jawnie wskazywały zgodność ze specyfikacją CLS używając CLSCompliantAttribute.Jeśli ten atrybut nie jest obecny w zestawie oznacza to, że zestaw jest niezgodny. |
|
.NET Framework używa numeru wersji, aby jednoznacznie zidentyfikować zestaw i powiązać z typami w zestawach o silnej nazwie.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. |
|
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. |
|
Podczas definiowania atrybutu niestandardowego należy go oznaczyć przy użyciu elementu AttributeUsageAttribute, aby wskazać, w którym miejscu kodu źródłowego można zastosować niestandardowy atrybut.Znaczenie i zamierzone użycie atrybutu określi jego prawidłowe lokalizacje w kodzie. |
|
Atrybuty mogą definiować obowiązkowe argumenty, które muszą zostać określone, aby 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ą także definiować argumenty opcjonalne, które są również znane jako argumenty nazwane.Te argumenty są dostarczane do konstruktorów atrybutu poprzez nazwę i powinny posiadać odpowiadającą właściwość umożliwiającą odczyt i zapis. |
|
Należy upewnić się, że każda z przestrzeni nazw posiada organizację logiczną oraz że istnieje ważna przyczyna, aby umieszczać typy w słabo wypełnionych przestrzeniach nazw. |
|
Przekazywanie typów przez odwołanie (używając out lub ref) wymaga doświadczenia ze wskaźnikami, rozumienia różnicy między typami wartości i typami odwołania oraz obsługi metod z wieloma wartościami zwracanymi.Ponadto różnica między parametrami out i ref nie jest powszechnie zrozumiała. |
|
Indeksatory (właściwości indeksowane) powinny używać pojedynczego indeksu.Indeksatory wielowymiarowe mogą znacznie zmniejszyć użyteczność biblioteki. |
|
CA1024: Używaj właściwości wszędzie, gdzie jest to odpowiednie |
Metody publiczne lub chronione posiadają nazwę zaczynającą się od "Get", nie posiadają parametrów i zwracają wartość, która nie jest tablicą.Metoda może być dobrym kandydatem na właściwość. |
Używaj tablicy parametrów zamiast powtarzających się argumentów, gdy znana jest dokładna liczba argumentów oraz gdy argumenty zmiennych są tego samego typu lub mogą być przekazane jako ten typ. |
|
Metody, które używają parametrów domyślnych są dozwolone w ramach CLS; jednakże CLS umożliwia kompilatorom ignorowanie wartości, które są przypisane do tych parametrów.Aby zapewnić odpowiednie zachowanie w językach programowania, metody, które używają parametrów domyślnych powinny zostać zastąpione przez metody przeciążone, które dostarczają parametry domyślne. |
|
Wyliczenie to typ wartości, który definiuje zestaw powiązanych, nazwanych stałych.Zastosuj FlagsAttribute do wyliczenia, gdy jego stałe nazwane mogą zostać sensownie połączone. |
|
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 podstawowy, nie jest to wymagane ani zalecane dla większości scenariuszy. |
|
Ta reguła wykrywa metody posiadające nazwy, które normalnie byłyby używane dla zdarzeń.Jeśli metoda jest wywoływana w odpowiedzi na jasno określoną zmianę stanu, metoda ta powinna zostać wywołana przez program obsługi zdarzeń.Obiekty, które wywołują tą metodę powinny wywoływać zdarzenia zamiast wywołać metodę bezpośrednio. |
|
Ogólne wyjątki nie powinny być przechwytywane.Przechwytuj wyjątek bardziej precyzyjny lub zgłoś ponownie ogólny wyjątek jako ostatnią instrukcję w bloku catch. |
|
CA1032: Implementowanie standardowych konstruktorów wyjątków |
Niepowodzenie podczas dostarczenia pełnego zestawu konstruktorów może utrudnić poprawną obsługę wyjątków. |
CA1033: Typy potomne powinny móc wywoływać metody interfejsu |
Niezapieczętowany typ widoczny z zewnątrz zapewnia jawną implementację metody interfejsu publicznego i nie dostarcza alternatywnej metody widocznej z zewnątrz o tej samej nazwie. |
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 zawierającego typu.Używane w tym celu typy zagnieżdżone nie powinny być widoczne z zewnątrz. |
|
CA1035: Implementacje ICollection mają silnie typizowane elementy członkowskie |
Ta reguła wymaga implementacji ICollection w celu dostarczenia silnie typizowanych elementów członkowskich tak, aby użytkownicy nie musieli rzutować argumentów na typ Object w przypadku używania funkcjonalności dostarczonej przez interfejs.Ta reguła zakłada, że typ, który implementuje ICollection robi to tak, aby zarządzać kolekcją wystąpień typów mocniejszych niż Object. |
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ż. |
|
Ta reguła wymaga implementacji IEnumerator w celu dostarczenia silnie typizowanej wersji właściwości Current, tak aby użytkownicy nie musieli rzutować wartości zwróconej na typ silny w przypadku używania funkcjonalności dostarczonej przez interfejs. |
|
Ta reguła wymaga implementacji IList w celu dostarczenia silnie typizowanych elementów członkowskich tak, aby użytkownicy nie musieli rzutować argumentów na typ System.Object w przypadku używania funkcjonalności dostarczonej przez interfejs. |
|
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 elementów członkowskich interfejsu.Pusty interfejs nie definiuje żadnych elementów członkowskich; dlatego też nie definiuje kontraktu, który można zaimplementować. |
|
Typ lub element członkowski jest oznaczony za pomocą atrybutu System.ObsoleteAttribute, który nie posiada określonej właściwości ObsoleteAttribute.Message.Podczas kompilowania typu lub elementu członkowskiego, który jest oznaczony za pomocą ObsoleteAttribute, wyświetlana jest właściwość Wiadomość atrybutu, co dostarcza informacje użytkownika o przestarzałym typie lub elemencie członkowskim. |
|
CA1043: Dla indeksatorów używaj argumentów integral lub string |
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. |
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.Jest tak, ponieważ umożliwiając użytkownikowi ustawienie wartości, a następnie uniemożliwianie użytkownikowi przeglądanie tej wartości nie zapewnia żadnych zabezpieczeń.Tak, więc bez dostępu do odczytu nie można przeglądać stanu obiektów udostępnionych, co ogranicza ich przydatność. |
|
Przekazywanie typów przez odwołanie (używając out lub ref) wymaga doświadczenia ze wskaźnikami, rozumienia różnicy między typami wartości i typami odwołania oraz obsługi metod z wieloma wartościami zwracanymi.Architekci biblioteki, którzy tworzą dla wszystkich nie powinni oczekiwać od użytkowników dobrej znajomości parametrów out lub ref. |
|
CA1046: Nie przeciążaj operatora equals 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 chronionych elementów członkowskich w typach zapieczętowanych |
Chronione elementy członkowskie są zadeklarowane w typach tak, aby typy dziedziczące posiadały dostęp oraz mogły zastąpić element członkowski.Z definicji po typach zapieczętowanych nie może dziedziczyć, co oznacza, że nie można wywołać metody chronionej na typach zapieczętowanych. |
CA1048: Nie deklaruj wirtualnych elementów członkowskich w typach zapieczętowanych |
Metody wirtualne są zadeklarowane w typach tak, aby typy dziedziczące mogły zmieniać implementację metod wirtualnych.Z definicji po typie zapieczętowanym nie można dziedziczyć.Powoduje to, że metoda wirtualna w typie zapieczętowanym jest całkowicie nieprzydatna. |
CA1049: Typy, które posiadają natywne zasoby powinny być usuwalne |
Typy, które przydzielają zasoby niezarządzane powinny implementować interfejs IDisposable umożliwiając metodom wywołującym zwalnianie tych zasobów na żądanie i skrócenie czasu istnienia obiektów, które zawierają te zasoby. |
Typy są zadeklarowane w obszarach nazw, aby zapobiec kolizjom nazw oraz jest to sposób organizowania typów powiązanych w hierarchii obiektów. |
|
Głównym zastosowaniem pola powinno być to, co szczegółowo opisuje implementacja.Pola powinny być prywatne lub wewnętrzne i powinny być dostępne przy użyciu właściwości. |
|
Typ publiczny lub chroniony zawiera tylko statyczne elementy członkowskie i nie jest zadeklarowany za pomocą modyfikatora sealed (C#) lub NotInheritable (Visual Basic).Typ, po którym nie będzie dziedziczenia powinien być oznakowany przy użyciu modyfikatora sealed, aby zapobiec jego użyciu jako typu podstawowego. |
|
CA1053: Typy obsługi statycznej 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 |
Reguła ta 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. |
CA1057: Przeciążenia identyfikatora URI, który jest ciągiem, wywołują przeciążenia System.Uri |
Typ deklaruje przeciążenia metody, które różnią się jedynie zastąpieniem parametru typu ciąg parametrem System.Uri.Przeciążenie, która przyjmuje parametr typu ciąg nie wywołuje przeciążenia, które przyjmuje parametr identyfikatora URI. |
Typ widoczny z zewnątrz rozszerza niektóre typy podstawowe.Użyj jednej z alternatyw. |
|
CA1059: Elementy członkowskie nie powinny uwidaczniać pewnych typów konkretnych |
Konkretny typ jest typem, który posiada pełną implementację i dlatego też może zostać utworzone jego wystąpienie.Aby włączyć powszechne użycie elementu członkowskiego, zamień konkretny typ używając sugerowanego interfejsu. |
Metody Wywołania platformy, takie jak oznaczone DllImportAttribute lub metody zdefiniowane przy użyciu słowa kluczowego Declare w Visual Basic, posiadają dostęp do kodu niezarządzanego.Metody te powinny być klasy NativeMethods, SafeNativeMethods lub UnsafeNativeMethods. |
|
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ą bardziej słabo dziedziczone niż odpowiadające typy w sygnaturze parametru metody podstawowej. |
|
Wszystkie argumenty odwołania, które są przekazywane do metody widocznej z zewnątrz powinny być sprawdzane czy nie są wartości null. |
|
CA1063: Należy prawidłowo zaimplementować interfejs IDisposable |
Wszystkie typy IDisposable powinny poprawnie implementować wzorzec Dispose. |
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 przechwycenia tego wyjątku.Jeśli wyjątek wewnętrzny jest dziedziczony z Exception, SystemException lub ApplicationException kod zewnętrzny nie posiada wystarczających informacji, aby wiedzieć co należy zrobić z wyjątkiem. |
|
CA1065: Nie należy wyrzucać wyjątków w nieoczekiwanych lokalizacjach |
Metoda, od której nie oczekiwano zgłaszania wyjątków, zgłasza wyjątek. |
Silna nazwa chroni klientów przed nieświadomym ładowaniem zestawu, który został zmieniony.Zestawy bez mocnej nazwy nie powinny być wdrażane poza bardzo ograniczonymi scenariuszami.Jeśli udostępnia lub dystrybuuje się zestawy, które nie są poprawnie podpisane, zestaw może zostać zmieniony, środowisko uruchomieniowe języka wspólnego może nie załadować zestawu lub użytkownik będzie musiał wyłączyć weryfikację na swoim komputerze. |