Skip to content

Commit c6ad588

Browse files
AndiBellstedtAndiBellstedt
authored
Merge pull request #2 from AndiBellstedt/Development
Release WinEventLogCustomization Version 1.0.0.0
2 parents 4422806 + edcdba4 commit c6ad588

39 files changed

+2850
-3305
lines changed

‎README.md

+120-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,122 @@
1-
# WinEventLogCustomization
1+
# ![logo][] WinEventLogCustomization
22

3-
# Description
43

5-
Description for the WinEventLogCustomization project.
4+
| Plattform | Information |
5+
| --------- | ----------- |
6+
| 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) |
7+
| 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) |
8+
<br><br>
9+
10+
## Description
11+
12+
A PowerShell module helping you build custom eventlog channels and registering them into Windows Event Viewer.
13+
The build logs appear under "Application and Services", even like the "Windows PowerShell" or the "PowerShellCore/Operational" EventLog.<br>
14+
<br>
15+
All cmdlets are build with
16+
- powershell regular verbs
17+
- pipeline availabilities wherever it makes sense
18+
- comprehensive logging on verbose and debug channel by the logging system of PSFramework<br>
19+
<br>
20+
21+
## Prerequisites
22+
23+
- Windows PowerShell 5.1
24+
- PowerShell 6 or 7
25+
- Administrative Priviledges are required for registering or unregistering EventChannels<br>
26+
<br>
27+
28+
## Installation
29+
30+
Install the module from the PowerShell Gallery (systemwide):
31+
```PowerShell
32+
Install-Module WinEventLogCustomization
33+
```
34+
<br>
35+
36+
## Quick start
37+
### Creating a manifest for a EventChannel
38+
For a quick start you can just execute:
39+
```PowerShell
40+
New-WELCEventChannelManifest -ChannelFullName "AndiBellstedt/MyPersonalLog"
41+
```
42+
another way is the following command style, if you are not familiar with the notation on ChannelFullNames:
43+
```PowerShell
44+
New-WELCEventChannelManifest -RootFolderName "AndiBellstedt" -FolderSecondLevel "PowerShell" -FolderThirdLevel "Tasks" -ChannelName "Operational"
45+
```
46+
This will create a manifest- and a dll file (*AndiBellstedt.man & AndiBellstedt.dll*) within you current directory.<br>
47+
With the manifest file, the dll file can be registered to Windows EventLog system. <br>
48+
**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>
49+
<br>
50+
### Register the EventChannel
51+
Registering a manifest and its dll file is also easy:
52+
```PowerShell
53+
Register-WELCEventChannelManifest -Path .\AndiBellstedt.man
54+
```
55+
**Attention, executing this command will require admninistrative priviledges.** <br>
56+
Due to the fact, that changes on the Windows EventLog system are a administrative task. <br>
57+
<br>
58+
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>
59+
60+
![EventChannel][]
61+
<br>
62+
<br>
63+
### Remove the EventChannel
64+
If the EventChannel is no longer needed, it can be removed by unregistering the manifest:
65+
```PowerShell
66+
UnRegister-WELCEventChannelManifest -Path .\AndiBellstedt.man
67+
```
68+
<br>
69+
70+
### Show registered EventChannels
71+
After registering a manifest, the defined EventChannel can be queried<br>
72+
To query a EventChannel you can use:
73+
```PowerShell
74+
Get-WELCEventChannel -ChannelFullName "AndiBellstedt-PowerShell-Tasks/Operational"
75+
```
76+
This will output something like this, showing you the details and the config of the EventChannel:
77+
```
78+
PS C:\> Get-WELCEventChannel -ChannelFullName "AndiBellstedt-PowerShell-Tasks/Operational" | Format-List
79+
80+
ComputerName : MyComputer
81+
Name : AndiBellstedt-PowerShell-Tasks/Operational
82+
Enabled : False
83+
LogMode : Circular
84+
LogType : Administrative
85+
LogFullName : C:\WINDOWS\System32\Winevt\Logs\AndiBellstedt-PowerShell-Tasks%4Operational.evtx
86+
MaxEventLogSize : 1052672
87+
FileSize :
88+
RecordCount :
89+
IsFull :
90+
LastWriteTime :
91+
LastAccessTime :
92+
ProviderName : AndiBellstedt-PowerShell-Tasks
93+
ProviderId : 43b94bbe-2d97-4f04-96b4-c254483b53f4
94+
MessageFilePath : C:\EventLogs\AndiBellstedt.dll
95+
ResourceFilePath : C:\EventLogs\AndiBellstedt.dll
96+
ParameterFilePath : C:\EventLogs\AndiBellstedt.dll
97+
Owner : Administrators
98+
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)…}
99+
```
100+
### Configuration on EventChannels
101+
There are multiple ways to configure a EventChannel.<br>
102+
The first, and explicit one is: <br>
103+
```PowerShell
104+
Set-WELCEventChannel -ChannelFullName "AndiBellstedt-PowerShell-Tasks/Operational" -Enabled $true -MaxEventLogSize 1GB -LogMode Circular -LogFilePath "C:\EventLogs\AB-PS-T-Ops.evtx"
105+
```
106+
107+
Another way is to pipe in the result of a `Get-WELCEventChannel` command:
108+
```PowerShell
109+
$channel = Get-WELCEventChannel "AndiBellstedt*"
110+
111+
$channel | Set-WELCEventChannel -Enabled $true -MaxEventLogSize 1GB -LogMode AutoBackup -LogFilePath "C:\EventLogs"
112+
```
113+
Doing it this way, `$channel` can contain more than one EventChannel to configure.<br>
114+
<br>
115+
116+
## Practical usage - Managing, creating and configuring multiple custom EventChannel
117+
<< more to come >>
118+
<br>
119+
120+
121+
[logo]: assets/WinEventLogCustomization_128x128.png
122+
[EventChannel]: assets/pictures/EventChannel.png

