1 | # Windows Phone Utility Library [![Build Status](https://travis-ci.org/appcelerator/windowslib.svg?branch=master)](https://travis-ci.org/appcelerator/windowslib)
|
2 |
|
3 | This is a library of utilities for dealing programmatically with Windows Phone applications,
|
4 | used namely for tools like [Titanium](https://github.com/appcelerator/titanium).
|
5 |
|
6 | windowslib supports Visual Studio 2012, 2013, and 2015.
|
7 |
|
8 | [![NPM](https://nodei.co/npm/windowslib.png?downloads=true&stars=true)](https://nodei.co/npm/windowslib/)
|
9 |
|
10 | ## Installation
|
11 |
|
12 | From NPM:
|
13 |
|
14 | npm install windowslib
|
15 |
|
16 | From GitHub:
|
17 |
|
18 | npm install git://github.com/appcelerator/windowslib.git
|
19 |
|
20 | ## Caveats
|
21 |
|
22 | - Some of the emulator detection functionality requires the use of PowerShell
|
23 | scripts. For the library to be able to execute these scripts, the user must
|
24 | change their ExecutionPolicy by running the following in a PowerShell
|
25 | terminal as the Administrator:
|
26 | ```
|
27 | Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
28 | ```
|
29 |
|
30 | - If attempting to connect to a device, you need to ensure the connected device
|
31 | is not asleep/locked or connecting will fail. There's no way to
|
32 | programmatically unlock the device.
|
33 |
|
34 | ## Examples
|
35 |
|
36 | ### Detect all the connected Windows Phone devices:
|
37 |
|
38 | Note: Microsoft's tooling always reports a single device present regardless if
|
39 | there are no devices connected or several. The device will have an ID of `0`
|
40 | (zero).
|
41 |
|
42 | In the event Microsoft's next mobile platform has improved tooling that supports
|
43 | multiple devices, this detection code should be good to go.
|
44 |
|
45 | ```javascript
|
46 | var windowslib = require('windowslib');
|
47 |
|
48 | windowslib.device.detect(function (err, devices) {
|
49 | if (err) {
|
50 | console.error(err);
|
51 | } else {
|
52 | console.log(devices);
|
53 | }
|
54 | });
|
55 | ```
|
56 |
|
57 | ### Install an Application on Device
|
58 |
|
59 | ```javascript
|
60 | var deviceUDID = null; // string or null to pick first device
|
61 |
|
62 | windowslib.device.install(deviceUDID, 'C:\\path\\to\\appfile.appx')
|
63 | .on('installed', function () {
|
64 | console.log('App successfully installed on device');
|
65 | })
|
66 | .on('error', function (err) {
|
67 | console.error(err);
|
68 | });
|
69 | ```
|
70 |
|
71 | ### Launch the Windows Phone Emulator
|
72 |
|
73 | Passing in null for the `udid` will auto-select a emulator and launch it.
|
74 |
|
75 | ```javascript
|
76 | windowslib.emulator.launch(null, function (err, handle) {
|
77 | console.log('Emulator launched');
|
78 | windowslib.emulator.stop(handle, function () {
|
79 | console.log('Emulator stopped');
|
80 | });
|
81 | });
|
82 | ```
|
83 |
|
84 | ### Launch, install, and Run an Application on the Emulator
|
85 |
|
86 | ```javascript
|
87 | var udid = null; // string or null to pick an emulator
|
88 |
|
89 | windowslib.emulator.install(udid, 'C:\\path\\to\\appfile.appx')
|
90 | .on('launched', function (msg) {
|
91 | console.log('Emulator has launched');
|
92 | })
|
93 | .on('appStarted', function (msg) {
|
94 | console.log('App has started');
|
95 | })
|
96 | .on('log', function (msg) {
|
97 | console.log('[LOG] ' + msg);
|
98 | })
|
99 | .on('error', function (err) {
|
100 | console.error(err);
|
101 | });
|
102 | ```
|
103 |
|
104 | ### Force Stop an Application Running on the Emulator
|
105 |
|
106 | ```javascript
|
107 | windowslib.emulator.launch(udid)
|
108 | .on('launched', function (handle) {
|
109 | console.log('Emulator launched');
|
110 | windowslib.emulator.stop(handle).on('stopped', function () {
|
111 | console.log('Emulator stopped');
|
112 | });
|
113 | });
|
114 | ```
|
115 |
|
116 | ### Detect Everything
|
117 |
|
118 | ```javascript
|
119 | windowslib.detect(function (err, info) {
|
120 | if (err) {
|
121 | console.error(err);
|
122 | } else {
|
123 | console.log(info);
|
124 | }
|
125 | });
|
126 | ```
|
127 |
|
128 | ## Running Tests
|
129 |
|
130 | For best results, connect a Windows phone device.
|
131 |
|
132 | To run all tests:
|
133 |
|
134 | ```
|
135 | npm test
|
136 | ```
|
137 |
|
138 | To run a specific test suite:
|
139 |
|
140 | ```
|
141 | npm run-script test-assemblies
|
142 |
|
143 | npm run-script test-device
|
144 |
|
145 | npm run-script test-emulator
|
146 |
|
147 | npm run-script test-env
|
148 |
|
149 | npm run-script test-logrelay
|
150 |
|
151 | npm run-script test-process
|
152 |
|
153 | npm run-script test-visualstudio
|
154 |
|
155 | npm run-script test-windowsphone
|
156 |
|
157 | npm run-script test-wptool
|
158 | ```
|
159 |
|
160 | ## Reporting Bugs or Submitting Fixes
|
161 |
|
162 | If you run into problems, and trust us, there are likely plenty of them at this
|
163 | point -- please create an [Issue](https://github.com/appcelerator/windowslib/issues)
|
164 | or, even better, send us a pull request.
|
165 |
|
166 | ## Contributing
|
167 |
|
168 | windowslib is an open source project. windowslib wouldn't be where it is now without
|
169 | contributions by the community. Please consider forking windowslib to improve,
|
170 | enhance or fix issues. If you feel like the community will benefit from your
|
171 | fork, please open a pull request.
|
172 |
|
173 | To protect the interests of the windowslib contributors, Appcelerator, customers
|
174 | and end users we require contributors to sign a Contributors License Agreement
|
175 | (CLA) before we pull the changes into the main repository. Our CLA is simple and
|
176 | straightforward - it requires that the contributions you make to any
|
177 | Appcelerator open source project are properly licensed and that you have the
|
178 | legal authority to make those changes. This helps us significantly reduce future
|
179 | legal risk for everyone involved. It is easy, helps everyone, takes only a few
|
180 | minutes, and only needs to be completed once.
|
181 |
|
182 | [You can digitally sign the CLA](http://bit.ly/app_cla) online. Please indicate
|
183 | your email address in your first pull request so that we can make sure that will
|
184 | locate your CLA. Once you've submitted it, you no longer need to send one for
|
185 | subsequent submissions.
|
186 |
|
187 | ## Legal
|
188 |
|
189 | Copyright (c) 2014-2015 by [Appcelerator, Inc](http://www.appcelerator.com). All
|
190 | Rights Reserved. This project is licensed under the Apache Public License,
|
191 | version 2. Please see details in the LICENSE file.
|