CA1819: Las propiedades no deben devolver matrices

  • Artículo
Propiedad Value
Identificador de la regla CA1819
Título Las propiedades no deben devolver matrices
Categoría Rendimiento
La corrección es problemática o no problemática Problemático
Habilitado de forma predeterminada en .NET 8 No

Causa

Una propiedad devuelve una matriz.

De forma predeterminada, esta regla solo examina las propiedades y los tipos visibles externamente, pero es configurable.

Descripción de la regla

Las matrices devueltas por las propiedades no están protegidas contra escritura, incluso si la propiedad es de solo lectura. Para mantener la matriz inviolable, la propiedad debe devolver una copia de la matriz. Por lo general, los usuarios no entienden las implicaciones de rendimiento adversas que se originan al llamar a este tipo de propiedad. En concreto, puede que usen la propiedad como una propiedad indizada.

Cómo corregir infracciones

Para corregir una infracción de esta regla, convierta la propiedad en un método o cambie la propiedad para que devuelva una colección.

Cuándo suprimir las advertencias

Puede suprimir una advertencia que se genere para una propiedad de un atributo que derive de la clase Attribute. Los atributos pueden contener propiedades que devuelven matrices, pero no pueden contener propiedades que devuelven colecciones.

Puede suprimir la advertencia si la propiedad forma parte de una clase de objeto de transferencia de datos (DTO).

De lo contrario, no suprima las advertencias de esta regla.

Supresión de una advertencia

Si solo quiere suprimir una única infracción, agregue directivas de preprocesador al archivo de origen para deshabilitar y volver a habilitar la regla.

#pragma warning disable CA1819
// The code that's violating the rule is on this line.
#pragma warning restore CA1819

Para deshabilitar la regla de un archivo, una carpeta o un proyecto, establezca su gravedad en none del archivo de configuración.

[*.{cs,vb}]
dotnet_diagnostic.CA1819.severity = none

Para obtener más información, consulte Procedimiento para suprimir advertencias de análisis de código.

Configuración del código para analizar

Use la opción siguiente para configurar en qué partes del código base ejecutar esta regla.

Puede configurar esta opción solo para esta regla, para todas las reglas a las que se aplica o para todas las reglas de esta categoría (Rendimiento) a las que se aplica. Para más información, vea Opciones de configuración de reglas de calidad de código.

Incluir superficies de API específicas

Puede configurar en qué partes del código base ejecutar esta regla, en función de su accesibilidad. Por ejemplo, para especificar que la regla solo se debe ejecutar en la superficie de API no públicas, agregue el siguiente par clave-valor a un archivo .editorconfig en el proyecto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Ejemplo de infracción

En el ejemplo siguiente se muestra una propiedad que infringe la regla:

public class Book
{
    private string[] _Pages;

    public Book(string[] pages)
    {
        _Pages = pages;
    }

    public string[] Pages
    {
        get { return _Pages; }
    }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = pages
    End Sub

    Public ReadOnly Property Pages() As String()
End Class

Para corregir una infracción de esta regla, convierta la propiedad en un método o cambie la propiedad para que devuelva una colección en lugar de una matriz.

Cambio de la propiedad a un método

En el ejemplo siguiente se corrige la infracción mediante el cambio de la propiedad a un método:

Public Class Book

    Private _Pages As String()

    Public Sub New(ByVal pages As String())
        _Pages = pages
    End Sub

    Public Function GetPages() As String()
        ' Need to return a clone of the array so that consumers            
        ' of this library cannot change its contents            
        Return DirectCast(_Pages.Clone(), String())
    End Function

End Class

public class Book
{
    private string[] _Pages;

    public Book(string[] pages)
    {
        _Pages = pages;
    }

    public string[] GetPages()
    {
        // Need to return a clone of the array so that consumers            
        // of this library cannot change its contents            
        return (string[])_Pages.Clone();
    }
}

Cambio de la propiedad para devolver una colección

En el ejemplo siguiente se corrige la infracción mediante el cambio de la propiedad para que devuelva System.Collections.ObjectModel.ReadOnlyCollection<T>:

public class Book
{
    private ReadOnlyCollection<string> _Pages;
    public Book(string[] pages)
    {
        _Pages = new ReadOnlyCollection<string>(pages);
    }

    public ReadOnlyCollection<string> Pages
    {
        get { return _Pages; }
    }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = New ReadOnlyCollection(Of String)(pages)
    End Sub

    Public ReadOnly Property Pages() As ReadOnlyCollection(Of String)

End Class

Asignación de permisos a los usuarios para modificar una propiedad

Es posible que quiera permitir que el consumidor de la clase modifique una propiedad. En el ejemplo siguiente se muestra una propiedad de lectura/escritura que infringe la regla:

public class Book
{
    private string[] _Pages;

    public Book(string[] pages)
    {
        _Pages = pages;
    }

    public string[] Pages
    {
        get { return _Pages; }
        set { _Pages = value; }
    }
}

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = pages
    End Sub

    Public Property Pages() As String()

End Class

En el ejemplo siguiente se corrige la infracción mediante el cambio de la propiedad para que devuelva System.Collections.ObjectModel.Collection<T>:

Public Class Book
    Public Sub New(ByVal pages As String())
        Me.Pages = New Collection(Of String)(pages)
    End Sub

    Public ReadOnly Property Pages() As Collection(Of String)
End Class

public class Book
{
    private Collection<string> _Pages;

    public Book(string[] pages)
    {
        _Pages = new Collection<string>(pages);
    }

    public Collection<string> Pages
    {
        get { return _Pages; }
    }
}