Avvisi di progettazione

Gli avvisi di progettazione supportano la conformità alle linee guida di progettazione di Microsoft .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 del tipo. Quando viene chiamato un membro di istanza generica che non supporta l'inferenza, è necessario specificare l'argomento di tipo relativo al membro. In questi due casi, la sintassi necessaria per specificare l'argomento del 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 di 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>)>) è un insieme generico progettato per le prestazioni, non per l'ereditarietà. List, pertanto, non contiene membri virtuali. Dovrebbero invece essere esposti gli insiemi generici che sono stati progettati per l'ereditarietà.
Ca1003: Utilizzare istanze di gestori eventi generici	Un tipo contiene un delegato che restituisce un tipo void, la cui firma contiene due parametri (il primo è un oggetto e il secondo un tipo assegnabile a EventArgs) e l'assembly che lo contiene è destinato a .NET Framework 2.0.
CA1004: I metodi generici devono fornire parametri di tipo	Per inferenza si intende la procedura con cui viene determinato l'argomento di tipo di un metodo generico in base al tipo di argomento passato al metodo piuttosto che in base alla specifica esplicita dell'argomento di tipo. Per consentire l'inferenza, la firma di parametro di un metodo generico deve includere un parametro dello stesso tipo del parametro di tipo relativo al metodo. In tal caso non è necessario specificare l'argomento di tipo. Quando si utilizza l'inferenza per tutti i parametri di tipo, la sintassi necessaria per chiamare metodi di istanza generici e non generici è identica. In questo modo si semplifica l'usabilità dei metodi generici.
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 del tipo, come in List<T>, e in alcuni casi con due parametri del 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.
CA1006: Non annidare tipi generici nelle firme dei membri	Un argomento di tipo annidato è un argomento di tipo che è anche un tipo generico. Per chiamare un membro la cui firma contiene un argomento di tipo annidato, l'utente deve creare un'istanza su un tipo generico e passare il tipo al costruttore di un secondo tipo generico. La sintassi e la procedura necessarie sono complesse ed è opportuno evitarle.
CA1007: Utilizzare generics dove appropriato	Un metodo visibile esternamente contiene un parametro di riferimento di tipo System.Object. L'utilizzo di un metodo generico consente di passare al metodo tutti i tipi, soggetti a vincoli, senza prima eseguire il cast del tipo al tipo di parametro di riferimento.
CA1008: Gli enum devono avere valore zero	Il valore predefinito di un'enumerazione non inizializzata, come altri tipi di valore, è zero. Un'enumerazione senza attributi flag definisce 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.
CA1009: Dichiarare correttamente i gestori eventi	I metodi di gestione eventi accettano due parametri. Il primo è di tipo System.Object ed è denominato "sender". Corrisponde all'oggetto che ha generato l'evento. Il secondo parametro è di tipo System.EventArgs ed è denominato "e". Questi sono i dati associati all'evento. I metodi del gestore eventi non restituiscono un valore. Nel linguaggio di programmazione C# il tipo restituito è void.
CA1010: Gli insiemi devono implementare un'interfaccia generica	Per ampliare la possibilità di utilizzo di un insieme, implementare una delle interfacce di insiemi generici. L'insieme potrà quindi essere utilizzato per popolare tipi di insiemi generici.
CA1011: Considerare il passaggio di tipi di base come parametri	Quando un tipo di base viene specificato come parametro in una dichiarazione di metodo, qualsiasi tipo derivato dal tipo di base può essere passato al metodo come argomento corrispondente. Se la funzionalità aggiuntiva fornita dal tipo di parametro derivato non è necessaria, l'utilizzo del tipo di base consente un utilizzo più ampio del metodo.
CA1012: I tipi astratti non devono avere costruttori	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.
CA1013: Eseguire l'overload dell'operatore "uguale a" all'overload degli operatori di addizione e sottrazione	Un membro pubblico o protetto implementa gli operatori di addizione o sottrazione senza implementare l'operatore di uguaglianza.
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. In una buona programmazione tutti gli assembly devono indicare in modo esplicito la conformità CLS utilizzando CLSCompliantAttribute. Se questo attributo non è presente in un assembly, tale assembly non è conforme.
CA1016: Contrassegnare gli assembly con AssemblyVersionAttribute	In .NET Framework viene utilizzato il numero di versione per identificare in modo univoco un assembly e per stabilire associazioni a 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.
CA1020: Evitare l'utilizzo di spazi dei nomi con un numero ridotto di tipi	Accertarsi che ognuno degli spazi dei nomi disponga di un'organizzazione logica e che sia presente un motivo valido per inserire tipi in uno spazio dei nomi scarsamente popolato.
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 è nota a tutti.
CA1023: Gli indicizzatori non devono essere multidimensionali	Gli indicizzatori, ovvero le proprietà indicizzate, devono utilizzare un indice singolo. Gli indicizzatori multidimensionali possono ridurre sensibilmente la semplicità di utilizzo della libreria.
CA1024: Utilizzare 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à.
Ca1025: Sostituire gli argomenti ripetitivi con una matrice di parametri	Utilizzare una matrice di parametri anziché argomenti ripetuti quando non si conosce il numero esatto di argomenti e quando gli argomenti variabili sono dello stesso tipo oppure possono essere passati come lo stesso tipo.
CA1026: Evitare l'utilizzo di parametri predefiniti	I metodi che utilizzano parametri predefiniti sono consentiti dalla specifica CLS; questa specifica, tuttavia, consente ai compilatori di ignorare i valori assegnati a questi parametri. Per mantenere il comportamento desiderato tra diversi linguaggi di programmazione, è necessario sostituire i metodi che utilizzano parametri predefiniti con overload di metodi che forniscono i parametri predefiniti.
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 è necessario né consigliato nella maggior parte degli scenari.
CA1030: Utilizzare 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. Rilevare un'eccezione più specifica oppure generare nuovamente 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.
CA1035: Le implementazioni di ICollection hanno membri fortemente tipizzati	La regola richiede che le implementazioni di ICollection forniscano membri fortemente tipizzati in modo che agli utenti non venga richiesto di eseguire il cast di argomenti al tipo Object quando utilizzano la funzionalità fornita dall'interfaccia. La regola presuppone che il tipo che implementa ICollection esegua questa operazione per gestire un insieme di istanze di un tipo più sicuro di Object.
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.
CA1038: Gli enumeratori devono essere fortemente tipizzati	Questa regola richiede che le implementazioni di IEnumerator forniscano anche una versione fortemente tipizzata della proprietà Current in modo che agli utenti non venga richiesto di eseguire il cast del valore restituito al tipo sicuro quando utilizzano la funzionalità fornita dall'interfaccia.
CA1039: Gli elenchi sono fortemente tipizzati	La regola richiede che le implementazioni di IList forniscano membri fortemente tipizzati in modo che agli utenti non venga richiesto di eseguire il cast di argomenti al tipo System.Object quando utilizzano la funzionalità fornita dall'interfaccia.
CA1040: Evitare l'utilizzo 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: Fornire 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 membro o un tipo contrassegnato utilizzando ObsoleteAttribute, viene visualizzata la proprietà Message dell'attributo che fornisce all'utente informazioni sul tipo o membro obsoleto.
CA0143: Utilizzare 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 è 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 di librerie destinate a un pubblico generico non devono aspettarsi che gli utenti siano in grado di utilizzare i 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.
CA1048: Non dichiarare membri virtuali nei tipi sealed	I tipi dichiarano metodi come virtuali in modo che l'ereditarietà di tipi possa eseguire l'override dell'implementazione del metodo virtuale. Per definizione, non è possibile ereditare da un tipo sealed. Di conseguenza, un metodo virtuale su un tipo sealed risulterà non significativo.
CA1049: I tipi delle risorse native devono essere Disposable	I tipi che allocano risorse non gestite devono implementare IDisposable per consentire ai chiamanti di rilasciare quelle risorse su richiesta e di ridurre la durata degli oggetti che le contengono.
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 è 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.
CA1057: Gli overload URI dei valori di stringa chiamano gli overload System.Uri	Un tipo dichiara overload del metodo che risultano diversi solo per la sostituzione di un parametro di stringa con un parametro System.Uri. L'overload che accetta il parametro di stringa non chiama l'overload che accetta il parametro URI.
CA1058: I tipi non devono estendere tipi di base specifici	Un tipo visibile esternamente estende tipi di base specifici. Utilizzare una delle alternative seguenti:
CA1059: I membri non devono esporre tipi concreti specifici	Un tipo concreto è un tipo con implementazione completa, pertanto è possibile crearne un'istanza. Per consentire un utilizzo esteso del membro, sostituire il tipo concreto utilizzando l'interfaccia suggerita.
CA1060: Spostare i P/Invoke nella classe NativeMethods	I metodi di chiamata al sistema operativo, ad esempio quelli contrassegnati con System.Runtime.InteropServices.DllImportAttribute o i metodi definiti mediante la parola chiave Declare in Visual Basic accedono a 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 è ereditata da System.Exception, System.SystemException o System.ApplicationException, il codice esterno non disporrà di informazioni sufficienti per la corretta gestione dell'eccezione.
CA1065: Non generare eccezioni in posizioni non previste	Un metodo che normalmente non genera eccezioni genera un'eccezione.
CA2210: Gli assembly devono avere nomi sicuri validi	Il nome sicuro protegge i client dal caricamento involontario di un assembly alterato. Gli assembly con nomi sicuri non devono essere distribuiti al di fuori di scenari molto limitati. Se si condividono o distribuiscono assembly non firmati correttamente, l'assembly può essere alterato, non essere caricato in Common Language Runtime oppure l'utente potrebbe avere la necessità di disabilitare la verifica nel proprio computer.