out 參數修飾詞 (C# 參考)

  • 發行項

out 關鍵字會導致引數由參考傳遞。 它會使形式參數成為引數的別名，其必須為變數。 換句話說，參數上的任何作業都會在引數上進行。 它類似於 ref 關鍵字，只是 ref 需要在傳遞之前，先初始化變數。 其類似於 in 關鍵字，但不同處在於 in 不允許呼叫的方法來修改引數的值。 若要使用 out 參數，方法定義和呼叫方法都必須明確地使用 out 關鍵字。 例如：

int initializeInMethod;
OutArgExample(out initializeInMethod);
Console.WriteLine(initializeInMethod);     // value is now 44

void OutArgExample(out int number)
{
    number = 44;
}

注意

out 關鍵字也可以和泛型型別參數一起使用，指定型別參數為 Covariant。 如需在此內容中使用 out 關鍵字的詳細資訊，請參閱 out (泛型修飾詞)。

當作 out 引數傳遞的變數不必先初始化，再於方法呼叫中傳遞。 不過，需要先指派值給被呼叫的方法，方法才能傳回。

針對多載解析的目的，in、ref 和 out 關鍵字不被視為方法簽章的一部分。 因此，如果唯一的差別是一種方法採用 ref 或 in 引數，而另一種方法採用 out 引數，則無法對方法進行多載。 例如，將不會編譯下列程式碼：

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

但如果有一種方法採用 ref、in 或 out 引數，而另一種方法完全沒有這些修飾詞，則類似於：

class OutOverloadExample
{
    public void SampleMethod(int i) { }
    public void SampleMethod(out int i) => i = 5;
}

編譯器會選擇最佳的多載，方法是比對呼叫位置的參數修飾詞，與方法呼叫中所使用的參數修飾詞。

屬性不是變數，因此無法做為 out 參數傳遞。

您不可為下列幾種方法使用 in、ref 和 out 關鍵字：

  • 使用 async 修飾詞定義的 async 方法。

  • 迭代器方法，其包括 yield return 或 yield break 陳述式。

此外， 擴充方法 具有下列限制：

  • out關鍵字不能用在擴充方法的第一個引數上。
  • ref當引數不是結構，或是泛型型別不受限制為結構時，無法在擴充方法的第一個引數上使用 關鍵字。
  • in除非第一個引數是結構，否則無法使用 關鍵字。 in關鍵字不能用於任何泛型型別，即使限制為 結構也一樣。

宣告 out 參數

使用 out 引數來宣告方法是傳回多個值的傳統因應措施。 針對類似的案例 ，請考慮使用值元組 。 下列範例使用 out，在單一方法呼叫中，傳回三個變數。 第三個引數會指派給 null。 這可讓方法能選擇性地傳回值。

void Method(out int answer, out string message, out string stillNull)
{
    answer = 44;
    message = "I've been returned";
    stillNull = null;
}

int argNumber;
string argMessage, argDefault;
Method(out argNumber, out argMessage, out argDefault);
Console.WriteLine(argNumber);
Console.WriteLine(argMessage);
Console.WriteLine(argDefault == null);

// The example displays the following output:
//      44
//      I've been returned
//      True

呼叫有 out 引數的方法

您可以先在個別語句中宣告變數，再將它當做 out 引數傳遞。 下列範例宣告名為 number 的變數，然後將它傳遞到 Int32.TryParse 方法，此方法嘗試將字串轉換為數字。

string numberAsString = "1640";

int number;
if (Int32.TryParse(numberAsString, out number))
    Console.WriteLine($"Converted '{numberAsString}' to {number}");
else
    Console.WriteLine($"Unable to convert '{numberAsString}'");
// The example displays the following output:
//       Converted '1640' to 1640

您也可以在方法呼叫的引數清單中宣告 out 變數，而不是在不同的變數宣告中。 這會產生更精簡、更容易閱讀的程式碼，也可避免不小心在方法呼叫前先將值指派給變數。 下列範例與上一個範例類似，但下列範例會在對 Int32.TryParse 方法的呼叫中定義 number 變數。

string numberAsString = "1640";

if (Int32.TryParse(numberAsString, out int number))
    Console.WriteLine($"Converted '{numberAsString}' to {number}");
else
    Console.WriteLine($"Unable to convert '{numberAsString}'");
// The example displays the following output:
//       Converted '1640' to 1640

在上例中，number 變數是如同 int 的強型別。 您也可以宣告隱含型別的區域變數，如下例所示。

string numberAsString = "1640";

if (Int32.TryParse(numberAsString, out var number))
    Console.WriteLine($"Converted '{numberAsString}' to {number}");
else
    Console.WriteLine($"Unable to convert '{numberAsString}'");
// The example displays the following output:
//       Converted '1640' to 1640

C# 語言規格

如需詳細資訊，請參閱 C# 語言規格。 語言規格是 C# 語法及用法的限定來源。

另請參閱