Partial methods

Partial methods can be defined in one part of a type declaration and implemented in another. The implementation is optional; if no part implements the partial method, the partial method declaration and all calls to it are removed from the type declaration resulting from the combination of the parts.

Partial methods cannot define access modifiers, but are implicitly private. Their return type must be void, and their parameters cannot have the out modifier. The identifier partial is recognized as a special keyword in a method declaration only if it appears right before the void type; otherwise it can be used as a normal identifier. A partial method cannot explicitly implement interface methods.

There are two kinds of partial method declarations: If the body of the method declaration is a semicolon, the declaration is said to be a defining partial method declaration. If the body is given as a block, the declaration is said to be an implementing partial method declaration. Across the parts of a type declaration there can be only one defining partial method declaration with a given signature, and there can be only one implementing partial method declaration with a given signature. If an implementing partial method declaration is given, a corresponding defining partial method declaration must exist, and the declarations must match as specified in the following:

• The declarations must have the same modifiers (although not necessarily in the same order), method name, number of type parameters and number of parameters.
• Corresponding parameters in the declarations must have the same modifiers (although not necessarily in the same order) and the same types (modulo differences in type parameter names).
• Corresponding type parameters in the declarations must have the same constraints (modulo differences in type parameter names).

An implementing partial method declaration can appear in the same part as the corresponding defining partial method declaration.

Only a defining partial method participates in overload resolution. Thus, whether or not an implementing declaration is given, invocation expressions may resolve to invocations of the partial method. Because a partial method always returns void, such invocation expressions will always be expression statements. Furthermore, because a partial method is implicitly private, such statements will always occur within one of the parts of the type declaration within which the partial method is declared.

If no part of a partial type declaration contains an implementing declaration for a given partial method, any expression statement invoking it is simply removed from the combined type declaration. Thus the invocation expression, including any constituent expressions, has no effect at run-time. The partial method itself is also removed and will not be a member of the combined type declaration.

If an implementing declaration exist for a given partial method, the invocations of the partial methods are retained. The partial method gives rise to a method declaration similar to the implementing partial method declaration except for the following:

• The partial modifier is not included
• The attributes in the resulting method declaration are the combined attributes of the defining and the implementing partial method declaration in unspecified order. Duplicates are not removed.
• The attributes on the parameters of the resulting method declaration are the combined attributes of the corresponding parameters of the defining and the implementing partial method declaration in unspecified order. Duplicates are not removed.

If a defining declaration but not an implementing declaration is given for a partial method M, the following restrictions apply:

• It is a compile-time error to create a delegate to method (§7.6.10.5).
• It is a compile-time error to refer to M inside an anonymous function that is converted to an expression tree type (§6.5.2).
• Expressions occurring as part of an invocation of M do not affect the definite assignment state (§5.3), which can potentially lead to compile-time errors.
• M cannot be the entry point for an application (§3.1).

Partial methods are useful for allowing one part of a type declaration to customize the behavior of another part, e.g., one that is generated by a tool. Consider the following partial class declaration:

partial class Customer
{
string name;

public string Name {

get { return name; }

set {
OnNameChanging(value);
name = value;
OnNameChanged();
}

}

partial void OnNameChanging(string newName);

partial void OnNameChanged();
}

If this class is compiled without any other parts, the defining partial method declarations and their invocations will be removed, and the resulting combined class declaration will be equivalent to the following:

class Customer
{
string name;

public string Name {

get { return name; }

set { name = value; }
}
}

Assume that another part is given, however, which provides implementing declarations of the partial methods:

partial class Customer
{
partial void OnNameChanging(string newName)
{
Console.WriteLine(“Changing “ + name + “ to “ + newName);
}

partial void OnNameChanged()
{
Console.WriteLine(“Changed to “ + name);
}
}

Then the resulting combined class declaration will be equivalent to the following:

class Customer
{
string name;

public string Name {

get { return name; }

set {
OnNameChanging(value);
name = value;
OnNameChanged();
}

}

void OnNameChanging(string newName)
{
Console.WriteLine(“Changing “ + name + “ to “ + newName);
}

void OnNameChanged()
{
Console.WriteLine(“Changed to “ + name);
}
}