CA1045: Nie przekazuj typów przez odwołanie

Przyczyna

Metoda publiczna lub chroniona w typie publicznym ma ref parametr, który przyjmuje typ pierwotny, typ odwołania lub typ wartości, który nie jest jednym z wbudowanych typów.

Opis reguły

Przekazywanie typów przez odwołanie (przy użyciu out lub ref) wymaga doświadczenia w posługiwaniu się wskaźnikami, zrozumienia różnic między typami wartości i typami odwołań oraz umiejętności obsługi metod, które zwracają wiele wartości. Ponadto różnica między parametrami out i ref nie jest powszechnie rozumiana.

Gdy typ odwołania jest przekazywany przez odwołanie, metoda zamierza użyć parametru w celu zwrócenia nowego wystąpienia tego obiektu. (Przekazywanie typu odwołania według odwołania jest również nazywane użyciem podwójnego wskaźnika, wskaźnika do wskaźnika lub podwójnego pośrednictwa). Przy użyciu domyślnej konwencji wywoływania, czyli przekazywania "według wartości", parametr, który przyjmuje parametr typu odwołania, już otrzymuje wskaźnik do tego obiektu. Wskaźnik, a nie obiekt, do którego wskazuje, jest przekazywany przez wartość. Przekazywanie według wartości oznacza, że metoda nie może zmienić wskaźnika, aby wskazywał na nową instancję typu referencyjnego, ale może zmienić zawartość obiektu, na który wskazuje. W przypadku większości aplikacji jest to wystarczające i daje odpowiednie zachowanie.

Jeśli metoda musi zwrócić inne wystąpienie, użyj wartości zwracanej przez metodę , aby to osiągnąć. Aby uzyskać metody, które działają na ciągach i zwracają nowe wystąpienie ciągu, zobacz klasę System.String . Korzystając z tego modelu, do osoby wywołującej należy decyzja, czy oryginalny obiekt zostanie zachowany.

Chociaż wartości zwracane są powszechnie używane i intensywnie używane, prawidłowe zastosowanie parametrów out i ref wymaga pośrednich umiejętności projektowania i kodowania. Architekci bibliotek, którzy projektują dla odbiorców ogólnych, nie powinni oczekiwać, że użytkownicy staną się biegłi w pracy z parametrami out lub ref .

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, która jest spowodowana przez typ wartości, metoda zwraca obiekt jako wartość zwracaną. Jeśli metoda musi zwracać wiele wartości, przeprojektuj ją, aby zwrócić pojedyncze wystąpienie obiektu, który przechowuje wartości.

Aby naprawić naruszenie tej reguły spowodowane przez typ odwołania, upewnij się, że zamierzonym działaniem jest zwrócenie nowej instancji tego odwołania. Jeśli tak jest, metoda powinna użyć swojej wartości zwracanej, aby tego dokonać.

Kiedy pomijać ostrzeżenia

Można bezpiecznie pominąć ostrzeżenie z tej reguły; jednak ten projekt może powodować problemy z użytecznością.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj następującej opcji, aby skonfigurować, do których części kodu stosować tę regułę.

• Uwzględnij określone powierzchnie interfejsu API

Tę opcję można skonfigurować tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (Projekt), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Uwzględnij określone powierzchnie interfejsu API

Możesz skonfigurować, które części bazy kodu mają być objęte tą regułą na podstawie ich dostępności, ustawiając opcję api_surface. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Przykład 1

Poniższa biblioteka przedstawia dwie implementacje klasy, która generuje odpowiedzi na opinie użytkownika. Pierwsza implementacja (BadRefAndOut) wymusza, aby użytkownik biblioteki zarządzał trzema zwracanymi wartościami. Druga implementacja (RedesignedRefAndOut) upraszcza środowisko użytkownika, zwracając wystąpienie klasy kontenera (ReplyData), które zarządza danymi jako pojedynczą jednostką.

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)
    {
        string replyText = """
            Your feedback has been forwarded to the product manager.
            """;

        reply = string.Empty;
        bool returnReply;
        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 record class ReplyData(string Reply, Actions Action, bool ReturnReply = false)
{
    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)
    {
        string replyText = "Your feedback has been forwarded " +
           "to the product manager.";
        ReplyData? answer = input switch
        {
            TypeOfFeedback.Complaint or TypeOfFeedback.Praise => new ReplyData(
                                   "Thank you. " + replyText,
                                   Actions.ForwardToManagement,
                                   true),
            TypeOfFeedback.Suggestion => new ReplyData(
                                   replyText,
                                   Actions.ForwardToDeveloper,
                                   true),
            _ => null,
        };
        return answer;
    }
}

Przykład 2

Poniższa aplikacja ilustruje środowisko użytkownika. Wywołanie przeprojektowanej biblioteki (UseTheSimplifiedClass metody) jest prostsze, a informacje zwracane przez metodę są łatwo zarządzane. Dane wyjściowe z dwóch metod są identyczne.

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

Przykład 3

Poniższa przykładowa biblioteka ilustruje sposób ref użycia parametrów typów odwołań i przedstawia lepszy sposób implementacji tej funkcji.

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";
    }
}

Przykład 4

Poniższa aplikacja wywołuje każdą metodę w bibliotece, aby zademonstrować zachowanie.

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

Ten przykład generuje następujące wyniki:

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

Powiązane reguły

CA1021: Unikaj parametrów out