Optional Parameters in Office Solutions
Many of the methods in the object models of Microsoft Office applications accept optional parameters. If you use Visual Basic to develop an Office solution in Visual Studio 2010, you do not have to pass a value for optional parameters because the default values are automatically used for each missing parameter. In most cases, you can also omit optional parameters in Visual C# projects. However, you cannot omit optional ref parameters of the ThisDocument class in document-level Word projects.
Applies to: The information in this topic applies to document-level projects and application-level projects for Microsoft Office 2010 and the 2007 Microsoft Office system. For more information, see Features Available by Office Application and Project Type.
For more information about working with optional parameters in Visual C# and Visual Basic projects, see Named and Optional Arguments (C# Programming Guide) and Optional Parameters (Visual Basic).
Note
In earlier versions of Visual Studio, you must pass a value for every optional parameter in Visual C# projects. For convenience, these projects include a global variable named missing that you can pass to an optional parameter when you want to use the default value of the parameter. Visual C# projects for Office in Visual Studio 2010 still include the missing variable, but you typically do not need to use it when you develop Office solutions in Visual Studio 2010, except when you call methods with optional ref parameters in the ThisDocument class in document-level projects for Word.
Example in Excel
The Worksheet.CheckSpelling method has many optional parameters. You can specify values for some parameters and accept the default value of others as shown in the following code example. This example requires a document-level project with a worksheet class named Sheet1.
Globals.Sheet1.CheckSpelling(ignoreUppercase:=True)
// In projects that target the .NET Framework 3.5, change "ignoreUppercase" to "IgnoreUppercase"
// in the following line of code.
Globals.Sheet1.CheckSpelling(ignoreUppercase: true);
Example in Word
The Find.Execute method has many optional parameters. You can specify values for some parameters and accept the default value of others as shown in the following code example.
With Me.Application.ActiveDocument.Content
.Find.ClearFormatting()
.Find.Execute(FindText:="blue", ReplaceWith:="red", Replace:=Word.WdReplace.wdReplaceAll)
End With
Word.Range documentRange = this.Application.ActiveDocument.Content;
documentRange.Find.ClearFormatting();
documentRange.Find.Execute(FindText: "blue", ReplaceWith: "red", Replace: Word.WdReplace.wdReplaceAll);
Using Optional Parameters of Methods in the ThisDocument Class in Visual C# Document-Level Projects for Word
The Word object model contains many methods with optional ref parameters that accept Object values. However, you cannot omit optional ref parameters of methods of the generated ThisDocument class in Visual C# document-level projects for Word. Visual C# enables you to omit optional ref parameters only for methods of interfaces, not classes. For example, the following code example does not compile, because you cannot omit optional ref parameters of the CheckSpelling method of the ThisDocument class.
Globals.ThisDocument.CheckSpelling(ignoreUppercase: true);
When you call methods of the ThisDocument class, follow these guidelines:
To accept the default value of an optional ref parameter, pass the missing variable to the parameter. The missing variable is automatically defined in Visual C# Office projects and is assigned to the value Type.Missing in the generated project code.
To specify your own value for an optional ref parameter, declare an object that is assigned to the value that you want to specify, and then pass the object to the parameter.
The following code example demonstrates how to call the CheckSpelling method by specifying a value for the ignoreUppercase parameter and accepting the default value for the other parameters.
object ignoreUppercase = true;
Globals.ThisDocument.CheckSpelling(
ref missing, ref ignoreUppercase, ref missing, ref missing, ref missing, ref missing,
ref missing, ref missing, ref missing, ref missing, ref missing, ref missing);
If you want to write code that omits optional ref parameters of a method in the ThisDocument class, you can alternatively call the same method on the Microsoft.Office.Interop.Word.Document object returned by the InnerObject property, and omit the parameters from that method. You can do this because Microsoft.Office.Interop.Word.Document is an interface, rather than a class.
Globals.ThisDocument.InnerObject.CheckSpelling(IgnoreUppercase: true);
For more information about value and reference type parameters, see Passing Arguments by Value and by Reference (Visual Basic) (for Visual Basic) and Passing Parameters (C# Programming Guide).
See Also
Concepts
Writing Code in Office Solutions