Active Directory Commands’ Filter Parameter Primer

Welcome Forums Non-Technical Discussions Patterns & Practices Active Directory Commands’ Filter Parameter Primer

Viewing 0 reply threads
  • Author
    • #263717
      Topics: 1
      Replies: 85
      Points: 387
      Helping Hand
      Rank: Contributor

      Microsoft has online documentation, for example Get-ADUser, that describes how to pass a value to -Filter. Forget that you ever read that section of documentation because it suggests bad practices.

      First of all, the value bound to -Filter is a string. It is not a script block as the documentation suggests. There’s no reason to ever use the syntax -Filter { property -operator value }.

      Second, there are two layers of parsing happening when -Filter is used. The first parsing is initiated by your shell when you execute the command. The second parsing is initiated by the command itself. Knowing that two parsing routines happen should make it easier to understand how to quote the -Filter value and any embedded value strings. This is better explained with an example.

      Example 1 throws a parsing error. The first parse happens without issues because ‘SamAccountName -eq jdoe1’ is a verbatim string due to the surrounding single quotes. This means Get-ADUser will now attempt to parse SamAccountName -eq jdoe1 for the -Filter. Since the right-hand side (RHS) of an operator (-eq in this case) is expected to be a value, jdoe1 is evaluated. This throws an error because PowerShell will parse that value as a command rather than a string. It is the same as typing jdoe1 at the PowerShell prompt. If you wanted the string jdoe1, you would type ‘jdoe1’. The -Filter parameter expects the same syntactical input. Consider a corrected example below:

      Example 2 executes without a parsing error. This is because Get-ADUser receives a -Filter value of SamAccountName -eq "jdoe1" where the RHS is an actual string "jdoe1" and PowerShell will parse it correctly.

      When throwing variables into the mix, the same rules still apply once you know how variables are substituted and interpreted. If you have a variable that contains a string, PowerShell knows how to parse it as a string. PowerShell substitutes the variable with its value and then types the value as a string (or whatever type it may actually be). This means you can type $variable at the command line without quotes and have it evaluate without any errors. It is just how the parser is designed to work. The parser tokenizes a command and knows how to handle the situation where a token begins with $. See the example below when using double quotes around the filter with a variable:

      Example 3 throws a parsing error. This occurs because the outer double quotes tell PowerShell to expand the string inside. This means inside variables are substituted with their values. Once layer one of parsing is done, -Filter is passed the value SamAccountName -eq jdoe1, which us back to Example 1.

      Example 4 has no errors. -Filter is passed the verbatim string SamAccountName -eq $user. Then Get-ADUser processes the filter value and PowerShell parses $user as the string jdoe1. Since the RHS value is determined to be a value (as opposed to a command) and is typed as a string, the command successfully executes with no errors. Consider the next example with a more complex but common variable scenario:

      Example 5 has the correct syntax. If we consider how strings are expanded, the use of the sub-expression operator $() makes sense here. When a string that contains a variable is expanded, variable references inside are substituted with their values. The parser knows when there is a variable when it sees a token beginning with $. The remaining characters following the $ are part of the variable name until a character is reached that is not legal for a standard variable name. You could have a variable named $var, but if you enter "$vars", then $vars (because s is legal) will be parsed as the variable yielding no result. If you enter $var.., then $var will be substituted and .. will be appended to the output string (because .. is not legal). So you cannot use "$" without helping the parser tokenize it as a variable and property reference. Enter the sub-expression operator to get the intended result: "$(". Once Example 5 command is parsed by PowerShell, -Filter is passed "SamAccountName -eq ‘jdoe1’", which takes us back to example 2.

      • This topic was modified 1 week, 4 days ago by grokkit.
      • This topic was modified 1 week, 3 days ago by kvprasoon. Reason: Code formatting
Viewing 0 reply threads
  • You must be logged in to reply to this topic.