CA1045: Nie przekazuj typów przez odwołanie
| Właściwości | Wartość |
|---|---|
| Identyfikator reguły | CA1045 |
| Stanowisko | Nie przekazuj typów przez odwołanie |
| Kategoria | Projekt |
| Poprawka powodująca niezgodność lub niezgodność | Kluczowa |
| Domyślnie włączone na platformie .NET 8 | Nie. |
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 według odwołania (przy użyciu out lub ref) wymaga doświadczenia ze wskaźnikami, zrozumienia różnic typów wartości i typów odwołań oraz obsługi metod, które mają wiele zwracanych 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 innego wystąpienia 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średnia). Przy użyciu domyślnej konwencji wywoływania, która jest przekazywana "według wartości", parametr, który przyjmuje typ odwołania, otrzymuje już wskaźnik do 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ła nowe wystąpienie typu odwołania, 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ąć. Zobacz klasę System.String dla różnych metod, które działają na ciągach i zwracają nowe wystąpienie ciągu. Korzystając z tego modelu, pozostało do obiektu wywołującego, aby zdecydować, czy oryginalny obiekt jest 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 .
Uwaga
Podczas pracy z parametrami, które są dużymi strukturami, dodatkowe zasoby wymagane do skopiowania tych struktur mogą spowodować efekt wydajności po przekazaniu wartości. W takich przypadkach możesz rozważyć użycie ref parametrów lub out .
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, która jest spowodowana przez typ odwołania, upewnij się, że zachowanie, które chcesz, ma zwrócić nowe wystąpienie odwołania. Jeśli tak jest, metoda powinna użyć jej wartości zwracanej, aby to zrobić.
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ć, które części bazy kodu mają być uruchamiane w tej regule.
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ć, na których częściach bazy kodu ma być uruchamiana ta reguła, na podstawie ich ułatwień dostępu. 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)
{
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;
}
}
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(typeof(TypeOfFeedback)))
{
// The call to the library.
disposition[i] = BadRefAndOut.ReplyInformation(
t, out reply[i], ref action[i]);
Console.WriteLine("Reply: {0} Action: {1} return? {2} ",
reply[i], action[i], 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();
}
}
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
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla