Members with a Variable Number of Parameters 

Arrays are used to pass a variable number of parameters to a member. Some languages, such as C#, provide a keyword that decorates an array that is used to pass variable arguments. For languages that do not provide a keyword, the ParamArrayAttribute attribute provides this functionality. The keyword and attribute affect the last parameter in a member's signature. That parameter must be a single-dimension array.

The following code example demonstrates defining and calling a method that takes a variable number of parameters. Notice that in the DemonstrateVariableParameters method, the arguments are not put into an array before calling UseVariableParameters.

Public Shared Sub UseVariableParameters(ParamArray list() as  Integer) 
     For  i as Integer = 0  to list.Length -1 
        Console.WriteLine(list(i))
     Next i 
     Console.WriteLine()
End Sub

Public Shared Sub DemonstrateVariableParameters()

    Manager.UseVariableParameters(1,2,3,4,5)
End Sub

public static void UseVariableParameters(params int[] list) 
{
     for ( int i = 0 ; i < list.Length ; i++ )
     {
        Console.WriteLine(list[i]);
     }
     Console.WriteLine();
}

public static void DemonstrateVariableParameters()
{
    Manager.UseVariableParameters(1,2,3,4,5);
}

The following guidelines can help you understand when it is appropriate and beneficial to use variable arrays for parameters.

Consider adding the params keyword to array parameters if you expect the end users to pass a small number of elements.

If the developer will pass many elements in common scenarios, the params keyword is probably less useful because it is not likely that the developer will pass large numbers of objects inline.

Do not use params arrays if the caller would almost always already have the input in an array.

For example, byte data is typically stored and manipulated in byte arrays. Adding the params keyword to a bite array parameter does not address a common scenario because developers typically do not work with individual bytes that are not already stored in a byte array.

Do not use params arrays if the array is modified by the member taking the params array parameter.

The common language runtime (CLR) might have created a temporary array object. If the method modifies a temporary array, the modifications are not available to the caller.

Consider using the params keyword in a simple overload, even if a more complex overload cannot use it.

It is possible that developers will benefit from having the params array in one overload, even if it is not in all overloads.

Do try to order parameters to make it possible to use the params keyword.

This means that when possible, an array parameter should be the last parameter specified. The following code example demonstrates an incorrect parameter ordering.

Overloads Public Function Add (i as Integer,j as Integer, numberBase as Int16) _
    as Integer

public int Add (int i,int j, short numberBase) 

Overloads Public Function Add (i as Integer, j as Integer, k as Integer, _
    numberBase as int16) as Integer

public int Add (int i, int j, int k, short numberBase) 

' Can't use params array.
Overloads Public Function Add (numbers() as Integer, numberBase as Int16) _
    as Integer

// Can't use params array.
public int Add (int [] numbers, short numberBase) 

The parameters should be reordered as follows:

Overloads Public Function Add (numberBase as Int16, i as Integer,j as Integer) _
    as Integer

public int Add (short numberBase, int i,int j)

Overloads Public Function Add (numberBase as Int16, i as Integer, _
    j as Integer, k as Integer) as Integer

public int Add (short numberBase, int i, int j, int k) 

' Can use params array.
Overloads Public Function Add (numberBase as Int16, _
    ParamArray numbers() as Integer) as Integer

// Can use params array.
public int Add (short numberBase, params int [] numbers) 

Consider providing special overloads and code paths for calls with a small number of arguments in extremely performance-sensitive APIs.

By following this guideline, you can avoid creating arrays when a member is called with a small number of arguments. The parameter names should be a singular form of the array parameter followed by a numeric suffix. The following code example shows a member signature that follows this guideline.

Public Shared Sub WriteLine( _
     format as String,  _
     arg0 as Object, _
     arg1 as Object, _
     arg2 as Object _
)

public static void WriteLine(
    string format, 
    object arg0, 
    object arg1, 
    object arg2
)

Do be aware that null (Nothing in Visual Basic) could be passed as a params array argument.

Your member should check for a null array before processing it.

Do not use the varargs methods, otherwise known as the ellipsis.

Because the varargs calling convention is not CLS-compliant, it should not be used in public members. It can be used internally.

Portions Copyright 2005 Microsoft Corporation. All rights reserved.

Portions Copyright Addison-Wesley Corporation. All rights reserved.

For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.

See Also

Concepts

Parameter Design

Other Resources

Member Design Guidelines
Design Guidelines for Developing Class Libraries