‎WinEventLogCustomization/WinEventLogCustomization.psd1

+46-29
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,54 @@
11
@{
22
# Script module or binary module file associated with this manifest
3-
RootModule = 'WinEventLogCustomization.psm1'
3+
RootModule = 'WinEventLogCustomization.psm1'
44

55
# Version number of this module.
6-
ModuleVersion = '0.9.0'
6+
ModuleVersion = '1.0.0'
77

88
# ID used to uniquely identify this module
9-
GUID = '9268705a-75d5-401c-b13d-4d1a8f380b17'
9+
GUID = '9268705a-75d5-401c-b13d-4d1a8f380b17'
1010

1111
# Author of this module
12-
Author = 'Andreas Bellstedt'
12+
Author = 'Andreas Bellstedt'
1313

1414
# Company or vendor of this module
15-
CompanyName = ''
15+
CompanyName = ''
1616

1717
# Copyright statement for this module
18-
Copyright = 'Copyright (c) 2022 Andreas Bellstedt'
18+
Copyright = 'Copyright (c) 2022 Andreas Bellstedt'
1919

2020
# Description of the functionality provided by this module
21-
Description = 'Module for creating and managing custom Windows EventLog channels'
21+
Description = 'Module for creating and managing custom Windows EventLog channels'
2222

2323
# Minimum version of the Windows PowerShell engine required by this module
24-
PowerShellVersion = '5.1'
24+
PowerShellVersion = '5.1'
2525

2626
# Supported PSEditions
2727
CompatiblePSEditions = 'Desktop'
2828

2929
# Modules that must be imported into the global environment prior to importing
3030
# this module
31-
RequiredModules = @(
31+
RequiredModules = @(
3232
@{
33-
ModuleName='PSFramework';
34-
ModuleVersion='1.7.227'
33+
ModuleName = 'PSFramework';
34+
ModuleVersion = '1.7.227'
3535
}
3636
)
3737

3838
# Assemblies that must be loaded prior to importing this module
39-
# RequiredAssemblies = @('bin\WinEventLogCustomization.dll')
40-
RequiredAssemblies = @(
39+
RequiredAssemblies = @(
4140
'bin\EPPlus.Net40.dll'
4241
'bin\WinEventLogCustomization.dll'
4342
)
4443

4544
# Type files (.ps1xml) to be loaded when importing this module
46-
TypesToProcess = @('xml\WinEventLogCustomization.Types.ps1xml')
45+
TypesToProcess = @('xml\WinEventLogCustomization.Types.ps1xml')
4746

4847
# Format files (.ps1xml) to be loaded when importing this module
49-
FormatsToProcess = @('xml\WinEventLogCustomization.Format.ps1xml')
48+
FormatsToProcess = @('xml\WinEventLogCustomization.Format.ps1xml')
5049

5150
# Functions to export from this module
52-
FunctionsToExport = @(
51+
FunctionsToExport = @(
5352
'Import-WELCChannelDefinition',
5453
'New-WELCEventChannelManifest',
5554
'Register-WELCEventChannelManifest',
@@ -62,40 +61,58 @@
6261
)
6362

6463
# Cmdlets to export from this module
65-
CmdletsToExport = ''
64+
CmdletsToExport = ''
6665

6766
# Variables to export from this module
68-
VariablesToExport = ''
67+
VariablesToExport = ''
6968

7069
# Aliases to export from this module
71-
AliasesToExport = ''
70+
AliasesToExport = ''
7271

7372
# List of all modules packaged with this module
74-
ModuleList = @()
73+
ModuleList = @()
7574

7675
# List of all files packaged with this module
77-
FileList = @()
76+
FileList = @()
7877

7978
# Private data to pass to the module specified in ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
80-
PrivateData = @{
81-
79+
PrivateData = @{
8280
#Support for PowerShellGet galleries.
8381
PSData = @{
84-
8582
# Tags applied to this module. These help with module discovery in online galleries.
86-
# Tags = @()
83+
Tags = @(
84+
'EventLog',
85+
'WindowsEvent',
86+
'WindowsEventLog',
87+
'EventLogChannel',
88+
'EventLogChannels',
89+
'EventChannel',
90+
'EventChannels',
91+
'CustomEventChannel',
92+
'CustomEventLog',
93+
'CustomEventLogChannel',
94+
'CustomEventLogFile',
95+
'CustomEventLogFiles',
96+
'EventLogManifest',
97+
'LogFile',
98+
'LogFiles',
99+
'Automation',
100+
'Logging',
101+
'PSEdition_Desktop',
102+
'Windows'
103+
)
87104

88105
# A URL to the license for this module.
89-
# LicenseUri = ''
106+
LicenseUri = 'https://github.com/AndiBellstedt/WinEventLogCustomization/blob/main/license'
90107

91108
# A URL to the main website for this project.
92-
# ProjectUri = ''
109+
ProjectUri = 'https://github.com/AndiBellstedt/WinEventLogCustomization'
93110

94111
# A URL to an icon representing this module.
95-
# IconUri = ''
112+
IconUri = 'https://github.com/AndiBellstedt/WinEventLogCustomization/raw/main/assets/WinEventLogCustomization_128x128.png'
96113

97114
# ReleaseNotes of this module
98-
# ReleaseNotes = ''
115+
ReleaseNotes = 'https://github.com/AndiBellstedt/WinEventLogCustomization/blob/main/WinEventLogCustomization/changelog.md'
99116

100117
} # End of PSData hashtable
101118

‎WinEventLogCustomization/WinEventLogCustomization.psm1

+54-56
Original file line numberDiff line numberDiff line change
@@ -18,65 +18,63 @@ $importIndividualFiles = Get-PSFConfigValue -FullName WinEventLogCustomization.I
1818
if ($WinEventLogCustomization_importIndividualFiles) { $importIndividualFiles = $true }
1919
if (Test-Path (Resolve-PSFPath -Path "$($script:ModuleRoot)\..\.git" -SingleItem -NewChild)) { $importIndividualFiles = $true }
2020
if ("<was not compiled>" -eq '<was not compiled>') { $importIndividualFiles = $true }
21-
22-
function Import-ModuleFile
23-
{
24-
<#
25-
.SYNOPSIS
26-
Loads files into the module on module import.
27-
28-
.DESCRIPTION
29-
This helper function is used during module initialization.
30-
It should always be dotsourced itself, in order to proper function.
31-
32-
This provides a central location to react to files being imported, if later desired
33-
34-
.PARAMETER Path
35-
The path to the file to load
36-
37-
.EXAMPLE
38-
PS C:\> . Import-ModuleFile -File $function.FullName
39-
40-
Imports the file stored in $function according to import policy
41-
#>
42-
[CmdletBinding()]
43-
Param (
44-
[string]
45-
$Path
46-
)
47-
48-
$resolvedPath = $ExecutionContext.SessionState.Path.GetResolvedPSPathFromPSPath($Path).ProviderPath
49-
if ($doDotSource) { . $resolvedPath }
50-
else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText($resolvedPath))), $null, $null) }
21+
22+
function Import-ModuleFile {
23+
<#
24+
.SYNOPSIS
25+
Loads files into the module on module import.
26+
27+
.DESCRIPTION
28+
This helper function is used during module initialization.
29+
It should always be dotsourced itself, in order to proper function.
30+
31+
This provides a central location to react to files being imported, if later desired
32+
33+
.PARAMETER Path
34+
The path to the file to load
35+
36+
.EXAMPLE
37+
PS C:\> . Import-ModuleFile -File $function.FullName
38+
39+
Imports the file stored in $function according to import policy
40+
#>
41+
[CmdletBinding()]
42+
Param (
43+
[string]
44+
$Path
45+
)
46+
47+
$resolvedPath = $ExecutionContext.SessionState.Path.GetResolvedPSPathFromPSPath($Path).ProviderPath
48+
if ($doDotSource) { . $resolvedPath }
49+
else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText($resolvedPath))), $null, $null) }
5150
}
5251

