.NET 3.0+

C# Partial Methods

by Richard Carr, published at http://www.blackwasp.co.uk/CSharpPartialMethods.aspx

C# 2.0 introduced partial types to allow class definitions to be split between several files. C# 3.0 extends the concept with partial methods, allowing method signatures to be declared but not implemented. This is ideal for use with code generation tools.

What are Partial Methods?

C# 2.0 introduced the concept of partial types. These permit the code for a single class, structure or interface to be split across multiple source files. One of the common uses of partial types is employed by Visual Studio when generating the code for Windows Forms applications; the generated code is held in a file that is separate from the code created by the programmer.

The Windows Forms code generator is quite simple. When using more complex generators or CASE tools, the tool may create classes containing method and property declarations. One of the classic problems that can occur when using such systems is that when a programmer modifies these class members, the tool may overwrite the custom code. Partial methods introduced into version 3.0 of the C# language help to overcome this issue.

A partial method can be defined within a partial class or structure. It is created in two parts. Firstly, the method's signature, or definition, can be declared with no body code block. This acts as a placeholder that may, or may not, be implemented later. This signature may be defined by a code generation tool or created manually, should you wish to reserve the method name for later completion.

The second part of the partial method is the implementation. This may be within the same code file or within a different file. The method is declared in the same manner as the signature definition, except that a code block containing the required functionality is included. The implementation is optional. If it is not included, the method's signature will not be included in the compiled class and any calls to the method will also be removed. There is no cost involved in not implementing a partial method when compared to not including the method signature in the first instance.

Example

To demonstrate the use of partial methods, create a new console application project. We will use this project to simulate the code created by a CASE tool. Add two class files to the project, named ControllerGenerated.cs and Controller.cs. The first of these will contain our partial method signature, as may be created by a code generator. The second will contain the custom code that would be added by the developer. Both of the class files will contain sections of the same partial class, so change both class declarations to be as follows:

public partial class Controller
{
}

In the ControllerGenerated.cs file, we can create the signature of a method as may be created by a code generator. This method will be used to output a message if it is implemented. However, the tool would not know how the message is to be outputted, only the method name and parameters used.

Add the following signature to the ControllerGenerated.cs file within the Controller class. Note the use of the "partial" keyword to indicate that this is indeed a partial method:

partial void OutputMessage(string Message);

We can now turn our attention to the Controller.cs file. We will start by adding a new method to this file that can be used by an external class and that calls the partial method. Add the following to the Controller class within the Controller.cs file:

public void SetStatus(string status)
{
    // Code to process status omitted

    string message = string.Format("Status changed to '{0}'", status);
    OutputMessage(message);
}

This code performs some activity that processes the new status for the controller. The actual workings have been omitted for clarity in the example. Once the status has been processed, a message is generated and outputted using the partial method. We can now edit the Main method of the program to use the controller class and see the effect. Modify the Main method as follows:

static void Main()
{
    Controller c = new Controller();
    c.SetStatus("OK");
}

You can now execute this program. Even though the SetStatus method makes a call to the OutputMessage method that has not yet been implemented, the code compiles and executes. This is because the OutputMessage signature and all calls to it have been removed from the compiled assembly.

To complete the example, let's implement the method within the Controller.cs file's part of the Controller class. To implement a partial method, an exact copy of the signature, including the "partial" keyword is added, this time with a code block. In this case, we will include a code block and a statement to output the message to the console.

partial void OutputMessage(string Message)
{
    Console.WriteLine(Message);
}

Now when the program is executed, the message is shown.

Limitations

There are some limitations when using partial methods. The key technical limitations are as follows:

• Partial methods must have a void return type. It is not possible to return a value from a partial method.
• You may not use output parameters with a partial method, although you can use reference parameters.
• Partial methods are implicitly private.
• Partial methods may not be used by delegates unless they are implemented.
• You cannot modify a partial method using the extern keyword.

In addition to the technical limitations, you should also consider the maintainability of code that uses partial methods. It is natural for a developer reading code to assume that a method call actually performs an action. The belief can be particularly strong if the method is well named. With a partial method that has not been implemented this can easily lead to incorrect assumptions. It may therefore we worthwhile to comment calls to methods that may not be implemented or to use a naming convention to indicate this.