C# Ref Parameter

Ref parameters are changed at the calling site. They are passed as references, not values. This means you can assign the parameter in the called method and have it also be assigned at the calling site. Ref arguments are powerful and useful. They also have disadvantages.

This C# example program demonstrates the ref keyword on arguments.

Example

There is a big difference between ref and out parameters at the language level. Before you can pass a ref parameter, you must assign it to a value. This is for the purpose of definite assignment analysis. On the other hand, you don't need to assign an out parameter before passing it to a method. However, the out parameter in that method must assign the parameter before returning.

Tip: A variable passed with ref must be assigned first. One with out must be assigned in the called method.

Program that uses ref and out [C#]

using System;

class Program
{
    static void Main()
    {
	string value1 = "cat"; // Assign string value
	SetString1(ref value1); // Pass as reference parameter
	Console.WriteLine(value1); // Write result

	string value2; // Unassigned string
	SetString2(1, out value2); // Pass as out parameter
	Console.WriteLine(value2); // Write result
    }

    static void SetString1(ref string value)
    {
	if (value == "cat") // Test parameter value
	{
	    Console.WriteLine("Is cat");
	}
	value = "dog"; // Assign parameter to new value
    }

    static void SetString2(int number, out string value)
    {
	if (number == 1) // Check int parameter
	{
	    value = "one"; // Assign out parameter
	}
	else
	{
	    value = "carrot"; // Assign out parameter
	}
    }
}

Output

Is cat
dog
one

Description. The program in the example defines the Program class with the Main entry point and two static methods, SetString1 and SetString2. The methods have formal parameter lists with the reference parameter keywords.

SetString1 method with ref string. The SetString1 method shown above has the "ref" keyword in its method signature. This requires that whenever you pass a string to this method, it must be described with the "ref" keyword before the identifier. When the method is called, the storage location of the string variable is copied to the method. None of the characters pointed to by the string variable are copied.

SetString2 method with out string. The SetString2 method has the "out" keyword in its signature. This means that whenever you want to call it, you must describe the string parameter with the "out" keyword. You do not need to assign the string parameter before sending it to SetString2. However, you will get a compile-time error if you do not assign the string parameter before any return points.

Definite assignment analysis

The C# language compiler performs a form of static analysis called definite assignment analysis. This is how the compiler proves that each variable is initialized to a value before it is used. In the example above, the difference between the "ref" and "out" parameters is that the compiler proves the variables are assigned at different points. With "ref", definite assignment occurs before the method invocation. With "out", it occurs in the method body.

CLR implementation

The difference between "ref" and "out" is not in the Common Language Runtime, but is in the C# programming language itself. In the intermediate language, you will see that in the example code above, the ref and out parameters are called with the "string&" type. The "string" type actually aliases the System.String type in the base class library, so it is not special-cased here.

FxCop warnings. Microsoft's useful FxCop tool will warn you when you use "ref" and "out" parameters. It is considered that the best object-oriented design methodologies will return new objects containing fields and properties instead of variable reference parameters.

Overload resolution problems. These parameter decorators can confuse the overload resolution step in the C# compiler. For this reason, it is a bad idea to mix "ref" and "out" parameters in an interface or object method group. Many development teams standardize on either decorator instead of using both.

Tester-doer

There are more examples of the out keyword on this site. It can sometimes be used in methods that enhance performance and can actually lead to simpler code. In many places, though, the ref and out keywords make your code more complex and should be avoided.

Summary

We looked at reference parameter decorators in the C# programming language. These keywords allow you to pass variable references, as opposed to object references. The actual storage location of the variable itself is copied on the method invocations in this article. We reviewed warnings relating to ref and out, and finally discussed some language-level and runtime-level issues related to these decorators.