Merge pull request #18 from PowershellFrameworkCollective/scopes

docs updates for 1.13.406

Author: FriedrichWeinmann

documentation/documents/psframework/logging/loggingto/logfile.md

@@ -54,6 +54,25 @@ Set-PSFLoggingProvider @paramSetPSFLoggingProvider
 
 This will delete all logs older than 30 days.
 
+> Plaintext Logs
+
+Want a classic plaintext log?
+Well, generally we do not recommend using those (as they are hard to process automatically, compared to structured data logs), but sometimes you just need something for a quick peek in notepad and a plain text logfile is just easy to read for the human eye.
+
+Worry not, we have you covered:
+
+```powershell
+$paramSetPSFLoggingProvider = @{
+    Name         = 'logfile'
+    InstanceName = '<taskname>'
+    FilePath     = 'C:\Logs\TaskName-%Date%.txt'
+    FileType     = 'TXT'
+    Enabled      = $true
+    Wait         = $true
+}
+Set-PSFLoggingProvider @paramSetPSFLoggingProvider
+```
+
 ## Generating Messages
 
 You can write messages using the `Write-PSFMessage` cmdlet, which functionally replaces Write-Verbose, Write-Host, Write-Warning, Write-Debug or Write-Log:

documentation/documents/psframework/logging/providers/logfile.md

@@ -30,7 +30,7 @@ It also offers logrotate capabilities, to clean up after itself.
 |---|---|---|
 |CsvDelimiter|,|The delimiter to use when writing to csv.|
 |FilePath||The path to where the logfile is written. Supports some placeholders such as %Date% to allow for timestamp in the name.|
-|FileType|CSV|In what format to write the logfile. Supported styles: CSV, XML, Html, Json or CMTrace. Html, XML and Json will be written as fragments.|
+|FileType|CSV|In what format to write the logfile. Supported styles: CSV, XML, Html, Json, TXT or CMTrace. Html, XML and Json will be written as fragments.|
 |Headers|'ComputerName', 'File', 'FunctionName', 'Level', 'Line', 'Message', 'ModuleName', 'Runspace', 'Tags', 'TargetObject', 'Timestamp', 'Type', 'Username'|The properties to export, in the order to select them. For writing the data field or renaming properties, see below under "Notes".|
 |IncludeHeader|True|Whether a written csv file will include headers|
 |Logname||A special string you can use as a placeholder in the logfile path (by using '%logname%' as placeholder)|
@@ -45,6 +45,11 @@ It also offers logrotate capabilities, to clean up after itself.
 |JsonCompress|$false|Will compress the json entries, condensing each entry into a single line.|
 |JsonString|$false|Will convert all enumerated properties to string values when converting to json. This causes the level property to be 'Debug','Host', ... rather than 8,2,...|
 |JsonNoComma|$false|Prevent adding commas between two json entries.|
+|JsonNoEmptyFirstLine|$false|Prevent the empty first line when commas have not been disabled.|
+|CMTraceOverrideComponent|$false|When Enabled, messages that include a "Data" hashtable with a "Component" entry will use that Entry for the log message Component element, rather than the auto-calculated one.|
+|TXTPattern|'%Timestamp% [%Level%] %Message%'|The pattern of any given line in the TXT-based logfile. Use %PROPERTYNAME% as placeholder, e.g. "%Message%". Same properties as with the headers configuration - you need to specify both settings, if your pattern includes non-default properties such as "Data".|
+|MoveOnFinal|''|Path to a target folder to move logfiles to when shutting down the logging provider instance. This happens automatically when PSFramework ends or the provider instance is disabled again.|
+|CopyOnFinal|''|Path to a target folder to copy logfiles to when shutting down the logging provider instance. This happens automatically when PSFramework ends or the provider instance is disabled again.|
 
 ## Notes
 
@@ -57,6 +62,7 @@ The default format is CSV, but there is more ...
 |---|---|
 |CSV|The default format. A common CSV and the only type that respects the CsvDelimiter setting. Easy to open in Excel, making it a popular format for admins. However, as it is a flat table, this format cannot support the Data field.|
 |Json|Writes entries as Json string. However, as each individual write cannot guarantee it being the last to write an entry to the file, all entries are written as _fragments_ . To turn the resulting file content into valid json, wrap it into square brackets.|
