w modyfikator parametrów (odwołanie w C#)in parameter modifier (C# Reference)

in — Słowo kluczowe powoduje, że argumenty przekazywane przez odwołanie.The in keyword causes arguments to be passed by reference. To sprawia, że parametr formalny alias dla argumentu, który musi być zmienną.It makes the formal parameter an alias for the argument, which must be a variable. Innymi słowy żadnych operacji na parametr składa się od argumentu.In other words, any operation on the parameter is made on the argument. Jest on podobny do ref lub się słów kluczowych, poza tym, że in argumentów nie można zmodyfikować przez metodę o nazwie.It is like the ref or out keywords, except that in arguments cannot be modified by the called method. Natomiast ref argumentów może być modyfikowany, out argumenty muszą zostać zmodyfikowane przez metodę o nazwie, a te zmiany są obserwowalnymi w kontekst wywołania.Whereas ref arguments may be modified, out arguments must be modified by the called method, and those modifications are observable in the calling context.

int readonlyArgument = 44;
InArgExample(readonlyArgument);
Console.WriteLine(readonlyArgument);     // value is still 44

void InArgExample(in int number)
{
    // Uncomment the following line to see error CS8331
    //number = 19;
}

Poprzedni przykład pokazuje, że in modyfikator jest zazwyczaj zbędna w witrynie wywołania.The preceding example demonstrates that the in modifier is usually unnecessary at the call site. Jest wymagany tylko w deklaracji metody.It is only required in the method declaration.

Uwaga

in — Słowo kluczowe można również za pomocą parametru typu ogólnego do określenia, czy parametr typu jest kontrawariantny, jako część foreach instrukcji, lub jako część join klauzuli w zapytaniu LINQ.The in keyword can also be used with a generic type parameter to specify that the type parameter is contravariant, as part of a foreach statement, or as part of a join clause in a LINQ query. Aby uzyskać więcej informacji na temat użytkowania in Zobacz — słowo kluczowe w tych kontekstach w, który zawiera łącza do wszystkich tych zastosowań.For more information on the use of the in keyword in these contexts, see in, which provides links to all those uses.

Zmienne są przekazywane jako in argumentów musi zostać zainicjowany przed przesłaniem w wywołaniu metody.Variables passed as in arguments must be initialized before being passed in a method call. Jednak wywoływanej metody nie może przypisać wartość lub zmodyfikuj argumentu.However, the called method may not assign a value or modify the argument.

in Modyfikator parametru jest dostępna w C# wersji 7.2 lub nowszy.The in parameter modifier is available in C# 7.2 and later. Poprzednie wersje wygenerować błąd kompilatora CS8107 ("Funkcja"odwołań tylko do odczytu"nie jest dostępna w C# 7.0.Previous versions generate compiler error CS8107 ("Feature 'readonly references' is not available in C# 7.0. Użyj języka w wersji 7.2 lub większą.") Aby skonfigurować wersji kompilatora języka, zobacz wybierz C# wersji językowej.Please use language version 7.2 or greater.") To configure the compiler language version, see Select the C# language version.

in, ref, I out słowa kluczowe nie są uważane za część podpisu metody na potrzeby rozwiązania przeciążenia.The in, ref, and out keywords are not considered part of the method signature for the purpose of overload resolution. W związku z tym, nie mogą być przeciążone metody, jeśli jedyna różnica polega na to, że jedna metoda przyjmuje strukturę ref lub in argument i drugie out argumentu.Therefore, methods cannot be overloaded if the only difference is that one method takes a ref or in argument and the other takes an out argument. Poniższy kod, na przykład, nie zostanie skompilowany:The following code, for example, will not compile:

class CS0663_Example
{
    // Compiler error CS0663: "Cannot define overloaded 
    // methods that differ only on in, ref and out".
    public void SampleMethod(in int i) { }
    public void SampleMethod(ref int i) { }
}

Przeciążenie oparte na obecność in jest dozwolony:Overloading based on the presence of in is allowed:

class InOverloads
{
    public void SampleMethod(in int i) { }
    public void SampleMethod(int i) { }
}

Zasad rozpoznawania przeciążeniaOverload resolution rules

Rozumiesz reguły rozdzielczość przeciążenia dla metod z według wartości a in argumenty dzięki zrozumieniu motywacją in argumentów.You can understand the overload resolution rules for methods with by value vs. in arguments by understanding the motivation for in arguments. Definiowanie metody przy użyciu in parametry są potencjalnymi optymalizacji wydajności.Defining methods using in parameters is a potential performance optimization. Niektóre struct argumentów typu może być duży, rozmiar i metody wywołanego w ścisłej pętli lub ścieżek kodu krytycznego koszt kopiowania tych konstrukcji jest krytyczny.Some struct type arguments may be large in size, and when methods are called in tight loops or critical code paths, the cost of copying those structures is critical. Zadeklaruj metody in parametry, aby określić, że argumenty mogą być przekazywane przez odwołanie bezpiecznie ponieważ wywoływanej metody nie powoduje modyfikacji stanu tego argumentu.Methods declare in parameters to specify that arguments may be passed by reference safely because the called method does not modify the state of that argument. Przekazywanie tych argumentów poprzez odwołanie pozwala uniknąć kopiowania (potencjalnie).Passing those arguments by reference avoids the (potentially) expensive copy.

Określanie in dla argumentów w wywołaniu witryny jest zazwyczaj opcjonalna.Specifying in for arguments at the call site is typically optional. Nie ma żadnej różnicy semantycznego między przekazywanie argumentów według wartości i przekazywania ich za pomocą odwołania in modyfikator.There is no semantic difference between passing arguments by value and passing them by reference using the in modifier. in Modyfikator lokacji wywołanie jest opcjonalny, ponieważ nie wymaga wskazać, że wartość argumentu może ulec zmianie.The in modifier at the call site is optional because you don't need to indicate that the argument's value might be changed. Jawnie dodać in modyfikator w witrynie wywołania, aby upewnić się, argument jest przekazywany przez odwołanie, nie przez wartość.You explicitly add the in modifier at the call site to ensure the argument is passed by reference, not by value. Lepiej nie używać in ma następujące dwa skutki:Explicitly using in has the following two effects:

Po pierwsze, określając in w wywołaniu witryny wymusza na kompilatorze o wybranie metody zdefiniowane przy użyciu zgodnego in parametru.First, specifying in at the call site forces the compiler to select a method defined with a matching in parameter. W przeciwnym razie, gdy dwie metody różnią się tylko w obecności właściwości in, według wartości przeciążenia ma lepsze dopasowanie.Otherwise, when two methods differ only in the presence of in, the by value overload is a better match.

Po drugie, określając in deklaruje zgodne z zamiarami użytkownika do przekazywania argumentu przez odwołanie.Second, specifying in declares your intent to pass an argument by reference. Argument używane z in musi reprezentować lokalizacji, która może być bezpośrednio określonych.The argument used with in must represent a location that can be directly referred to. Ten sam ogólne reguły out i ref stosowanie argumentów: Nie można używać stałych, właściwości zwykłych lub innych wyrażeń, które generują wartości.The same general rules for out and ref arguments apply: You cannot use constants, ordinary properties, or other expressions that produce values. W przeciwnym razie pominięcie in w wywołaniu witryny informuje kompilator, będą mogli go, aby utworzyć zmiennej tymczasowej, aby przekazać tylko do odczytu odwołanie do metody.Otherwise, omitting in at the call site informs the compiler that you will allow it to create a temporary variable to pass by read-only reference to the method. Kompilator tworzy zmienną tymczasową celu wyeliminowanie kilku ograniczeń za pomocą in argumenty:The compiler creates a temporary variable to overcome several restrictions with in arguments:

  • Zmienna tymczasowa umożliwia stałe kompilacji jako in parametrów.A temporary variable allows compile-time constants as in parameters.
  • Zmienna tymczasowa umożliwia właściwości lub innych wyrażeń dla in parametrów.A temporary variable allows properties, or other expressions for in parameters.
  • Zmienna tymczasowa zezwala argumenty w przypadku, gdy istnieje niejawna konwersja z typu argumentu z typem parametru.A temporary variable allows arguments where there is an implicit conversion from the argument type to the parameter type.

We wszystkich wystąpieniach poprzedniej kompilator tworzy zmiennej tymczasowej, która przechowuje wartość stałą, właściwość lub innego wyrażenia.In all the preceding instances, the compiler creates a temporary variable that stores the value of the constant, property, or other expression.

Poniższy kod ilustruje te reguły:The following code illustrates these rules:

static void Method(in int argument)
{
    // implementation removed
}

Method(5); // OK, temporary variable created.
Method(5L); // CS1503: no implicit conversion from long to int
short s = 0;
Method(s); // OK, temporary int created with the value 0
Method(in s); // CS1503: cannot convert from in short to in int
int i = 42;
Method(i); // passed by readonly reference
Method(in i); // passed by readonly reference, explicitly using `in`

Teraz załóżmy, że innej metody, używając wartości argumentów była dostępna.Now, suppose another method using by value arguments was available. Wyniki zmiany, jak pokazano w poniższym kodzie:The results change as shown in the following code:

static void Method(int argument)
{
    // implementation removed
}

static void Method(in int argument)
{
    // implementation removed
}

Method(5); // Calls overload passed by value
Method(5L); // CS1503: no implicit conversion from long to int
short s = 0;
Method(s); // Calls overload passed by value.
Method(in s); // CS1503: cannot convert from in short to in int
int i = 42;
Method(i); // Calls overload passed by value
Method(in i); // passed by readonly reference, explicitly using `in`

Wywołanie metody tylko wtedy, gdy argument jest przekazywany przez odwołanie jest ostatecznej.The only method call where the argument is passed by reference is the final one.

Uwaga

W poprzednim kodzie użyto int jako typ argumentu dla uproszczenia.The preceding code uses int as the argument type for simplicity. Ponieważ int jest nie większy niż odwołanie w większości współczesnych komputerów jest przekazanie pojedynczej żadnych korzyści int jako odwołanie tylko do odczytu.Because int is no larger than a reference in most modern machines, there is no benefit to passing a single int as a readonly reference.

Ograniczenia dotyczące in parametrówLimitations on in parameters

Nie można użyć in, ref, i out słowa kluczowe dla następujących rodzajów metod:You can't use the in, ref, and out keywords for the following kinds of methods:

  • Metody asynchroniczne, które można zdefiniować przy użyciu async modyfikator.Async methods, which you define by using the async modifier.
  • Metody iteratora, które obejmują yield return lub yield break instrukcji.Iterator methods, which include a yield return or yield break statement.

Specyfikacja języka C#C# Language Specification

Aby uzyskać więcej informacji, zobacz Specyfikacja języka C#.For more information, see the C# Language Specification. Specyfikacja języka jest ostatecznym źródłem informacji o składni i użyciu języka C#.The language specification is the definitive source for C# syntax and usage.

Zobacz takżeSee also