Skip to content

Commit 74892e0

Browse files
committed
Added multi-platform support information to readme.
1 parent 8c0a79d commit 74892e0

File tree

1 file changed

+88
-86
lines changed

1 file changed

+88
-86
lines changed

Diff for: README.md

+88-86
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,88 @@
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](https://img.shields.io/maven-central/v/com.github.tuupertunut/powershell-lib-java.svg?style=for-the-badge)](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](https://img.shields.io/maven-central/v/com.github.tuupertunut/powershell-lib-java.svg?style=for-the-badge)](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

Comments
 (0)