Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

windowslib

appcelerator351Apache Public License v20.6.9

Windows Phone Utility Library

appcelerator, windows, windows phone, winstore, windows store, visualstudio, visual studio, microsoft

readme

Windows Phone Utility Library Build Status

This is a library of utilities for dealing programmatically with Windows Phone applications, used namely for tools like Titanium.

windowslib supports Visual Studio 2012, 2013, and 2015.

NPM

Installation

From NPM:

npm install windowslib

From GitHub:

npm install git://github.com/appcelerator/windowslib.git

Caveats

  • Some of the emulator detection functionality requires the use of PowerShell scripts. For the library to be able to execute these scripts, the user must change their ExecutionPolicy by running the following in a PowerShell terminal as the Administrator:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  • If attempting to connect to a device, you need to ensure the connected device is not asleep/locked or connecting will fail. There's no way to programmatically unlock the device.

Examples

Detect all the connected Windows Phone devices:

Note: Microsoft's tooling always reports a single device present regardless if there are no devices connected or several. The device will have an ID of 0 (zero).

In the event Microsoft's next mobile platform has improved tooling that supports multiple devices, this detection code should be good to go.

var windowslib = require('windowslib');

windowslib.device.detect(function (err, devices) {
    if (err) {
        console.error(err);
    } else {
        console.log(devices);
    }
});

Install an Application on Device

var deviceUDID = null; // string or null to pick first device

windowslib.device.install(deviceUDID, 'C:\\path\\to\\appfile.appx')
    .on('installed', function () {
        console.log('App successfully installed on device');
    })
    .on('error', function (err) {
        console.error(err);
    });

Launch the Windows Phone Emulator

Passing in null for the udid will auto-select a emulator and launch it.

windowslib.emulator.launch(null, function (err, handle) {
    console.log('Emulator launched');
    windowslib.emulator.stop(handle, function () {
        console.log('Emulator stopped');
    });
});

Launch, install, and Run an Application on the Emulator

var udid = null; // string or null to pick an emulator

windowslib.emulator.install(udid, 'C:\\path\\to\\appfile.appx')
    .on('launched', function (msg) {
        console.log('Emulator has launched');
    })
    .on('appStarted', function (msg) {
        console.log('App has started');
    })
    .on('log', function (msg) {
        console.log('[LOG] ' + msg);
    })
    .on('error', function (err) {
        console.error(err);
    });

Force Stop an Application Running on the Emulator

windowslib.emulator.launch(udid)
    .on('launched', function (handle) {
        console.log('Emulator launched');
        windowslib.emulator.stop(handle).on('stopped', function () {
            console.log('Emulator stopped');
        });
    });

Detect Everything

windowslib.detect(function (err, info) {
    if (err) {
        console.error(err);
    } else {
        console.log(info);
    }
});

Running Tests

For best results, connect a Windows phone device.

To run all tests:

npm test

To run a specific test suite:

npm run-script test-assemblies

npm run-script test-device

npm run-script test-emulator

npm run-script test-env

npm run-script test-logrelay

npm run-script test-process

npm run-script test-visualstudio

npm run-script test-windowsphone

npm run-script test-wptool

Reporting Bugs or Submitting Fixes

If you run into problems, and trust us, there are likely plenty of them at this point -- please create an Issue or, even better, send us a pull request.

Contributing

windowslib is an open source project. windowslib wouldn't be where it is now without contributions by the community. Please consider forking windowslib to improve, enhance or fix issues. If you feel like the community will benefit from your fork, please open a pull request.

To protect the interests of the windowslib contributors, Appcelerator, customers and end users we require contributors to sign a Contributors License Agreement (CLA) before we pull the changes into the main repository. Our CLA is simple and straightforward - it requires that the contributions you make to any Appcelerator open source project are properly licensed and that you have the legal authority to make those changes. This helps us significantly reduce future legal risk for everyone involved. It is easy, helps everyone, takes only a few minutes, and only needs to be completed once.

You can digitally sign the CLA online. Please indicate your email address in your first pull request so that we can make sure that will locate your CLA. Once you've submitted it, you no longer need to send one for subsequent submissions.

Copyright (c) 2014-2015 by Appcelerator, Inc. All Rights Reserved. This project is licensed under the Apache Public License, version 2. Please see details in the LICENSE file.

changelog