5352
#region Load individual files
54-
if ($importIndividualFiles)
55-
{
56-
# Execute Preimport actions
57-
foreach ($path in (& "$ModuleRoot\internal\scripts\preimport.ps1")) {
58-
. Import-ModuleFile -Path $path
59-
}
60-
61-
# Import all internal functions
62-
foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
63-
{
64-
. Import-ModuleFile -Path $function.FullName
65-
}
66-
67-
# Import all public functions
68-
foreach ($function in (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore))
69-
{
70-
. Import-ModuleFile -Path $function.FullName
71-
}
72-
73-
# Execute Postimport actions
74-
foreach ($path in (& "$ModuleRoot\internal\scripts\postimport.ps1")) {
75-
. Import-ModuleFile -Path $path
76-
}
77-
78-
# End it here, do not load compiled code below
79-
return
53+
if ($importIndividualFiles) {
54+
# Execute Preimport actions
55+
foreach ($path in (& "$ModuleRoot\internal\scripts\preimport.ps1")) {
56+
. Import-ModuleFile -Path $path
57+
}
58+
59+
# Import all internal functions
60+
foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)) {
61+
. Import-ModuleFile -Path $function.FullName
62+
}
63+
64+
# Import all public functions
65+
$functions = (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)
66+
$function = $functions[6]
67+
foreach ($function in $functions) {
68+
. Import-ModuleFile -Path $function.FullName
69+
}
70+
71+
# Execute Postimport actions
72+
foreach ($path in (& "$ModuleRoot\internal\scripts\postimport.ps1")) {
73+
. Import-ModuleFile -Path $path
74+
}
75+
76+
# End it here, do not load compiled code below
77+
return
8078
}
8179
#endregion Load individual files
8280

‎WinEventLogCustomization/bin/WinEventLogCustomization.xltx

5.04 KB
Binary file not shown.

0 commit comments

Comments
 (0)