Diseñar advertencias
Las advertencias diseñadas admiten el cumplimiento de las Instrucciones de diseño de .NET Framework.
En esta sección
Regla |
Descripción |
|---|---|
Cuando se llama a un miembro estático de un tipo genérico, se debe especificar el argumento de tipo correspondiente a ese tipo.Cuando se llama a un miembro de instancia genérico que no admite la interferencia, se debe especificar el argumento de tipo para el miembro.En estos dos casos, la sintaxis para especificar el argumento de tipo es diferente y resulta fácil confundirse. |
|
CA1001: Los tipos que poseen campos descartables deben ser descartables |
Una clase declara e implementa un campo de instancias que es de tipo System.IDisposable y la clase no implementa IDisposable.Una clase que declara un campo IDisposable posee indirectamente un recurso no administrado y debería implementar la interfaz IDisposable. |
System.Collections.Generic.List<(Of <(T>)>) es una colección genérica diseñada para el rendimiento, no para la herencia.Por consiguiente, List no contiene ningún miembro virtual.En su lugar, se debe exponer las colecciones genéricas diseñadas para herencia. |
|
CA1003: Utilizar instancias genéricas de controlador de eventos |
Un tipo contiene un delegado que devuelve void cuya firma contiene dos parámetros (el primero un objeto y el segundo un tipo asignable a EventArgs), y el ensamblado que lo contiene está dirigido a .NET Framework 2.0. |
CA1004: Los métodos genéricos deben proporcionar un parámetro de tipo |
La inferencia es el modo en que se determina el argumento de tipo de un método genérico partiendo del tipo de argumento pasado al método, en lugar de especificar directamente el argumento de tipo.Para habilitar la inferencia, la firma de parámetro de un método genérico debe incluir un parámetro del mismo tipo que el parámetro type del método.En este caso, no es necesario especificar el argumento de tipo.Cuando se utiliza la inferencia para todos los parámetros de tipo, la sintaxis para llamar a los métodos de instancia genéricos y no genéricos es la misma; esto simplifica la capacidad de uso de los métodos genéricos. |
Cuantos más parámetros type contenga un tipo genérico, más difícil resulta saber y recordar qué representa cada uno de ellos.Normalmente, esto resulta evidente con los parámetros de tipo, como en List <T>, y en algunos casos con dos parámetros de tipo, como en Dictionary<TKey, TValue>.Sin embargo, si hay más de dos parámetros de tipo, la dificultad se vuelve demasiado grande para la mayoría de los usuarios. |
|
Un argumento de tipo anidado es un argumento de tipo que también es un tipo genérico.Para llamar a un miembro cuya firma contenga un argumento de tipo anidado, el usuario debe crear instancias de un tipo genérico y pasar este tipo al constructor de un segundo tipo genérico.El procedimiento y la sintaxis necesarios para ello son complejos, por lo que es preferible evitarlo. |
|
Un método visible externamente contiene un parámetro de referencia de tipo System.Object.El uso de un método genérico permite pasar al método todos los tipos, en función de las restricciones, sin convertirlos antes al tipo del parámetro de referencia. |
|
El valor predeterminado de una enumeración no inicializada, igual que otros tipos de valor, es cero.Una enumeración con atributo y sin marcadores debe definir un miembro con el valor de cero, de modo que el valor predeterminado es un valor válido de la enumeración.Si una enumeración a la que se le haya aplicado el atributo FlagsAttribute define un miembro con valor cero, su nombre debe ser "None" para indicar que no se han establecido valores en la enumeración. |
|
Los métodos de control de eventos toman dos parámetros.El primero es de tipo System.Object y se denomina "sender".Éste es el objeto que provocó el evento.El segundo parámetro es de tipo System.EventArgs y se denomina "e".Estos son los datos están asociados a este evento.Los métodos de control de eventos no deben devolver un valor; en el lenguaje de programación C#, esto se indica mediante el tipo de valor devuelto void. |
|
CA1010: Las colecciones deben implementar la interfaz genérica |
Para ampliar la utilidad de una colección, implemente una de las interfaces de colección genéricas.Entonces podrá utilizar la colección para rellenar tipos de colecciones genéricas. |
Cuando en una declaración de método se especifica un tipo base como parámetro, cualquier tipo derivado del tipo base puede pasarse al método como el argumento correspondiente.Si la funcionalidad adicional proporcionada por el tipo de parámetro derivado no resulta necesaria, el uso del tipo base permite que el método se utilice más ampliamente. |
|
CA1012: Los tipos abstractos no deberían tener constructores |
Los tipos derivados pueden llamar solo a los constructores de tipos abstractos.Puesto que los constructores públicos crean instancias de un tipo y no se pueden crear instancias de un tipo abstracto, no es correcto diseñar un tipo abstracto con un constructor público. |
CA1013: El operador de sobrecarga es igual que la suma y resta de sobrecarga |
Un tipo público o protegido implementa los operadores de suma o resta sin implementar el operador de igualdad. |
La Common Language Specification (CLS) define las restricciones de nomenclatura, los tipos de datos y las reglas a las que los ensamblados deben ajustarse si se van a utilizar los lenguajes de programación.El buen diseño establece que todos los ensamblados deben indicar explícitamente la conformidad a CLS mediante el atributo CLSCompliantAttribute.Si este atributo no está presente en un ensamblado, el ensamblado no es conforme. |
|
.NET Framework utiliza el número de versión para identificar de forma única un ensamblado y para enlazarse a tipos de ensamblados con nombre seguro.El número de versión se utiliza junto con la versión y la directiva del fabricante.De forma predeterminada, las aplicaciones sólo se ejecutan con la versión de ensamblado con la que se compilaron. |
|
ComVisibleAttribute determina cómo obtienen acceso los clientes COM al código administrado.Los procedimientos de diseño recomendados dictan que los ensamblados indican explícitamente la visibilidad COM.La visibilidad COM se puede establecer para un ensamblado completo y, a continuación, se puede invalidar para los tipos individuales y los miembros de tipo.Si este atributo no está presente, el contenido del ensamblado es visible para los clientes COM. |
|
Cuando defina un atributo personalizado, márquelo utilizando AttributeUsageAttribute para indicar dónde se puede aplicar en el código fuente.El significado de un atributo y el uso que se le va a dar determinará sus ubicaciones válidas en código. |
|
CA1019: Definir descriptores de acceso para los argumentos de atributo |
Los atributos pueden definir argumentos obligatorios que deben especificarse al aplicar el atributo a un destino.Éstos también se denominan argumentos posicionales porque se proporcionan para atribuir constructores como parámetros posicionales.Para cada argumento obligatorio, el atributo debe proporcionar también una propiedad de sólo lectura correspondiente de modo que el valor del argumento se pueda recuperar en tiempo de ejecución.Los atributos también pueden definir argumentos opcionales, que también se denominan argumentos con nombre.Estos argumentos se proporcionan para atribuir constructores por nombre y deben tener una propiedad de lectura/escritura correspondiente. |
Asegúrese de que existe una organización lógica para cada espacio de nombres y que hay una razón para colocar los tipos en un espacio de nombres apenas lleno. |
|
Para pasar tipos por referencia (utilizando los parámetros out o ref) es necesario tener experiencia con punteros, saber la diferencia entre los tipos de referencia y los tipos de valor, y controlar métodos con varios valores devueltos.Además, no se suele saber qué diferencia hay entre los parámetros out y ref. |
|
Los indizadores (es decir, las propiedades indizadas) deben utilizar un índice único.Los indizadores multidimensionales pueden reducir de forma significativa la utilización de la biblioteca. |
|
Un método público o protegido tiene un nombre que comienza por "Get", no toma ningún parámetro y devuelve un valor que no es una matriz.El método podría ser un buen candidato para convertirse en propiedad. |
|
CA1025: Reemplaza argumentos repetitivos con una matriz de parámetros |
Utilice una matriz de parámetros en lugar de argumentos repetidos si no conoce el número exacto de argumentos y si los argumentos de variable son del mismo tipo o pueden pasarse como si fueran del mismo tipo. |
Los métodos que utilizan parámetros predeterminados están permitidos en CLS; sin embargo, CLS permite que los compiladores omitan los valores asignados a estos parámetros.Para seguir utilizando el comportamiento que desea en los lenguajes de programación, los métodos que utilizan parámetros predeterminados deberían reemplazarse con sobrecargas de métodos que proporcionen los parámetros predeterminados. |
|
Una enumeración es un tipo de valor que define un conjunto de constantes con nombre relacionadas.Aplique FlagsAttribute a una enumeración cuando se pueda combinar con sentido sus constantes con nombre. |
|
CA1028: El almacenamiento de la enumeración debe ser de tipo Int32 |
Una enumeración es un tipo de valor que define un conjunto de constantes con nombre relacionadas.De manera predeterminada, el tipo de datos System.Int32 se utiliza para almacenar el valor constante.Aunque puede cambiar este tipo subyacente, no es necesario ni se recomienda en la mayoría de los escenarios. |
Esta regla detecta métodos que tienen nombres que normalmente se utilizarían para eventos.Si se llama a un método en respuesta a un cambio de estado claramente definido, un controlador de eventos debe invocar al método.Los objetos que llaman al método deben provocar eventos en lugar de llamar directamente al método. |
|
No se deben capturar excepciones generales.Detecte una excepción más específica, o vuelva a producir una excepción general como la última instrucción del bloque Catch. |
|
El error al proporcionar el conjunto completo de constructores puede dificultar el control correcto de las excepciones. |
|
CA1033: Los tipos secundarios deberían poder llamar a los métodos de interfaz |
Un tipo no sellado visible externamente proporciona un método explícito de implementación de una interfaz pública pero no proporciona un método visible externamente alternativo con el mismo nombre. |
Los tipos anidados son tipos declarados en el ámbito de otro tipo.Los tipos anidados son útiles para encapsular los detalles de la implementación privada del tipo contenido.Los tipos anidados, utilizados para este propósito, no deben ser visibles externamente. |
|
CA1035: Las implementaciones de ICollection tienen miembros fuertemente tipados |
Esta regla requiere que las implementaciones de ICollection proporcionen miembros fuertemente tipados para que los usuarios no necesiten convertir los argumentos en el tipo Object cuando utilicen la funcionalidad proporcionada por la interfaz.Esta regla supone que el tipo que implementa ICollection lo hace para administrar una colección de instancias de un tipo que es más fuerte que Object. |
Un tipo público o protegido implementa la interfaz System.IComparable.No invalida Object.Equals ni sobrecarga al operador específico del lenguaje para la igualdad, desigualdad, menor que o mayor que. |
|
Esta regla requiere que las implementaciones de IEnumerator también proporcionen una versión fuertemente tipada de la propiedad Current para que los usuarios no tengan que convertir el valor devuelto en un tipo inflexible cuando utilicen la funcionalidad proporcionada por la interfaz. |
|
Esta regla requiere que las implementaciones de IList proporcionen miembros fuertemente tipados para que los usuarios no necesiten convertir los argumentos en el tipo System.Object cuando utilicen la funcionalidad proporcionada por la interfaz. |
|
Las interfaces definen miembros que proporcionan un comportamiento o acuerdo de uso.Cualquier tipo puede adoptar la funcionalidad descrita por la interfaz sin tener en cuenta dónde aparece el tipo en la jerarquía de herencia.Un tipo implementa una interfaz proporcionando las implementaciones para los miembros de la interfaz.Una interfaz vacía no define ningún miembro; por consiguiente, no define ningún contrato que se pueda implementar. |
|
Un tipo o miembro se marca con un atributo System.ObsoleteAttribute para el que no se ha especificado su propiedad ObsoleteAttribute.Message.Cuando se compila un tipo o miembro marcado con ObsoleteAttribute, se muestra la propiedad Message del atributo, que proporciona al usuario información relacionada con el tipo o miembro obsoleto. |
|
CA1043: Utilizar argumento integral o de cadena para los indizadores |
Los indizadores (es decir, las propiedades indizadas) deben utilizar tipos enteros o de cadena para el índice.Estos tipos se utilizan normalmente para indizar las estructuras de datos y aumentan la utilidad de la biblioteca.El uso del tipo Object debería limitarse a los casos en los que el tipo entero o de cadena no se puede especificar en tiempo de diseño. |
Aunque es aceptable y a menudo necesario tener una propiedad de solo lectura, las directrices de diseño prohíben el uso de propiedades de solo escritura.Esto es porque si se deja que un usuario configure un valor, y a continuación se impide que el usuario vea ese valor, no proporciona ninguna seguridad.Además, sin acceso de lectura, no se puede ver el estado de los objetos compartidos, lo que limita su utilidad. |
|
Para pasar tipos por referencia (utilizando los parámetros out o ref) es necesario tener experiencia con punteros, saber la diferencia entre los tipos de referencia y los tipos de valor, y controlar métodos con varios valores devueltos.Los arquitectos de biblioteca cuyos diseños están destinados a los usuarios en general no deben esperar que los usuarios dominen el uso de los parámetros out o ref. |
|
CA1046: No sobrecargar el operador de igualdad en los tipos de referencia |
Para los tipos de referencia, la implementación predeterminada del operador de igualdad casi siempre es correcta.De manera predeterminada, dos referencias son iguales sólo si señalan al mismo objeto. |
Los tipos declaran miembros protegidos para que los tipos heredados puedan obtener acceso o reemplazar el miembro.Por definición, no se puede heredar de tipos sealed, lo que significa que no se puede llamar a los métodos protegidos en tipos sealed. |
|
Los tipos declaran los métodos como virtuales para que los tipos heredados puedan reemplazar la implementación del método virtual.Por definición, no se puede heredar de un tipo sealed.Esto hace que un método virtual en un tipo sealed no tenga sentido. |
|
CA1049: Los tipos que poseen recursos nativos deben ser descartables |
Los tipos que se asignan a recursos no administrados deberían implementar IDisposable para permitir que los llamadores liberen estos recursos a petición y reduzcan el período de duración de los objetos que contienen los recursos. |
Los tipos se declaran dentro de los espacios de nombres para evitar conflictos de nombre y como una forma de organizar los tipos relacionados en una jerarquía de objetos. |
|
El uso principal de un campo debe ser como un detalle de implementación.Los campos deben ser privados o internos y deben exponerse utilizando propiedades. |
|
Un tipo público o protegido solamente contiene miembros estáticos y no se declara con el modificador sealed (C#) o NotInheritable (Visual Basic).Un tipo que no está diseñado para heredarse debería marcarse con el modificador sealed para impedir su uso como tipo base. |
|
CA1053: Los tipos titulares estáticos no deben tener constructores |
Un tipo público o público anidado declara sólo miembros estáticos y tiene un constructor predeterminado público o protegido.El constructor no es necesario puesto que al llamar a los miembros estáticos no se requiere una instancia del tipo.La sobrecarga de la cadena debería llamar a la sobrecarga del identificador URI utilizando el argumento string por motivos de seguridad y protección. |
Si un método toma una representación de cadena de un identificador URI, debe proporcionarse la sobrecarga correspondiente que toma una instancia de la clase URI, que proporciona estos servicios de forma segura. |
|
Esta regla supone que el método devuelve un URI.Las representaciones de cadena de identificadores URI tienen tendencia a analizar y codificar errores, por lo que pueden crear puntos vulnerables en la seguridad.La clase System.Uri proporciona estos servicios de una manera segura. |
|
Esta regla supone que la propiedad representa un URI.Las representaciones de cadena de identificadores URI tienen tendencia a analizar y codificar errores, por lo que pueden crear puntos vulnerables en la seguridad.La clase System.Uri proporciona estos servicios de una manera segura. |
|
CA1057: Las sobrecargas URI de cadena llaman a sobrecargas System.Uri |
Un tipo declara sobrecargas de método que solamente se distinguen por la sustitución de un parámetro de cadena por un parámetro System.Uri.La sobrecarga que toma el parámetro de cadena no llama a la sobrecarga que toma el parámetro URI. |
Un tipo visible externamente extiende algunos tipos base.Utilice una de las alternativas. |
|
CA1059: Los miembros no deben exponer determinados tipos concretos |
Un tipo concreto es un tipo que tiene una implementación completa y, por consiguiente, se pueden crear instancias de él.Para permitir un uso extendido del miembro, reemplace el tipo concreto por la interfaz sugerida. |
Los métodos de invocación de plataforma, como aquellos marcados con el atributo System.Runtime.InteropServices.DllImportAttribute o los métodos definidos utilizando la palabra clave Declare en Visual Basic, tienen acceso al código no administrado.Estos métodos deben ser de la clase NativeMethods, UnsafeNativeMethods o SafeNativeMethods. |
|
Un método de un tipo base está oculto por un método del mismo nombre en un tipo derivado, cuando la firma del parámetro del método derivado solo se diferencia por tipos derivados de manera más débil que los tipos correspondientes de la firma del parámetro del método base. |
|
Todos los argumentos de referencia pasados a métodos visibles externamente se deben comprobar para ver si son null. |
|
Todos los tipos IDisposable deben implementar el modelo de Dispose correctamente. |
|
Una excepción interna solo se ve dentro de su propio ámbito interno.Cuando la excepción esté fuera del ámbito interno, sólo se podrá usar la excepción base para detectarla.Si la excepción interna se hereda de System.Exception, System.SystemException o System.ApplicationException, el código externo no tendrá información suficiente para saber qué hacer con ella. |
|
Un método que no se espera que produzca excepciones inicia una excepción. |
|
El nombre seguro protege los clientes de cargar inconscientemente un ensamblado con el que se ha alterado.Los ensamblados sin nombres seguros sólo deben implementarse en escenarios muy limitados.Si se comparten o se distribuyen ensamblados que no están correctamente firmados, el ensamblado puede manipularse, el Common Language Runtime podría no cargar el ensamblado o el usuario podría deshabilitar la comprobación del equipo. |