Edit

Share via

Optional parameters in Office solutions

  • Article

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, 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 VSTO Add-in projects. 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 still include the missing variable, but you typically do not need to use it when you develop Office solutions in Visual Studio 2013, except when you call methods with optional ref parameters in the ThisDocument class in document-level projects for Word.

Example in Excel

The 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);

Example in Word

The 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.

Word.Range documentRange = this.Application.ActiveDocument.Content;
documentRange.Find.ClearFormatting();
documentRange.Find.Execute(FindText: "blue", ReplaceWith: "red", Replace: Word.WdReplace.wdReplaceAll);

Use 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 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 Document object returned by the InnerObject property, and omit the parameters from that method. You can do this because Document is an interface, rather than a class.

    Globals.ThisDocument.InnerObject.CheckSpelling(IgnoreUppercase: true);

    For more information about value and reference type parameters, see Pass arguments by value and by reference (Visual Basic) (for Visual Basic) and Pass parameters (C# programming guide).

Related content