OfficeExtension.ClientRequestContext class

  • Reference
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

constructor(url?: string);

Parameters

url

string

Property Details

debugInfo

Debug information

readonly debugInfo: RequestContextDebugInfo;

Property Value

OfficeExtension.RequestContextDebugInfo

requestHeaders

Request headers

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.

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.

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.

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.

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.

trace(message: string): void;

Parameters

message

string

Returns

void