+|TXT|Writes a plaintext logfile. Generally not recommended, as logs in structured data formats are easier to automatically process, parse and monitor. Use the `TXTPattern` setting to define just how the log looks, all properties selected must also be included in the `Headers` setting.|
 |XML|Writes entries as XML string. However, as each individual write cannot guarantee it being the last to write an entry to the file, all entries are written as _fragments_ . To turn the resulting file content into valid XML, wrap it into a `<Messages>` XML element.|
 |Html|Writes entries as Html string. However, as each individual write cannot guarantee it being the last to write an entry to the file, all entries are written as _fragments_ . To turn the resulting file content into valid html, wrap it into a `<table>` html element.|
 |CMTrace|Writes log entries in a format that can easily be consumed by the CMTrace log reading utility part of SCCM. This type ignores the selected headers to write and cannot support the Data field.|

documentation/documents/psframework/logging/providers/sql.md

@@ -42,6 +42,8 @@ Or manually deploy the required module.
 |Table|LoggingTable|Name of the table in that database to write to. Will be created if needed and able.|
 |SqlServer||The SQL Server to connect to.|
 |Credential||The credentials to use for connecting to the SQL server.|
+|Schema|dbo|SQL Server schema.|
+|Headers|'Message', 'Timestamp', 'Level', 'Tags', 'Data', 'ComputerName', 'Runspace', 'UserName', 'ModuleName', 'FunctionName', 'File', 'Line', 'CallStack', 'TargetObject', 'ErrorRecord'|Columns to write to the table|
 
 ## Notes
 

documentation/documents/psframework/parameter-classes/path-parameter.md

@@ -15,28 +15,28 @@ Example:
 
 ```powershell
 function Get-FileContent {
-	[CmdletBinding()]
-	param (
-		[string[]]
-		$Path
-	)
-
-	foreach ($entry in $Path) {
-		try { $resolvedPaths = Resolve-Path -Path $entry -ErrorAction Stop }
-		catch {
-			Write-Error $_
-			continue
-		}
-
-		foreach ($resolvedPath in $resolvedPaths) {
-			if (-not (Test-Path -Path $resolvedPath -PathType Leaf)) {
-				Write-Warning "Not a file: $resolvedPath"
-				continue
-			}
-
-			# Do Something
-		}
-	}
+    [CmdletBinding()]
+    param (
+        [string[]]
+        $Path
+    )
+
+    foreach ($entry in $Path) {
+        try { $resolvedPaths = Resolve-Path -Path $entry -ErrorAction Stop }
+        catch {
+            Write-Error $_
+            continue
+        }
+
+        foreach ($resolvedPath in $resolvedPaths) {
+            if (-not (Test-Path -Path $resolvedPath -PathType Leaf)) {
+                Write-Warning "Not a file: $resolvedPath"
+                continue
+            }
+
+            # Do Something
+        }
+    }
 }
 ```
 
@@ -45,34 +45,34 @@ with this parameter class, the same code however can be condensed to ...
 
 ```powershell
 function Get-FileContent {
-	[CmdletBinding()]
-	param (
-		[PsfFile]
-		$Path
-	)
-
-	foreach ($filePath in $Path) {
-		# Do Something
-	}
+    [CmdletBinding()]
+    param (
+        [PsfFile]
+        $Path
+    )
+
+    foreach ($filePath in $Path) {
+        # Do Something
+    }
 }
 ```
 
 Adding support for `-LiteralPath` is no harder:
 
 ```powershell
 function Get-FileContent {
-	[CmdletBinding()]
-	param (
-		[PsfFile]
-		$Path,
-
-		[PsfLiteralPath]
-		$LiteralPath
-	)
-
-	foreach ($filePath in $Path + $LiteralPath) {
-		# Do Something
-	}
+    [CmdletBinding()]
+    param (
+        [PsfFile]
+        $Path,
+
+        [PsfLiteralPath]
+        $LiteralPath
+    )
+
+    foreach ($filePath in $Path + $LiteralPath) {
+        # Do Something
+    }
 }
 ```
 
@@ -82,21 +82,21 @@ Sometimes we need to provide a path to a file that does not yet exist - for exam
 In that case, the folder should already exist, but the file usually would not.
 In the previous example however, we require the file to already exist!
 
