CA1045: Türleri başvuruya göre geçirmeyin

Neden

Ortak türdeki genel veya korumalı bir yöntem, temel tür, başvuru türü veya yerleşik türlerden biri olmayan bir değer türü alan bir parametreye sahiptir ref .

Kural açıklaması

Türleri başvuruya göre geçirme ( out veya refkullanarak) işaretçilerle ilgili deneyim, değer türlerinin ve başvuru türlerinin farkının anlaşılması ve birden çok dönüş değeri olan yöntemlerin işlenmesi gerekir. Ayrıca ve out parametreleri arasındaki ref fark yaygın olarak anlaşılamayabilir.

Bir başvuru türü "başvuruya göre" geçirildiğinde yöntemi, nesnesinin farklı bir örneğini döndürmek için parametresini kullanmayı amaçlıyor. (Başvuru türünü başvuruya göre geçirme, çift işaretçi, işaretçi işaretçisi veya çift dolaylı olarak da bilinir.) "Değere göre" geçen varsayılan çağırma kuralını kullanarak, başvuru türünü alan bir parametre nesneye zaten bir işaretçi alır. İşaret ettiği nesne değil işaretçi değere göre geçirilir. Değerin geçirilmesi, yöntemin işaretçiyi başvuru türünün yeni bir örneğine işaret etmek için değiştiremeyeceği, ancak işaret ettiği nesnenin içeriğini değiştirebileceği anlamına gelir. Çoğu uygulama için bu yeterlidir ve istediğiniz davranışı verir.

Bir yöntemin farklı bir örnek döndürmesi gerekiyorsa, bunu gerçekleştirmek için yönteminin dönüş değerini kullanın. Dizeler System.String üzerinde çalışan ve bir dizenin yeni bir örneğini döndüren çeşitli yöntemler için sınıfına bakın. Bu model kullanıldığında, özgün nesnenin korunup korunmadığına karar vermek için arayana bırakılır.

Dönüş değerleri sık kullanılan ve yoğun olarak kullanılan değerler olsa da ve out parametrelerinin ref doğru şekilde uygulanması için ara tasarım ve kodlama becerileri gerekir. Genel bir hedef kitle için tasarım yapan kitaplık mimarları, kullanıcıların veya out parametreleriyle ref çalışma konusunda yetkin olmasını beklememelidir.

İhlalleri düzeltme

Bir değer türünden kaynaklanan bu kuralın ihlalini düzeltmek için yönteminin nesnesini dönüş değeri olarak döndürmesini sağlayın. Yöntemin birden çok değer döndürmesi gerekiyorsa, değerleri barındıran bir nesnenin tek bir örneğini döndürmek için yeniden tasarlayın.

Başvuru türünden kaynaklanan bu kuralın ihlalini düzeltmek için, istediğiniz davranışın başvurunun yeni bir örneğini döndürmek olduğundan emin olun. Bu durumda, yöntemi bunu yapmak için dönüş değerini kullanmalıdır.

Uyarıların ne zaman bastırılması gerekiyor?

Bu kuraldan gelen bir uyarıyı engellemek güvenlidir; ancak bu tasarım kullanılabilirlik sorunlarına neden olabilir.

Uyarıyı gizleme

Yalnızca tek bir ihlali engellemek istiyorsanız, kuralı devre dışı bırakmak ve sonra yeniden etkinleştirmek için kaynak dosyanıza ön işlemci yönergeleri ekleyin.

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

Bir dosya, klasör veya projenin kuralını devre dışı bırakmak için, yapılandırma dosyasındaki önem derecesini noneolarak ayarlayın.

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

Daha fazla bilgi için bkz . Kod analizi uyarılarını gizleme.

Çözümlemek için kod yapılandırma

Bu kuralın kod tabanınızın hangi bölümlerinde çalıştırılacaklarını yapılandırmak için aşağıdaki seçeneği kullanın.

