René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Make Get-WinEvent compatible to Get-EventLog","articleBody":"### Summary of the new feature / enhancement\r\n\r\nFor decades, Windows admins have been using `Get-EventLog` to query classic event logs. In PowerShell 3, `Get-EventLog` was superseeded by the more powerful and versatile `Get-WinEvent` which technically has convincing features: it is faster, accepts sophisticated xml queries, can access evtx based event logs, and more. \r\n\r\nHowever, `Get-WinEvent` was never really adopted by the community, and still `Get-EventLog` is used most often. In *PowerShell Core*, `Get-Eventlog` was actually removed from the package so users hooked to `Get-EventLog` are faced with code changes.\r\n\r\nThe primary reason just **why** users did not adopt the technically superior `Get-WinEvent` is simple: its user interface is awkward and non-discoverable. To perform an average query, at minimum a *FilterHashtable* is needed, and its predefined supported keys are not discoverable. So a user would have to google and investigate which keys are needed when in contrast, `Get-EventLog` would simply suggest intuitive parameters.\r\n\r\nSince the new `Get-WinEvent` can do what `Get-EventLog` did (and more and faster), this cmdlet should simply support the old parametersets from `Get-EventLog` and translate them into the awkward filter hashtable keys.\r\n\r\n## Current Situation\r\n\r\nHere is an average event log query using `Get-EventLog` returning the installed updates within the past 30 days:\r\n```powershell\r\n$30Days = (Get-Date).AddDays(-30)\r\nGet-Eventlog -LogName System -EntryType Information -InstanceId 19 -After $30Days -Source 'Microsoft-Windows-WindowsUpdateClient'\r\n```\r\n\r\nWith `Get-WinEvent`, a user would have to compose at minimum a filter hashtable like so:\r\n```powershell\r\n$30Days = (Get-Date).AddDays(-30)\r\n$filter = @{\r\n    LogName = 'System'\r\n    Level = 4,5\r\n    Id = 19\r\n    StartTime = $30Days\r\n    ProviderName = 'Microsoft-Windows-WindowsUpdateClient'\r\n}\r\nGet-WinEvent -FilterHashtable $filter\r\n```\r\nNone of the hashtable keys needed here is discoverable. They are not intuitive, there is no intellisense or completion, thus a user would have to go google.\r\n\r\nThat said, once the correct filter hashtable has been composed, `Get-WinEvent` returns the very same information (albeit property names may differ a little, this would be something admins can easily work around).\r\n\r\n## Suggestion\r\n\r\nBy adding the parameters supported by `Get-EventLog` to `Get-WinEvent`, the cmdlet could automate the process of composing the filter hashtable. In essence, `Get-WinEvent` would be usable just as easily as `Get-EventLog` has been for years. This would ease transition to *PowerShell Core* and also increase the performance of event log queries altogether.\r\n\r\nWith such a concept, the user would run `Get-WinEvent` like this:\r\n\r\n```powershell\r\n$30Days = (Get-Date).AddDays(-30)\r\nGet-WinEvent -LogName System -EntryType Information -InstanceId 19 -After $30Days -Source 'Microsoft-Windows-WindowsUpdateClient'\r\n```\r\n\r\n\r\n\r\n### Proposed technical implementation details (optional)\r\n\r\nThe implementation is primarily diligence work and not technically challenging. Basically, the parameters have to be translated to the appropriate hashtable keys.\r\n\r\nBelow is a proof of concept which is obviously **neither complete nor production ready**. I added the most commonly used parameters used by `Get-EventLog`. I did not i.e. implement the *list* parameterset (which should be trivial enough).\r\n\r\n```powershell\r\n\u003c#\r\nSuggestion to improve Get-WinEvent in order to make it compatible to the commonly used Get-EventLog calls\r\n\r\nBelow is a prototype using a proxy function. Run it to enhance Get-WinEvent.\r\nTo get rid of the enhancement, either restart PowerShell or run:\r\nRemove-Item -Path function:Get-WinEvent\r\n\r\nNote that the prototype emits the composed hashtable to the console (green)\r\n#\u003e\r\n\r\nfunction Get-WinEvent\r\n{\r\n    [CmdletBinding(DefaultParameterSetName='GetLogSet', HelpUri='https://go.microsoft.com/fwlink/?LinkID=138336')]\r\n    param(\r\n        \r\n        [Parameter(ParameterSetName='ListLogSet', Mandatory=$true, Position=0)]\r\n        [AllowEmptyCollection()]\r\n        [string[]]\r\n        ${ListLog},\r\n\r\n        [Parameter(ParameterSetName='LogNameGetEventlog', Mandatory=$true, Position=0)] \u003c#NEW#\u003e \r\n        [Parameter(ParameterSetName='GetLogSet', Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]\r\n        [string[]]\r\n        ${LogName},\r\n\r\n        [Parameter(ParameterSetName='ListProviderSet', Mandatory=$true, Position=0)]\r\n        [AllowEmptyCollection()]\r\n        [string[]]\r\n        ${ListProvider},\r\n\r\n        \u003c# Get-EventLog supports wildcards, Get-WinEvent does not. Needs to be corrected. #\u003e\r\n        [Parameter(ParameterSetName='GetProviderSet', Mandatory=$true, Position=0, ValueFromPipelineByPropertyName=$true)]\r\n        [string[]]\r\n        ${ProviderName},\r\n\r\n        [Parameter(ParameterSetName='FileSet', Mandatory=$true, Position=0, ValueFromPipelineByPropertyName=$true)]\r\n        [Alias('PSPath')]\r\n        [string[]]\r\n        ${Path},\r\n\r\n        [Parameter(ParameterSetName='FileSet')]\r\n        [Parameter(ParameterSetName='GetProviderSet')]\r\n        [Parameter(ParameterSetName='GetLogSet')]\r\n        [Parameter(ParameterSetName='HashQuerySet')]\r\n        [Parameter(ParameterSetName='XmlQuerySet')]\r\n        [ValidateRange(1, 9223372036854775807)]\r\n        [long]\r\n        ${MaxEvents},\r\n        \r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [ValidateRange(0, 2147483647)]\r\n        [int]\r\n        ${Newest},\r\n        \r\n        [Parameter(ParameterSetName='GetProviderSet')]\r\n        [Parameter(ParameterSetName='ListProviderSet')]\r\n        [Parameter(ParameterSetName='ListLogSet')]\r\n        [Parameter(ParameterSetName='GetLogSet')]\r\n        [Parameter(ParameterSetName='HashQuerySet')]\r\n        [Parameter(ParameterSetName='XmlQuerySet')]\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')] \u003c#NEW#\u003e \r\n        [Alias('Cn')]\r\n        [ValidateNotNullOrEmpty()] \u003c#CORRECTED#\u003e\r\n        [string] \u003c# used to be [String[]], Get-WinEvent accepts [string] only, should be changed to accept string arrays #\u003e\r\n        ${ComputerName},\r\n\r\n        [Parameter(ParameterSetName='GetProviderSet')]\r\n        [Parameter(ParameterSetName='ListProviderSet')]\r\n        [Parameter(ParameterSetName='ListLogSet')]\r\n        [Parameter(ParameterSetName='GetLogSet')]\r\n        [Parameter(ParameterSetName='HashQuerySet')]\r\n        [Parameter(ParameterSetName='XmlQuerySet')]\r\n        [Parameter(ParameterSetName='FileSet')]\r\n        [pscredential]\r\n        [System.Management.Automation.CredentialAttribute()]\r\n        ${Credential},\r\n\r\n        [Parameter(ParameterSetName='FileSet')]\r\n        [Parameter(ParameterSetName='GetProviderSet')]\r\n        [Parameter(ParameterSetName='GetLogSet')]\r\n        [ValidateNotNull()]\r\n        [string]\r\n        ${FilterXPath},\r\n\r\n        [Parameter(ParameterSetName='XmlQuerySet', Mandatory=$true, Position=0)]\r\n        [xml]\r\n        ${FilterXml},\r\n\r\n        [Parameter(ParameterSetName='HashQuerySet', Mandatory=$true, Position=0)]\r\n        [hashtable[]]\r\n        ${FilterHashtable},\r\n\r\n        [Parameter(ParameterSetName='GetProviderSet')]\r\n        [Parameter(ParameterSetName='ListLogSet')]\r\n        [Parameter(ParameterSetName='GetLogSet')]\r\n        [Parameter(ParameterSetName='HashQuerySet')]\r\n        [switch]\r\n        ${Force},\r\n\r\n        [Parameter(ParameterSetName='GetLogSet')]\r\n        [Parameter(ParameterSetName='GetProviderSet')]\r\n        [Parameter(ParameterSetName='FileSet')]\r\n        [Parameter(ParameterSetName='HashQuerySet')]\r\n        [Parameter(ParameterSetName='XmlQuerySet')]\r\n        [switch]\r\n        ${Oldest},\r\n    \r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [datetime]\r\n        ${After},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [datetime]\r\n        ${Before},\r\n        \r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [string[]]\r\n        ${UserName},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog', Position=1)]\r\n        [ValidateRange(0, 9223372036854775807)]\r\n        [ValidateNotNullOrEmpty()]\r\n        [long[]]\r\n        ${InstanceId},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [ValidateRange(1, 2147483647)]\r\n        [int[]]\r\n        ${Index},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [Alias('ET')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [ValidateSet('Error','Information','FailureAudit','SuccessAudit','Warning')]\r\n        [string[]]\r\n        ${EntryType},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [Alias('ABO')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [string[]]\r\n        ${Source},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [Alias('MSG')]\r\n        [ValidateNotNullOrEmpty()]\r\n        [string]\r\n        ${Message},\r\n\r\n        \u003c# NEW #\u003e\r\n        [Parameter(ParameterSetName='LogNameGetEventlog')]\r\n        [switch]\r\n        ${AsBaseObject},\r\n        \r\n        [Parameter(ParameterSetName='ListGetEventlog')]\r\n        [switch]\r\n        ${List},\r\n\r\n        [Parameter(ParameterSetName='ListGetEventlog')]\r\n        [switch]\r\n        ${AsString}\r\n        \r\n        \r\n        \r\n    )\r\n\r\n    begin\r\n    {\r\n        try {\r\n            $outBuffer = $null\r\n            if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer))\r\n            {\r\n                $PSBoundParameters['OutBuffer'] = 1\r\n            }\r\n            $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Microsoft.PowerShell.Diagnostics\\Get-WinEvent', [System.Management.Automation.CommandTypes]::Cmdlet)\r\n\r\n            # if the user chose the Get-EventLog compatible parameters,\r\n            # compose the appropriate filterhashtable:\r\n            $scriptCmd = if ($PSCmdlet.ParameterSetName -eq 'LogNameGetEventlog')\r\n            {\r\n                # mandatory parameter:\r\n                $filter = @{\r\n                    LogName = $PSBoundParameters['Logname']\r\n                }\r\n                $null = $PSBoundParameters.Remove('LogName')\r\n                \r\n                if ($PSBoundParameters.ContainsKey('Before'))\r\n                {\r\n                    $filter['EndTime'] = $PSBoundParameters['Before']\r\n                    $null = $PSBoundParameters.Remove('Before')\r\n                }\r\n                if ($PSBoundParameters.ContainsKey('After'))\r\n                {\r\n                    $filter['StartTime'] = $PSBoundParameters['After']\r\n                    $null = $PSBoundParameters.Remove('After')\r\n                }\r\n                if ($PSBoundParameters.ContainsKey('EntryType'))\r\n                {\r\n                    # severity is translated to an integer array:\r\n                    \r\n                    $levelFlags = [System.Collections.Generic.List[int]]@()\r\n\r\n                    # string input converted to integer array:\r\n                    if ($PSBoundParameters['EntryType'] -contains 'Error')\r\n                    {\r\n                        $levelFlags.Add(1) # critical\r\n                        $levelFlags.Add(2) # error\r\n                    }\r\n                    if ($PSBoundParameters['EntryType'] -contains 'Warning')\r\n                    {\r\n                        $levelFlags.Add(3) # warning\r\n                    }\r\n                    if ($PSBoundParameters['EntryType'] -contains 'Information')\r\n                    {\r\n                        $levelFlags.Add(4) # informational\r\n                        $levelFlags.Add(5) # verbose\r\n                    }\r\n                    \r\n                        \r\n                    # default to 0:\r\n                    if ($levelFlags.Count -gt 0)\r\n                    {\r\n                        $filter['Level'] = [int[]]$levelFlags\r\n                    }\r\n                        \r\n                    # audit settings stored in Keywords key:\r\n                    if ($PSBoundParameters['EntryType'] -contains 'FailureAudit')\r\n                    {\r\n                        $filter['Keywords'] += 0x10000000000000\r\n                    }\r\n                    if ($PSBoundParameters['EntryType'] -contains 'SuccessAudit')\r\n                    {\r\n                        $filter['Keywords'] += 0x20000000000000\r\n                    }\r\n                    $null = $PSBoundParameters.Remove('EntryType')\r\n                }\r\n                if ($PSBoundParameters.ContainsKey('InstanceId'))\r\n                {\r\n                    $filter['ID'] = $PSBoundParameters['InstanceId']\r\n                    $null = $PSBoundParameters.Remove('InstanceId')\r\n                }\r\n                if ($PSBoundParameters.ContainsKey('Source'))\r\n                {\r\n                    $filter['ProviderName'] = $PSBoundParameters['Source']\r\n                    $null = $PSBoundParameters.Remove('Source')\r\n                }\r\n                \r\n                $PSBoundParameters['FilterHashtable'] = $filter\r\n                Write-Host ($filter | Out-String) -ForegroundColor Green\r\n                \r\n                if ($PSBoundParameters.ContainsKey('Newest'))\r\n                {\r\n                    $PSBoundParameters['MaxEvents'] = $PSBoundParameters['Newest']\r\n                    $null = $PSBoundParameters.Remove('Newest')\r\n                }\r\n            }\r\n            \r\n            \r\n            $scriptCmd = \r\n            {\r\n                \u0026 $wrappedCmd @PSBoundParameters\r\n            } \r\n            $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOrigin)\r\n            $steppablePipeline.Begin($PSCmdlet)\r\n        } catch {\r\n            throw\r\n        }\r\n    }\r\n\r\n    process\r\n    {\r\n        try {\r\n            $steppablePipeline.Process($_)\r\n        } catch {\r\n            throw\r\n        }\r\n    }\r\n\r\n    end\r\n    {\r\n        try {\r\n            $steppablePipeline.End()\r\n        } catch {\r\n            throw\r\n        }\r\n    }\r\n    \u003c#\r\n\r\n            .ForwardHelpTargetName Microsoft.PowerShell.Diagnostics\\Get-WinEvent\r\n            .ForwardHelpCategory Cmdlet\r\n\r\n    #\u003e\r\n\r\n}\r\n```\r\n\r\nOnce you run this code, you can then continue to use `Get-WinEvent` like before, but you now *can also start using the parameters that you know from `Get-EventLog`*. The enhanced `Get-WinEvent` automatically converts these parameters into a filterhashtable, and there is no need anymore for the user to know its keys or predefined awkward codes for event types.\r\n\r\n## Notes\r\n\r\nThere are a few technical limitations, i.e. `Get-EventLog` supports wildcards for providernames whereas `Get-WinEvent` does not. `Get-WinEvent` should be enhanced in these areas to be on the same level.\r\n\r\nObviously the new parameters should get rich intellisense to suggest available lognames and provider names.\r\n","author":{"url":"https://github.com/TobiasPSP","@type":"Person","name":"TobiasPSP"},"datePublished":"2021-07-29T09:42:03.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":17},"url":"https://github.com/15844/PowerShell/issues/15844"}