Merge pull request #2 from AndiBellstedt/Development

Release WinEventLogCustomization Version 1.0.0.0
AndiBellstedt · Jul 24, 2022 · c6ad588 · c6ad588
2 parents 4422806 + edcdba4
commit c6ad588
Show file tree

Hide file tree

Showing 39 changed files with 2,850 additions and 3,305 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,122 @@
-# WinEventLogCustomization
+# ![logo][] WinEventLogCustomization
 
-# Description
 
-Description for the WinEventLogCustomization project.
+| Plattform | Information |
+| --------- | ----------- |
+| PowerShell gallery | [![PowerShell Gallery](https://img.shields.io/powershellgallery/v/WinEventLogCustomization?label=psgallery)](https://www.powershellgallery.com/packages/WinEventLogCustomization) [![PowerShell Gallery](https://img.shields.io/powershellgallery/p/WinEventLogCustomization)](https://www.powershellgallery.com/packages/WinEventLogCustomization) [![PowerShell Gallery](https://img.shields.io/powershellgallery/dt/WinEventLogCustomization?style=plastic)](https://www.powershellgallery.com/packages/WinEventLogCustomization) |
+| GitHub  | [![GitHub release](https://img.shields.io/github/release/AndiBellstedt/WinEventLogCustomization.svg)](https://github.com/AndiBellstedt/WinEventLogCustomization/releases/latest) ![GitHub](https://img.shields.io/github/license/AndiBellstedt/WinEventLogCustomization?style=plastic) <br> ![GitHub issues](https://img.shields.io/github/issues-raw/AndiBellstedt/WinEventLogCustomization?style=plastic) <br> ![GitHub last commit (branch)](https://img.shields.io/github/last-commit/AndiBellstedt/WinEventLogCustomization/main?label=last%20commit%3A%20master&style=plastic) <br> ![GitHub last commit (branch)](https://img.shields.io/github/last-commit/AndiBellstedt/WinEventLogCustomization/Development?label=last%20commit%3A%20development&style=plastic) |
+<br><br>
+
+## Description
+
+A PowerShell module helping you build custom eventlog channels and registering them into Windows Event Viewer.
+The build logs appear under "Application and Services", even like the "Windows PowerShell"  or the "PowerShellCore/Operational" EventLog.<br>
+<br>
+All cmdlets are build with
+- powershell regular verbs
+- pipeline availabilities wherever it makes sense
+- comprehensive logging on verbose and debug channel by the logging system of PSFramework<br>
+<br>
+
+## Prerequisites
+
+- Windows PowerShell 5.1
+- PowerShell 6 or 7
+- Administrative Priviledges are required for registering or unregistering EventChannels<br>
+<br>
+
+## Installation
+
+Install the module from the PowerShell Gallery (systemwide):
+```PowerShell
+Install-Module WinEventLogCustomization
+```
+<br>
+
+## Quick start
+### Creating a manifest for a EventChannel
+For a quick start you can just execute:
+```PowerShell
+New-WELCEventChannelManifest -ChannelFullName "AndiBellstedt/MyPersonalLog"
+```
+another way is the following command style, if you are not familiar with the notation on ChannelFullNames:
+```PowerShell
+New-WELCEventChannelManifest -RootFolderName "AndiBellstedt" -FolderSecondLevel "PowerShell" -FolderThirdLevel "Tasks" -ChannelName "Operational"
+```
+This will create a manifest- and a dll file (*AndiBellstedt.man & AndiBellstedt.dll*) within you current directory.<br>
+With the manifest file, the dll file can be registered to Windows EventLog system. <br>
+**Attention**, the manifest file contains the paths to the dll and should not be moved in the Windows Explorer.  *There is a command in the module to move the manifest with it's dll file consistently.* <br>
+<br>
+### Register the EventChannel
+Registering a manifest and its dll file is also easy:
+```PowerShell
+Register-WELCEventChannelManifest -Path .\AndiBellstedt.man
+```
+**Attention, executing this command will require admninistrative priviledges.** <br>
+Due to the fact, that changes on the Windows EventLog system are a administrative task. <br>
+<br>
+Following this, results in a new folder "AndiBellstedt" with two subfolders ("PowerShell" & "Tasks") and a EventLog "Operational" under "Application and Services Logs" withing the Event Viewer.<br>
+
+![EventChannel][]
+<br>
+<br>
+### Remove the EventChannel
+If the EventChannel is no longer needed, it can be removed by unregistering the manifest:
+```PowerShell
+UnRegister-WELCEventChannelManifest -Path .\AndiBellstedt.man
+```
+<br>
+
+### Show registered EventChannels
+After registering a manifest, the defined EventChannel can be queried<br>
+To query a EventChannel you can use:
+```PowerShell
+Get-WELCEventChannel -ChannelFullName "AndiBellstedt-PowerShell-Tasks/Operational"
+```
+This will output something like this, showing you the details and the config of the EventChannel:
+```
+PS C:\> Get-WELCEventChannel -ChannelFullName "AndiBellstedt-PowerShell-Tasks/Operational" | Format-List
+
+ComputerName      : MyComputer
+Name              : AndiBellstedt-PowerShell-Tasks/Operational
+Enabled           : False
+LogMode           : Circular
+LogType           : Administrative
+LogFullName       : C:\WINDOWS\System32\Winevt\Logs\AndiBellstedt-PowerShell-Tasks%4Operational.evtx
+MaxEventLogSize   : 1052672
+FileSize          :
+RecordCount       :
+IsFull            :
+LastWriteTime     :
+LastAccessTime    :
+ProviderName      : AndiBellstedt-PowerShell-Tasks
+ProviderId        : 43b94bbe-2d97-4f04-96b4-c254483b53f4
+MessageFilePath   : C:\EventLogs\AndiBellstedt.dll
+ResourceFilePath  : C:\EventLogs\AndiBellstedt.dll
+ParameterFilePath : C:\EventLogs\AndiBellstedt.dll
+Owner             : Administrators
+Access            : {NT AUTORITY\BATCH: AccessAllowed (ListDirectory, WriteData), NT AUTORITY\INTERACTIVE: AccessAllowed (ListDirectory, WriteData), NT AUTORITY\SERVICE: AccessAllowed (ListDirectory, WriteData), NT AUTORITY\SYSTEM: AccessAllowed (ChangePermissions, CreateDirectories, Delete, GenericExecute, ListDirectory, ReadPermissions, TakeOwnership, WriteData, WriteKey)…}
+```
+### Configuration on EventChannels
+There are multiple ways to configure a EventChannel.<br>
+The first, and explicit one is: <br>
+```PowerShell
+Set-WELCEventChannel -ChannelFullName "AndiBellstedt-PowerShell-Tasks/Operational" -Enabled $true -MaxEventLogSize 1GB -LogMode Circular -LogFilePath "C:\EventLogs\AB-PS-T-Ops.evtx"
+```
+
+Another way is to pipe in the result of a `Get-WELCEventChannel` command:
+```PowerShell
+$channel = Get-WELCEventChannel "AndiBellstedt*"
+
+$channel | Set-WELCEventChannel -Enabled $true -MaxEventLogSize 1GB -LogMode AutoBackup -LogFilePath "C:\EventLogs"
+```
+Doing it this way, `$channel` can contain more than one EventChannel to configure.<br>
+<br>
+
+## Practical usage - Managing, creating and configuring multiple custom EventChannel
+<< more to come >>
+<br>
+
+
+[logo]: assets/WinEventLogCustomization_128x128.png
+[EventChannel]: assets/pictures/EventChannel.png
diff --git a/WinEventLogCustomization/WinEventLogCustomization.psd1 b/WinEventLogCustomization/WinEventLogCustomization.psd1
@@ -1,55 +1,54 @@
 @{
     # Script module or binary module file associated with this manifest
-    RootModule = 'WinEventLogCustomization.psm1'
+    RootModule           = 'WinEventLogCustomization.psm1'
 
     # Version number of this module.
-    ModuleVersion = '0.9.0'
+    ModuleVersion        = '1.0.0'
 
     # ID used to uniquely identify this module
-    GUID = '9268705a-75d5-401c-b13d-4d1a8f380b17'
+    GUID                 = '9268705a-75d5-401c-b13d-4d1a8f380b17'
 
     # Author of this module
-    Author = 'Andreas Bellstedt'
+    Author               = 'Andreas Bellstedt'
 
     # Company or vendor of this module
-    CompanyName = ''
+    CompanyName          = ''
 
     # Copyright statement for this module
-    Copyright = 'Copyright (c) 2022 Andreas Bellstedt'
+    Copyright            = 'Copyright (c) 2022 Andreas Bellstedt'
 
     # Description of the functionality provided by this module
-    Description = 'Module for creating and managing custom Windows EventLog channels'
+    Description          = 'Module for creating and managing custom Windows EventLog channels'
 
     # Minimum version of the Windows PowerShell engine required by this module
-    PowerShellVersion = '5.1'
+    PowerShellVersion    = '5.1'
 
     # Supported PSEditions
     CompatiblePSEditions = 'Desktop'
 
     # Modules that must be imported into the global environment prior to importing
     # this module
-    RequiredModules = @(
+    RequiredModules      = @(
         @{
-            ModuleName='PSFramework';
-            ModuleVersion='1.7.227'
+            ModuleName    = 'PSFramework';
+            ModuleVersion = '1.7.227'
         }
     )
 
     # Assemblies that must be loaded prior to importing this module
-    # RequiredAssemblies = @('bin\WinEventLogCustomization.dll')
-    RequiredAssemblies = @(
+    RequiredAssemblies   = @(
         'bin\EPPlus.Net40.dll'
         'bin\WinEventLogCustomization.dll'
     )
 
     # Type files (.ps1xml) to be loaded when importing this module
-    TypesToProcess = @('xml\WinEventLogCustomization.Types.ps1xml')
+    TypesToProcess       = @('xml\WinEventLogCustomization.Types.ps1xml')
 
     # Format files (.ps1xml) to be loaded when importing this module
-    FormatsToProcess = @('xml\WinEventLogCustomization.Format.ps1xml')
+    FormatsToProcess     = @('xml\WinEventLogCustomization.Format.ps1xml')
 
     # Functions to export from this module
-    FunctionsToExport = @(
+    FunctionsToExport    = @(
         'Import-WELCChannelDefinition',
         'New-WELCEventChannelManifest',
         'Register-WELCEventChannelManifest',
@@ -62,40 +61,58 @@
     )
 
     # Cmdlets to export from this module
-    CmdletsToExport = ''
+    CmdletsToExport      = ''
 
     # Variables to export from this module
-    VariablesToExport = ''
+    VariablesToExport    = ''
 
     # Aliases to export from this module
-    AliasesToExport = ''
+    AliasesToExport      = ''
 
     # List of all modules packaged with this module
-    ModuleList = @()
+    ModuleList           = @()
 
     # List of all files packaged with this module
-    FileList = @()
+    FileList             = @()
 
     # Private data to pass to the module specified in ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
-    PrivateData = @{
-
+    PrivateData          = @{
         #Support for PowerShellGet galleries.
         PSData = @{
-
             # Tags applied to this module. These help with module discovery in online galleries.
-            # Tags = @()
+            Tags         = @(
+                'EventLog',
+                'WindowsEvent',
+                'WindowsEventLog',
+                'EventLogChannel',
+                'EventLogChannels',
+                'EventChannel',
+                'EventChannels',
+                'CustomEventChannel',
+                'CustomEventLog',
+                'CustomEventLogChannel',
+                'CustomEventLogFile',
+                'CustomEventLogFiles',
+                'EventLogManifest',
+                'LogFile',
+                'LogFiles',
+                'Automation',
+                'Logging',
+                'PSEdition_Desktop',
+                'Windows'
+            )
 
             # A URL to the license for this module.
-            # LicenseUri = ''
+            LicenseUri   = 'https://github.com/AndiBellstedt/WinEventLogCustomization/blob/main/license'
 
             # A URL to the main website for this project.
-            # ProjectUri = ''
+            ProjectUri   = 'https://github.com/AndiBellstedt/WinEventLogCustomization'
 
             # A URL to an icon representing this module.
-            # IconUri = ''
+            IconUri      = 'https://github.com/AndiBellstedt/WinEventLogCustomization/raw/main/assets/WinEventLogCustomization_128x128.png'
 
             # ReleaseNotes of this module
-            # ReleaseNotes = ''
+            ReleaseNotes = 'https://github.com/AndiBellstedt/WinEventLogCustomization/blob/main/WinEventLogCustomization/changelog.md'
 
         } # End of PSData hashtable
 

diff --git a/WinEventLogCustomization/WinEventLogCustomization.psm1 b/WinEventLogCustomization/WinEventLogCustomization.psm1
@@ -18,65 +18,63 @@ $importIndividualFiles = Get-PSFConfigValue -FullName WinEventLogCustomization.I
 if ($WinEventLogCustomization_importIndividualFiles) { $importIndividualFiles = $true }
 if (Test-Path (Resolve-PSFPath -Path "$($script:ModuleRoot)\..\.git" -SingleItem -NewChild)) { $importIndividualFiles = $true }
 if ("<was not compiled>" -eq '<was not compiled>') { $importIndividualFiles = $true }
-
-function Import-ModuleFile
-{
-	<#
-		.SYNOPSIS
-			Loads files into the module on module import.
-		
-		.DESCRIPTION
-			This helper function is used during module initialization.
-			It should always be dotsourced itself, in order to proper function.
-			
-			This provides a central location to react to files being imported, if later desired
-		
-		.PARAMETER Path
-			The path to the file to load
-		
-		.EXAMPLE
-			PS C:\> . Import-ModuleFile -File $function.FullName
-	
-			Imports the file stored in $function according to import policy
-	#>
-	[CmdletBinding()]
-	Param (
-		[string]
-		$Path
-	)
-
-	$resolvedPath = $ExecutionContext.SessionState.Path.GetResolvedPSPathFromPSPath($Path).ProviderPath
-	if ($doDotSource) { . $resolvedPath }
-	else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText($resolvedPath))), $null, $null) }
+
+function Import-ModuleFile {
+    <#
+        .SYNOPSIS
+            Loads files into the module on module import.
+
+        .DESCRIPTION
+            This helper function is used during module initialization.
+            It should always be dotsourced itself, in order to proper function.
+
+            This provides a central location to react to files being imported, if later desired
+
+        .PARAMETER Path
+            The path to the file to load
+
+        .EXAMPLE
+            PS C:\> . Import-ModuleFile -File $function.FullName
+
+            Imports the file stored in $function according to import policy
+    #>
+    [CmdletBinding()]
+    Param (
+        [string]
+        $Path
+    )
+
+    $resolvedPath = $ExecutionContext.SessionState.Path.GetResolvedPSPathFromPSPath($Path).ProviderPath
+    if ($doDotSource) { . $resolvedPath }
+    else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText($resolvedPath))), $null, $null) }
 }
 
 #region Load individual files
-if ($importIndividualFiles)
-{
-	# Execute Preimport actions
-	foreach ($path in (& "$ModuleRoot\internal\scripts\preimport.ps1")) {
-		. Import-ModuleFile -Path $path
-	}
-
-	# Import all internal functions
-	foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
-	{
-		. Import-ModuleFile -Path $function.FullName
-	}
-
-	# Import all public functions
-	foreach ($function in (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
-	{
-		. Import-ModuleFile -Path $function.FullName
-	}
-
-	# Execute Postimport actions
-	foreach ($path in (& "$ModuleRoot\internal\scripts\postimport.ps1")) {
-		. Import-ModuleFile -Path $path
-	}
-
-	# End it here, do not load compiled code below
-	return
+if ($importIndividualFiles) {
+    # Execute Preimport actions
+    foreach ($path in (& "$ModuleRoot\internal\scripts\preimport.ps1")) {
+        . Import-ModuleFile -Path $path
+    }
+
+    # Import all internal functions
+    foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)) {
+        . Import-ModuleFile -Path $function.FullName
+    }
+
+    # Import all public functions
+    $functions = (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)
+    $function = $functions[6]
+    foreach ($function in $functions) {
+        . Import-ModuleFile -Path $function.FullName
+    }
+
+    # Execute Postimport actions
+    foreach ($path in (& "$ModuleRoot\internal\scripts\postimport.ps1")) {
+        . Import-ModuleFile -Path $path
+    }
+
+    # End it here, do not load compiled code below
+    return
 }
 #endregion Load individual files
 

diff --git a/WinEventLogCustomization/bin/WinEventLogCustomization.xltx b/WinEventLogCustomization/bin/WinEventLogCustomization.xltx