CA1819:屬性不應該傳回陣列

  • 發行項
屬性 值
規則識別碼 CA1819
標題 屬性不應該傳回陣列
類別 效能
修正程式是中斷或非中斷 中斷
預設在 .NET 8 中啟用 No

原因

屬性會傳回陣列。

根據預設，此規則只會查看外部可見的屬性和類型，但這是可設定的。

檔案描述

即使屬性是只讀的，屬性所傳回的陣列也不會受到寫入保護。 若要保持陣列為防止遭他人修改，屬性必須傳回陣列複本。 一般而言，使用者不會瞭解呼叫這類屬性的不良效能影響。 具體而言，它們可能會使用 屬性做為索引屬性。

如何修正違規

若要修正此規則的違規，請將 屬性設為方法，或變更 屬性以傳回集合。

隱藏警告的時機

您可以隱藏針對衍生自 Attribute 類別之屬性的屬性所引發的警告。 屬性可以包含傳回數位的屬性，但不能包含傳回集合的屬性。

如果 屬性是資料傳輸物件 （DTO） 類別的一部分，您可以隱藏警告。

否則，請勿隱藏此規則的警告。

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

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

若要停用檔案、資料夾或項目的規則，請在組態檔中將其嚴重性設定為 。none

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

如需詳細資訊，請參閱 如何隱藏程式代碼分析警告。

設定程式代碼以分析

使用下列選項來設定程式代碼基底要執行此規則的部分。

您可以只針對此規則、它套用的所有規則，或針對套用至此類別的所有規則（效能）設定此選項。 如需詳細資訊，請參閱 程式代碼品質規則組態選項。

包含特定 API 介面

您可以根據程式代碼基底的存取範圍，設定要執行此規則的部分。 例如，若要指定規則只應該針對非公用 API 介面執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.api_surface = private, internal

範例違規

下列範例顯示違反此規則的屬性：

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

若要修正此規則的違規，請將 屬性設為方法，或變更 屬性以傳回集合，而不是陣列。

將屬性變更為方法

下列範例會藉由將 屬性變更為 方法來修正違規：

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();
    }
}

變更 屬性以傳回集合

下列範例會藉由變更 屬性以傳回 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

允許使用者修改屬性

您可能想要允許 類別的取用者修改屬性。 下列範例顯示違反此規則的讀取/寫入屬性：

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

下列範例會藉由變更 屬性以傳回 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; }
    }
}