main

Author: sharpchen

docs/document/PowerShell/docs/Job/Background Job.md

@@ -0,0 +1,69 @@
+# Background Job
+
+A background job is a job running on another PowerShell process(sub-shell) created by the current PowerShell instance.
+
+- `Start-Job`: start a background job(process job)
+    - `-ScriptBlock`: specify custom action for the job
+    - `-FilePath`: run from a script file
+    - `-Name`: specify name for the job
+    - `-InitializationScript`: preparation for the action run in current PowerShell process
+    - `-WorkingDirectory`: specify cwd for the job
+    - `-ArgumentList`: arguments to be passed into the process
+    - `-PSVersion`: run in specific version
+
+- `&`: syntactic shorthand for `Start-Job`
+
+- `Receive-Job`: retrieve job state from a job object.
+    - `-Wait` synchronously wait for the job.
+
+## Start a Job
+
+`Start-Job` creates a new background job and returns a `System.Management.Automation.PSRemotingJob` to represent the state of the job.
+
+```ps1
+Start-Job -ScriptBlock { foo }
+```
+
+### Using `&` <Badge type="info" text="PowerShell 6+" />
+
+Using `&` to create a background job is only equivalent to `Start-Job -ScriptBlock { ... }`
+
+```ps1
+$job = gps pwsh &
+# equivalent to 
+$job = sajb { gps pwsh }
+```
+
+`&` can be recognized as a statement terminator, so you don't have to use an extra `;` for multiple expression inline.
+
+```ps1
+gps pwsh &; rcjb $job -Wait
+gps pwsh & rcjb $job -Wait # ; can be elided # [!code highlight] 
+```
+
+### Passing Arguments
+
+Closure is not allowed for `-ScriptBlock`.
+
+```ps1
+$foo = 'pwsh'
+$job = sajb { gps $foo }
+rcjb $job # receive error message # [!code error] 
+
+$job = sajb { gps $args } -ArgumentList pwsh,notepad # [!code highlight] 
+rcjb $job # ok # [!code highlight] 
+```
+
+### Run as Job from other Cmdlet
+
+There's some other cmdlet supports `-AsJob` switch to perform action as backgraound jobs, like `ForEach-Object` and `Invoke-Command`.
+
+```ps1
+# Run a job in the remote
+Invoke-Command -HostName <host> -UserName <usr> -ScriptBlock { foo } -AsJob
+```
+
+
+### Querying Jobs
+
+

docs/document/PowerShell/docs/Job/Job Manipulation.md

@@ -0,0 +1,84 @@
+# Job Manipulation
+
+- `Receive-Job`: retrieve output from existing job
+- `Get-Job`: query existing jobs
+- `Remove-Job`: remove job from background
+- `Stop-Job`: terminate the job
+- `Wait-Job`: block the thread until one or all jobs are in a terminated state
+
+Jobs has few identifier, such as name, id, instance id. All these cmdlet supports the corresponding parameters to specify the identity of jobs.
+They might not be pointed out explicitly for all sections
+
+## Parent & Child Jobs
+
+Each background job has at least one child job, the parent job does not return or execute anything, child jobs takes the real work.
+
+```ps1
+$job = sajb { foo }
+$job.ChildJobs
+```
+
+## Job Type
+
+- `BackgroundJob`
+- `ThreadJob`
+- `RemoteJob`
+
+## Querying Job
+
+`Get-Job` returns all parent background jobs by default.
+
+- `-IncludeChildJob`: list both parent jobs and child jobs, you might notice the job id is successive.
+- `-ChildJobState`: filter by child job state
+- `-Command`: get all jobs that executes a command satisfies the pattern in literal.
+    ```ps1
+    gkb -Command 'gps *'
+    ```
+- `-State`: get all jobs with specific state.
+    ```ps1
+    gjb -State Completed,Running
+    ```
+- `-Name`: get by job name
+- ...
+
+## Remove Job
+
+`Remove-Job` is not interesting and various, its parameters are pretty similar to `Get-Job` and it's commonly used together with `Get-Job` too.
+
+```ps1
+gjb | rjb # remove all job
+```
+
+## Terminate Job
+
+`Stop-Job`, has the same form as `Remove-Job`, to terminate a running job.
+
+## Retrieve Job Result
+
+`Receive-Job` returns all results from the child jobs of a job.
+The return type of job result is not certain. It depends on the action you specified.
+
+- `-Name`: retrieve result from given job name
+- `-Id`: retrieve result from given job id
+- `-Job`: retrieve result from given job object, positional
+- `-Keep`: preserve the job object after inspection
+    ```ps1
+    rcjb $job -Keep # some result
+    rcjb $job # some result, consumed here # [!code highlight] 
+    rcjb $job # no result # [!code highlight] 
+    $job -eq $null # False, the object is still available
+    ```
+- `-Wait`: synchronously block the thread to wait for the job to complete and finally get the result.
+    ```ps1
+    rcjb $job -Wait # session blocked
+    # result here
+    ```
+
+## Wait for Job
+
+`Wait-Job` can wait for jobs until they reach a terminated state like `Completed`, `Failed`, `Stopped`, `Suspended`, `Disconnected`
+
+- `-Any`: wait until any job terminated
+- `-Timeout`: wait until timeout were reached
+- `-Force`: wait for `Suspended` and `Disconnected`
+