-For this scenario, there exists the `[PsfNewFile]` parameter class, which allows for a file to not yet exist, so long as the parent folder does:
+For this scenario, there exists the `[PsfNewFileSingle]` parameter class, which allows for a file to not yet exist, so long as the parent folder does:
 
 ```powershell
 function Export-SystemReport {
-	[CmdletBinding()]
-	param (
-		[Parameter(Mandatory = $true)]
-		[PsfNewFile]
-		$OutPath
-	)
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory = $true)]
+        [PsfNewFileSingle]
+        $OutPath
+    )
 
-	# Do Something
-	# ...
+    # Do Something
+    # ...
 
-	$results | Export-PSFClixml -Path $OutPath
+    $results | Export-PSFClixml -Path $OutPath
 }
 ```
 
@@ -112,34 +112,41 @@ Instead, this variant will have a `FailedInput` property, listing all the input
 
 ```powershell
 function Get-FileContent {
-	[CmdletBinding()]
-	param (
-		[PsfFileLax]
-		$Path
-	)
-
-	foreach ($entry in $Path.FailedInput) {
-		Write-Warning "Could not resolve as file: $entry"
-	}
-
-	foreach ($filePath in $Path) {
-		# Do Something
-	}
+    [CmdletBinding()]
+    param (
+        [PsfFileLax]
+        $Path
+    )
+
+    foreach ($entry in $Path.FailedInput) {
+        Write-Warning "Could not resolve as file: $entry"
+    }
+
+    foreach ($filePath in $Path) {
+        # Do Something
+    }
 }
 ```
 
 ## The different types
 
-There are 9 different parameter classes that fall under this category:
+There are 16 different parameter classes that fall under this category:
 
 + PsfPath: Path to folders or files
 + PsfPathLax: Path to folders or files, will not generate errors on bad input
++ PsfPathSingle: Path to a single folder or file
 + PsfNewFile: Path to a file where at least the folder exists
++ PsfNewFileSingle: Path to a single file where at least the folder exists
 + PsfFile: Path to files that exist
 + PsfFileLax: Path to files that exist, will not generate errors on bad input
++ PsfFileSingle: Path to a single file that exists
 + PsfDirectory: Path to folders that exist
 + PsfDirectoryLax: Path to folders that exist, will not generate errors on bad input
++ PsfDirectorySingle: Path to a single folder that exists
 + PsfLiteralpath: Path to folders or files, will not use wildcard interpretation.
 + PsfLiteralpathLax: Path to folders or files, will not use wildcard interpretation. Will not generate errors on bad input
++ PsfLiteralpathSingle: Path to a single folder or file, will not use wildcard interpretation.
++ PsfLiteralFileSingle: Path to a single file, will not use wildcard interpretation.
++ PsfLiteralDirectorySingle: Path to a single folder, will not use wildcard interpretation.
 
 [Back to Parameter Classes](https://psframework.org/documentation/documents/psframework/parameter-classes.html)

documentation/quickstart/psframework.md

@@ -5,7 +5,11 @@ In many cases, we build helping infrastructure for our modules in as minimal a w
 The PSFramework fills that gap, whether it is powerful and flexible logging, configuration management, tab completion or runspace management.
 Its functionalities are split into many separate groups, these are quick start guides that are supposed to give you an easy entry into their respective group:
 
- - Configuration: [Getting Started with Configuration](psframework/configuration.html)
- - Logging: [Getting Started with Logging](psframework/logging.html)
- - Parameter Classes: [Getting Started with Parameter Classes](psframework/parameter-classes.html)
- - Tab Completion: [Getting Started with Tab Completion](psframework/tabcompletion.html)
+- Configuration: [Getting Started with Configuration](psframework/configuration.html)
+- Logging: [Getting Started with Logging](psframework/logging.html)
+- Parameter Classes: [Getting Started with Parameter Classes](psframework/parameter-classes.html)
+- Tab Completion: [Getting Started with Tab Completion](psframework/tabcompletion.html)
+
+> Conference Recording
+
+At PSConfEU 2024, Fred gave a talk on [Quick Wins with the PSFramework](https://www.youtube.com/watch?v=xD3Hh-jNOg4), which should also serve well in getting ... well quick wins / gains and accelerate adoption.