0.6.8 (01/29/2018)

  • [TIMOB-24422] Fix deployment issue with "violates pattern constraint of bms-resource" 0.6.7 (06/13/2018)
  • Update .npmignore to avoid including test files, other unnecessary files in release 0.6.6 (06/13/2018)
  • Update npm dependencies 0.6.5 (02/03/2018)
  • [TIMOB-25827] Fix error when fresh install with forceUnInstall 0.6.4 (19/12/2017)
  • [TIMOB-25616] Don't forceUnInstall unless user explicitly specifies it 0.6.3 (27/11/2017)
  • [DAEMON-184] Remove unnecessary quote when building project 0.6.2 (27/11/2017)
  • [DAEMON-184] Wrap project name in quotes when building a project 0.6.1 (21/11/2017)
  • [DAEMON-165] Handle max path when building wptool 0.6.0 (08/30/2017)
  • [TIMOB-25027] Only detect emulators based off the optional supportedWindowsPhoneSDKVersions parameter
  • Add coverage gathering 0.5.5 (09/07/2017)
  • [TIMOB-25232] Make sure to catch JSON.parse errors 0.5.4 (08/15/2017)
  • [TIMOB-24958] Fix detection of SDK specific winappdeploycmd 0.5.3 (08/09/2017)
  • [TIMOB-24683] Must call the callback with an object like {devices:[], emulator:[]} 0.5.2 (07/12/2017)
  • [TIMOB-24683] Do not attempt to run winappdeploycmd if it does not exist
  • [TIMOB-24956] Fix issue where temporary AppxManifest would not get written when fetching project guid 0.5.1 (07/04/2017)

  • [TIMOB-24922] Fix cert generation on VS2017 - Move to using vsDevCmd instead of vcvarsall
  • [TIMOB-24668] Update VS2017 detection logic to prevent error with VS2015 0.5.0 (05/9/2017)

  • Add emulator#status to get numeric status of emulator.
  • Use status to poll emulator for running state (2) after launching but before installing app
  • Add type property to object describing emulator or device, with value 'emulator' or 'device'
  • re-use cached emulator listing inside emulator#isRunning and emulator#launch
  • Fix winstore unit test to work with various version of Microsoft.Photos app

0.4.30 (04/28/2017)

  • [TIMOB-24422] Windows: Fails to install dependencies for app on Windows 10 Phone Emulator
  • Remove os win32 restriction on package.json so we can install into titanium_mobile from non-Windows machines using yarn
  • Avoid possible double-callback call on app install when also launching. If app installs ok but failed to launch, we'd fire two callbacks: one for the successful install and another for the failure. We still emit multiple events, but only fire the callback after launch when being asked to both install and launch.

0.4.29 (03/14/2017)

  • [TIMOB-24189] Use VsDevCmd instead of vcvarsall

0.4.28 (02/27/2017)

  • [TIMOB-24189] Support Visual Studio 2017

0.4.27 (01/03/2017)

  • [TIMOB-24183] Failed to install WP 8.1 app

0.4.26 (12/20/2016)

  • Use uuid instead of node-uuid

0.4.25 (11/24/2016)

  • [TIMOB-23976] enumerate should just move on even when no results with given version

0.4.24 (11/22/2016)

  • [TIMOB-24157] Install certificate in new window

0.4.23 (9/16/2016)

  • [TIMOB-23879] Terminate running app at launch

0.4.22 (9/14/2016)

  • [TIMOB-23661] Fix typo around preferred SDK

0.4.21 (8/26/2016)

  • [TIMOB-23834] Ability to skip windows phone detection

0.4.20 (8/26/2016)

  • [TIMOB-23816] Fix 8.1 emulator listing

0.4.19 (8/23/2016)

  • [TIMOB-23800] CLI hangs on install of app when a different app is installed

0.4.18 (8/12/2016)

  • [TIMOB-23762] Handle duplicate package error from Windows SDK 10.0.14393

0.4.17 (8/12/2016)

  • [TIMOB-23768] Detect installed Win10 SDK versions

0.4.16 (8/9/2016)

  • [TIMOB-23748] Fix: Failed to connect to WP 8.1 device

0.4.15 (7/13/2016)

  • [TIMOB-23279] Only report detected device

0.4.14 (6/24/2016)

  • [TIMOB-23484] wptool.detect() ignore errors when results are present

0.4.13 (4/29/2016)

  • Fix [TIMOB-20376] Windows Phone: Cannot read property 'split' of undefined

0.4.12 (4/27/2016)

  • Fix "TypeError: undefined is not a function" at Array.findIndex on Node.js 0.12.7

0.4.11 (4/27/2016)

  • Fix: async.each to async.eachSeries

