{"id":85197,"date":"2019-09-17T15:27:38","date_gmt":"2019-09-17T15:27:38","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=85197"},"modified":"2026-03-18T11:25:24","modified_gmt":"2026-03-18T11:25:24","slug":"how-to-use-parameters-in-powershell","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/sysadmin\/powershell\/how-to-use-parameters-in-powershell\/","title":{"rendered":"PowerShell Parameters: A Practical Guide"},"content":{"rendered":"

The series so far:<\/strong><\/p>\n

    \n
  1. How to Use Parameters in PowerShell Part I<\/a><\/li>\n
  2. How to User Parameters in PowerShell Part II<\/a><\/li>\n<\/ol>\n\n\n\n\n

    PowerShell provides two main ways to accept parameters in a script: unnamed arguments using the $args array, and named parameters using the Param() block. Named parameters are the recommended approach because they provide type safety, built-in help messages, mandatory enforcement, and default values – making scripts more readable and portable across environments. This guide walks through both methods with working examples you can run immediately.<\/p>\n\n\n\n

    Introduction<\/strong><\/p>\n\n\n\n

    Recently I had a client ask me to update a script in both production and UAT. He wanted any emails sent out to include the name of the environment. It was a simple request, and I supplied a simple solution. I just created a new variable:<\/p>\n\n\n\n

    $envname = \"UAT\"<\/pre>\n\n\n\n
    After updating the script for the production environment, I then modified the subject line for any outgoing emails to include the new variable.<\/p>\n\n\n\n
    At the time though, I wanted to do this in a better way, and not just for this variable, but also for the others I use in the script. When I wrote this script, it was early in my days of writing PowerShell, so I simply hardcoded variables into it. It soon became apparent that this was less than optimal when I needed to move a script from Dev\\UAT into production because certain variables would need to be updated between the environments.<\/p>\n\n\n\n
    Fortunately, like most languages, PowerShell permits the use of parameters, but, like many things in PowerShell, there\u2019s more than one way of doing it. I will show you how to do it in two different ways and discuss why I prefer one method over the other.
    Read also: <\/strong>    Using LINQ for high-performance PowerShell<\/a><\/p>\n\n\n\n
    Let\u2019s Have an Argument<\/h2>\n\n\n\n
    The first and arguably (see what I did there) the easiest way to get command line arguments is to write something like the following:<\/p>\n\n\n\n
    $param1=$args[0]\nwrite-host $param1<\/pre>\n\n\n\n
    If you run this from within the PowerShell ISE by pressing F5<\/em>, nothing interesting will happen. This is a case where you will need to run the saved file from the ISE Console and supply a value for the argument.<\/p>\n\n\n\n
    To make sure PowerShell executes what you want, navigate in the command line to the same directory where you will save your scripts. Name the script Unnamed_Arguments_Example_1.ps1<\/em> and run it with the argument FOO<\/em>. It will echo back FOO<\/em>. (The scripts for this article can be found <\/span>here<\/a>.)<\/span><\/p>\n\n\n\n
     .\\Unnamed_Arguments_Example_1.ps1 FOO<\/pre>\n\n\n\n
    You\u2019ve probably already guessed that since $args<\/code> is an array, you can access multiple values from the command line.<\/p>\n\n\n\n
    Save the following script as Unnamed_Arguments_Example_2.ps1. <\/em><\/p>\n\n\n\n
    $servername=$args[0]\n$envname=$args[1]\nwrite-host \"If this script were really going to do something, it would do it on $servername in the $envname environment\"<\/pre>\n\n\n\n
    Run it as follows:<\/p>\n\n\n\n
    .\\Unnamed_Arguments_Example_2.ps1 HAL Odyssey<\/pre>\n\n\n\n
    You should see:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    One nice ability of reading the arguments this way is that you can pass in an arbitrary number of arguments if you need to. Save the following example as Unnamed_Arguments_Example_3.ps1<\/em><\/p>\n\n\n\n
    write-host \"There are a total of $($args.count) arguments\"\nfor ( $i = 0; $i -lt $args.count; $i++ ) {\n    write-host \"Argument  $i is $($args[$i])\"\n}<\/pre>\n\n\n\n
    If you call it as follows:<\/p>\n\n\n\n
    .\\Unnamed_Arguments_Example_3.ps1 foo bar baz<\/pre>\n\n\n\n
    You should get:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    The method works, but I would argue that it\u2019s not ideal. For one thing, you can accidentally pass in parameters in the wrong order. For another, it doesn\u2019t provide the user with any useful feedback. I will outline the preferred method below.<\/p>\n\n\n\n
    Using Named Parameters<\/h2>\n\n\n\n
    Copy the following script and save it as Named_Parameters_Example_1.ps1<\/em>.<\/p>\n\n\n\n
    param ($param1)\nwrite-host $param1<\/pre>\n\n\n\n
    Then run it.<\/p>\n\n\n\n
    .\\Named_Parameters_Example_1.ps1<\/pre>\n\n\n\n
    When you run it like this, nothing will happen.<\/p>\n\n\n\n
    But now enter:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_1.ps1 test<\/pre>\n\n\n\n
    And you will see your script echo back the word test<\/em>.<\/p>\n\n\n\n
    This is what you might expect, but say you had multiple parameters and wanted to make sure you had assigned the right value to each one. You might have trouble remembering their names and perhaps their order. But that\u2019s OK; PowerShell is smart. Type in the same command as above but add a dash (-) at the end.<\/p>\n\n\n\n
    .\\Named_Parameters_Example_1.ps1 -<\/pre>\n\n\n\n
    PowerShell should now pop up a little dropdown that shows you the available parameters. In this case, you only have the one parameter, param1<\/code>. Hit tab to autocomplete and enter the word test<\/em> or any other word you want, and you should see something similar to:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_1.ps1 -param1 test<\/pre>\n\n\n\n
    Now if you hit enter, you will again see the word test <\/em>echoed.<\/p>\n\n\n\n
    If you run the script from directly inside PowerShell itself, as opposed to the ISE, tab completion will still show you the available parameters, but will not pop them up in a nice little display.<\/p>\n\n\n\n
    Create and save the following script as Named_Parameters_Example_2.ps1<\/em>.<\/p>\n\n\n\n
    param ($servername, $envname)\nwrite-host \"If this script were really going to do something, it would do it on $servername in the $envname environment\"<\/pre>\n\n\n\n
    Note now you have two parameters.<\/p>\n\n\n\n
    By default, PowerShell will use the position of the parameters in the file to determine what the parameter is when you enter it. This means the following will work:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_2.ps1 HAL Odyssey<\/pre>\n\n\n\n
    The result will be:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    Here\u2019s where the beauty of named parameters shines. Besides not having to remember what parameters the script may need, you don\u2019t have to worry about the order in which they\u2019re entered.<\/p>\n\n\n\n
    .\\Named_Parameters_Example_2.ps1 -envname Odyssey -servername HAL<\/pre>\n\n\n\n
    This will result in the exact same output as above, which is what you should expect:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    If you used tab completion to enter the parameter names, what you will notice is once you\u2019ve entered a value for one of the parameters (such as \u2013envname<\/code> above), when you try to use tab completion for another parameter, only the remaining parameters appear. In other words, PowerShell won\u2019t let you enter the same parameter twice if you use tab completion.<\/p>\n\n\n\n
    If you do force the same parameter name twice, PowerShell will give you an error similar to:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    One question that probably comes to mind at this point is how you would handle a parameter with a space in it. For example, how would you enter a file path like C:\\path to file\\File.ext<\/em>.<\/p>\n\n\n\n
    The answer is simple; you can wrap the parameter in quotes:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_2.ps1 -servername HAL -envname 'USS Odyssey'<\/pre>\n\n\n\n
    The code will result in:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    With the flexibility of PowerShell and quoting, you can do something like:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_2.ps1 -servername HAL -envname \"'USS Odyssey'\"<\/pre>\n\n\n\n
    You\u2019ll see this message back:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    If you experiment with entering different values into the scripts above, you\u2019ll notice that it doesn\u2019t care if you type in a string or a number or pretty much anything you want. This may be a problem if you need to control the type of data the user is entering.<\/p>\n\n\n\n
    This leads to typing of your parameter variables. I generally do not do this for variables within PowerShell scripts themselves (because in most cases I\u2019m controlling how those variables are being used), but I almost always ensure typing of my parameter variables so I can have some validation over my input.<\/p>\n\n\n\n
    Consider why this may be important. Save the following script as Named_Parameters_Example_3.ps1<\/em><\/p>\n\n\n\n
    param ([int] $anInt, $maybeanInt)\nwrite-host \"Adding $anint to itself results in: $($anInt + $anInt)\"\nwrite-host \"But trying to add $maybeanInt to itself results in: $($maybeanInt + $maybeanInt)\"<\/pre>\n\n\n\n
    Now run it as follows:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_3.ps1 -anInt 5 -maybeanInt 6<\/pre>\n\n\n\n
    You will get the results you expect:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    What if you don\u2019t control the data being passed, and the passing program passes items in quoted strings?<\/p>\n\n\n\n
    To simulate that run the script with a slight modification:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_3.ps1 -anInt \"5\" -maybeanInt \"6\"<\/pre>\n\n\n\n
    This will result in:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    If you instead declare $maybeanInt<\/code> as an [int]<\/code> like you did $anInt<\/code>, you can assure the two get added together, not concatenated.<\/p>\n\n\n\n
    However, keep in mind if someone tries to call the same script with an actual string such as:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_3.ps1 Foo 6<\/pre>\n\n\n\n
    It will return a gross error message, so this can be a double-edged sword.<\/p>\n\n\n\n
    \n    
    \n        
    \n            
    \n                
    Automate your SQL workflows with PowerShell and Redgate<\/h3>\n                
    \n                                            The PowerShell parameters you\u2019re learning here can do more than automate simple tasks. With tools like Redgate Monitor, SQL Clone, SQL Change Automation, SQL Data Catalog, and Redgate Flyway, you can monitor servers, create clones, deploy database changes, and more – all from your scripts.                                    <\/div>\n            <\/div>\n                                            Explore the full portfolio<\/a>\n                    <\/div>\n    <\/div>\n<\/section>\n\n\n
    Using Defaults<\/h2>\n\n\n\n
    When running a script, I prefer to make it require as little typing as possible and to eliminate errors where I can. This means that I try to use defaults.<\/p>\n\n\n\n
    Modify the Named_Parameters_Example_2.ps1<\/em> script as follows and save it as Named_Parameters_Example_4.ps1<\/em><\/p>\n\n\n\n
    param ($servername, $envname='Odyssey')\nwrite-host \"If this script were really going to do something, it would do it on $servername in the $envname environment\"<\/pre>\n\n\n\n
    And then run it as follows:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_4.ps1 -servername HAL<\/pre>\n\n\n\n
    Do not bother to enter the environment name. You should get:<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    <\/p>\n\n\n\n
    This isn\u2019t much savings in typing but does make it a bit easier and does mean that you don\u2019t have to remember how to spell Odyssey<\/em>!<\/p>\n\n\n\n
    There may also be cases where you don\u2019t want a default parameter, but you absolutely want to make sure a value is entered. You can do this by testing to see if the parameter is null and then prompting the user for input.<\/p>\n\n\n\n
    Save the following script as Named_Parameters_Example_5.ps1<\/em>.<\/p>\n\n\n\n
    param ($servername, $envname='Odyssey')\nif ($servername -eq $null) {\n$servername = read-host -Prompt \"Please enter a servername\" \n}\nwrite-host \"If this script were really going to do something, it would do it on $servername in the $envname environment\"<\/pre>\n\n\n\n
    You will notice that this combines both, a default parameter and testing the see if the $servername<\/code> is null and if it is, prompting the user to enter a value.<\/p>\n\n\n\n
    You can run this from the command line in multiple ways:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_5.ps1 -servername HAL<\/pre>\n\n\n\n
    It will do exactly what you think: use the passed in servername value of HAL<\/em> and the default environment of Odyssey<\/em>.<\/p>\n\n\n\n
    But you could also run it as:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_5.ps1 -envname Discovery<\/pre>\n\n\n\n
    And in this case, it will override the default parameter for the environment with Discovery<\/em>, and it will prompt the user for the computer name. To me, this is the best of both worlds.<\/p>\n\n\n\n
    There is another way of ensuring your users enter a parameter when it\u2019s mandatory.<\/p>\n\n\n\n
    Save the following as Named_Parameters_Example_6.ps1<\/em><\/p>\n\n\n\n
    param ([Parameter(Mandatory)]$servername, $envname='Odessey')\nwrite-host \"If this script were really going to do something, it would do it on $servername in the $envname environment\"<\/pre>\n\n\n\n
    and run it as follows:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_6.ps1<\/pre>\n\n\n\n
    You\u2019ll notice it forces you to enter the servername because you made that mandatory, but it still used the default environment name of Odyssey<\/em>.<\/p>\n\n\n\n
    You can still enter the parameter on the command line too:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_6.ps1  -servername HAL -envname Discovery<\/pre>\n\n\n\n
    And PowerShell won\u2019t prompt for the servername since it\u2019s already there.<\/p>\n\n\n\n
    Using an Unknown Number of Arguments<\/h2>\n\n\n\n
    Generally, I find using named parameters far superior over merely reading the arguments from the command line. One area that reading the arguments is a tad easier is when you need the ability to handle an unknown number of arguments.<\/p>\n\n\n\n
    For example, save the following script as Unnamed_Arguments_Example_4.ps1<\/em><\/p>\n\n\n\n
    write-host \"There are a total of $($args.count) arguments\"\nfor ( $i = 0; $i -lt $args.count; $i++ ) {\n    $diskdata = get-PSdrive $args[$i] | Select-Object Used,Free\n    write-host \"$($args[$i]) has  $($diskdata.Used) Used and $($diskdata.Free) free\"\n}<\/pre>\n\n\n\n
    Then call it as follows:<\/p>\n\n\n\n
    .\\Unnamed_Arguments_Example_4.ps1 C D E<\/pre>\n\n\n\n
    You will get back results for the amount of space free on the drive letters you list. As you can see, you can enter as many drive letters as you want.<\/p>\n\n\n\n
    One attempt to write this using named parameters might look like:<\/p>\n\n\n\n
    param($drive1, $drive2, $drive3)\n$diskdata = get-PSdrive $drive1 | Select-Object Used,Free\nwrite-host \"$($drive1) has  $($diskdata.Used) Used and $($diskdata.Free) free\"\nif ($drive2 -ne $null) {\n$diskdata = get-PSdrive $drive2 | Select-Object Used,Free\nwrite-host \"$($drive2) has  $($diskdata.Used) Used and $($diskdata.Free) free\"\n    if ($drive3 -ne $null) {\n    $diskdata = get-PSdrive $drive3 | Select-Object Used,Free\n    write-host \"$($drive3) has  $($diskdata.Used) Used and $($diskdata.Free) free\"\n    }\n    else\n    { return}\n}\nelse\n{return} # don't bother testing for drive3 since we didn't even have drive 3<\/pre>\n\n\n\n
    As you can see, that gets ugly fairly quickly as you would have to handle up to 26 drive letters.<\/p>\n\n\n\n
    Fortunately, there\u2019s a better way to handle this using named parameters. Save the following as Named_Parameters_Example_7.ps1<\/em><\/p>\n\n\n\n
    param($drives)\nforeach ($drive in $drives) \n{\n    $diskdata = get-PSdrive $drive | Select-Object Used,Free\n    write-host \"$($drive) has  $($diskdata.Used) Used and $($diskdata.Free) free\"\n}<\/pre>\n\n\n\n
    If you want to check the space on a single drive, then you call this as you would expect:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_7.ps1 C<\/pre>\n\n\n\n
    On the other hand, if you want to test multiple drives, you can pass an array of strings.<\/p>\n\n\n\n
    This can be done one of two ways:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_7.ps1 C,D,E<\/pre>\n\n\n\n
    Note that there are commas separating the drive letters, not spaces. This lets PowerShell know that this is all one parameter. (An interesting side note: if you do put a space after comma, it will still treat the list of drive letters as a single parameter, the comma basically eats the space.)<\/p>\n\n\n\n
    If you want to be a bit more explicit in what you\u2019re doing, you can also pass the values in as an array:<\/p>\n\n\n\n
    .\\Named_Parameters_Example_7.ps1 @(\"C\",\"D\",\"E\")<\/pre>\n\n\n\n
    Note that in this case, you do have to qualify the drive letters as strings by using quotes around them.<\/p>\n\n\n\n
    Conclusion<\/h2>\n\n\n\n
    Hopefully, this article has given you some insight into the two methods of passing in variables to PowerShell scripts. This ability, combined with the ability to read JSON files in a previous article should give you a great deal of power to be able to control what your scripts do and how they operate. And now I have a script to rewrite!<\/p>\n\n\n\n
    \n    
    FAQs: How to Use Parameters in PowerShell<\/h2>\n\n                        
    1. What is a parameter in PowerShell?<\/h3>\n            
    \n                
    A parameter in PowerShell lets you pass values into scripts or functions so they behave dynamically instead of using hard\u2011coded data. Parameters improve flexibility and reuse.<\/p>\n            <\/div>\n                    
    2. How do I define a parameter in a PowerShell script?<\/h3>\n            
    \n                
    You define parameters with the param()<\/code> block at the top of your script, listing each variable you want to accept.<\/p>\n            <\/div>\n                    
    3. What\u2019s the difference between unnamed and named parameters in PowerShell?<\/h3>\n            
    \n                
    Unnamed parameters come from the $args<\/code> array and rely on position, while named parameters are declared in a param()<\/code> block and can be passed in any order with the \u2011parameterName value<\/code> syntax.<\/p>\n            <\/div>\n                    
    4. Can PowerShell parameters have default values?<\/h3>\n            
    \n                
    Yes – you can set default values in the param()<\/code> block so a parameter uses the default if no value is provided.<\/p>\n            <\/div>\n                    
    5. How do I make a parameter required?<\/h3>\n            
    \n                
    Use the [Parameter(Mandatory)]<\/code> attribute in the param()<\/code> declaration to force the user to supply a value before the script runs.<\/p>\n            <\/div>\n                    
    6. Can I accept multiple values with a single parameter in PowerShell?<\/h3>\n            
    \n                
    Yes – you can define a parameter to accept an array of values, letting users pass multiple entries at once.<\/p>\n            <\/div>\n                    
    7. Why should I use parameters instead of hard\u2011coding values?<\/h3>\n            
    \n                
    Using parameters makes your scripts easier to maintain, more reusable, and less error\u2011prone when moving between environments like Dev, UAT, and Prod\u2014 a principle that scales directly into cloud workflows, as shown in PowerShell functions for reusability in Azure.<\/a><\/p>\n            <\/div>\n            <\/section>\n\n\n\n
    \n    
    \n        
    \n            
    \n                
    Subscribe to the Simple Talk newsletter<\/h3>\n                
    \n                                            Get selected articles, event information, podcasts and other industry content delivered straight to your inbox every two weeks.                                    <\/div>\n            <\/div>\n                                            Subscribe now<\/a>\n                    <\/div>\n    <\/div>\n<\/section>","protected":false},"excerpt":{"rendered":"
    Learn how to use parameters in PowerShell scripts using $args, named parameters, and the Param() block. Includes examples for passing arguments, setting defaults, and making parameters mandatory.…<\/p>\n","protected":false},"author":319367,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":true,"footnotes":""},"categories":[53,35],"tags":[159019],"coauthors":[61343],"class_list":["post-85197","post","type-post","status-publish","format-standard","hentry","category-featured","category-powershell","tag-stateofdatabaselandscapesurvey"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/85197","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/319367"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=85197"}],"version-history":[{"count":18,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/85197\/revisions"}],"predecessor-version":[{"id":109307,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/85197\/revisions\/109307"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=85197"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=85197"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=85197"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=85197"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}