• Belirli API yüzeylerini ekleme

Bu seçeneği yalnızca bu kural, geçerli olduğu tüm kurallar veya bu kategorideki (Tasarım) tüm kurallar için yapılandırabilirsiniz. Daha fazla bilgi için bkz . Kod kalitesi kuralı yapılandırma seçenekleri.

Belirli API yüzeylerini ekleme

api_surface seçeneğini ayarlayarak, bu kuralın erişilebilirliği temelinde kod tabanınızın hangi bölümlerinde çalıştırılacaklarını yapılandırabilirsiniz. Örneğin, kuralın yalnızca genel olmayan API yüzeyinde çalıştırılması gerektiğini belirtmek için projenizdeki bir .editorconfig dosyasına aşağıdaki anahtar-değer çiftini ekleyin:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Örnek 1

Aşağıdaki kitaplık, kullanıcının geri bildirimine yanıtlar oluşturan bir sınıfın iki uygulamasını gösterir. İlk uygulama (BadRefAndOut), kitaplık kullanıcısını üç dönüş değerini yönetmeye zorlar. İkinci uygulama (RedesignedRefAndOut), verileri tek bir birim olarak yöneten bir kapsayıcı sınıfının (ReplyData) örneğini döndürerek kullanıcı deneyimini basitleştirir.

public enum Actions
{
    Unknown,
    Discard,
    ForwardToManagement,
    ForwardToDeveloper
}

public enum TypeOfFeedback
{
    Complaint,
    Praise,
    Suggestion,
    Incomprehensible
}

public class BadRefAndOut
{
    // Violates rule: DoNotPassTypesByReference.

    public static bool ReplyInformation(TypeOfFeedback input,
       out string reply, ref Actions action)
    {
        bool returnReply = false;
        string replyText = "Your feedback has been forwarded " +
                           "to the product manager.";

        reply = String.Empty;
        switch (input)
        {
            case TypeOfFeedback.Complaint:
            case TypeOfFeedback.Praise:
                action = Actions.ForwardToManagement;
                reply = "Thank you. " + replyText;
                returnReply = true;
                break;
            case TypeOfFeedback.Suggestion:
                action = Actions.ForwardToDeveloper;
                reply = replyText;
                returnReply = true;
                break;
            case TypeOfFeedback.Incomprehensible:
            default:
                action = Actions.Discard;
                returnReply = false;
                break;
        }
        return returnReply;
    }
}

// Redesigned version does not use out or ref parameters;
// instead, it returns this container type.

public class ReplyData
{
    string reply;
    Actions action;
    bool returnReply;

    // Constructors.
    public ReplyData()
    {
        this.reply = String.Empty;
        this.action = Actions.Discard;
        this.returnReply = false;
    }

    public ReplyData(Actions action, string reply, bool returnReply)
    {
        this.reply = reply;
        this.action = action;
        this.returnReply = returnReply;
    }

    // Properties.
    public string Reply { get { return reply; } }
    public Actions Action { get { return action; } }

    public override string ToString()
    {
        return String.Format("Reply: {0} Action: {1} return? {2}",
           reply, action.ToString(), returnReply.ToString());
    }
}

public class RedesignedRefAndOut
{
    public static ReplyData ReplyInformation(TypeOfFeedback input)
    {
        ReplyData answer;
        string replyText = "Your feedback has been forwarded " +
           "to the product manager.";

        switch (input)
        {
            case TypeOfFeedback.Complaint:
            case TypeOfFeedback.Praise:
                answer = new ReplyData(
                   Actions.ForwardToManagement,
                   "Thank you. " + replyText,
                   true);
                break;
            case TypeOfFeedback.Suggestion:
                answer = new ReplyData(
                   Actions.ForwardToDeveloper,
                   replyText,
                   true);
                break;
            case TypeOfFeedback.Incomprehensible:
            default:
                answer = new ReplyData();
                break;
        }
        return answer;
    }
}

