|
1 |
| -# PowerShellLibJava |
2 |
| - |
3 |
| -A simple library for using PowerShell from Java. |
4 |
| - |
5 |
| -## Usage |
6 |
| - |
7 |
| -`PowerShell.open()` opens a new PowerShell session. You can execute a PowerShell command with `psSession.executeCommands(command)`. It will return the output of the command as a string: |
8 |
| -```java |
9 |
| -try (PowerShell psSession = PowerShell.open()) { |
10 |
| - System.out.println(psSession.executeCommands("Write-Output 'hello Java'")); |
11 |
| -} catch (IOException | PowerShellExecutionException ex) { |
12 |
| - ex.printStackTrace(); |
13 |
| -} |
14 |
| -``` |
15 |
| -``` |
16 |
| -hello Java |
17 |
| -``` |
18 |
| - |
19 |
| ---- |
20 |
| - |
21 |
| -You can also execute multiple lines of commands at once: |
22 |
| -```java |
23 |
| -try (PowerShell psSession = PowerShell.open()) { |
24 |
| - System.out.println(psSession.executeCommands( |
25 |
| - "for ($i = 1; $i -le 5; $i++) {", |
26 |
| - " Write-Output $i", |
27 |
| - "}")); |
28 |
| -} catch (IOException | PowerShellExecutionException ex) { |
29 |
| - ex.printStackTrace(); |
30 |
| -} |
31 |
| -``` |
32 |
| -``` |
33 |
| -1 |
34 |
| -2 |
35 |
| -3 |
36 |
| -4 |
37 |
| -5 |
38 |
| -``` |
39 |
| - |
40 |
| ---- |
41 |
| - |
42 |
| -If your PowerShell code has parameters that are dynamically read from Java strings, they might contain characters that have special meaning in PowerShell (kind of like SQL injection). You can sanitize your input with `PowerShell.escapePowerShellString(parameter)`: |
43 |
| -```java |
44 |
| -String param = "thi's won't bre;ak' the' code"; |
45 |
| - |
46 |
| -try (PowerShell psSession = PowerShell.open()) { |
47 |
| - System.out.println(psSession.executeCommands("Write-Output " + PowerShell.escapePowerShellString(param))); |
48 |
| -} catch (IOException | PowerShellExecutionException ex) { |
49 |
| - ex.printStackTrace(); |
50 |
| -} |
51 |
| -``` |
52 |
| -``` |
53 |
| -thi's won't bre;ak' the' code |
54 |
| -``` |
55 |
| - |
56 |
| ---- |
57 |
| - |
58 |
| -If there is an error on executing the command, a `PowerShellExecutionException` is thrown: |
59 |
| -```java |
60 |
| -try (PowerShell psSession = PowerShell.open()) { |
61 |
| - System.out.println(psSession.executeCommands("this is not a valid command")); |
62 |
| -} catch (IOException | PowerShellExecutionException ex) { |
63 |
| - ex.printStackTrace(); |
64 |
| -} |
65 |
| -``` |
66 |
| -``` |
67 |
| -tuupertunut.powershelllibjava.PowerShellExecutionException: Error while executing PowerShell commands: |
68 |
| -this : The term 'this' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. |
69 |
| -... |
70 |
| -``` |
71 |
| - |
72 |
| -## Requirements |
73 |
| - |
74 |
| -You must have PowerShell installed on your machine. |
75 |
| - |
76 |
| -**OS:** Windows is the only currently supported OS. This library has not been tested on Linux, but it might work. |
77 |
| - |
78 |
| -**Java:** Java 8 or higher is required. |
79 |
| - |
80 |
| -## Maven Central |
81 |
| - |
82 |
| -[](https://mvnrepository.com/artifact/com.github.tuupertunut/powershell-lib-java) |
83 |
| - |
84 |
| -**groupId:** com.github.tuupertunut |
85 |
| - |
86 |
| -**artifactId:** powershell-lib-java |
| 1 | +# PowerShellLibJava |
| 2 | + |
| 3 | +A simple library for using PowerShell from Java. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +`PowerShell.open()` opens a new PowerShell session with default executable. On Windows it is `powershell`, and on other platforms it is `pwsh` from PowerShell Core. You can also specify a custom PowerShell executable, for example `PowerShell.open("/usr/bin/pwsh-preview")`. |
| 8 | + |
| 9 | +You can execute a PowerShell command with `psSession.executeCommands(command)`. It will return the output of the command as a string: |
| 10 | +```java |
| 11 | +try (PowerShell psSession = PowerShell.open()) { |
| 12 | + System.out.println(psSession.executeCommands("Write-Output 'hello Java'")); |
| 13 | +} catch (IOException | PowerShellExecutionException ex) { |
| 14 | + ex.printStackTrace(); |
| 15 | +} |
| 16 | +``` |
| 17 | +``` |
| 18 | +hello Java |
| 19 | +``` |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +You can also execute multiple lines of commands at once: |
| 24 | +```java |
| 25 | +try (PowerShell psSession = PowerShell.open()) { |
| 26 | + System.out.println(psSession.executeCommands( |
| 27 | + "for ($i = 1; $i -le 5; $i++) {", |
| 28 | + " Write-Output $i", |
| 29 | + "}")); |
| 30 | +} catch (IOException | PowerShellExecutionException ex) { |
| 31 | + ex.printStackTrace(); |
| 32 | +} |
| 33 | +``` |
| 34 | +``` |
| 35 | +1 |
| 36 | +2 |
| 37 | +3 |
| 38 | +4 |
| 39 | +5 |
| 40 | +``` |
| 41 | + |
| 42 | +--- |
| 43 | + |
| 44 | +If your PowerShell code has parameters that are dynamically read from Java strings, they might contain characters that have special meaning in PowerShell (kind of like SQL injection). You can sanitize your input with `PowerShell.escapePowerShellString(parameter)`: |
| 45 | +```java |
| 46 | +String param = "thi's won't bre;ak' the' code"; |
| 47 | + |
| 48 | +try (PowerShell psSession = PowerShell.open()) { |
| 49 | + System.out.println(psSession.executeCommands("Write-Output " + PowerShell.escapePowerShellString(param))); |
| 50 | +} catch (IOException | PowerShellExecutionException ex) { |
| 51 | + ex.printStackTrace(); |
| 52 | +} |
| 53 | +``` |
| 54 | +``` |
| 55 | +thi's won't bre;ak' the' code |
| 56 | +``` |
| 57 | + |
| 58 | +--- |
| 59 | + |
| 60 | +If there is an error on executing the command, a `PowerShellExecutionException` is thrown: |
| 61 | +```java |
| 62 | +try (PowerShell psSession = PowerShell.open()) { |
| 63 | + System.out.println(psSession.executeCommands("this is not a valid command")); |
| 64 | +} catch (IOException | PowerShellExecutionException ex) { |
| 65 | + ex.printStackTrace(); |
| 66 | +} |
| 67 | +``` |
| 68 | +``` |
| 69 | +tuupertunut.powershelllibjava.PowerShellExecutionException: Error while executing PowerShell commands: |
| 70 | +this : The term 'this' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. |
| 71 | +... |
| 72 | +``` |
| 73 | + |
| 74 | +## Requirements |
| 75 | + |
| 76 | +**OS:** Works on every platform that has PowerShell available. |
| 77 | + |
| 78 | +**PowerShell:** On Windows 7 and newer, Windows PowerShell is installed by default and this library should work with it out of the box. On other platforms, you need to have PowerShell Core (https://github.com/PowerShell/PowerShell) installed. |
| 79 | + |
| 80 | +**Java:** Java 8 or higher is required. |
| 81 | + |
| 82 | +## Maven Central |
| 83 | + |
| 84 | +[](https://mvnrepository.com/artifact/com.github.tuupertunut/powershell-lib-java) |
| 85 | + |
| 86 | +**groupId:** com.github.tuupertunut |
| 87 | + |
| 88 | +**artifactId:** powershell-lib-java |
0 commit comments