initial commit of the fo docs and necessary basics for mkdocs static site generation (#40)
This commit is contained in:
Ali Hajy
GitHub
Родитель
7e791626f6
Коммит
74011bce52
|
|
@ -332,3 +332,10 @@ ASALocalRun/
|
|||
|
||||
# MFractors (Xamarin productivity tool) working folder
|
||||
.mfractor/
|
||||
|
||||
# Python
|
||||
.venv
|
||||
venv/
|
||||
|
||||
# Mkdocs site out
|
||||
site/
|
||||
|
|
|
|||
146
README.md
146
README.md
|
|
@ -1,98 +1,126 @@
|
|||
| CI Build |
|
||||
|----|
|
||||
| [](https://microsoft.visualstudio.com/OneCore/_build/latest?definitionId=54749&branchName=main) |
|
||||
# [Factory Orchestrator](https://microsoft.github.io/FactoryOrchestrator/)
|
||||
|
||||
# Introduction
|
||||
Factory Orchestrator is a tool for built for Original Equipment Maufacturers to aid in the manufacturing of Windows devices.
|
||||
Factory Orchestrator consists of the following projects:
|
||||
## FactoryOrchestratorCoreLibrary
|
||||
.NET Standard library containing the core FactoryOrchestrator classes. Required in all projects.
|
||||
## FactoryOrchestratorServerLibrary
|
||||
A .NET Standard library containing the server-side FactoryOrchestrator classes. Required on all FactoryOrchestrator server projects.
|
||||
## FactoryOrchestratorService
|
||||
.NET Core Executable project for FactoryOrchestratorService.exe, the FactoryOrchestrator server implementation. Requires administrator access to run.
|
||||
## FactoryOrchestratorClientLibrary
|
||||
.NET Standard library containing the client-side FactoryOrchestrator classes, required to interact with FactoryOrchestratorService. Also contains optional helper classess.
|
||||
## FactoryOrchestratorApp
|
||||
C# UWP app project for FactoryOrchestratorApp.exe, the UWP used to manually interact with FactoryOrchestratorService via GUI.
|
||||
## Open Source Components
|
||||
### IpcServiceFramework
|
||||
FactoryOrchestrator forks the source of [IpcServiceFramework](https://github.com/jacqueskang/IpcServiceFramework). At this time, we are actively working on integrating our version of IpcServiceFramework with the [official IpcServiceFramework repo](https://github.com/jacqueskang/IpcServiceFramework), removing the need for this fork.
|
||||
### Pe-Utility
|
||||
FactoryOrchestrator minimally forks a portion of the source of [Pe-Utility](https://github.com/AndresTraks/pe-utility), to build it as a .NET Standard library and reduce the code complexity for FactoryOrchestrator's use case.
|
||||
[](https://microsoft.visualstudio.com/OneCore/_build/latest?definitionId=54749&branchName=main)
|
||||
|
||||
# Contributing
|
||||
Factory Orchestrator provides a simple and reliable way to run and manage factory line validation and fault analysis workflows. Beyond the factory floor Factory Orchestrator can be during os and hardware development to support various developer inner-loop and diagnostics activities.
|
||||
|
||||
## 1. Accept Contributor Licence Agreement (CLA)
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
||||
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
|
||||
Learn more about this tool and how to use it by reading the [documentation here](https://microsoft.github.io/FactoryOrchestrator/).
|
||||
|
||||
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
|
||||
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
|
||||
provided by the bot. You will only need to do this once across all repos using our CLA.
|
||||
The [getting started](https://microsoft.github.io/FactoryOrchestrator/get-started-with-factory-orchestrator/) page is a great place to go once you've built the binaries for the project.
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
## **Factory Orchestrator consists of the following projects:**
|
||||
|
||||
## 2. Prerequisite steps
|
||||
### Install Visual Studio
|
||||
Any variation of [Visual Studio 2019+ (Enterprise, Community)](https://visualstudio.microsoft.com/vs/) is fine. In the installer, make sure you click the checkboxes for .NET Core cross-platform Development, and Universal Windows Platform Development (10.0.17763.0).
|
||||
* **FactoryOrchestratorCoreLibrary**
|
||||
A .NET Standard library containing the core FactoryOrchestrator classes. Required in all projects.
|
||||
|
||||
Other development environments such as [Visual Studio Code](https://code.visualstudio.com/) are acceptible if you are not making FactoryOrchestratorApp changes.
|
||||
* **FactoryOrchestratorServerLibrary**
|
||||
A .NET Standard library containing the server-side FactoryOrchestrator classes. Required on all FactoryOrchestrator server projects.
|
||||
|
||||
### Clone the repository
|
||||
* **FactoryOrchestratorService**
|
||||
.NET Core Executable project for FactoryOrchestratorService.exe, the FactoryOrchestrator server implementation. Requires administrator access to run.
|
||||
|
||||
* **FactoryOrchestratorClientLibrary**
|
||||
.NET Standard library containing the client-side FactoryOrchestrator classes, required to interact with FactoryOrchestratorService. Also contains optional helper classes.
|
||||
|
||||
* **FactoryOrchestratorApp**
|
||||
C# UWP app project for FactoryOrchestratorApp.exe, the UWP provides a GUI (Graphical User Interface) to manually interact with FactoryOrchestratorService.
|
||||
|
||||
Factory Orchestrator :green_heart: OSS.
|
||||
|
||||
### **OSS Projects currently consumes:**
|
||||
|
||||
* **IpcServiceFramework**
|
||||
|
||||
FactoryOrchestrator forks the source of [IpcServiceFramework](https://github.com/jacqueskang/IpcServiceFramework). At this time, we are actively working on integrating our version of IpcServiceFramework with the [official IpcServiceFramework repo](https://github.com/jacqueskang/IpcServiceFramework), removing the need for this fork.
|
||||
|
||||
* **Pe-Utility**
|
||||
|
||||
FactoryOrchestrator minimally forks a portion of the source of [Pe-Utility](https://github.com/AndresTraks/pe-utility), to build it as a .NET Standard library and reduce the code complexity for FactoryOrchestrator's use case.
|
||||
|
||||
|
||||
**Factory Orchestrator ```src``` directory structure:**
|
||||
|
||||
```
|
||||
FactoryOrchestrator
|
||||
└──src
|
||||
| App
|
||||
| ClientLibrary
|
||||
| ClientSample
|
||||
| CoreLibrary
|
||||
| oss
|
||||
| ServerLibrary
|
||||
| Service
|
||||
| Tests
|
||||
└ UWPClientLibrary
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Install dependencies
|
||||
|
||||
The easiest way to open the project is using any variation of [Visual Studio 2019+ (Enterprise, Community)](https://visualstudio.microsoft.com/vs/). In the installer, make sure you click the checkboxes for .NET Core cross-platform Development, and Universal Windows Platform Development (10.0.17763.0).
|
||||
|
||||
You can also use [Visual Studio Code](https://code.visualstudio.com/), or any whatever editor you prefer. Visual Studio provides a sleek [command-line installer](https://docs.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio) that can be used to just deploy the necessary dependencies using their [workload component id](https://docs.microsoft.com/en-us/visualstudio/install/workload-component-id-vs-community).
|
||||
|
||||
### Enable developer mode on Windows
|
||||
|
||||
### Enable developer mode on Windows
|
||||
https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development
|
||||
|
||||
### Address Unsigned Powershell Scripts
|
||||
### Addressing Unsigned Powershell Scripts
|
||||
FactoryOrchestrator contains a series of unsigned powershell scripts. Windows security measures prevent unsigned scripts from executing. In order to develop on FactoryOrchestrator, you need to do one of two things.
|
||||
|
||||
#### Self-sign
|
||||
More information on how to do this can be found here: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7
|
||||
1. Self-sign the scripts
|
||||
|
||||
#### Set the Execution Policy to Unrestricted
|
||||
This method is not recommended. Setting the Execution Policy to Unresricted allows any powershell script to run.
|
||||
Documentation on Execution Policy:
|
||||
More information on how to do this can be found here: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7
|
||||
|
||||
2. Set the Execution Policy to Unrestricted
|
||||
|
||||
This method is not recommended. Setting the Execution Policy to Unresricted allows any powershell script to run.
|
||||
|
||||
Documentation on Execution Policy:
|
||||
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7
|
||||
|
||||
## 3. Building
|
||||
When building the source code, keep in mind that certain actions only occur when the build is run as part of an Azure DevOps Pipeline or when run in the "Release" configuration locally. For example, [DocFX documentation](https://dotnet.github.io/docfx/) for the Core and Client Libraries is only generated when the build is run in in one of those two modes. These actions are skipped in Debug builds to increase inner-dev-loop speed.
|
||||
|
||||
## 4. Debugging
|
||||
Run _FactoryOrchestratorApp (Universal Windows)_ and _FactoryOrchestratorService_ in separate Visual Studio 2019+ instances. This will allow the app and the service to communicate with each other.
|
||||
Even if you are coding for just the app, you generally need to run the service so the app has something to connect to. The service must be run as administrator.
|
||||
## Debugging
|
||||
|
||||
At the moment, running either the app or service under a debugger will cause exceptions to be thrown related to certain registry keys (ex: GetOEMVersionString()), but all exceptions are caught and will not result in a crash. This is because they try to access registry keys specific to a Microsoft internal product. You can routinely skip over these exceptions when they occur or disable them.
|
||||
Run _FactoryOrchestratorApp (Universal Windows)_ and _FactoryOrchestratorService_ in separate Visual Studio 2019+ instances. This will allow the app and the service to communicate with each other.
|
||||
|
||||
## Versioning
|
||||
|
||||
## 5. Versioning
|
||||
Factory Orchestrator uses a slightly modified form of [semver versioning](https://semver.org/). All Factory Orchestrator binaries from the same build share the same version; there is no unique client or service version. In the [src/custom.props](src/custom.props) file, increment the:
|
||||
|
||||
- MAJOR version when you make incompatible API changes,
|
||||
- MINOR version when you add functionality in a backwards compatible manner.
|
||||
* MAJOR version when you make incompatible API changes,
|
||||
* MINOR version when you add functionality in a backwards compatible manner.
|
||||
|
||||
The PATCH version is automatically set by the build, and is based on the [date/time the build is run](build/SetSourceVersion.ps1). The PATCH version is only changed when the build is run as part of an Azure Pipeline or when run in the "Release" configuration locally.
|
||||
|
||||
When the MAJOR version diverges between a Client and Service, Clients will be prevented from connecting to the Service by default. Changing the signiture of any FactoryOrchestratorCoreLibrary class is therefore usually a MAJOR version change and should be done sparingly.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
|
||||
|
||||
## Contributing
|
||||
|
||||
Accepting the Contributor Licence Agreement (CLA)
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
|
||||
|
||||
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
|
||||
|
||||
Happy Coding!
|
||||
|
||||
# Reporting Security Issues
|
||||
## Reporting Security Issues
|
||||
|
||||
Please refer to [SECURITY.md](./SECURITY.md).
|
||||
|
||||
# License
|
||||
Copyright (c) Microsoft Corporation. All rights reserved.
|
||||
## Open Source Software Acknowledgments
|
||||
|
||||
Licensed under the [MIT License](./LICENSE).
|
||||
|
||||
# Open Source Software Acknowledgments
|
||||
[IpcServiceFramework](https://github.com/jacqueskang/IpcServiceFramework) - Jacques Kang - [MIT License](https://github.com/jacqueskang/IpcServiceFramework/blob/develop/LICENSE)
|
||||
|
||||
[DotNetCore.WindowsService](https://github.com/PeterKottas/DotNetCore.WindowsService) - Peter Kottas - [MIT License](https://github.com/PeterKottas/DotNetCore.WindowsService/blob/master/LICENSE)
|
||||
|
||||
[Pe-Utility](https://github.com/AndresTraks/pe-utility) - Andres Traks - [MIT License](https://github.com/AndresTraks/pe-utility/blob/master/LICENSE)
|
||||
|
||||
[WindowsDevicePortalWrapper (mgurlitz .NET Standard fork)](https://github.com/mgurlitz/WindowsDevicePortalWrapper/tree/feat-standard) - Microsoft Corporation and mgurlitz - [MIT License](https://github.com/mgurlitz/WindowsDevicePortalWrapper/blob/feat-standard/License.txt)
|
||||
[WindowsDevicePortalWrapper (mgurlitz .NET Standard fork)](https://github.com/mgurlitz/WindowsDevicePortalWrapper/tree/feat-standard) - Microsoft Corporation and mgurlitz - [MIT License](https://github.com/mgurlitz/WindowsDevicePortalWrapper/blob/feat-standard/License.txt)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
# Factory Orchestrator Documentation
|
||||
|
||||
[Factory Orchestrator](https://microsoft.github.io/FactoryOrchestrator/) uses [MkDocs](https://www.mkdocs.org/) to generate usage documentation.
|
||||
|
||||
We welcome contributions on our documentation as well under the same code of conduct as the rest of the project.
|
||||
|
||||
To build & locally view the docs you can follow [these steps](https://www.mkdocs.org/#building-the-site):
|
||||
|
||||
From the root:
|
||||
|
||||
1. pip install --upgrade -r requirements.txt
|
||||
2. mkdocs build --clean
|
||||
3. mkdocs serve
|
||||
|
||||
Once you are happy with the changes, you can prepare a pull request to update the checked in docs as you would with any other code change.
|
||||
|
||||
When completed, then you will have to manually update the live docs by do the following from the root (todo: make better):
|
||||
|
||||
1. (optional- in case you rev'd it) mkdocs build --clean --config-file .\docs\mkdocs.yml
|
||||
2. git checkout gh-pages
|
||||
3. git checkout -b <topic branch with>
|
||||
4. Commit your changes, open a pull request. Once approved and the remote 'gh-branch' has the last changes then it will update the website.
|
||||
|
||||
## ## Open Source Software Acknowledgments
|
||||
|
||||
### Mkdocs
|
||||
|
||||
<https://www.mkdocs.org/>
|
||||
|
||||
MkDocs License (BSD)
|
||||
Copyright © 2014, Tom Christie. All rights reserved.
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
### Material for MkDocs
|
||||
|
||||
<https://squidfunk.github.io/mkdocs-material/>
|
||||
|
||||
License
|
||||
MIT License
|
||||
Copyright © 2016 - 2017 Martin Donath
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
|
||||
# Factory Orchestrator utilities
|
||||
|
||||
In addition to providing a graphical interface to create, manage, and run Tasks and TaskLists. The Factory Orchestrator app also includes some basic utilities intended as a starting point for integration into a manufacturing line, fault analysis workflow or developer inner loop.
|
||||
|
||||
<!-- ## UWP Apps
|
||||
|
||||
This launches a UWP app that's installed on a device under test (DUT). This allows you to launch a UWP directly from the Factory Orchestrator app by clicking on its name in the list of installed UWP apps.
|
||||
|
||||
Your device must be configured to launch into an environment that supports launching UWP apps.
|
||||
|
||||
You can exit a launched UWP with ALT+F4, or from Windows Device Portal. -->
|
||||
|
||||
## Command Prompt
|
||||
|
||||
A basic, non-interactive, command prompt that allows you to troubleshoot without having use other methods like SSH or Windows Device Portal to connect to your DUT.
|
||||
|
||||
While you can run commands and see output when using the built-in command prompt in Factory Orchestrator, it's not an interactive shell. If you run a command that requires additional input, you won't be able to enter the additional input.
|
||||
|
||||
|
||||
|
||||
## (very) basic File Transfer
|
||||
|
||||
A basic file transfer function that enables you to transfer files to and from your device when you're connected from a technician PC. This feature is not visible in the Factory Orchestrator app when run the app and service on the same device.
|
||||
|
||||
### One-time setup (Windows 10 only)
|
||||
|
||||
First, install the Factory Orchestrator app on a Windows 10 system:
|
||||
|
||||
```PowerShell
|
||||
Add-AppxPackage -path "FactoryOrchestrator\Microsoft.FactoryOrchestratorApp_8wekyb3d8bbwe.msixbundle" -DependencyPath "frameworks\Microsoft.NET.CoreFramework.x64.Debug.2.2.appx" -DependencyPath "frameworks\Microsoft.NET.CoreRuntime.x64.2.2.appx" -DependencyPath "frameworks\Microsoft.VCLibs.x64.14.00.appx"
|
||||
```
|
||||
|
||||
Next, you need to give the Factory Orchestrator app full file system access for file transfer to work. Follow the directions on the [Windows 10 file system access and privacy](https://support.microsoft.com/en-us/help/4468237/windows-10-file-system-access-and-privacy-microsoft-privacy) page to give Factory Orchestrator access to the file system. You may need to launch the app at least once before it appears on the Settings app.
|
||||
|
||||
### Send file to a DUT
|
||||
|
||||
- From your Windows 10 device, launch Factory Orchestrator and connect to the IP address of the DUT.
|
||||
- In the "Client File" textbox, enter the full path to a file on your Windows 10 device.
|
||||
- In the "Server File" textbox, enter the full path of where you wish the file to be saved on the DUT. Make sure the location you're saving to is writeable.
|
||||
- Click "Send Client File to Server" to transfer the file from the Windows 10 device to the device.
|
||||
|
||||
### Receive file from your device device
|
||||
|
||||
- From your Windows 10 technician PC, launch Factory Orchestrator and connect to the IP address of the DUT.
|
||||
- In the "Server File" textbox, enter the full path to a file on the DUT.
|
||||
- In the "Client File" textbox, enter the full path to where you wish the file to be saved on the Windows 10 device.
|
||||
- Click "Save Server File to Client" to transfer the file to the DUT.
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
|
||||
# Get Started with Factory Orchestrator
|
||||
|
||||
## Install the service
|
||||
|
||||
The Factory Orchestrator service (FactoryOrchestratorService.exe) runs on your Device under Test and acts as the engine powering Factory Orchestrator. You can connect to the Factory Orchestrator service from a remote technician PC, or from the device itself.
|
||||
|
||||
User PowerShell to install the Factory Orchestrator on your device:
|
||||
|
||||
```PowerShell
|
||||
## Optionally set it's start up to automatic with: -StartupType Automatic
|
||||
New-Service -Name "FactoryOrchestrator" -BinaryPathName "FactoryOrchestratorService.exe"
|
||||
|
||||
Start-Service -Name "FactoryOrchestrator"
|
||||
```
|
||||
|
||||
To connect to the service, you can use the Factory Orchestrator UWP app, or interact with the service programattically using the Factory Orchestrator client APIs.
|
||||
|
||||
## Install the app
|
||||
|
||||
You can install the Factory Orchestrator app on your DUT or on a technician PC.
|
||||
|
||||
To install the app:
|
||||
|
||||
1. On your technician PC, open an administrative Command prompt.
|
||||
|
||||
2. Use Powershell to [install the app and its dependencies](https://docs.microsoft.com/powershell/module/appx/add-appxpackage?view=win10-ps).
|
||||
|
||||
```PowerShell
|
||||
Add-AppxPackage -path "FactoryOrchestrator\Microsoft.FactoryOrchestratorApp_8wekyb3d8bbwe.msixbundle" -DependencyPath "frameworks\Microsoft.NET.CoreFramework.x64.Debug.2.2.appx" -DependencyPath "frameworks\Microsoft.NET.CoreRuntime.x64.2.2.appx" -DependencyPath "frameworks\Microsoft.VCLibs.x64.14.00.appx"
|
||||
```
|
||||
|
||||
## Run Factory Orchestrator
|
||||
|
||||
### Default behavior
|
||||
|
||||
>[!Important]
|
||||
>Need instructions on how to configure a device to run FO automatically
|
||||
|
||||
### If the app isn't configured to run automatically
|
||||
|
||||
To run the Factory Orchestrator app:
|
||||
|
||||
1. Connect to the device where the app is installed with Device Portal
|
||||
2. From Device Portal's Apps manager tab, choose `Factory Orchestrator (App)` from the Installed Apps list.
|
||||
3. Click Start
|
||||
|
||||
The Factory Orchestrator app will start on the DUT. The Factory Orchestrator service is always running.
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 15 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 28 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 45 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 5.5 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 10 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 3.7 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 54 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 54 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 13 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 24 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 135 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 38 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 75 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 14 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 45 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 63 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 20 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 1.5 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 16 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 29 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 5.5 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 6.4 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 26 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 17 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 29 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 12 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 623 B |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 9.9 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 1.7 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 391 B |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 65 KiB |
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
author: themar-msft;hajya
|
||||
ms.date: 09/30/2019
|
||||
---
|
||||
|
||||
# Factory Orchestrator
|
||||
|
||||
Factory Orchestrator provides a simple and reliable way to run and manage factory line validation and fault analysis workflows. Beyond the factory floor Factory Orchestrator can be during os and hardware development to support various developer inner-loop and diagnostics activities.
|
||||
|
||||
Factory Orchestrator consists of two components:
|
||||
|
||||
- A system service (FactoryOrchestratorService.exe): The service tracks task information, including run unique per-run results and logging; even persisting task state to allow the service to be resilient to data loss due to client failure.
|
||||
|
||||
- A UWP app: Communicates with the service to run executable tasks and commands on a device under test (DUT). This app can communicate with the service running on the same device and/or over a network.
|
||||
|
||||
Tasks are used to capture actions that the server can executre, and TaskLists are used to organize and manage these Tasks. Learn more about [Tasks and Tasklists](tasks-and-tasklists.md)
|
||||
|
||||
[Getting started with Factory Orchestrator](get-started-with-factory-orchestrator.md)
|
||||
|
||||
## Factory Orchestrator logs
|
||||
|
||||
By default, the Factory Orchestrator Service generates log files in the following location on the test device: `%ProgramData%\FactoryOrchestrator`.
|
||||
|
||||
### Factory Orchestrator Service log file
|
||||
|
||||
The service log file contains details about the operation of the Factory Orchestrator Service. It is always found at `%ProgramData%\FactoryOrchestrator\FactoryOrchestratorService.log` on a device. Inspect this log for details about the service's operation.
|
||||
|
||||
### Factory Orchestrator Task log files
|
||||
|
||||
The Task log files contain details about the execution of a specific of the Factory Orchestrator Task. There is one log file generated for each run of a Task. The files are saved to `%ProgramData%\FactoryOrchestrator\Logs\` on a device by default, but this location can be changed using the FactoryOrchestratorClient.SetLogFolder() API. Use the FactoryOrchestratorClient.GetLogFolder() API to programmatically retrieve the log folder.
|
||||
|
|
@ -0,0 +1,396 @@
|
|||
|
||||
# Tasks and TasksLists
|
||||
|
||||
Factory Orchestrator uses Tasks to capture a single action. Tasks can be executables, TAEF tests, UWP apps, or external tasks. TasksLists are used to order and group Tasks. Tasks in a TaskList can be configured run in series, parallel, or in the background.
|
||||
|
||||
## Factory Orchestrator tasks
|
||||
|
||||
## Task types
|
||||
|
||||
Factory Orchestrator TaskLists allow adding different types of tasks:
|
||||
|
||||
- **Executable**
|
||||
|
||||
These tasks are .exe files which are run directly. When you add this type of task, you can specify additional arguments and if the task should run as a background task.
|
||||
|
||||
- **Batch File**
|
||||
|
||||
These tasks are .bat or .cmd files which are run by the command prompt (cmd.exe). When you add this type of task, you can specify additional arguments and if the task should run as a background task.
|
||||
|
||||
- **PowerShell**
|
||||
|
||||
These tasks are .ps1 files which are run by PowerShell Core (pwsh.exe). When you add this type of task, you can specify additional arguments and if the task should run as a background task.
|
||||
|
||||
- **TAEF**
|
||||
|
||||
[TAEF tests](https://docs.microsoft.com/windows-hardware/drivers/taef/) can be added to a TaskList, and you can specify arguments and if the task should run as a background task.
|
||||
|
||||
- **UWP App**
|
||||
|
||||
Allows you to run a UWP app as a task.
|
||||
|
||||
UWP apps cannot take arguments (though you can use arguments to pass info to the operator about the goal of the Task), nor can they automatically return a pass/fail result. Instead, the operator must manually specify if the app passed or failed via a result prompt that the Factory Orchestrator App launches when the UWP app exits. You can also exit apps via ALT+F4 or Windows Device Portal.
|
||||
|
||||
The Factory Orchestrator service can launch apps even if the Factory Orchestrator app isn't running.
|
||||
|
||||
UWP App tasks will only run on DUTs booted into an environment that supports UWP apps.
|
||||
|
||||
- **External**
|
||||
|
||||
These are tasks that require interaction from a technician before completing. These types of tasks could be used to tell a technician to connect a cable, check a device for scratches, move the device to the next station, etc.
|
||||
|
||||
External Tasks can't automatically return a pass/fail result. The operator must manually specify if the Task passed or failed via a result prompt that the Factory Orchestrator App launches when the Task executes. External tasks will only run on devices that support displaying graphics. Devices configured to boot into a console that can't display graphics won't display external tasks.
|
||||
|
||||
The operator must manually specify if the app passed or failed via a result prompt that the Factory Orchestrator App launches when the app exits, like is shown on this screen:
|
||||
|
||||
|
||||
|
||||
External tasks also support displaying custom images or video as part of the task. These images and videos are intended to allow external tasks to convey more information to technicians on the factory floor. When you create an external task, use **Arguments** to let the operator know what to expect or what actions to take. When you create an external task, use the **Image or Video Path:** field to specify an image or a video.
|
||||
|
||||
 
|
||||
|
||||
### Background tasks
|
||||
|
||||
A BackgroundTask is a type of Task which is not expected to return a pass/fail result. Instead, BackgroundTasks are started before any Tasks defined in the TaskList, and are not tracked by the Factory Orchestrator Service, though their output is logged to a file. BackgroundTasks are intended to be used for logging/monitoring tasks that need to be running before any Task in the TaskList executes.
|
||||
|
||||
BackgroundTasks are defined the exactly the same as a normal Task with the following exceptions:
|
||||
|
||||
- BackgroundTasks can only be an Executable, PowerShell, or BatchFile Task
|
||||
- BackgroundTasks cannot have Timeout or MaxNumberOfRetries set
|
||||
|
||||
When editing a task from the Factory Orchestrator app, you can choose the option of making the task a background task by choosing the "Add as background task?" option.
|
||||
|
||||
Once you've run a task, the Factory Orchestrator service creates a **TaskRun** that is the output and results of the task, as well as other details about the task such as runtime.
|
||||
|
||||
# Author and manage Factory Orchestrator TaskLists
|
||||
|
||||
You can define a collection of tasks in a **TaskList**. Tasks in a TaskList are run in a defined order, and can be a mixture that includes any type of tasks that's supported by Factory Orchestrator. TaskList data persists through reboots. TaskList data is stored and maintained by the Factory Orchestrator service, and doesn't depend on the app being open or running.
|
||||
|
||||
Factory Orchestrator uses XML files to define TaskLists and their associated Tasks. An XML file can contain one or more TaskLists, each with any number of Tasks.
|
||||
|
||||
The XML can either be hand-authored; or authored, imported, and/or exported using the [Factory Orchestrator app's "Manage TaskLists"](#managing-tasklists) section.
|
||||
|
||||
You can get started with Factory Orchestrator by using the **Manage TaskLists** screen in the Factory Orchestrator app to create a TaskList. TaskLists allow you to create collections of tasks that you use to validate your hardware. The Factory Orchestrator app also allows you to export TaskLists for use on other systems. See [Managing TaskLists](#managing-tasklists) below.
|
||||
|
||||
## Managing TaskLists
|
||||
|
||||
Use the Factory Orchestrator app to manage a TaskList. TaskLists can be made up from a combination of the different task types. You can choose whether the tasks in the TaskList will be run one-at-a-time (series), or in parallel.
|
||||
|
||||
When you run Factory Orchestrator, you're presented with the 'Run TaskLists' tab. If you're opening the app for the first time, the app won't show any TaskLists. Once you create a TaskList, it will show on this screen.
|
||||
|
||||
Factory Orchestrator supports using environment variables (ex: %ProgramData%) in all commands.
|
||||
|
||||
To create, modify, and delete TaskLists, click on 'Manage TaskLists'.
|
||||
|
||||
### Create and manage TaskLists
|
||||
|
||||
The 'Manage TaskLists' tab in the Factory Orchestrator app allows you to create, modify, and delete TaskLists.
|
||||
|
||||
#### Create or import TaskLists
|
||||
|
||||
- **Add a whole folder as a TaskList**
|
||||
|
||||
Adds the contents of a local folder into a new TaskList. After you've added a folder, you can edit individual tasks to configure additional arguments, timeout settings, etc.
|
||||
|
||||
|
||||
|
||||
- **Choose individual files to add to a TaskList**
|
||||
|
||||
Use `Create new TaskList` to create a new TaskList where you can individual tasks one-at-a-time to your TaskList. When you add tasks this way, you choose the type of task that you're adding and can configure arguments, timeout settings, etc as you add tasks.
|
||||
|
||||
|
||||
|
||||
- **Import a previously generated TaskLists XML file**
|
||||
|
||||
This enables you to generate and export a TaskList on one device, and import it into your device. Once loaded, imported TaskList XML files can be modified like any other Task List.
|
||||
|
||||
To import a TaskList:
|
||||
|
||||
1. On the **Manage TaskLists** page, click on **Import FactoryOrchestratorXML file**
|
||||
|
||||
|
||||
2. Enter the full path to the FactoryOrchestratorXML you want to import and click ✓
|
||||
|
||||
|
||||
|
||||
When you import a TaskList:
|
||||
|
||||
- All the TaskLists defined in the file are imported
|
||||
- If the TaskList(s) were previously run, the TaskList state is also imported but not Task run results
|
||||
|
||||
When you create a new TaskList, the Factory Orchestrator app generates a GUID that it assigns as the TaskList's name.
|
||||
|
||||
#### Create and modify TaskLists
|
||||
|
||||
Once you've added tasks to a TaskList, you can click the pencil icon to modify as TaskList.
|
||||
|
||||
|
||||
|
||||
When you click the pencil icon, you'll see the following screen:
|
||||
|
||||
|
||||
|
||||
This screen allows you to create new Tasks, rename existing Tasks, reorder Tasks, or edit Tasks.
|
||||
|
||||
- Use the "New `<TaskType>` Task" buttons to create a new Task in the TaskList
|
||||
|
||||
- Use the rename icon () to rename TaskLists
|
||||
|
||||
- Click and drag on the bars to the left of a Task to reorder the Tasks.
|
||||
|
||||
- Use the pencil (edit) button to edit a task. When you click the edit or "New `<TaskType>` Task" buttons, you'll see something similar to:
|
||||
|
||||
|
||||
|
||||
See [FactoryOrchestratorXML](tasks-and-tasklists.md) for information about the different options on this screen.
|
||||
|
||||
- Use the delete buttons to delete an existing Task.
|
||||
|
||||
#### Configure Factory Orchestrator to automatically load TaskLists when it starts
|
||||
|
||||
Factory Orchestrator looks for certain FactoryOrchestratorXML files when it starts. You can use these FactoryOrchestratorXML files to pre-load tasks into Factory Orchestrator, run tasks the first time a device boots, or run tasks every time a device boots.
|
||||
|
||||
See [Special FactoryOrchestratorXML files](tasks-and-tasklists.md#special-factoryorchestratorxml-files) for more information.
|
||||
|
||||
#### Export TaskLists
|
||||
|
||||
If you create one or more TaskLists, you can export and save them. This allows you to add them onto another device. From the 'Manage TaskLists" screen:
|
||||
|
||||
- Save a single TaskList by clicking on the disk icon next to the TaskList name
|
||||
- Save all your TaskLists by clicking on the button that says 'Save All TaskLists to XML File`
|
||||
|
||||
To export TaskLists:
|
||||
|
||||
Here is an image of the **Manage TaskLists** page with one TaskList loaded:
|
||||
|
||||
|
||||
|
||||
From this page, you can:
|
||||
|
||||
- Export a specific TaskList by clicking on the save icon (./images/save-icon.png) next to the Task
|
||||
- Export all TaskLists by clicking on the **Save All TaskLists to File** button.
|
||||
|
||||
After you click one of these buttons, enter the full path of the file to save and click the (✓) to confirm.
|
||||
|
||||
## Special FactoryOrchestratorXML files
|
||||
|
||||
When it starts, the Factory Orchestrator service looks in `%DataDrive%\TestContent` for the following FactoryOrchestratorXML files that determine startup behavior:
|
||||
|
||||
| Filename | Usage |
|
||||
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| InitialTaskLists.xml | These Factory Orchestrator TaskLists are loaded on first boot only. This file defines the default state of Factory Orchestrator, that is the TaskLists & tasks that are shown in the FO UI. |
|
||||
| FirstBootTasks.xml | These TaskLists are run once, on the first boot of the DUT. |
|
||||
| EveryBootTasks.xml | These TaskLists are run on every boot of the DUT, including first boot. On first boot, it is always run after FirstBootTasks. |
|
||||
|
||||
When Factory Orchestrator is running these tasks, you'll see a warning in the Factory Orchestrator UI:
|
||||
|
||||
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The Factory Orchestrator Service does not allow communication with clients such as the Factory Orchestrator app until any `<Tasks>` defined in the relevant *BootTasks.xml files are done executing.
|
||||
- **DO NOT use External or UWP Tasks in these files**, as there is no way to mark those Tasks as completed without a connected Factory Orchestrator client.
|
||||
- While you can author normal `<Tasks>` in the *BootTasks.xml files, `<BackgroundTasks>` are very useful for the FirstBootTasks and EveryBootTasks XML files, as you can define `<BackgroundTasks>` which start on boot, aren't expected to ever exit, and will run in the background forever (provided `TerminateBackgroundTasksOnCompletion="false"`).
|
||||
- You can inspect the [FactoryOrchestrator log files](index.md#factory-orchestrator-logs) for details about the execution of these special FactoryOrchestratorXML files.
|
||||
|
||||
## Factory Orchestrator XML Schema
|
||||
|
||||
When hand-authoring FactoryOrchestratorXML files, you'll need to follow the FactoryOrchestratorXML schema. At the end of this topic, we've also provided a [sample FactoryOrchestratorXML file](#sample-factory-orchestrator-xml-file):
|
||||
|
||||
```XML
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<xs:schema id="FactoryOrchestratorXML"
|
||||
elementFormDefault="qualified"
|
||||
xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
>
|
||||
<xs:element name="TaskRunGuids">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element name="Guid" type="xs:string" minOccurs="1" maxOccurs="unbounded"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
|
||||
<xs:complexType name="TaskType">
|
||||
<xs:all>
|
||||
<xs:element name="LatestTaskRunTimeStarted" type="xs:dateTime" minOccurs="0" maxOccurs="1"/>
|
||||
<xs:element name="LatestTaskRunTimeFinished" type="xs:dateTime" minOccurs="0" maxOccurs="1"/>
|
||||
<xs:element name="LatestTaskRunStatus" type="xs:string" minOccurs="0" maxOccurs="1"/>
|
||||
<xs:element name="LatestTaskRunExitCode" type="xs:int" minOccurs="0" maxOccurs="1"/>
|
||||
<xs:element name="TimesRetried" type="xs:int" minOccurs="0" maxOccurs="1"/>
|
||||
<xs:element ref="TaskRunGuids" minOccurs="0" maxOccurs="1"/>
|
||||
</xs:all>
|
||||
<xs:attribute type="xs:string" name="Name" use="optional"/>
|
||||
<xs:attribute type="xs:string" name="Path" use="optional"/>
|
||||
<xs:attribute type="xs:string" name="Guid" use="optional"/>
|
||||
<xs:attribute type="xs:string" name="Arguments" use="optional"/>
|
||||
<xs:attribute type="xs:int" name="MaxNumberOfRetries" use="optional"/>
|
||||
<xs:attribute type="xs:int" name="Timeout" use="optional"/>
|
||||
<xs:attribute type="xs:boolean" name="AbortTaskListOnFailed" use="optional"/>
|
||||
<xs:attribute type="xs:boolean" name="AutoPassedIfLaunched" use="optional"/>
|
||||
<xs:attribute type="xs:boolean" name="TerminateOnCompleted" use="optional"/>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:complexType name="TasksType">
|
||||
<xs:sequence>
|
||||
<xs:element name="Task" type="TaskType" minOccurs="1" maxOccurs="unbounded"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
|
||||
<xs:element name="TaskList">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element name="Tasks" type="TasksType" minOccurs="0" maxOccurs="1"/>
|
||||
<xs:element name="BackgroundTasks" type="TasksType" minOccurs="0" maxOccurs="1"/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name="Name" type="xs:string" use="required"/>
|
||||
<xs:attribute name="Guid" type="xs:string" use="optional"/>
|
||||
<xs:attribute name="RunInParallel" type="xs:boolean" use="required"/>
|
||||
<xs:attribute name="AllowOtherTaskListsToRun" type="xs:boolean" use="required"/>
|
||||
<xs:attribute name="TerminateBackgroundTasksOnCompletion" type="xs:boolean" use="optional"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="TaskLists">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element ref="TaskList" minOccurs="1" maxOccurs="unbounded"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
<xs:element name="FactoryOrchestratorXML">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element ref="TaskLists" minOccurs="1" maxOccurs="1"/>
|
||||
</xs:sequence>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:schema>
|
||||
```
|
||||
|
||||
### TaskList attributes
|
||||
|
||||
A TaskList element defines a Factory Orchestrator TaskList. The following defines that attributes of the `TaskList` element in the Factory Orchestrator XML schema.
|
||||
|
||||
| Attribute Name | Type | Required? | Details |
|
||||
|---------------------------------------|---------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Name | String | Y | The "friendly name" of the TaskList. |
|
||||
| Guid | String | N | The GUID used to identify the TaskList. If not set, it will be assigned by the Factory Orchestrator Service automatically when the FactoryOrchestratorXML is loaded. |
|
||||
| RunInParallel | Bool | Y | If "true", the Tasks in this TaskList are executed in parallel. If "false", the Tasks in this TaskList are executed in order, one at a time. |
|
||||
| AllowOtherTaskListsToRun | Bool | Y | If "false", while this TaskList is running all other TaskLists are blocked from executing. If "true", other TaskLists may execute while this TaskList is running. |
|
||||
| TerminateBackgroundTasksOnCompletion | Bool | N | If "true", any BackgroundTasks defined in this TaskList are forcibly terminated when the TaskList's Tasks complete. If "false", any BackgroundTasks defined in this TaskList continue executing. Defaults to "true". |
|
||||
|
||||
#### Sample TaskList element
|
||||
|
||||
```xml
|
||||
<TaskList Guid="15332a4b-ee08-4c97-a7ad-d69d4210c3a6" Name="List2" RunInParallel="true" AllowOtherTaskListsToRun="true" TerminateBackgroundTasksOnCompletion="true">
|
||||
```
|
||||
|
||||
### Task attributes
|
||||
|
||||
A Task element defines a Factory Orchestrator Task. Tasks are pass/fail executables, apps, or jobs that are run as part of the TaskList that defines them. The following defines that attributes of the `Task` element in the Factory Orchestrator XML schema.
|
||||
|
||||
<!--Delete this table-->
|
||||
| Attribute Name | Type | Required? | Details |
|
||||
|------------------------|--------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| xsi:type | See details | Y | The type of the Task. Allowed values are: ExecutableTask, PowerShellTask, BatchFileTask, TAEFTest, UWPTask, and ExternalTask. |
|
||||
| Name | String | N | The "friendly name" of the Task. If not set, it will be assigned by the Factory Orchestrator Service automatically when the FactoryOrchestratorXML is loaded, based on the Task type and other attributes. |
|
||||
| Guid | String | N | The GUID used to identify the Task. If not set, it will be assigned by the Factory Orchestrator Service automatically when the FactoryOrchestratorXML is loaded. |
|
||||
| Path | String | Depends | See the [Path table below](#path-definitions) to see which Tasks require you to include a Path element. | |
|
||||
| Arguments | String | N | For Executable, PowerShell, BatchFile, and TAEF Tasks: this is the list of arguments to provide to the executable you specified in the "Path".<br><br> For UWP Tasks: this can be used to provide details about the Task to the client. It is NOT passed to the UWP app.<br><br>For External Tasks: this can be used to provide details about the Task to the client. |
|
||||
| Timeout | Int | N | In seconds, the amount of time to wait for the Task to be completed. Defaults to "-1" (infinite).<br><br> If "-1", the Task will never timeout.<br><br>If the timeout is reached, the Task status is set to "Timeout", a failed state. The Task's executable is also forcibly terminated (if it has one). |
|
||||
| MaxNumberOfRetries | Int | N | The number of times the Task should automatically be re-run if it completes in a failed state (Aborted/Failed/Timeout). Defaults to "0" (do not retry).<br><br>For example, if this is set to "2", the Task could be run up to 3 times automatically. |
|
||||
| AbortTaskListOnFailed | Bool | N | If "true", if the Task is run during a TaskList and the Task fails (Aborted/Failed/Timeout), the TaskList is aborted in its current state. Any other pending or running Tasks will be aborted.<br><br>This action takes place after any re-runs specified by MaxNumberOfRetries.<br><br>While allowed, it is not recommended to use this for "RunInParallel" TaskLists, as the execution order of such a TaskList is not guaranteed, and Tasks may be aborted mid-execution. |
|
||||
| TerminateOnCompleted | Bool | N | By default, an app is terminated when the UWPTask completes. Set to false to not terminate after a UWPTask completes. TerminateOnCompleted is ignored if AutoPassedIfLaunched=`true` |
|
||||
| AutoPassedIfLaunched | Bool | N | By default, a UWPTask waits for its TaskRun to be completed by a Factory Orchestrator Client. Setting this to true marks the UWP task completed when the app is launched. |
|
||||
|
||||
#### Path definitions
|
||||
|
||||
| Task type | Required | Path definition |
|
||||
| --- | --- | --- |
|
||||
| Executable | Yes | The path to the executable file that should be executed for this Task. |
|
||||
| PowerShell | Yes | The path to the PowerShell file that should be executed for this Task. |
|
||||
| BatchFile | Yes | The path to the Batch file that should be executed for this Task. |
|
||||
| TAEF | Yes | The path to the TAEF test that should be executed for this Task. |
|
||||
| UWP | Yes | the PackageFamilyName of the app you wish to launch. The PackageFamilyName is found in the package.appxmanifest for your app. It is also shown on the Factory Orchestrator app's "UWP Apps" page. |
|
||||
| External | No | This is optional, but can be used to provide details about the Task. |
|
||||
|
||||
#### Sample Task element
|
||||
|
||||
```xml
|
||||
<Task xsi:type="ExecutableTask" Name="Exe with abort tasklist on fail" Path="%DataDrive%\TestContent\testapp4.exe" Arguments="" Guid="6279616a-345d-4469-bba0-fd019c78b531" AbortTaskListOnFailed="true"/>
|
||||
```
|
||||
|
||||
#### Validate Factory Orchestrator XML
|
||||
|
||||
You can validate FactoryOrchestratorXML using the Factory Orchestrator app on a technician PC.
|
||||
|
||||
1. Install the Factory Orchestrator app on a technician PC and launch it.
|
||||
2. Click "Validate FactoryOrchestratorXML" in the bottom left of the app.
|
||||
3. Browse to the path of your FactoryOrchestratorXML file and click open.
|
||||
4. The FactoryOrchestratorXML file will be validated against the schema. Because this validation happens on the technician PC, it will only catch XML syntax errors not Factory Orchestrator Service errors such as duplicate GUIDs or invalid file paths.
|
||||
|
||||
- If the FactoryOrchestratorXML is valid you will see a success message saying that "FactoryOrchestratorXML was successfully validated."
|
||||
|
||||
- If the FactoryOrchestratorXML is invalid, you'll see a message that says "FactoryOrchestratorXML failed validation", with a description of why it failed validation.
|
||||
|
||||
### Background tasks
|
||||
|
||||
A Background Task is a type of Task which is not expected to return a pass/fail result. Instead, Background Tasks are started before any Tasks defined in the TaskList, and are not tracked by the Factory Orchestrator Service, though their output is logged to a file. Background Tasks are intended to be used for logging/monitoring tasks that need to be running before any Task in the TaskList executes.
|
||||
|
||||
Background Tasks are defined as children of the `<BackgroundTasks>` element. That element can have any number of child `<Task>` elements which are run as Background Tasks.
|
||||
|
||||
The `TerminateBackgroundTasksOnCompletion` attribute on the owning TaskList determines if the Background Tasks are forcibly terminated when the TaskList is done executing.
|
||||
|
||||
Background Tasks are defined the exactly the same as a normal Task with the following exceptions:
|
||||
|
||||
- Any Executable, PowerShell, or Batch File Task can be made a Background Task.
|
||||
- Background Tasks cannot have Timeout or MaxNumberOfRetries set
|
||||
|
||||
#### Sample BackgroundTasks element
|
||||
|
||||
```xml
|
||||
<BackgroundTasks>
|
||||
<Task xsi:type="ExecutableTask" Name="Background Monitor" Path="%DataDrive%\TestContent\SomeBackgroundProcess.exe" Arguments="" Guid="34d3827c-6397-411f-85a6-7e92dca5f364"/>
|
||||
</BackgroundTasks>
|
||||
```
|
||||
|
||||
## Sample Factory Orchestrator XML file
|
||||
|
||||
The following sample FactoryOrchestratorXML file shows two TaskLists containing various types of tests, as well as a BackgroundTask that is part of the first TaskList.
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<FactoryOrchestratorXML xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
|
||||
<TaskLists>
|
||||
<!-- RunInParallel = all tasks can be executed simultaneously. AllowOtherTaskListsToRun = other tasklists can run in parallel with this one. TerminateBackgroundTasksOnCompletion = Any still running background tasks are forcefully terminated when all tasks complete -->
|
||||
<TaskList Guid="15332a4b-ee08-4c97-a7ad-d69d4210c3a5" Name="List1" RunInParallel="false" AllowOtherTaskListsToRun="true" TerminateBackgroundTasksOnCompletion="true">
|
||||
<Tasks>
|
||||
<!-- When a UWPTask is launched from Factory Orchestrator, the Factory Orchestrator app will prompt the user for the result of the app after it terminates. -->
|
||||
<!-- UWPTasks require Factory Orchestrator app is running! -->
|
||||
<Task xsi:type="UWPTask" Name="Launch app directly via FO (exit with ALT+F4)" Path="Microsoft.FactoryOrchestratorApp_8wekyb3d8bbwe" Arguments="" Guid="6ec52ded-e455-44cb-b861-b8d78996db95"/>
|
||||
<Task xsi:type="TAEFTest" Name="TAEF test" Path="%DataDrive%\TestContent\taeftest1.dll" Arguments="" Guid="ff908b05-e491-4a6e-9305-793b3c2d7f97"/>
|
||||
<Task xsi:type="ExecutableTask" Name="Exe with 5 retries" Path="%DataDrive%\TestContent\testapp1.exe" Arguments="" Guid="d75f7c9c-8de9-4d0f-b6dc-d2a51d8818cb" MaxNumberOfRetries="5"/>
|
||||
<Task xsi:type="ExecutableTask" Name="Exe with 10 second timeout" Path="%DataDrive%\TestContent\testapp2.exe" Arguments="" Guid="7ffd4516-b092-4f22-beec-f12c814f50dc" Timeout="10"/>
|
||||
<Task xsi:type="ExecutableTask" Name="Exe with arguments" Path="%DataDrive%\TestContent\testapp3.exe" Arguments="-arg1 abc -arg2 def" Guid="186e4b74-280f-45ca-a73b-a0b342fa1cb8" />
|
||||
<Task xsi:type="ExecutableTask" Name="Exe with abort tasklist on fail" Path="%DataDrive%\TestContent\testapp4.exe" Arguments="" Guid="6279616a-345d-4469-bba0-fd019c78b531" AbortTaskListOnFailed="true"/>
|
||||
<Task xsi:type="BatchFileTask" Name="Cmd/Batch file with arguments" Path="%DataDrive%\TestContent\cmdfile.cmd" Arguments="-arg1 abc" Guid="cf334ad7-4480-4915-b84c-2a38c84b4e8c"/>
|
||||
<Task xsi:type="PowerShellTask" Name="RunAppViaDevicePortal.ps1 (PowerShell Core, exit app with ALT+F4)" Path="%DataDrive%\TestContent\RunAppViaDevicePortal.ps1" Arguments="-AppId Microsoft.FactoryOrchestratorApp_8wekyb3d8bbwe!App" Guid="1f596b55-7c9b-4e71-97b4-a0c93c098a86"/>
|
||||
<!-- When a ExternalTask is launched from Factory Orchestrator, the Factory Orchestrator app will prompt the user for the result of task -->
|
||||
<Task xsi:type="ExternalTask" Name="External Task (No executable code or app)" Path="User interaction required" Arguments="Plug in power cord" Guid="f90ba40d-4982-46dc-b9a2-c1cd7900fef7" AbortTaskListOnFailed="true"/>
|
||||
</Tasks>
|
||||
<!-- Background Tasks are started before any other task in the TaskList, they are intended for processes that you want running throughout the entire tasklist, ex: a monitor or logging program -->
|
||||
<!-- BackgroundTasks can be ExecutableTask, BatchFileTask, or PowerShellTask -->
|
||||
<BackgroundTasks>
|
||||
<Task xsi:type="ExecutableTask" Name="Background Monitor" Path="%DataDrive%\TestContent\SomeBackgroundProcess.exe" Arguments="" Guid="34d3827c-6397-411f-85a6-7e92dca5f364"/>
|
||||
</BackgroundTasks>
|
||||
</TaskList>
|
||||
<!-- FactoryOrchestratorXML can contain multiple tasklists, so you can define your entire factory flow in one file, if desired. -->
|
||||
<TaskList Guid="15332a4b-ee08-4c97-a7ad-d69d4210c3a6" Name="List2" RunInParallel="true" AllowOtherTaskListsToRun="true" TerminateBackgroundTasksOnCompletion="true">
|
||||
<Tasks>
|
||||
<Task xsi:type="ExecutableTask" Name="Exe in another tasklist" Path="%DataDrive%\TestContent\testapp5.exe" Arguments="" Guid="45945e43-d251-4c97-a9ad-63cd52b09801"/>
|
||||
</Tasks>
|
||||
</TaskList>
|
||||
</TaskLists>
|
||||
</FactoryOrchestratorXML>
|
||||
```
|
||||
|
|
@ -0,0 +1,65 @@
|
|||
|
||||
# Using the Factory Orchestrator client API
|
||||
|
||||
The Factory Orchestrator service, FactoryOrchestratorService.exe, provides a robust API surface for clients to interact with test devices via .NET code. You can use these APIs to author advanced task orchestration code to programmatically interact with the service outside of what the app provides.
|
||||
|
||||
All FactoryOrchestratorClient API calls other than `Connect()` are [asynchronous](https://docs.microsoft.com/dotnet/csharp/async).
|
||||
|
||||
The FactoryOrchestator service uses [semver](https://semver.org/) versioning. If the target device is running a different Factory Orchestrator build than one used to create the client program, you need to ensure that the program you build will run as expected by calling Client.GetServiceVersionString() and comparing against the client API version. If there is a major version mismatch your program may not work as expected and either the client program or test device should be updated so the major versions match. You can check the version of the client API by:
|
||||
|
||||
- Manually inspecting the properties of the FactoryOrchestratorClientLibrary.dll file used by your program
|
||||
|
||||
|
||||
|
||||
- Programmatically by the following code snippet:
|
||||
|
||||
```C#
|
||||
using System.Reflection;
|
||||
|
||||
...
|
||||
|
||||
var client = new FactoryOrchestratorClient(ipAddress);
|
||||
client.GetClientVersionString();
|
||||
```
|
||||
|
||||
If you are writing a UWP app that uses the Factory Orchestrator Client API, you should use the FactoryOrchestratorUWPClient class instead of FactoryOrchestratorClient. The FactoryOrchestratorUWPClient APIs are identical to the FactoryOrchestratorClient APIs. The UWP Client is available in FactoryOrchestratorUWPClientLibrary.dll.
|
||||
|
||||
## Using FactoryOrchestratorUWPClient.dll in a UWP
|
||||
|
||||
If you're using FactoryOrchestratorUWPClient.dll in a UWP, you have to configure Visual Studio so that it doesn't build with .NET Native.
|
||||
|
||||
1. Load your app project in visual studio.
|
||||
2. Right click the app project and select **Properties**:
|
||||
|
||||
|
||||
|
||||
|
||||
3. On the **Build** tab, select **All Configurations** and **All Platforms**:
|
||||
|
||||
|
||||
|
||||
4. Uncheck **Compile with .NET Native tool chain**
|
||||
|
||||
|
||||
|
||||
5. Rebuild and re-publish your app. The app dependencies will be different for your newly built app, so you'll need to install different framework packages with your app;
|
||||
|
||||
|
||||
|
||||
After building without the .NET native tool chain, your app should run successfully.
|
||||
|
||||
## Factory Orchestrator client sample
|
||||
|
||||
A sample .NET Core program that communicates with the Factory Orchestrator service is available in the Faactory Orchestrator GitHub repo at: `<Link to sample app>`. Copy the entire directory to your technician PC, then open ClientSample.csproj in Visual Studio 2019. (Visual Studio 2019 is required for working with NET Core 2.2 and newer.)
|
||||
|
||||
The sample shows you how to connect to a remote test device running Factory Orchestrator service, copy files to that device, execute test content, and retrieve the test results from the device both using an API and by retreiving the log files.
|
||||
|
||||
### Factory Orchestrator client sample usage
|
||||
|
||||
Once the sample is built, create a folder on your technican PC with test content and a FactoryOrchestratorXML file that references the test content in the location it will execute from on the test device. Then, run the sample by calling:
|
||||
|
||||
```cmd
|
||||
dotnet ClientSample.dll <IP Address of DUT> <Folder on technician PC with test content AND FactoryOrchestratorXML files> <Destination folder on DUT> <Destination folder on this PC to save logs>
|
||||
```
|
||||
|
||||
The sample will then connect to the test device, copy files to that device, execute test content, and retrieve the test results from the device both using an API and by retreiving the log files. You will be able to monitor the progress of the sample in the console window, on the DUT (if it is running the Factory Orchestrator app), and on the Factory Orchestrator app on the Technician PC (if it is connected to the test device).
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
|
||||
# Run tasks with Factory Orchestrator
|
||||
|
||||
Once you've created or imported a TaskList into Factory Orchestrator, you can run it. This topic covers the process of running a TaskList.
|
||||
|
||||
## Run a TaskList
|
||||
|
||||
When you click on the **Run TaskLists** menu item, you'll be see the "Run TaskLists" screen.
|
||||
|
||||
Hit the 'Play' button to run a TaskList. As tasks complete, the tasks' output will show next to the task.
|
||||
|
||||
|
||||
|
||||
While a TaskList is running, the Factory Orchestrator service will continue to run the tasks, even if you close the Factory Orchestrator app.
|
||||
|
||||
If you're running a task or a tasklist, the Factory Orchestrator UI allows you to easily monitor the status of any running task by displaying task status. You can disable this task status display by going to the **Run TaskLists** page and unchecking **Track Execution**.
|
||||
|
||||
|
||||
|
||||
As tasks complete, the Tasks' output will show next to the Task. While a TaskList is running, the Factory Orchestrator service will continue to run the tasks, even if you close the Factory Orchestrator app. A running TaskList can be "Aborted" by clicking the 'Pause' button.
|
||||
|
||||
|
||||
|
||||
If a TaskList is aborted you can either click the 'Play' button to resume executing it or the 'Re-run' button to restart the TaskList from the beginning.
|
||||
|
||||
A 'Re-run' button will also appear next to a Task if the TaskList is done executing and that Task failed. Press that button to retry the failed Task.
|
||||
|
||||
|
||||
|
||||
If you click on a Task, the results page will load and show you the status of the latest "run" (TaskRun) of that Task, including the any output of the Task. The results page also allows you to see the log file path for that run. You can also use the buttons at the top of the page to view older or newer runs of the Task, provided it has been run multiple times.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
site_name: Factory Orchestrator
|
||||
site_author: themar-msft;hajya
|
||||
repo_url: https://github.com/microsoft/FactoryOrchestrator
|
||||
site_description: "Factory Orchestrator Documentation"
|
||||
site_url: 'https://microsoft.github.io/FactoryOrchestrator/'
|
||||
plugins:
|
||||
- search
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: 'images/fo-logo.png'
|
||||
favicon: 'images/fo-logo.png'
|
||||
palette:
|
||||
primary: 'blue grey'
|
||||
accent: 'amber'
|
||||
|
||||
nav:
|
||||
- Overview: 'index.md'
|
||||
- Get Started: 'get-started-with-factory-orchestrator.md'
|
||||
- Tasks & TaskLists : 'tasks-and-tasklists.md'
|
||||
- Run using the application: 'use-the-factory-orchestrator-app.md'
|
||||
- Run using the client api: 'use-the-factory-orchestrator-api.md'
|
||||
- Built-In Utilities: 'factory-orchestrator-utilities.md'
|
||||
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
click==7.1.2
|
||||
future==0.18.2
|
||||
Jinja2==2.11.2
|
||||
joblib==0.17.0
|
||||
livereload==2.6.3
|
||||
lunr==0.5.8
|
||||
Markdown==3.3
|
||||
MarkupSafe==1.1.1
|
||||
mkdocs==1.1.2
|
||||
mkdocs-material==6.0.2
|
||||
mkdocs-material-extensions==1.0.1
|
||||
nltk==3.5
|
||||
Pygments==2.7.1
|
||||
pymdown-extensions==8.0.1
|
||||
PyYAML==5.3.1
|
||||
regex==2020.9.27
|
||||
six==1.15.0
|
||||
tornado==6.0.4
|
||||
tqdm==4.50.1
|
||||
Загрузка…
Ссылка в новой задаче