MSApp
This documentation is archived and is not being maintained.
The MSApp object and its members are supported only for Windows apps using JavaScript (including PWAs accessing Windows API features). The MSApp object only exists in the local context of an HTML document in a Windows app loaded via the ms-appx URI scheme; otherwise, the object doesn't exist (and consequently, none of its methods and properties are available).
It provides helper functions that enable you to create Blob and MSStream objects.
var result = MSApp.method;
clearTemporaryWebDataAsync, createBlobFromRandomAccessSream, createDataPackage, createDataPackageFromSelection, createFileFromStorageFile, createStreamFromInputStream, execAsyncAtPriority, execAtPriority, getCurrentPriority, getHtmlPrintDocumentSource,getHtmlPrintDocumentSourceAsynce, getViewId, isTaskScheduledAtPriorityOrHigher, pageHandlesAllApplicationActivations, suppressSubdownloadCredentialPrompts, terminateApp.
MSApp methods
clearTemporaryWebDataAsync
Clears cache and indexedDB data for the app or WebView.
var retval = MSApp.clearTemporaryWebDataAsync(#);
Parameters
This method has no parameters.
Exceptions
None.
Remarks
None.
Example
createBlobFromRandomAccessStream
Creates a Blob from an IRandomAccessStream object. This method should be used when dealing with IRandomAccessStream objects in apps in order to create a W3C based object from the stream. Once the blob is created, it can be used with the FileReader, URL APIs, and XMLHttpRequest.
var retVal = MSApp.createBlobFromRandomAccessStream(type, stream);
Parameters
type [in]
| Type | Description |
|---|---|
| String | Content type of the data. This string should be in the format specified in the media-type token defined in section 3.7 of RFC 2616. |
stream [in]
| Type | Description |
|---|---|
| Any | IRandomAccessStream to be stored in the Blob. |
Return value
| Type | Description |
|---|---|
| Blob | New blob object that contains the stream. |
Exceptions
| Exception | Condition |
|---|---|
| TypeMismatchError | The node type is incompatible with the expected parameter type. For versions earlier than Internet Explorer 10, TYPE_MISMATCH_ERR is returned. |
Remarks
Creates a Blob from Windows Runtime types via the MSApp namespace on the window object. This method will create a blob that is essentially a light wrapper over the RandomAccessStream object provided to it. The blob owns the lifetime of this stream and the stream will be closed when the blob is destroyed.
Example
var randomAccessStream = dataPackage.GetData("image/bmp");
var blob = window.MSApp.createBlobFromRandomAccessStream("image/bmp", randomAccessStream);
var url = window.URL.createObjectURL(blob, {oneTimeOnly:true});
document.getElementById("imagetag").src = url;
createDataPackage
Converts the user's or the application's specified range to an HTML fragment that can be shared.
var retVal = MSApp.createDataPackage(object);
Parameters
object [in]
| Type | Description |
|---|---|
| Any | This range can be created either from a selection object, for example: window.selection.getRangeAt(0), or manually. |
Return value
| Type | Description |
|---|---|
| Any | Contains the HTML markup for the specified range. |
Exceptions
None.
Remarks
This method supports only Document Object Model (DOM) Range, not TextRange. The returned data package for the specified range contains HTML markup in clipboard format.
There are no available properties for the returned data package.
Example
None.
createDataPackageFromSelection
Converts the user's or the application's selection to an HTML fragment that can be shared.
var retVal = MSApp.createDataPackageFromSelection();
Parameters
This method has no parameters.
Return value
| Type | Description |
|---|---|
| Any | Contains the HTML markup for the specified range. |
Exceptions
None.
Remarks
The returned data package for the selection contains HTML markup in clipboard format. If there is no user selection anywhere within the application's UI, the createDataPackageFromSelection returns null.
There are no available properties for the returned data package.
Example
createFileFromStorageFile
Converts a WinRT StorageFile to a standard W3C File object.
var retVal = MSApp.createFileFromStorageFile(storageFile);
Parameters
storageFile [in]
| Type | Description |
|---|---|
| Any | Contains the storage file. |
Return value
None
Exceptions
| Exception | Condition |
|---|---|
| TypeMismatchError | The specified W3C file reference is invalid. For versions earlier than Internet Explorer 10, TYPE_MISMATCH_ERR is returned. |
Remarks
None.
Example
createStreamFromInputStream
Creates an MSStream from an InputStream.
var msStream = MSApp.createStreamFromInputStream("image/jpeg", inputStream);
Parameters
type [in]
| Type | Description |
|---|---|
| DOMString | Content type of the data. This string should be in the format specified in the media-type token defined in section 3.7 of RFC 2616. ([See MIME types,](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types\) such as text/plain, text/html, image/jpeg, image/png, audio/mpeg, audio/ogg, audio/*, video/mp4, and so on). |
inputStream [in]
| Type | Description |
|---|---|
| Any | The IInputStream to be stored in the MSStream. |
Return value
None.
Exceptions
None.
Remarks
This method takes a content-type, and the IInputStream reference. The method then verifies that the stream reference passed in is an instance of type IInputStream and if not, throws DOMException TYPE_MISMATCH_ERR. If no error occurs, createStreamFromInputStream creates an MSStream (from its inputs).
Example
An IInputStream can be used to create an MSStream. As MSStreams are inherently one-time-use objects, all URLs created by URL.createObjectURL are revoked the first time it's resolved by the image element. Additionally, requests for a second URL on this object after the stream has been used will fail.
var inputStream = myInputStream; //get InputStream from socket API, and so on
var stream = MSApp.createStreamFromInputStream("image/bmp", inputstream);
document.getElementById("imagetag").src = URL.createObjectURL(stream);
execAsyncAtPriority
Schedules a callback to be executed at a later time according to the given priority.
MSApp.execAsyncAtPriority(asynchronousCallback, priority, args);
Parameters
asynchronousCallback [in]
| Type | Description |
|---|---|
| Function | The callback function to run asynchronously, dispatched at the given priority priority. |
priority [in]
| Type | Description |
|---|---|
| DOMString | The contextual priority value at which the asynchronousCallback callback is run. See MSApp Constants. |
args [in]
| Type | Description |
|---|---|
| Any | An optional series of arguments that are passed to the synchronousCallback callback function (as parameters 1 and so on). |
Return value
This method does not return a value.
Exceptions
None.
Remarks
The provided asynchronousCallback callback function is executed asynchronously later. asynchronousCallback will be dispatched according to the provided priority. Normal priority is equivalent to the existing setImmediate method. When the callback is run, the current contextual priority is set to the provided priority parameter value for the duration of the callback's execution.
The asynchronousCallback callback parameter can be any function. If arguments are provided after the priority parameter, they will all be passed to the callback function.
Unlike execAtPriority, any object returned by the asynchronousCallback callback function is ignored (and not returned via execAsyncAtPriority).
Example
execAtPriority
Runs the specified callback function at the given contextual priority.
var retval = MSApp.execAtPriority(synchronousCallback, priority, args);
Parameters
synchronousCallback [in]
| Type | Description |
|---|---|
| Function | The callback function to run synchronously at the given priority contextual priority. |
priority [in]
| Type | Description |
|---|---|
| DOMString | The specified priority value to which the current contextual priority value will be set when running the synchronousCallback callback function. See MSApp Constants. |
args [in]
| Type | Description |
|---|---|
| Any | An optional series of arguments that are passed to the synchronousCallback callback function (as parameters 1 and so on). |
Return value
| Type | Description |
|---|---|
| Any | Returns the return value of the synchronousCallback callback (as applicable). |
Exceptions
None.
Remarks
The provided synchronousCallback callback method is execute synchronously. The current contextual priority is changed to the provided priority value (given by the priority argument) for the duration of the provided callback function. Once the callback function finishes executing, priority is returned to the previous value prior to the execAtPriority call. The return value from execAtPriority is the return value of the callback method (as provided).
The synchronousCallback callback parameter can be any function. If any arguments are provided after the priority parameter, they will be passed to the provided callback method. If the callback parameter returns a value, this value becomes the return value for execAtPriority as well.
Example
var user = Windows.System.UserProfile.UserInformation;
MSApp.execAtPriority(function () { // This callback executes synchronously.
user.getFirstNameAsync().then(function () { // Dispatches at high priority.
return user.getLastNameAsync();
}).done(function () { // Dispatches at high priority.
// USEFUL CODE HERE
});
}, MSApp.HIGH); // The second argument of the execAtPriority method.
getCurrentPriority
Returns the current contextual priority.
var retval = MSApp.getCurrentPriority();
Parameters
None.
Return value
| Type | Description |
|---|---|
| DOMString | The return value is one of the strings MSApp.HIGH, MSApp.NORMAL, or MSApp.IDLE. |
Exceptions
None.
Remarks
This method returns the current contextual priority (see MSApp Constants), which can be changed via execAtPriority and execAsyncAtPriority.
Example
if (MSApp.getCurrentPriority() === MSApp.IDLE) {
// YOUR CODE HERE
}
getHtmlPrintDocumentSource
Synchronous API that has been deprecated. For Windows 10, see getHtmlPrintDocumentSourceAsync. For Windows 8 and 8.1 apps, see the MSDN entry for getHtmlPrintDocumentSource.
getHtmlPrintDocumentSourceAsync
Returns the source content that is to be printed.
MSApp.getHtmlPrintDocumentSourceAsync(document);
Parameters
htmlDoc [in]
| Type | Description |
|---|---|
| Document | The HTML document to be printed. This can be the root document, the document in an iframe, a document fragment, or a SVG document. Be aware that htmlDoc must be a document, not an element. |
Return value
None.
Exceptions
None.
Remarks
None.
Example 1
var printTask = event.request.createPrintTask(title, function (args) {
var deferral = args.getDeferral();
var getPrintDocumentSourceAsync;
if (MSApp.getHtmlPrintDocumentSourceAsync) { // Windows 10
getPrintDocumentSourceAsync = MSApp.getHtmlPrintDocumentSourceAsync(document);
} else {
getPrintDocumentSourceAsync = WinJS.Promise.as(MSApp.getHtmlPrintDocumentSource(document));
}
getPrintDocumentSourceAsync.then(function (source) {
args.setSource(source);
deferral.complete();
}, function (error) {
console.error(error);
deferral.complete();
});
});
Example 2
function registerForPrintContract() {
var printManager = Windows.Graphics.Printing.PrintManager.getForCurrentView();
printManager.onprinttaskrequested = onPrintTaskRequested;
console.log("Print Contract registered. Use the Print button to print.", "sample", "status");
}
// Variable to hold the document source to print
var gHtmlPrintDocumentSource = null;
// Print event handler for printing via the PrintManager API.
function onPrintTaskRequested(printEvent) {
var printTask = printEvent.request.createPrintTask("Print Sample", function (args) {
args.setSource(gHtmlPrintDocumentSource);
// Register the handler for print task completion event
printTask.oncompleted = onPrintTaskCompleted;
});
}
// Print Task event handler is invoked when the print job is completed.
function onPrintTaskCompleted(printTaskCompletionEvent) {
// Notify the user about the failure
if (printTaskCompletionEvent.completion === Windows.Graphics.Printing.PrintTaskCompletion.failed) {
console.log("Failed to print.", "sample", "error");
}
}
// Executed just before printing.
var beforePrint = function () {
// Replace with code to be executed just before printing the current document:
};
// Executed immediately after printing.
var afterPrint = function () {
// Replace with code to be executed immediately after printing the current document:
};
function printButtonHandler() {
// Optionally, functions to be executed immediately before and after printing can be configured as following:
window.document.body.onbeforeprint = beforePrint;
window.document.body.onafterprint = afterPrint;
// Get document source to print
MSApp.getHtmlPrintDocumentSourceAsync(document).then(function (htmlPrintDocumentSource) {
gHtmlPrintDocumentSource = htmlPrintDocumentSource;
// If the print contract is registered, the print experience is invoked.
Windows.Graphics.Printing.PrintManager.showPrintUIAsync();
});
}
getViewId
Support for multiple windows.
Note
In Win8.1 JavaScript UWP apps supported multiple windows using MSApp DOM APIs which are now depricated. For Windows 10, use window.open, window, and the new MSApp.getViewId.
| Description | Windows 10 | Windows 8.1 |
|---|---|---|
| Create new window | window.open | MSApp.createNewView |
| New window object | window | MSAppView |
var retval = MSApp.getViewId(window);
Parameters
window
| Type | Description |
|---|---|
| DOMString | An object representing a window containing a DOM document. |
Return value
viewId
| Type | Description |
|---|---|
| Number | Can be used with the various Windows.UI.ViewManagement.ApplicationViewSwitcher APIs. |
Exceptions
None.
Remarks
Use window.open and window for creating new windows, but then to interact with WinRT APIs, add the MSApp.getViewId API. It takes a window object as a parameter and returns a viewId number that can be used with the various Windows.UI.ViewManagement.ApplicationViewSwitcher APIs.
- Delaying Visibility
Views in WinRT normally start hidden and the end developer uses something like TryShowAsStandaloneAsync to display the view once it is fully prepared. In the web world, window.open shows a window immediately and the end user can watch as content is loaded and rendered. To have your new windows act like views in WinRT and not display immediately we have added a window.open option. For example:
let newWindow = window.open("https://example.com", null, "msHideView=yes");
- Primary Window Differences
The primary window that is initially opened by the OS acts differently than the secondary windows that it opens:
| Description | Primary | Secondary |
|---|---|---|
| window.open | Allowed | Disallowed |
| window.close | Close app | Close window |
| Navigation restrictions | ACUR only | No restrictions |
- Same Origin Communication Restrictions
There is a difficult technical issue preventing proper support for synchronous, same-origin, cross-window, script calls. When you open a window that is same origin, script in one window is allowed to directly call functions in the other window, and some of these calls will fail. postMessage calls work just fine and is the recommended way to do things if possible. Work to improve this issue is in progress.
Example
isTaskScheduledAtPriorityOrHigher
Returns a Boolean value indicating whether there is pending work at the given priority level or higher.
var retval = MSApp.isTaskScheduledAtPriorityOrHigher(priority);
Parameters
priority [in]
| Type | Description |
|---|---|
| DOMString | A priority value (see MSApp Constants) specifying the priority level and above to query for any outstanding queued work. |
Return value
| Type | Description |
|---|---|
| Boolean | Returns true if there is any queued work at the specified priority level or above, false otherwise. |
Exceptions
None.
Remarks
The isTaskScheduledAtPriorityOrHigher method provides a means for JavaScript code to determine if there is pending work at the various priority levels (or above) with the intent that the calling JavaScript code can then decide to yield to higher priority work.
Example
function performIdleWork(array_in) {
var idx = 0;
function performIdleWorkHelper() {
for (; idx < array_in.length; ++idx) {
// USEFUL CODE HERE
if (MSApp.isTaskScheduledAtPriorityOrHigher(MSApp.NORMAL)) {
MSApp.execAsyncAtPriority(performIdleWorkHelper, msPriority.IDLE);
break;
} // if
} // for
} // performIdleWorkHelper
performIdleWorkHelper();
} // performIdleWork
pageHandlesAllApplicationActivations
Used to avoid a refresh of the start path (page reload) before every activate event (such as clicking a notification or a pinned tile).
MSApp.pageHandlesAllApplicationActivations(boolean);
Parameters
| Type | Description |
|---|---|
| Boolean | Use MSApp.pageHandlesAllApplicationActivations(true) to always skip refreshing the start path (page reload) and instead jump straight to firing the WebUIApplication activated event. Requires that all pages handle activation events separately. By defining this method as true, clicking an activated event (like a notification) will not trigger the reload, an essential for single-page apps wishing to avoid page reloads. |
Return value
None.
Exceptions
None.
Remarks
None.
Example
// Without this, the app will first refresh to the start path before every activate event
window.MSApp.pageHandlesAllApplicationActivations(true);
// This must not be deffered so that it can receive the initial `activated` event in time
window.Windows.UI.WebUI.WebUIApplication.addEventListener(
`activated`,
e =>
microsoftInterface.handleActivatedEvent(e);
}),
false
);
suppressSubdownloadCredentialPrompts
Controls whether an app suppresses possible authentication prompts during the download of resources.
MSApp.suppressSubdownloadCredentialPrompts(suppress);
Parameters
suppress [in]
| Type | Description |
|---|---|
| Boolean | A value of true suppresses potential authentication prompts. A value of false does not suppress any potential authentication prompts from the user. |
Return value
None.
Exceptions
None.
Remarks
The suppressSubdownloadCredentialPrompts method controls whether an app suppresses potential authentication prompts during the download of resources. The default behavior is to not suppress credential prompts.
suppressSubdownloadCredentialPrompts is intended for use by apps which may load an excessive number of resources that require authentication, such as a mail app (which could contain a newsletter containing a number of images where each image requires authentication).
When suppressing credential prompts, dialogs for authenticating to servers will not be shown when accessing resources that require authentication, and the resource will not be downloaded. Note that suppressSubdownloadCredentialPrompts does not impact other possible prompts such as proxy authentication or client certification request dialogs, nor does it impact XHR.
Be aware that suppressSubdownloadCredentialPrompts impacts all content in the application, including content hosted in the webview element.
Important
Credential prompt decisions are cached. Therefore, while suppressing credential prompts will take effect immediately, allowing credential prompts after suppressing them may need a reload of the document to take effect.
Example
// Set to true to suppress potential credential prompts:
MSApp.suppressSubdownloadCredentialPrompts(true);
// Now one can load content or navigate iframe/webview to some other site.
terminateApp
Terminates the current application and generates a failure report.
MSApp.terminateApp(error);
Parameters
error [in]
| Type | Description |
|---|---|
| Error | An Error object that you can use to describe the error that triggered the termination. The Error object must contain the number, description, and stack properties; a failure report won't be generated if the object doesn't contain these properties. |
Return value
None.
Exceptions
None.
Remarks
If the issue reported by terminateApp becomes one of your app's top 5 issues, it will show up on the app's Quality page.
Example
This example calls terminateApp when an exception is encountered. It uses the Error object provided when you catch an exception.
try {
var obj2 = null;
obj2.val = 5;
}
catch(e) {
window.MSApp.terminateApp(e);
}
MSApp Constants
Allowed priority values associated with execAsyncAtPriority, execAtPriority, getCurrentPriority, and isTaskScheduldAtPriorityOrHigher.
Current
current
| Type | Description |
|---|---|
| DOMString | When current is used with the appropriate method (See also section), the method will use the current contextual priority when executing the requested operation. |
High
high
| Type | Description |
|---|---|
| DOMString | When high is used with the appropriate method (See also section), the method will use higher than normal priority when executing the requested operation and will be dispatch the operation before any existing normal priority work. |
Idle
idle
| Type | Description |
|---|---|
| DOMString | When ideal is used with the appropriate method (See also section), the method will use lower than normal priority when executing the requested operation and will be dispatch the operation after any existing normal priority work. |
Normal
normal
| Type | Description |
|---|---|
| DOMString | When normal is used with the appropriate method (See also section), the method will use the normal existing priority when executing the requested operation. |
Example
if (window.MSApp.CURRENT) {
document.getElementById('outputMessageDiv').textContent = 'The value of window.MSApp.CURRENT is "current".';
}
Requirements
| Type | Description |
|---|---|
| IDL | Mshtml.idl |
MSAppAsyncOperation
var asyncOperation = MSApp.clearTemporaryWebDataAsync();
asyncOperation.oncomplete = function() { console.log("Temporary web data cleared successfully"); };
asyncOperation.onerror = function() { console.log("Failed to clear temporary web data"); };
asyncOperation.start();
start
Starts the MSAppAsyncOperation.
var retval = MSAppAsyncOperation.start();
Parameters
None.
Return value
None.
Properties
error property
| Type | Description |
|---|---|
| DOMError | Represents an error in MSAppAsyncOperation. |
p = object.error
oncomplete property
| Type | Description |
|---|---|
| EventHandler | Property for setting an event handler on completion of MSAppAsyncOperation. |
p = object.oncomplete
onerror property
| Type | Description |
|---|---|
| EventHandler | Property for setting an event handler upon an error during MSAppAsyncOperation. |
p = object.onerror
readyState property
| Type | Description |
|---|---|
| Number | Represents the state of the asynchronous operation within the Windows app using JavaScript. Values include: Started[0], Completed[1], Error[2]. |
p = object.readyState
result property
| Type | Description |
|---|---|
| Any | Represents the result of MSAppAsyncOperation. |
p = object.result