0.4.10 (4/27/2016)

  • [TIMOB-23253] Windows: Build errors when building to device and selecting second option in device prompt
  • Send separate installed and launched events for wptool#install/device#install/emulator#install/windowslib#install
  • We can tell if the app got installed but failed to launch (which I'm seeing repeatedly with my Windows 10 mobile device), allowing us to tell the user to launch the app manually.

0.4.9 (4/18/2016)

  • [TIMOB-20611] Allow wptool to launch Windows 10 apps

0.4.8 (4/14/2016)

  • [TIMOB-20571] Combine device listings

0.4.7 (4/13/2016)

  • [TIMOB-20571] Add device version and wpsdk to enumerate

0.4.6 (4/12/2016)

0.4.5 (4/5/2016)

  • [TIMOB-19673] Fix unescaped characters in vcvarsall

0.4.4 (3/16/2016)

  • [TIMOB-20566] Add support for Windows 10 devices
  • Improve log output from certutil

0.4.3 (2/17/2016)

  • Another fix for uninstalling store apps from Windows 8.1

0.4.2 (2/17/2016)

  • Align dependencies with titanium_mobile

0.4.1 (2/17/2016)

  • When removing windows store package, properly pass along command (was broken on Windows 8.1)

0.4.0 (2/10/2016)

  • Support enumerating devices using Windows 10 WinAppDeployCmd
  • Make wstool print pid after launching Windows Store app sucessfully (as stdout)
  • Move common code to utilities.js for checking if wptool/wstool need to be rebuilt.
  • Add method for loopback ip network isolation exempting a Windows Store app by id/Name: windowslib.winstore.loopbackExempt(appId, options, callback);
  • Add method to get listing of Windows appx containers as JSON: windowslib.winstore.getAppxPackages(options, callback);
  • Fix broken wp_get_appx_metadata.ps1 file from newline mid-line
  • Add method to find a process by pid: windowslib.process.find(pid, options, callback);

0.3.0 (1/6/2016)

  • Support detection and use of Windows 10 SDK/tooling without requiring 8.1 tools installed.

0.2.2 (12/14/2015)

  • Better error messages about bad app GUIDs when launching using our custom wptool
  • Support appxbundles for extracting the app GUID, look in multiple locations in XML (still may get just the text appid and not GUID)
  • Support passing in the app GUID for the launch/install methods so we don't need to extract it from appx/appxbundle if we already know it.

0.2.1 (12/11/2015)

  • Fix detection of Windows 10 phone details

0.2.0 (12/10/2015)

  • Add custom tooling for Win 10 mobile.
  • Support enumerating, launching and installing apps to Win 10 Mobile emulators

0.1.22 (12/4/2015)

  • Fix: Windows 10 Mobile detection #26

0.1.21 (10/29/2015)

  • Fix: escape vcvarsall before subprocess.run #25

0.1.20 (10/13/2015)

0.1.19 (10/7/2015)

  • Line up dependencies to match titanium_mobile's dependencies.

0.1.18 (10/7/2015)

0.1.17 (9/30/2015)

  • Line up dependencies to match titanium_mobile's dependencies.

0.1.16 (9/30/2015)

0.1.15 (6/29/2015)

  • Fix for TIMOB-19090 - Windows: Building for ws-local fails with powershell error 'Read-Host : Windows PowerShell is in NonInteractive mode'
  • Install of winstore app script requires not using the -NoInteractive flag to powershell.

0.1.14 (6/25/2015)

  • More changes related to fixing TIMOB-18958 - Windows: CLI builds hang on first try due to Powershell permission check in windowslib

0.1.13 (6/11/2015)

  • Expand cert utility functionality
  • Fix for winstore app install method

0.1.12 (6/9/2015)

  • Fix TIMOB-18958 - Windows: CLI builds hang on first try due to Powershell permission check in windowslib
  • Expand Win Store Tooling Detection

0.1.11 (4/16/2015)

  • Fix TIMOB-18822 - Added check so that os name and powershell info is only detected on Windows 8 or newer.

0.1.10 (3/18/2015)

  • Fix TIMOB-18706 - Error when Windows Phone SDK is NOT installed

0.1.9 (2/25/2015)

  • Update to node-appc 0.2.24

0.1.8 (2/23/2015)

  • Fix issues launching phone emulator seen on some setups/foreign languages

0.1.7 (1/8/2015)

  • Remove use of custom wptool, defer to deploy cmd for launch/connect [TIMOB-18303]
  • Surface exact error message from deploy command on failure (Issue #5)

0.1.6 (12/16/2014)

  • Minor fix for surfacing errors in wptool.js, wrong variable name referenced.

0.1.5 (12/05/2014)

  • Made wstool launch of WinStore apps more robust

0.1.4 (12/03/2014)

  • Detects Visual Studio Express editions and have a better error reporting when Visual Studio is not found
  • Added missing node-appc reference in the index.js

0.1.3 (12/01/2014)

  • add option to skipLaunch when installing Windows Phone app

0.1.2 (11/25/2014)

  • Added detection of the XapSignTool executable

0.1.1 (11/12/2014)

  • Fixed bug with installing Windows Store apps

0.1.0 (11/12/2014)

  • Initial release of windowslib
  • Supports launching Windows Phone emulators, install apps to emulators and devices, log output, cert generation, development environment detection and much, much more [TIMOB-17515]