Condividi tramite

Regole di progettazione

  • Articolo

Le regole di progettazione supportano la conformità alle linee guida per la progettazione di .NET Framework.

In questa sezione

Regola Descrizione
CA1000: Non dichiarare membri statici su tipi generici Quando viene chiamato un membro statico di un tipo generico, è necessario specificare l'argomento di tipo. Quando viene chiamato un membro di istanza generica che non supporta l'inferenza, è necessario specificare l'argomento tipo relativo al membro. In questi due casi, la sintassi necessaria per specificare l'argomento di tipo è diversa e può generare confusione.
CA1001: I tipi proprietari di campi Disposable devono essere Disposable Una classe dichiara e implementa un campo di istanza che è un tipo System.IDisposable e la classe non implementa IDisposable. Una classe che dichiara un campo IDisposable è indirettamente proprietaria di una risorsa non gestita e deve implementare l'interfaccia IDisposable.
CA1002: Non esporre elenchi generici System.Collections.Generic.List<(Of <(T>)>) è una raccolta generica progettata per le prestazioni, non per l'ereditarietà. List, pertanto, non contiene membri virtuali. Devono invece essere esposte le raccolte generiche che sono state progettate per l'ereditarietà.
CA1003: Usare istanze di gestori eventi generici Un tipo contiene un delegato che restituisce void, la cui firma contiene due parametri (il primo oggetto e il secondo un tipo assegnabile a EventArgs) e l'assembly contenitore è destinato a .NET Framework 2.0.
CA1005: Evitare un uso eccessivo di parametri nei tipi generici Quanto più è alto il numero di parametri di tipo contenuti, maggiore è la difficoltà di sapere e ricordare cosa rappresenta ciascun parametro. In genere è ovvio con un parametro di tipo, come in List<T>, e in alcuni casi con due parametri di tipo, come in Dictionary<TKey, TValue>. Tuttavia, se il numero dei parametri di tipo è superiore a due, il livello di difficoltà sarà troppo elevato per la maggior parte degli utenti.
CA1008: Gli enum devono avere valore zero Il valore predefinito di un'enumerazione non inizializzata, come altri tipi di valore, è zero. Un'enumerazione con attributi non flags deve definire un membro utilizzando il valore zero in modo che il valore predefinito sia un valore valido dell'enumerazione. Se un'enumerazione a cui è applicato l'attributo FlagsAttribute definisce un membro con valore zero, il relativo nome deve essere "None" per indicare che nell'enumerazione non è stato impostato alcun valore.
CA1010: Le raccolte devono implementare un'interfaccia generica Per ampliare la possibilità di utilizzo di una raccolta, implementare una delle interfacce di raccolta generiche. La raccolta può quindi essere utilizzata per popolare tipi di raccolte generiche.
CA1012: I tipi astratti non devono avere costruttori pubblici I costruttori sui tipi astratti possono essere chiamati solo da tipi derivati. Poiché i costruttori pubblici creano istanze di un tipo e non è possibile creare istanze di un tipo astratto, per una buona progettazione non bisognerebbe creare un tipo astratto con costruttore pubblico.
CA1014: Contrassegnare gli assembly con CLSCompliantAttribute In Common Language Specification (CLS) vengono definite limitazioni di denominazione, tipi di dati e regole che gli assembly devono rispettare per poter essere utilizzati tra diversi linguaggi di programmazione. Una buona progettazione determina che tutti gli assembly indicano in modo esplicito la conformità a CLS usando CLSCompliantAttribute. Se questo attributo non è presente in un assembly, tale assembly non è conforme.
CA1016: Contrassegnare gli assembly con AssemblyVersionAttribute .NET usa il numero di versione per identificare in modo univoco un assembly e per eseguire l'associazione ai tipi in assembly con nome sicuro. Il numero di versione viene utilizzato insieme ai criteri di versione ed editore. Per impostazione predefinita, le applicazioni vengono eseguite solo con la versione di assembly con cui sono state compilate.
CA1017: Contrassegnare gli assembly con ComVisibleAttribute ComVisibleAttribute determina il modo in cui i client COM accedono al codice gestito. In una buona progettazione gli assembly devono indicare in modo esplicito la visibilità COM. È possibile impostare la visibilità COM per l'intero assembly e quindi eseguirne l'override per singoli tipi e membri dei tipi. Se questo attributo non è presente, il contenuto dell'assembly è visibile ai client COM.
CA1018: Contrassegnare gli attributi con AttributeUsageAttribute Quando si definisce un attributo personalizzato, contrassegnarlo tramite AttributeUsageAttribute per indicare la posizione nel codice sorgente in cui applicare l'attributo personalizzato. Il significato e l'utilizzo previsto di un attributo ne determinano le posizioni valide nel codice.
CA1019: Definire le funzioni di accesso per gli argomenti degli attributi Gli attributi possono definire argomenti obbligatori che devono essere specificati quando si applica l'attributo a una destinazione. Sono inoltre noti come argomenti posizionali poiché vengono forniti ai costruttori di attributo come parametri posizionali. Per ogni argomento obbligatorio, l'attributo deve fornire anche una proprietà in sola lettura corrispondente in modo che il valore dell'argomento possa essere recuperato in fase di esecuzione. Gli attributi possono inoltre definire argomenti facoltativi, noti anche come argomenti denominati. Questi argomenti sono forniti ai costruttori degli attributi in base al nome e devono disporre di una proprietà in lettura e scrittura corrispondente.
CA1021: Evitare parametri out Il passaggio di tipi per riferimento (mediante out o ref) richiede esperienza nell'utilizzo dei puntatori, nonché la conoscenza delle differenze tra tipi di valore e tipi di riferimento e dei metodi di gestione con più valori restituiti. Inoltre, la differenza tra parametri out e ref non è sempre nota.
CA1024: Usare proprietà dove appropriato Un metodo pubblico o protetto presenta un nome che inizia con "Get", non accetta parametri e restituisce un valore diverso da una matrice. Il metodo presenta tutte le caratteristiche per diventare una proprietà.
CA1027: Contrassegnare le enumerazioni con FlagsAttribute Un'enumerazione è un tipo di valore che definisce un insieme di costanti denominate correlate. Applicare FlagsAttribute a un'enumerazione quando le relative costanti denominate possono essere combinate in modo significativo.
CA1028: L'archivio di enum deve essere Int32 Un'enumerazione è un tipo di valore che definisce un insieme di costanti denominate correlate. Per impostazione predefinita, il tipo di dati System.Int32 viene utilizzato per archiviare il valore costante. Anche se è possibile modificare questo tipo sottostante, non è obbligatorio o consigliato per la maggior parte degli scenari.
CA1030: Usare eventi dove appropriato Questa regola rileva i metodi che presentano nomi comunemente utilizzati per gli eventi. Se un metodo viene chiamato in risposta a una modifica dello stato chiaramente definita, il metodo deve essere richiamato da un gestore eventi. Gli oggetti che chiamano il metodo devono generare eventi anziché chiamare direttamente il metodo.
CA1031: Non rilevare tipi di eccezione generali Le eccezioni generali non devono essere rilevate. Intercettare un'eccezione più specifica o rigenerare l'eccezione generale come ultima istruzione nel blocco catch.
CA1032: Implementare costruttori di eccezioni standard Se non viene fornito l'insieme completo di costruttori può risultare difficile gestire correttamente le eccezioni.
CA1033: I metodi di interfaccia devono essere richiamabili dai tipi figlio Un tipo visibile esternamente non sealed fornisce un'implementazione di metodo esplicita di un'interfaccia pubblica e non fornisce un metodo visibile esternamente alternativo con lo stesso nome.
CA1034: I tipi annidati non devono essere visibili Un tipo annidato è un tipo dichiarato nell'ambito di un altro tipo. I tipi annidati sono utili per incapsulare dettagli di implementazione privati del tipo contenitore. I tipi annidati utilizzati per questo scopo non devono essere visibili esternamente.
CA1036: Eseguire l'override di metodi su tipi confrontabili Un tipo pubblico o protetto implementa l'interfaccia System.IComparable. Non esegue l'override di Object.Equals né l'overload dell'operatore specifico del linguaggio per uguaglianza, ineguaglianza, minore di o maggiore di.
CA1040: Evitare l'uso di interfacce vuote Le interfacce definiscono membri che forniscono un comportamento o un contratto di utilizzo. La funzionalità descritta dall'interfaccia può essere adottata da qualsiasi tipo, indipendentemente dal punto in cui il tipo è visualizzato nella gerarchia di ereditarietà. Un tipo implementa un'interfaccia fornendo implementazioni per i membri dell'interfaccia. Un'interfaccia vuota non definisce alcun membro. Di conseguenza, non definisce un contratto implementabile.
CA1041: Specificare una proprietà ObsoleteAttribute.Message Un tipo o un membro viene contrassegnato utilizzando un attributo System.ObsoleteAttribute per cui non è stata specificata la proprietà ObsoleteAttribute.Message. Quando viene compilato un tipo o un membro contrassegnato tramite ObsoleteAttribute, viene visualizzata la proprietà Message dell'attributo , che fornisce all'utente informazioni sul tipo o sul membro obsoleto.
CA1043: Usare argomento di tipo stringa o integrale per gli indicizzatori Gli indicizzatori, ovvero le proprietà indicizzate, devono utilizzare tipi integrali o stringa per l'indice. Questi tipi vengono in genere utilizzati per l'indicizzazione di strutture di dati e aumentano l'utilizzabilità della libreria. L'utilizzo del tipo Object deve essere limitato ai casi in cui non sia possibile specificare in fase di progettazione il tipo integrale o stringa.
CA1044: Le proprietà non devono essere in sola scrittura Sebbene la presenza di proprietà di sola lettura sia accettabile e spesso necessaria, le linee guida di progettazione proibiscono l'utilizzo di proprietà di sola scrittura. Ciò è dovuto al fatto che consentire a un utente di impostare un valore e quindi impedirgli di visualizzarlo, non offre alcuna sicurezza. Inoltre, senza accesso in lettura, lo stato degli oggetti condivisi non può essere visualizzato, il che ne limita l'utilità.
CA1045: Non passare i tipi per riferimento Il passaggio di tipi per riferimento (mediante out o ref) richiede esperienza nell'utilizzo dei puntatori, nonché la conoscenza delle differenze tra tipi di valore e tipi di riferimento e dei metodi di gestione con più valori restituiti. Gli architetti della libreria che progettano per un pubblico generale non devono aspettarsi che gli utenti diventino esperti nell'uso di parametri out o ref.
CA1046: Non eseguire l'overload dell'operatore "uguale a" per i tipi di riferimento Per i tipi di riferimento, l'implementazione predefinita dell'operatore di uguaglianza è quasi sempre corretta. Per impostazione predefinita, i due riferimenti sono uguali solo se puntano allo stesso oggetto.
CA1047: Non dichiarare membri protetti nei tipi sealed I tipi dichiarano membri protetti in modo che i tipi che ereditano possano accedere al membro o eseguirne l'override. Per definizione, non è possibile ereditare tipi sealed, pertanto non è possibile chiamare metodi protetti su tipi sealed.
CA1050: Dichiarare i tipi negli spazi dei nomi I tipi vengono dichiarati in spazi dei nomi per impedire conflitti di denominazione e per organizzare i tipi correlati in una gerarchia di oggetti.
CA1051: Non dichiarare campi di istanza visibili L'utilizzo principale di un campo deve essere come dettaglio di implementazione. I campi devono essere privati o interni e devono essere esposti tramite proprietà.
CA1052: I tipi che contengono membri statici devono essere sealed Un tipo pubblico o protetto contiene solo membri statici e non viene dichiarato utilizzando il modificatore sealed (C#) o NotInheritable (Visual Basic). Un tipo non adatto a essere ereditato deve essere contrassegnato utilizzando il modificatore sealed per impedire che venga utilizzato come tipo di base.
CA1053: I tipi che contengono membri statici non devono avere costruttori Un tipo pubblico o annidato dichiara solo membri statici e presenta un costruttore predefinito pubblico o protetto. Il costruttore non è necessario perché la chiamata a membri statici non richiede un'istanza del tipo. A scopo di sicurezza e protezione, l'overload dei valori di stringa deve chiamare l'overload URI tramite l'argomento stringa.
CA1054: I parametri URI non devono essere stringhe Se un metodo accetta una rappresentazione in forma di stringa di un URI, è necessario fornire un overload corrispondente che accetti un'istanza della classe URI che fornisce questi servizi in modo sicuro e protetto.
CA1055: I valori restituiti URI non devono essere stringhe Questa regola presuppone che il metodo restituisca un URI. Una rappresentazione in forma di stringa di un URI è soggetta a errori di analisi e codifica e può creare vulnerabilità nella sicurezza. La classe System.Uri fornisce questi servizi in modo sicuro e protetto.
CA1056: Le proprietà URI non devono essere stringhe Questa regola presuppone che la proprietà rappresenti un URI. Una rappresentazione in forma di stringa di un URI è soggetta a errori di analisi e codifica e può creare vulnerabilità nella sicurezza. La classe System.Uri fornisce questi servizi in modo sicuro e protetto.
CA1058: I tipi non devono estendere tipi di base specifici Un tipo visibile esternamente estende tipi di base specifici. Utilizzare una delle alternative seguenti:
CA1060: Spostare P/Invoke nella classe NativeMethods I metodi di chiamata della piattaforma, ad esempio quelli contrassegnati con i System.Runtime.InteropServices.DllImportAttribute metodi o definiti usando la parola chiave Declare in Visual Basic, accedono al codice non gestito. Questi metodi devono appartenere alla classe NativeMethods, SafeNativeMethods o UnsafeNativeMethods.
CA1061: Non nascondere i metodi di una classe base Un metodo di un tipo di base è nascosto da un metodo denominato in modo identico in un tipo derivato, quando la firma del parametro del metodo derivato differisce solo per i tipi che presentano una derivazione più debole rispetto ai tipi corrispondenti nella firma del parametro del metodo di base.
CA1062: Convalidare gli argomenti di metodi pubblici È necessario che tutti gli argomenti di riferimento passati a metodi visibili esternamente vengano sottoposti a verifica per accertarsi che non corrispondano a valori Null.
CA1063: Implementare IDisposable correttamente È necessario che tutti i tipi IDisposable implementino correttamente il modello Dispose.
CA1064: Le eccezioni devono essere pubbliche Un'eccezione interna è visibile solo nel relativo ambito interno. Se l'eccezione si verifica al di fuori dell'ambito interno, può essere rilevata solo tramite l'eccezione di base. Se l'eccezione interna viene ereditata da System.Exception, System.SystemExceptiono System.ApplicationException, il codice esterno non avrà informazioni sufficienti per sapere cosa fare con l'eccezione.
CA1065: Non generare eccezioni in posizioni impreviste Un metodo che normalmente non genera eccezioni genera un'eccezione.
CA1066: Implementare IEquatable quando si esegue l'override di Equals Un tipo valore esegue l'override Equals del metodo , ma non implementa IEquatable<T>.
CA1067: Eseguire l'override di Equals durante l'implementazione di IEquatable Un tipo implementa IEquatable<T>, ma non esegue l'override Equals del metodo .
CA1068: I parametri CancellationToken devono venire per ultimi Un metodo ha un parametro CancellationToken che non è l'ultimo parametro.
CA1069: Le enumerazioni non devono avere valori duplicati Un'enumerazione ha più membri a cui viene assegnato in modo esplicito lo stesso valore costante.
CA1070: Non dichiarare campi evento come virtuali Un evento simile a un campo è stato dichiarato come virtuale.