OfficeExtension.ClientRequestContext class

Package:

office

An abstract RequestContext object that facilitates requests to the Office application. The Excel.run and Word.run methods provide a request context.

Constructors

(constructor)(url)

Constructs a new instance of the ClientRequestContext class

Properties

debugInfo	Debug information
requestHeaders	Request headers
trackedObjects	Collection of objects that are tracked for automatic adjustments based on surrounding changes in the document.

Methods

load(object, option)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
loadRecursive(object, options, maxDepth)	Queues up a command to recursively load the specified properties of the object and its navigation properties. You must call context.sync() before reading the properties.
sync(passThroughValue)	Synchronizes the state between JavaScript proxy objects and the Office document, by executing instructions queued on the request context and retrieving properties of loaded Office objects for use in your code. This method returns a promise, which is resolved when the synchronization is complete.
trace(message)	Adds a trace message to the queue. If the promise returned by context.sync() is rejected due to an error, this adds a ".traceMessages" array to the OfficeExtension.Error object, containing all trace messages that were executed. These messages can help you monitor the program execution sequence and detect the cause of the error.

Constructor Details

(constructor)(url)

Constructs a new instance of the ClientRequestContext class

TypeScript

constructor(url?: string);

Parameters

url

string

Property Details

debugInfo

Debug information

TypeScript

readonly debugInfo: RequestContextDebugInfo;

Property Value

OfficeExtension.RequestContextDebugInfo

requestHeaders

Request headers

TypeScript

requestHeaders: { [name: string]: string };

Property Value

{ [name: string]: string }

trackedObjects

Collection of objects that are tracked for automatic adjustments based on surrounding changes in the document.

TypeScript

trackedObjects: TrackedObjects;

Property Value

OfficeExtension.TrackedObjects

Method Details

load(object, option)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

TypeScript

load(object: ClientObject, option?: string | string[] | LoadOption): void;

Parameters

object

OfficeExtension.ClientObject

The object whose properties are loaded.

option

string | string[] | OfficeExtension.LoadOption

A comma-delimited string, or array of strings, that specifies the properties to load, or an OfficeExtension.LoadOption object.

Returns

void

loadRecursive(object, options, maxDepth)

Queues up a command to recursively load the specified properties of the object and its navigation properties.

You must call context.sync() before reading the properties.

TypeScript

loadRecursive(object: ClientObject, options: { [typeName: string]: string | string[] | LoadOption }, maxDepth?: number): void;

Parameters

object

OfficeExtension.ClientObject

The object to be loaded.

options

{ [typeName: string]: string | string[] | OfficeExtension.LoadOption }

The key-value pairing of load options for the types, such as { "Workbook": "worksheets,tables", "Worksheet": "tables", "Tables": "name" }

maxDepth

number

The maximum recursive depth.

Returns

void

sync(passThroughValue)

Synchronizes the state between JavaScript proxy objects and the Office document, by executing instructions queued on the request context and retrieving properties of loaded Office objects for use in your code. This method returns a promise, which is resolved when the synchronization is complete.

TypeScript

sync<T>(passThroughValue?: T): Promise<T>;

Parameters

passThroughValue

T

Returns

Promise<T>

trace(message)

Adds a trace message to the queue. If the promise returned by context.sync() is rejected due to an error, this adds a ".traceMessages" array to the OfficeExtension.Error object, containing all trace messages that were executed. These messages can help you monitor the program execution sequence and detect the cause of the error.

TypeScript

trace(message: string): void;

Parameters

message

string

Returns

void