docs/document/PowerShell/docs/Job/Thread Job.md

@@ -0,0 +1,32 @@
+# Thread Job
+
+Thread job is running on the same process of PowerShell instance, so it's faster than other job types.
+
+## Create Thread Job <Badge type="info" text="PowerShell 6+" />
+
+Thread job utils was added since PowerShell 6, if you want to use it in lower version, install the module with this command:
+
+```ps1
+inmo ThreadJob -Scope CurrentUser
+```
+
+The usage of `Start-ThreadJob` is similar to `Start-Job`. A `-ScriptBlock` or `-FilePath` should be specified as the action of the job.
+`Start-ThreadJob` returns a `ThreadJob` to represent the state of the job.
+
+```ps1
+$job = Start-ThreadJob { foo }
+$job.GetType().Name # ThreadJob
+```
+
+## Multiple Thread Jobs <Badge type="info" text="PowerShell 7+" />
+
+`ForEach-Object` supports creating parallel thread job from pipeline input since PowerShell 7.
+
+- `-Parallel`: perform each action on pipeline item in parallel, requires a scripblock.
+- `-AsJob`: return an object with child jobs.
+
+`-AsJob` returns a `PSTaskJob` object that contains all child jobs representing each action on pipeline item.
+
+```ps1
+1..10 | foreach -Parallel { echo $_ } -AsJob | rcjb -Wait
+```

docs/document/PowerShell/docs/Object Manipulation/4.ForEach.md

@@ -36,13 +36,13 @@ Evaluating from a method member is available, you can even pass parameters by `-
 (1..3 | % GetType | select -first 1) -is [System.Type] # True
 
 '1,2,3' | foreach -MemberName Split -ArgumentList ','
-# or
+# or this, ',' is passed as ValueFromRemainingArguments for -ArgumentList
 '1,2,3' | foreach Split ','
 ```
 
 ## Value Transformation
 
-The way `ForEach-Object` behaves is collecting implicitly returned values as an array. Every implicitly returned value will be collected as a item.
+The way `-Process` behaves is collecting implicitly returned values as an array. Every implicitly returned value will be collected as a item.
 
 > [!NOTE]
 > See: `help % -Parameter MemberName`

docs/document/PowerShell/docs/Object Manipulation/5.Select.md

@@ -92,6 +92,12 @@ gps | select -ExpandProperty Name
 > # or use another alias of ForEach-Object %
 > gps | % Name
 > ```
+>EDIT: Well actually you can do the same thing without `foreach` and `select`, use memeber accessor might solve the problem already except there's property name conflict.
+>```ps1
+>(gps).Name
+># equivalent to
+>gps | foreach Name
+>```
 
 ### Append Extra NoteProperty
 

docs/document/PowerShell/docs/What to Learn for New cmdlet.md

@@ -4,7 +4,7 @@
 
 Positional parameter matters for understanding the examples listed on documentations since the example might elide parameter name.
 We can take advantages of `Get-Help` and `Select-String` to capture those parameters that have a explicit order.
-The `-Context` includes 3 lines above and 5 lines below the display the whole info of the parameter.
+The `-Context` includes 3 lines above and 5 lines below the matched line to display the whole info of the parameter.
 
 ```ps1
 help <cmd> | sls 'Position\??\s*\d' -Context 3,5
@@ -37,10 +37,15 @@ $ help sls | sls 'Position\??\s*\d+' -Context 3,5
           Accept wildcard characters?  false
 ```
 
-## Find Parameters Accepts Pipeline
+## Find Parameters Accept Pipeline
 
 Similar to finding position parameter.
 
 ```ps1
 help <cmd> | sls 'Accept pipeline input\??\s*true.*$' -Context 5,4
 ```
+
+## Path Specific Parameter
+
+Commonly named parameters for path are `-Path`, `-FilePath`, `-LiteralPath`.
+So once the cmdlet supports one of them, you should aware it probably supports one or more of others.