Örnek 2

Aşağıdaki uygulama kullanıcının deneyimini gösterir. Yeniden tasarlanan kitaplığa (UseTheSimplifiedClass yöntem) yapılan çağrı daha basittir ve yöntemi tarafından döndürülen bilgiler kolayca yönetilir. İki yöntemin çıkışı aynıdır.

public class UseComplexMethod
{
    static void UseTheComplicatedClass()
    {
        // Using the version with the ref and out parameters. 
        // You do not have to initialize an out parameter.

        string[] reply = new string[5];

        // You must initialize a ref parameter.
        Actions[] action = {Actions.Unknown,Actions.Unknown,
                         Actions.Unknown,Actions.Unknown,
                         Actions.Unknown,Actions.Unknown};
        bool[] disposition = new bool[5];
        int i = 0;

        foreach (TypeOfFeedback t in Enum.GetValues(typeof(TypeOfFeedback)))
        {
            // The call to the library.
            disposition[i] = BadRefAndOut.ReplyInformation(
               t, out reply[i], ref action[i]);
            Console.WriteLine($"Reply: {reply[i]} Action: {action[i]}  return? {disposition[i]} ");
            i++;
        }
    }

    static void UseTheSimplifiedClass()
    {
        ReplyData[] answer = new ReplyData[5];
        int i = 0;
        foreach (TypeOfFeedback t in Enum.GetValues(typeof(TypeOfFeedback)))
        {
            // The call to the library.
            answer[i] = RedesignedRefAndOut.ReplyInformation(t);
            Console.WriteLine(answer[i++]);
        }
    }

    public static void Main1045()
    {
        UseTheComplicatedClass();

        // Print a blank line in output.
        Console.WriteLine("");

        UseTheSimplifiedClass();
    }
}

Örnek 3

Aşağıdaki örnek kitaplık, başvuru türleri için parametrelerin nasıl ref kullanıldığını gösterir ve bu işlevselliği uygulamak için daha iyi bir yol gösterir.

public class ReferenceTypesAndParameters
{
    // The following syntax will not work. You cannot make a
    // reference type that is passed by value point to a new
    // instance. This needs the ref keyword.

    public static void BadPassTheObject(string argument)
    {
        argument = argument + " ABCDE";
    }

    // The following syntax will work, but is considered bad design.
    // It reassigns the argument to point to a new instance of string.
    // Violates rule DoNotPassTypesByReference.

    public static void PassTheReference(ref string argument)
    {
        argument = argument + " ABCDE";
    }

    // The following syntax will work and is a better design.
    // It returns the altered argument as a new instance of string.

    public static string BetterThanPassTheReference(string argument)
    {
        return argument + " ABCDE";
    }
}

Örnek 4

Aşağıdaki uygulama, davranışı göstermek için kitaplıktaki her yöntemi çağırır.

public class Test
{
    public static void Main1045()
    {
        string s1 = "12345";
        string s2 = "12345";
        string s3 = "12345";

        Console.WriteLine("Changing pointer - passed by value:");
        Console.WriteLine(s1);
        ReferenceTypesAndParameters.BadPassTheObject(s1);
        Console.WriteLine(s1);

        Console.WriteLine("Changing pointer - passed by reference:");
        Console.WriteLine(s2);
        ReferenceTypesAndParameters.PassTheReference(ref s2);
        Console.WriteLine(s2);

        Console.WriteLine("Passing by return value:");
        s3 = ReferenceTypesAndParameters.BetterThanPassTheReference(s3);
        Console.WriteLine(s3);
    }
}

Bu örnek aşağıdaki çıkışı oluşturur:

Changing pointer - passed by value:
12345
12345
Changing pointer - passed by reference:
12345
12345 ABCDE
Passing by return value:
12345 ABCDE

İlgili kurallar

CA1021: Out parametrelerinden kaçının