HelpCache/Microsoft.PowerShell.Utility.psm1-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns="http://msh" schema="maml"> <!-- Updatable Help Version 5.0.2.0 --> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Add-Member</command:name> <maml:description> <maml:para>Adds custom properties and methods to an instance of a Windows PowerShell object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Add</command:verb> <command:noun>Member</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Add-Member cmdlet lets you add members (properties and methods) to an instance of a Windows PowerShell object. For example, you can add a NoteProperty member that contains a description of the object or a ScriptMethod member that runs a script to change the object.</maml:para> <maml:para>To use Add-Member, pipe the object to Add-Member, or use the InputObject parameter to specify the object. Use the MemberType parameter to specify the type of member that you want to add, use the Name parameter to assign a name to the new member, and use the Value parameter to set the value of the member.</maml:para> <maml:para>The properties and methods that you add are added only to the particular instance of the object that you specify. Add-Member does not change the object type. To create a new object type, use the Add-Type cmdlet. You can also use the Export-Clixml cmdlet to save the instance of the object, including the additional members, in a file. Then you can use the Import-Clixml cmdlet to re-create the instance of the object from the information that is stored in the exported file.</maml:para> <maml:para>Beginning in Windows PowerShell 3.0, Add-Member has new features that make it easier to add note properties to objects. You can use the NotePropertyName and NotePropertyValue parameters to define a note property or use the NotePropertyMembers parameter, which takes a hash table of note property names and values. </maml:para> <maml:para>Also, beginning in Windows PowerShell 3.0, the PassThru parameter, which generates an output object, is needed less frequently. Add-Member now adds the new members directly to the input object of more types. For more information, see the PassThru parameter description.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Add-Member</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the newly extended object. By default, this cmdlet does not generate any output.</maml:para> <maml:para>For most objects, Add-Member adds the new members to the input object. However, when the input object is a string, Add-Member cannot add the member to the input object. For these objects, use the PassThru parameter to create an output object.</maml:para> <maml:para>In Windows PowerShell 2.0, Add-Member added members only to the PSObject wrapper of objects, not to the object. Use the PassThru parameter to create an output object for any object that has a PSObject wrapper.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies a name for the type.</maml:para> <maml:para>When the type is a class in the System namespace or a type that has a type accelerator, you can enter the short name of the type. Otherwise, the full type name is required. This parameter is effective only when the input object is a PSObject.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Member</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>NotePropertyName</maml:name> <maml:description> <maml:para>Adds a note property with the specified name.</maml:para> <maml:para>Use this parameter with the NotePropertyValue parameter. The parameter name (-NotePropertyName) is optional.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>NotePropertyValue</maml:name> <maml:description> <maml:para>Adds a note property with the specified value.</maml:para> <maml:para>Use this parameter with the NotePropertyName parameter. The parameter name (-NotePropertyValue) is optional.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Adds a new member even the object has a custom member with the same name. You cannot use the Force parameter to replace a standard member of a type.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the newly extended object. By default, this cmdlet does not generate any output.</maml:para> <maml:para>For most objects, Add-Member adds the new members to the input object. However, when the input object is a string, Add-Member cannot add the member to the input object. For these objects, use the PassThru parameter to create an output object.</maml:para> <maml:para>In Windows PowerShell 2.0, Add-Member added members only to the PSObject wrapper of objects, not to the object. Use the PassThru parameter to create an output object for any object that has a PSObject wrapper.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies a name for the type.</maml:para> <maml:para>When the type is a class in the System namespace or a type that has a type accelerator, you can enter the short name of the type. Otherwise, the full type name is required. This parameter is effective only when the input object is a PSObject.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Member</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>NotePropertyMembers</maml:name> <maml:description> <maml:para>Specifies a hash table or ordered dictionary of note property names and values. Type a hash table or dictionary in which the keys are note property names and the values are note property values.</maml:para> <maml:para>For more information about hash tables and ordered dictionaries in Windows PowerShell, see about_Hash_Tables (http://go.microsoft.com/fwlink/?LinkID=135175).</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Adds a new member even the object has a custom member with the same name. You cannot use the Force parameter to replace a standard member of a type.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the newly extended object. By default, this cmdlet does not generate any output.</maml:para> <maml:para>For most objects, Add-Member adds the new members to the input object. However, when the input object is a string, Add-Member cannot add the member to the input object. For these objects, use the PassThru parameter to create an output object.</maml:para> <maml:para>In Windows PowerShell 2.0, Add-Member added members only to the PSObject wrapper of objects, not to the object. Use the PassThru parameter to create an output object for any object that has a PSObject wrapper.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies a name for the type.</maml:para> <maml:para>When the type is a class in the System namespace or a type that has a type accelerator, you can enter the short name of the type. Otherwise, the full type name is required. This parameter is effective only when the input object is a PSObject.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Member</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="Type"> <maml:name>MemberType</maml:name> <maml:description> <maml:para>Specifies the type of the member to add. This parameter is mandatory.</maml:para> <maml:para>The valid values for this parameter are: "NoteProperty,AliasProperty,ScriptProperty,CodeProperty,ScriptMethod,CodeMethod" AliasProperty, CodeMethod, CodeProperty, Noteproperty, ScriptMethod, and ScriptProperty.</maml:para> <maml:para>For information about these values, see "PSMemberTypes Enumeration" in MSDN at <maml:navigationLink><maml:linkText>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.psmembertypes(v=vs.85).aspx</maml:linkText><maml:uri></maml:uri></maml:navigationLink>. </maml:para> <maml:para>Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns an error.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">AliasProperty</command:parameterValue> <command:parameterValue required="true" variableLength="false">CodeProperty</command:parameterValue> <command:parameterValue required="true" variableLength="false">Property</command:parameterValue> <command:parameterValue required="true" variableLength="false">NoteProperty</command:parameterValue> <command:parameterValue required="true" variableLength="false">ScriptProperty</command:parameterValue> <command:parameterValue required="true" variableLength="false">Properties</command:parameterValue> <command:parameterValue required="true" variableLength="false">PropertySet</command:parameterValue> <command:parameterValue required="true" variableLength="false">Method</command:parameterValue> <command:parameterValue required="true" variableLength="false">CodeMethod</command:parameterValue> <command:parameterValue required="true" variableLength="false">ScriptMethod</command:parameterValue> <command:parameterValue required="true" variableLength="false">Methods</command:parameterValue> <command:parameterValue required="true" variableLength="false">ParameterizedProperty</command:parameterValue> <command:parameterValue required="true" variableLength="false">MemberSet</command:parameterValue> <command:parameterValue required="true" variableLength="false">Event</command:parameterValue> <command:parameterValue required="true" variableLength="false">Dynamic</command:parameterValue> <command:parameterValue required="true" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the member to be added.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the initial value of the added member. If you add an AliasProperty, CodeProperty, ScriptProperty or CodeMethod member, you can supply optional, additional information by using the SecondValue parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>SecondValue</maml:name> <maml:description> <maml:para>Specifies optional additional information about AliasProperty, ScriptProperty, CodeProperty, or CodeMethod members. If used when adding an AliasProperty, this parameter must be a data type. A conversion (cast) to the specified data type is added to the value of the AliasProperty. For example, if you add an AliasProperty that provides an alternate name for a string property, you can also specify a SecondValue parameter of System.Int32 to indicate that the value of that string property should be converted to an integer when accessed by using the corresponding AliasProperty.</maml:para> <maml:para>You can use the SecondValue parameter to specify an additional ScriptBlock when adding a ScriptProperty member. In that case, the first ScriptBlock, specified in the Value parameter, is used to get the value of a variable. The second ScriptBlock, specified in the SecondValue parameter, is used to set the value of a variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Adds a new member even the object has a custom member with the same name. You cannot use the Force parameter to replace a standard member of a type.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the newly extended object. By default, this cmdlet does not generate any output.</maml:para> <maml:para>For most objects, Add-Member adds the new members to the input object. However, when the input object is a string, Add-Member cannot add the member to the input object. For these objects, use the PassThru parameter to create an output object.</maml:para> <maml:para>In Windows PowerShell 2.0, Add-Member added members only to the PSObject wrapper of objects, not to the object. Use the PassThru parameter to create an output object for any object that has a PSObject wrapper.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies a name for the type.</maml:para> <maml:para>When the type is a class in the System namespace or a type that has a type accelerator, you can enter the short name of the type. Otherwise, the full type name is required. This parameter is effective only when the input object is a PSObject.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Adds a new member even the object has a custom member with the same name. You cannot use the Force parameter to replace a standard member of a type.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to which the new member is added. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="Type"> <maml:name>MemberType</maml:name> <maml:description> <maml:para>Specifies the type of the member to add. This parameter is mandatory.</maml:para> <maml:para>The valid values for this parameter are: "NoteProperty,AliasProperty,ScriptProperty,CodeProperty,ScriptMethod,CodeMethod" AliasProperty, CodeMethod, CodeProperty, Noteproperty, ScriptMethod, and ScriptProperty.</maml:para> <maml:para>For information about these values, see "PSMemberTypes Enumeration" in MSDN at <maml:navigationLink><maml:linkText>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.psmembertypes(v=vs.85).aspx</maml:linkText><maml:uri></maml:uri></maml:navigationLink>. </maml:para> <maml:para>Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns an error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSMemberTypes</command:parameterValue> <dev:type> <maml:name>PSMemberTypes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the member to be added.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the newly extended object. By default, this cmdlet does not generate any output.</maml:para> <maml:para>For most objects, Add-Member adds the new members to the input object. However, when the input object is a string, Add-Member cannot add the member to the input object. For these objects, use the PassThru parameter to create an output object.</maml:para> <maml:para>In Windows PowerShell 2.0, Add-Member added members only to the PSObject wrapper of objects, not to the object. Use the PassThru parameter to create an output object for any object that has a PSObject wrapper.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>SecondValue</maml:name> <maml:description> <maml:para>Specifies optional additional information about AliasProperty, ScriptProperty, CodeProperty, or CodeMethod members. If used when adding an AliasProperty, this parameter must be a data type. A conversion (cast) to the specified data type is added to the value of the AliasProperty. For example, if you add an AliasProperty that provides an alternate name for a string property, you can also specify a SecondValue parameter of System.Int32 to indicate that the value of that string property should be converted to an integer when accessed by using the corresponding AliasProperty.</maml:para> <maml:para>You can use the SecondValue parameter to specify an additional ScriptBlock when adding a ScriptProperty member. In that case, the first ScriptBlock, specified in the Value parameter, is used to get the value of a variable. The second ScriptBlock, specified in the SecondValue parameter, is used to set the value of a variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the initial value of the added member. If you add an AliasProperty, CodeProperty, ScriptProperty or CodeMethod member, you can supply optional, additional information by using the SecondValue parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>NotePropertyMembers</maml:name> <maml:description> <maml:para>Specifies a hash table or ordered dictionary of note property names and values. Type a hash table or dictionary in which the keys are note property names and the values are note property values.</maml:para> <maml:para>For more information about hash tables and ordered dictionaries in Windows PowerShell, see about_Hash_Tables (http://go.microsoft.com/fwlink/?LinkID=135175).</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>NotePropertyName</maml:name> <maml:description> <maml:para>Adds a note property with the specified name.</maml:para> <maml:para>Use this parameter with the NotePropertyValue parameter. The parameter name (-NotePropertyName) is optional.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>NotePropertyValue</maml:name> <maml:description> <maml:para>Adds a note property with the specified value.</maml:para> <maml:para>Use this parameter with the NotePropertyName parameter. The parameter name (-NotePropertyValue) is optional.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies a name for the type.</maml:para> <maml:para>When the type is a class in the System namespace or a type that has a type accelerator, you can enter the short name of the type. Otherwise, the full type name is required. This parameter is effective only when the input object is a PSObject.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object type to Add-Member.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Add-Member returns the newly-extended object. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can add members only to PSObject objects. To determine whether an object is a PSObject object, use the "is" operator. For example, to test an object stored in the $obj variable, type "$obj -is [PSObject]".</maml:para> <maml:para>The names of the MemberType, Name, Value, and SecondValue parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: MemberType, Name, Value, SecondValue. If you include the parameter names, the parameters can appear in any order.</maml:para> <maml:para>You can use the $this automatic variable in script blocks that define the values of new properties and methods. The $this variable refers to the instance of the object to which the properties and methods are being added. For more information about the $this variable, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = dir c:\ps-test\test.txt PS C:\>$a | Add-Member -NotePropertyName Status -NotePropertyValue Done PS C:\>$a | Add-Member Status Done PS C:\>$a.Status Done </dev:code> <dev:remarks> <maml:para>These commands add the Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file.</maml:para> <maml:para>The first command uses the Get-ChildItem cmdlet (alias = "dir) to get the Test.txt file. It saves it in the $a variable.</maml:para> <maml:para>The second and third commands add the note property to the object in $a. The third command omits the optional parameter names, so the parameter values must be in the correct Name-Value order. These commands are equivalent and can be used interchangeably.</maml:para> <maml:para>The fourth command uses dot notation to get the value of the Status property of the object in $a. As the output shows, the value is "Done".</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = dir c:\ps-test\test.txt PS C:\>$a | Add-Member -MemberType AliasProperty -Name FileLength -Value Length PS C:\>$a.FileLength 2394 </dev:code> <dev:remarks> <maml:para>These commands add the FileLength alias property to the object that represents the Test.txt file. The new property is an alias for the Length property.</maml:para> <maml:para>The first command use the Get-ChildItem cmdlet (alias = "dir") to get the Test.txt file.</maml:para> <maml:para>The second command adds the FileLength alias property.</maml:para> <maml:para>The third command uses dot notation to get the value of the new FileLength property.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = "A string" PS C:\>$a = $a | Add-Member @{StringUse="Display"} -PassThru PS C:\>$a.StringUse Display </dev:code> <dev:remarks> <maml:para>These commands add the StringUse note property to a string. Because Add-Member cannot add types to String input objects, the command uses the PassThru parameter to generate an output object. The last command in the example displays the new property.</maml:para> <maml:para>The command uses the NotePropertyMembers parameter, but omits the parameter name, which is optional. The value of the NotePropertyMembers parameter is a hash table. The key is the note property name, StringUse, and the value is the note property value, Display.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = "This is a string." PS C:\>$a = Add-Member -InputObject $a -MemberType ScriptMethod -Name PadBoth -Value {$p = $this.PadLeft($this.Length + 1); $p.PadRight($p.Length + 1)} -PassThru PS C:\>$a.Padboth() This is a string. </dev:code> <dev:remarks> <maml:para>These commands add the PadBoth script method to a string object.</maml:para> <maml:para>The first command creates a string and saves it in the $a variable.</maml:para> <maml:para>The second command adds the Padboth script method to the object in the $a variable. The Value parameter defines the new script method. It uses the PadRight and PadLeft methods of a string to add one space the left and one space to the right of the string.</maml:para> <maml:para>The Value parameter also uses the $this automatic variable, which represents the current object. The $this variable is valid only in script blocks that define new properties and methods.</maml:para> <maml:para>The command includes the PassThru parameter which directs Add-Member to return an instance of the object that includes the new script property. By default, Add-Member adds members to PSObjects and does not generate any output.</maml:para> <maml:para>The third command uses dot notation to call the new PadBoth script method on the object in the $a variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> PS C:\>$event = Get-EventLog -LogName System -Newest 1 PS C:\>$event.TimeWritten | Get-Member TypeName: System.DateTime Name MemberType Definition ---- ---------- ---------- Add Method System.DateTime Add(System.TimeSpan value) AddDays Method System.DateTime AddDays(double value) AddHours Method System.DateTime AddHours(double value) AddMilliseconds Method System.DateTime AddMilliseconds(double value) AddMinutes Method System.DateTime AddMinutes(double value)... PS C:\>Add-Member -InputObject $event -MemberType AliasProperty -Name When -Value TimeWritten -SecondValue System.String PS C:\>$event.When | Get-Member TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() CompareTo Method int CompareTo(System.Object value), int CompareTo(string strB) Contains Method bool Contains(string value) </dev:code> <dev:remarks> <maml:para>These commands add the "When" alias property to an event in the System event log. The event is an EventLogEntry object that is returned by the Get-EventLog cmdlet.</maml:para> <maml:para>The "When" alias property is an alias for the TimeWritten property of the object. The SecondValue parameter is used to specify that the property value should be converted to type System.String when accessed by using the AliasProperty. The TimeWritten property is a DateTime object.</maml:para> <maml:para>The first command uses the Get-EventLog cmdlet to get the newest event in the System event log. It stores the event in the $Event variable.</maml:para> <maml:para>To demonstrate that the TimeWritten property is a DateTime type, the second command uses dot notation to get the TimeWritten property of that event and pipes it to the Get-Member cmdlet.</maml:para> <maml:para>The third command uses the Add-Member cmdlet to add the When alias property to the object instance in the $Event variable. The Name parameter assigns the name, "When," and the Value parameter specifies that When is an alias for the TimeWritten property. The SecondValue parameter indicates that the value that the When method returns should be cast to a System.String type.</maml:para> <maml:para>The fourth command uses dot notation to call the new When method. The command pipes the method value to the Get-Member cmdlet to confirm that it has returned a string.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>function Copy-Property ($From, $To) { foreach ($p in Get-Member -InputObject $From -MemberType Property) { Add-Member -InputObject $To -MemberType NoteProperty -Name $p.Name -Value $From.$($p.Name) �Force $To.$($p.Name) = $From.$($p.Name) } } </dev:code> <dev:remarks> <maml:para>This function copies all of the properties of one object to another object.</maml:para> <maml:para>The first command in the function declares the function name and lists its parameters.</maml:para> <maml:para>The Foreach loop uses the Get-Member cmdlet to get each of the properties of the From object. The commands within the ForEach loop are performed in series on each of the properties.</maml:para> <maml:para>The Add-Member command adds the property of the From object to the To object as a NoteProperty. It uses the Force parameter add members with the same member name.</maml:para> <maml:para>The last command in the function gives the new property the same name as the original property.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 7</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$Asset = New-Object -TypeName PSObject PS C:\>$d = [ordered]@{Name="Server30";System="Server Core";PSVersion="4.0"} PS C:\>$Asset | Add-Member -NotePropertyMembers $d -TypeName Asset PS C:\>$Asset | Get-Member TypeName: Asset Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) GetHashCode Method int GetHashCode() GetType Method type GetType() ToString Method string ToString() Name NoteProperty System.String Name=Server30 PSVersion NoteProperty System.String PSVersion=4.0 System NoteProperty System.String System=Server Core </dev:code> <dev:remarks> <maml:para>This example creates the Asset custom object.</maml:para> <maml:para>The first command uses the New-Object cmdlet to create a PSObject. The command saves the PSObject in the $Asset variable.</maml:para> <maml:para>The second command uses the [ordered] type accelerator to create an ordered dictionary of names and values. The command saves the result in the $d variable.</maml:para> <maml:para>The third command uses the NotePropertyMembers parameter of the Add-Member cmdlet to add the dictionary in the $d variable to the PSObject. It uses the TypeName property to assign a new name, Asset, to the PSObject.</maml:para> <maml:para>The fourth command sends the new Asset object in the $Asset variable to the Get-Member cmdlet. The output shows that the object has a type name of "Asset" and the note properties that we defined in the ordered dictionary.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293942</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Clixml</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Member</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Clixml</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Automatic_Variables</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Add-Type</command:name> <maml:description> <maml:para>Adds a Microsoft .NET Framework type (a class) to a Windows PowerShell session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Add</command:verb> <command:noun>Type</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Add-Type cmdlet lets you define a .NET Framework class in your Windows PowerShell session. You can then instantiate objects (by using the New-Object cmdlet) and use the objects, just as you would use any .NET Framework object. If you add an Add-Type command to your Windows PowerShell profile, the class is available in all Windows PowerShell sessions.</maml:para> <maml:para>You can specify the type by specifying an existing assembly or source code files, or you can specify the source code inline or saved in a variable. You can even specify only a method and Add-Type will define and generate the class. You can use this feature to make Platform Invoke (P/Invoke) calls to unmanaged functions in Windows PowerShell. If you specify source code, Add-Type compiles the specified source code and generates an in-memory assembly that contains the new .NET Framework types.</maml:para> <maml:para>You can use the parameters of Add-Type to specify an alternate language and compiler (CSharp is the default), compiler options, assembly dependencies, the class namespace, the names of the type, and the resulting assembly.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Add-Type</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>TypeDefinition</maml:name> <maml:description> <maml:para>Specifies the source code that contains the type definitions. Enter the source code in a string or here-string, or enter a variable that contains the source code. For more information about here-strings, see about_Quoting_Rules (http://go.microsoft.com/fwlink/?LinkID=113253).</maml:para> <maml:para>Include a namespace declaration in your type definition. If you omit the namespace declaration, your type might have the same name as another type or the shortcut for another type, causing an unintentional overwrite. For example, if you define a type called "Exception", scripts that use "Exception" as the shortcut for System.Exception will fail.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Provider"> <maml:name>CodeDomProvider</maml:name> <maml:description> <maml:para>Specifies a code generator or compiler. Add-Type uses the specified compiler to compile the source code. The default is the CSharp compiler. Use this parameter if you are using a language that cannot be specified by using the Language parameter. The CodeDomProvider that you specify must be able to generate assemblies from source code.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CodeDomProvider</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="CP"> <maml:name>CompilerParameters</maml:name> <maml:description> <maml:para>Specifies the options for the source code compiler. These options are sent to the compiler without revision.</maml:para> <maml:para>This parameter allows you to direct the compiler to generate an executable file, embed resources, or set command-line options, such as the "/unsafe" option. This parameter implements the CompilerParameters class (System.CodeDom.Compiler.CompilerParameters).</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CompilerParameters</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWarnings</maml:name> <maml:description> <maml:para>Ignores compiler warnings. Use this parameter to prevent Add-Type from handling compiler warnings as errors.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Language</maml:name> <maml:description> <maml:para>Specifies the language that is used in the source code. The Add-Type cmdlet uses the value of this parameter to select the appropriate CodeDomProvider. Valid values are "CSharp", "CSharpVersion3", "VisualBasic", and "JScript". "CSharp" is the default value.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">CSharp</command:parameterValue> <command:parameterValue required="false" variableLength="false">CSharpVersion2</command:parameterValue> <command:parameterValue required="false" variableLength="false">CSharpVersion3</command:parameterValue> <command:parameterValue required="false" variableLength="false">JScript</command:parameterValue> <command:parameterValue required="false" variableLength="false">VisualBasic</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OA"> <maml:name>OutputAssembly</maml:name> <maml:description> <maml:para>Generates a DLL file for the assembly with the specified name in the location. Enter a path (optional) and file name. Wildcard characters are permitted. By default, Add-Type generates the assembly only in memory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OT"> <maml:name>OutputType</maml:name> <maml:description> <maml:para>Specifies the output type of the output assembly. Valid values are Library, ConsoleApplication, and WindowsApplication. For more information about the values, see "OutputAssemblyType Enumeration" in MSDN.</maml:para> <maml:para>By default, no output type is specified.</maml:para> <maml:para>This parameter is valid only when an output assembly is specified in the command.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">ConsoleApplication</command:parameterValue> <command:parameterValue required="false" variableLength="false">Library</command:parameterValue> <command:parameterValue required="false" variableLength="false">WindowsApplication</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns a System.Runtime object that represents the types that were added. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="RA"> <maml:name>ReferencedAssemblies</maml:name> <maml:description> <maml:para>Specifies the assemblies upon which the type depends. By default, Add-Type references System.dll and System.Management.Automation.dll. The assemblies that you specify by using this parameter are referenced in addition to the default assemblies.</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Type</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWarnings</maml:name> <maml:description> <maml:para>Ignores compiler warnings. Use this parameter to prevent Add-Type from handling compiler warnings as errors.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns a System.Runtime object that represents the types that were added. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="AN"> <maml:name>AssemblyName</maml:name> <maml:description> <maml:para>Specifies the name of an assembly that includes the types. Add-Type takes the types from the specified assembly. This parameter is required when you are creating types based on an assembly name.</maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Type</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the class to create. This parameter is required when generating a type from a member definition.</maml:para> <maml:para>The type name and namespace must be unique within a session. You cannot unload a type or change it. If you need to change the code for a type, you must change the name or start a new Windows PowerShell session. Otherwise, the command fails.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>MemberDefinition</maml:name> <maml:description> <maml:para>Specifies new properties or methods for the class. Add-Type generates the template code that is required to support the properties or methods.</maml:para> <maml:para>You can use this feature to make Platform Invoke (P/Invoke) calls to unmanaged functions in Windows PowerShell. For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Provider"> <maml:name>CodeDomProvider</maml:name> <maml:description> <maml:para>Specifies a code generator or compiler. Add-Type uses the specified compiler to compile the source code. The default is the CSharp compiler. Use this parameter if you are using a language that cannot be specified by using the Language parameter. The CodeDomProvider that you specify must be able to generate assemblies from source code.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CodeDomProvider</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="CP"> <maml:name>CompilerParameters</maml:name> <maml:description> <maml:para>Specifies the options for the source code compiler. These options are sent to the compiler without revision.</maml:para> <maml:para>This parameter allows you to direct the compiler to generate an executable file, embed resources, or set command-line options, such as the "/unsafe" option. This parameter implements the CompilerParameters class (System.CodeDom.Compiler.CompilerParameters).</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CompilerParameters</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWarnings</maml:name> <maml:description> <maml:para>Ignores compiler warnings. Use this parameter to prevent Add-Type from handling compiler warnings as errors.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Language</maml:name> <maml:description> <maml:para>Specifies the language that is used in the source code. The Add-Type cmdlet uses the value of this parameter to select the appropriate CodeDomProvider. Valid values are "CSharp", "CSharpVersion3", "VisualBasic", and "JScript". "CSharp" is the default value.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">CSharp</command:parameterValue> <command:parameterValue required="false" variableLength="false">CSharpVersion2</command:parameterValue> <command:parameterValue required="false" variableLength="false">CSharpVersion3</command:parameterValue> <command:parameterValue required="false" variableLength="false">JScript</command:parameterValue> <command:parameterValue required="false" variableLength="false">VisualBasic</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NS"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a namespace for the type.</maml:para> <maml:para>If this parameter is not included in the command, the type is created in the Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes namespace. If the parameter is included in the command with an empty string value or a value of $null, the type is generated in the global namespace.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OA"> <maml:name>OutputAssembly</maml:name> <maml:description> <maml:para>Generates a DLL file for the assembly with the specified name in the location. Enter a path (optional) and file name. Wildcard characters are permitted. By default, Add-Type generates the assembly only in memory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OT"> <maml:name>OutputType</maml:name> <maml:description> <maml:para>Specifies the output type of the output assembly. Valid values are Library, ConsoleApplication, and WindowsApplication. For more information about the values, see "OutputAssemblyType Enumeration" in MSDN.</maml:para> <maml:para>By default, no output type is specified.</maml:para> <maml:para>This parameter is valid only when an output assembly is specified in the command.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">ConsoleApplication</command:parameterValue> <command:parameterValue required="false" variableLength="false">Library</command:parameterValue> <command:parameterValue required="false" variableLength="false">WindowsApplication</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns a System.Runtime object that represents the types that were added. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="RA"> <maml:name>ReferencedAssemblies</maml:name> <maml:description> <maml:para>Specifies the assemblies upon which the type depends. By default, Add-Type references System.dll and System.Management.Automation.dll. The assemblies that you specify by using this parameter are referenced in addition to the default assemblies.</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Using"> <maml:name>UsingNamespace</maml:name> <maml:description> <maml:para>Specifies other namespaces that are required for the class. This is much like the Using keyword in C#.</maml:para> <maml:para>By default, Add-Type references the System namespace. When the MemberDefinition parameter is used, Add-Type also references the System.Runtime.InteropServices namespace by default. The namespaces that you add by using the UsingNamespace parameter are referenced in addition to the default namespaces.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Type</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="CP"> <maml:name>CompilerParameters</maml:name> <maml:description> <maml:para>Specifies the options for the source code compiler. These options are sent to the compiler without revision.</maml:para> <maml:para>This parameter allows you to direct the compiler to generate an executable file, embed resources, or set command-line options, such as the "/unsafe" option. This parameter implements the CompilerParameters class (System.CodeDom.Compiler.CompilerParameters).</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CompilerParameters</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWarnings</maml:name> <maml:description> <maml:para>Ignores compiler warnings. Use this parameter to prevent Add-Type from handling compiler warnings as errors.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OA"> <maml:name>OutputAssembly</maml:name> <maml:description> <maml:para>Generates a DLL file for the assembly with the specified name in the location. Enter a path (optional) and file name. Wildcard characters are permitted. By default, Add-Type generates the assembly only in memory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OT"> <maml:name>OutputType</maml:name> <maml:description> <maml:para>Specifies the output type of the output assembly. Valid values are Library, ConsoleApplication, and WindowsApplication. For more information about the values, see "OutputAssemblyType Enumeration" in MSDN.</maml:para> <maml:para>By default, no output type is specified.</maml:para> <maml:para>This parameter is valid only when an output assembly is specified in the command.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">ConsoleApplication</command:parameterValue> <command:parameterValue required="false" variableLength="false">Library</command:parameterValue> <command:parameterValue required="false" variableLength="false">WindowsApplication</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns a System.Runtime object that represents the types that were added. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="RA"> <maml:name>ReferencedAssemblies</maml:name> <maml:description> <maml:para>Specifies the assemblies upon which the type depends. By default, Add-Type references System.dll and System.Management.Automation.dll. The assemblies that you specify by using this parameter are referenced in addition to the default assemblies.</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to source code files or assembly DLL files that contain the types. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Add-Type</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to source code files or assembly DLL files that contain the types.</maml:para> <maml:para>If you submit source code files, Add-Type compiles the code in the files and creates an in-memory assembly of the types. The file name extension specified in the value of Path determines the compiler that Add-Type uses.</maml:para> <maml:para>If you submit an assembly file, Add-Type takes the types from the assembly. To specify an in-memory assembly or the global assembly cache, use the AssemblyName parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="CP"> <maml:name>CompilerParameters</maml:name> <maml:description> <maml:para>Specifies the options for the source code compiler. These options are sent to the compiler without revision.</maml:para> <maml:para>This parameter allows you to direct the compiler to generate an executable file, embed resources, or set command-line options, such as the "/unsafe" option. This parameter implements the CompilerParameters class (System.CodeDom.Compiler.CompilerParameters).</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CompilerParameters</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWarnings</maml:name> <maml:description> <maml:para>Ignores compiler warnings. Use this parameter to prevent Add-Type from handling compiler warnings as errors.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OA"> <maml:name>OutputAssembly</maml:name> <maml:description> <maml:para>Generates a DLL file for the assembly with the specified name in the location. Enter a path (optional) and file name. Wildcard characters are permitted. By default, Add-Type generates the assembly only in memory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OT"> <maml:name>OutputType</maml:name> <maml:description> <maml:para>Specifies the output type of the output assembly. Valid values are Library, ConsoleApplication, and WindowsApplication. For more information about the values, see "OutputAssemblyType Enumeration" in MSDN.</maml:para> <maml:para>By default, no output type is specified.</maml:para> <maml:para>This parameter is valid only when an output assembly is specified in the command.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">ConsoleApplication</command:parameterValue> <command:parameterValue required="false" variableLength="false">Library</command:parameterValue> <command:parameterValue required="false" variableLength="false">WindowsApplication</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns a System.Runtime object that represents the types that were added. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="RA"> <maml:name>ReferencedAssemblies</maml:name> <maml:description> <maml:para>Specifies the assemblies upon which the type depends. By default, Add-Type references System.dll and System.Management.Automation.dll. The assemblies that you specify by using this parameter are referenced in addition to the default assemblies.</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="AN"> <maml:name>AssemblyName</maml:name> <maml:description> <maml:para>Specifies the name of an assembly that includes the types. Add-Type takes the types from the specified assembly. This parameter is required when you are creating types based on an assembly name.</maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Provider"> <maml:name>CodeDomProvider</maml:name> <maml:description> <maml:para>Specifies a code generator or compiler. Add-Type uses the specified compiler to compile the source code. The default is the CSharp compiler. Use this parameter if you are using a language that cannot be specified by using the Language parameter. The CodeDomProvider that you specify must be able to generate assemblies from source code.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CodeDomProvider</command:parameterValue> <dev:type> <maml:name>CodeDomProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="CP"> <maml:name>CompilerParameters</maml:name> <maml:description> <maml:para>Specifies the options for the source code compiler. These options are sent to the compiler without revision.</maml:para> <maml:para>This parameter allows you to direct the compiler to generate an executable file, embed resources, or set command-line options, such as the "/unsafe" option. This parameter implements the CompilerParameters class (System.CodeDom.Compiler.CompilerParameters).</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CompilerParameters</command:parameterValue> <dev:type> <maml:name>CompilerParameters</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWarnings</maml:name> <maml:description> <maml:para>Ignores compiler warnings. Use this parameter to prevent Add-Type from handling compiler warnings as errors.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the full or simple name (also known as the "partial name") of an assembly. Wildcard characters are permitted in the assembly name. If you enter a simple or partial name, Add-Type resolves it to the full name, and then uses the full name to load the assembly.</maml:para> <maml:para>This parameter does not accept a path or file name. To enter the path to the assembly dynamic-link library (DLL) file, use the Path parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Language</maml:name> <maml:description> <maml:para>Specifies the language that is used in the source code. The Add-Type cmdlet uses the value of this parameter to select the appropriate CodeDomProvider. Valid values are "CSharp", "CSharpVersion3", "VisualBasic", and "JScript". "CSharp" is the default value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Language</command:parameterValue> <dev:type> <maml:name>Language</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to source code files or assembly DLL files that contain the types. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>MemberDefinition</maml:name> <maml:description> <maml:para>Specifies new properties or methods for the class. Add-Type generates the template code that is required to support the properties or methods.</maml:para> <maml:para>You can use this feature to make Platform Invoke (P/Invoke) calls to unmanaged functions in Windows PowerShell. For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the class to create. This parameter is required when generating a type from a member definition.</maml:para> <maml:para>The type name and namespace must be unique within a session. You cannot unload a type or change it. If you need to change the code for a type, you must change the name or start a new Windows PowerShell session. Otherwise, the command fails.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NS"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a namespace for the type.</maml:para> <maml:para>If this parameter is not included in the command, the type is created in the Microsoft.PowerShell.Commands.AddType.AutoGeneratedTypes namespace. If the parameter is included in the command with an empty string value or a value of $null, the type is generated in the global namespace.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OA"> <maml:name>OutputAssembly</maml:name> <maml:description> <maml:para>Generates a DLL file for the assembly with the specified name in the location. Enter a path (optional) and file name. Wildcard characters are permitted. By default, Add-Type generates the assembly only in memory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="OT"> <maml:name>OutputType</maml:name> <maml:description> <maml:para>Specifies the output type of the output assembly. Valid values are Library, ConsoleApplication, and WindowsApplication. For more information about the values, see "OutputAssemblyType Enumeration" in MSDN.</maml:para> <maml:para>By default, no output type is specified.</maml:para> <maml:para>This parameter is valid only when an output assembly is specified in the command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">OutputAssemblyType</command:parameterValue> <dev:type> <maml:name>OutputAssemblyType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns a System.Runtime object that represents the types that were added. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to source code files or assembly DLL files that contain the types.</maml:para> <maml:para>If you submit source code files, Add-Type compiles the code in the files and creates an in-memory assembly of the types. The file name extension specified in the value of Path determines the compiler that Add-Type uses.</maml:para> <maml:para>If you submit an assembly file, Add-Type takes the types from the assembly. To specify an in-memory assembly or the global assembly cache, use the AssemblyName parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="RA"> <maml:name>ReferencedAssemblies</maml:name> <maml:description> <maml:para>Specifies the assemblies upon which the type depends. By default, Add-Type references System.dll and System.Management.Automation.dll. The assemblies that you specify by using this parameter are referenced in addition to the default assemblies.</maml:para> <maml:para>You cannot use the CompilerParameters and ReferencedAssemblies parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>TypeDefinition</maml:name> <maml:description> <maml:para>Specifies the source code that contains the type definitions. Enter the source code in a string or here-string, or enter a variable that contains the source code. For more information about here-strings, see about_Quoting_Rules (http://go.microsoft.com/fwlink/?LinkID=113253).</maml:para> <maml:para>Include a namespace declaration in your type definition. If you omit the namespace declaration, your type might have the same name as another type or the shortcut for another type, causing an unintentional overwrite. For example, if you define a type called "Exception", scripts that use "Exception" as the shortcut for System.Exception will fail.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Using"> <maml:name>UsingNamespace</maml:name> <maml:description> <maml:para>Specifies other namespaces that are required for the class. This is much like the Using keyword in C#.</maml:para> <maml:para>By default, Add-Type references the System namespace. When the MemberDefinition parameter is used, Add-Type also references the System.Runtime.InteropServices namespace by default. The namespaces that you add by using the UsingNamespace parameter are referenced in addition to the default namespaces.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to Add-Type.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Type</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Add-Type returns a System.Type object that represents the new type. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The types that you add exist only in the current session. To use the types in all sessions, add them to your Windows PowerShell profile. For more information about the profile, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729).</maml:para> <maml:para>Type names (and namespaces) must be unique within a session. You cannot unload a type or change it. If you need to change the code for a type, you must change the name or start a new Windows PowerShell session. Otherwise, the command fails.</maml:para> <maml:para>The CodeDomProvider class for some languages, such as IronPython and JSharp, does not generate output. As a result, types written in these languages cannot be used with Add-Type.</maml:para> <maml:para>This cmdlet is based on the CodeDomProvider class. For more information about this class, see the Microsoft .NET Framework SDK.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$source = @" public class BasicTest { public static int Add(int a, int b) { return (a + b); } public int Multiply(int a, int b) { return (a * b); } } "@ PS C:\>Add-Type -TypeDefinition $source PS C:\>[BasicTest]::Add(4, 3) PS C:\>$basicTestObject = New-Object BasicTest PS C:\>$basicTestObject.Multiply(5, 2) </dev:code> <dev:remarks> <maml:para>These commands add the BasicTest class to the session by specifying source code that is stored in a variable. The type has a static method called Add and a non-static method called Multiply.</maml:para> <maml:para>The first command stores the source code for the class in the $source variable.</maml:para> <maml:para>The second command uses the Add-Type cmdlet to add the class to the session. Because it is using inline source code, the command uses the TypeDefinition parameter to specify the code in the $source variable.</maml:para> <maml:para>The remaining commands use the new class.</maml:para> <maml:para>The third command calls the Add static method of the BasicTest class. It uses the double-colon characters (::) to specify a static member of the class.</maml:para> <maml:para>The fourth command uses the New-Object cmdlet to instantiate an instance of the BasicTest class. It saves the new object in the $basicTestObject variable.</maml:para> <maml:para>The fifth command uses the Multiply method of $basicTestObject.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>[BasicTest] | Get-Member PS C:\>[BasicTest] | Get-Member -Static PS C:\>$basicTestObject | Get-Member PS C:\>[BasicTest] | Get-Member TypeName: System.RuntimeType Name MemberType Definition ---- ---------- ---------- Clone Method System.ObjectClone( Equals Method System.BooleanEquals FindInterfaces Method System.Type[] FindInt... PS C:\>[BasicTest] | Get-Member -static TypeName: BasicTest Name MemberType Definition ---- ---------- ---------- Add Method static System.Int32 Add(Int32 a, Int32 b) Equals Method static System.Boolean Equals(Object objA, ReferenceEquals Method static System.Boolean ReferenceEquals(Obj PS C:\>$basicTestObject | Get-Member TypeName: BasicTest Name MemberType Definition ---- ---------- ---------- Equals Method System.Boolean Equals(Object obj) GetHashCode Method System.Int32 GetHashCode() GetType Method System.Type GetType() Multiply Method System.Int32 Multiply(Int32 a, Int32 b) ToString Method System.String ToString() </dev:code> <dev:remarks> <maml:para>These commands use the Get-Member cmdlet to examine the objects that the Add-Type and New-Object cmdlets created in the previous example.</maml:para> <maml:para>The first command uses the Get-Member cmdlet to get the type and members of the BasicTest class that Add-Type added to the session. The Get-Member command reveals that it is a System.RuntimeType object, which is derived from the System.Object class.</maml:para> <maml:para>The second command uses the Static parameter of the Get-Member cmdlet to get the static properties and methods of the BasicTest class. The output shows that the Add method is included.</maml:para> <maml:para>The third command uses the Get-Member cmdlet to get the members of the object stored in the $BasicTestObject variable. This was the object instance that was created by using the New-Object cmdlet with the $BasicType class.</maml:para> <maml:para>The output reveals that the value of the $BasicTestObject variable is an instance of the BasicTest class and that it includes a member called Multiply.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$accType = Add-Type -AssemblyName accessib* -PassThru </dev:code> <dev:remarks> <maml:para>This command adds the classes from the Accessibility assembly to the current session. The command uses the AssemblyName parameter to specify the name of the assembly. The wildcard character allows you to get the correct assembly even when you are not sure of the name or its spelling.</maml:para> <maml:para>The command uses the PassThru parameter to generate objects that represent the classes that are added to the session, and it saves the objects in the $accType variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Add-Type -Path c:\ps-test\Hello.vb[VBFromFile]::SayHello(", World") # From Hello.vb Public Class VBFromFilePublic Shared Function SayHello(sourceName As String) As StringDim myValue As String = "Hello"return myValue + sourceNameEnd FunctionEnd Class PS C:\>[VBFromFile]::SayHello(", World")Hello, World </dev:code> <dev:remarks> <maml:para>This example uses the Add-Type cmdlet to add the VBFromFile class that is defined in the Hello.vb file to the current session. The text of the Hello.vb file is shown in the command output.</maml:para> <maml:para>The first command uses the Add-Type cmdlet to add the type defined in the Hello.vb file to the current session. The command uses the Path parameter to specify the source file.</maml:para> <maml:para>The second command calls the SayHello function as a static method of the VBFromFile class.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$signature = @" [DllImport("user32.dll")]public static extern bool ShowWindowAsync(IntPtr hWnd, int nCmdShow); "@ $showWindowAsync = Add-Type -MemberDefinition $signature -Name "Win32ShowWindowAsync" -Namespace Win32Functions -PassThru # Minimize the Windows PowerShell console $showWindowAsync::ShowWindowAsync((Get-Process -Id $pid).MainWindowHandle, 2) # Restore it $showWindowAsync::ShowWindowAsync((Get-Process -Id $pid).MainWindowHandle, 4) </dev:code> <dev:remarks> <maml:para>The commands in this example demonstrate how to call native Windows APIs in Windows PowerShell. Add-Type uses the Platform Invoke (P/Invoke) mechanism to call a function in User32.dll from Windows PowerShell.</maml:para> <maml:para>The first command stores the C# signature of the ShowWindowAsync function in the $signature variable. (For more information, see "ShowWindowAsync Function" in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=143643.) To ensure that the resulting method will be visible in a Windows PowerShell session, the "public" keyword has been added to the standard signature.</maml:para> <maml:para>The second command uses the Add-Type cmdlet to add the ShowWindowAsync function to the Windows PowerShell session as a static method of a class that Add-Type creates. The command uses the MemberDefinition parameter to specify the method definition saved in the $signature variable.</maml:para> <maml:para>The command uses the Name and Namespace parameters to specify a name and namespace for the class. It uses the PassThru parameter to generate an object that represents the types, and it saves the object in the $showWindowAsync variable.</maml:para> <maml:para>The third and fourth commands use the new ShowWindowAsync static method. The method takes two parameters, the window handle, and an integer specifies how the window is to be shown.</maml:para> <maml:para>The third command calls ShowWindowAsync. It uses the Get-Process cmdlet with the $pid automatic variable to get the process that is hosting the current Windows PowerShell session. Then it uses the MainWindowHandle property of the current process and a value of "2", which represents the SW_MINIMIZE value.</maml:para> <maml:para>To restore the window, the fourth command use a value of "4" for the window position, which represents the SW_RESTORE value. (SW_MAXIMIZE is 3.)</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Add-Type -MemberDefinition $jsMethod -Name "PrintInfo" -Language JScript </dev:code> <dev:remarks> <maml:para>This command uses the Add-Type cmdlet to add a method from inline JScript code to the Windows PowerShell session. It uses the MemberDefinition parameter to submit source code stored in the $jsMethod variable. It uses the Name parameter to specify a name for the class that Add-Type creates for the method and the Language parameter to specify the JScript language.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Add-Type -Path FSharp.Compiler.CodeDom.dll PS C:\>Add-Type -Path FSharp.Compiler.CodeDom.dll PS C:\>$Provider = New-Object Microsoft.FSharp.Compiler.CodeDom.FSharpCodeProvider PS C:\>$fSharpCode = @" let rec loop n =if n <= 0 then () else beginprint_endline (string_of_int n);loop (n-1)end "@ PS C:\>$fsharpType = Add-Type -TypeDefinition $fSharpCode -CodeDomProvider $Provider -PassThru | where { $_.IsPublic } PS C:\>$fsharpType::loop(4)4321 </dev:code> <dev:remarks> <maml:para>This example shows how to use the Add-Type cmdlet to add an FSharp code compiler to your Windows PowerShell session. To run this example in Windows PowerShell, you must have the FSharp.Compiler.CodeDom.dll that is installed with the FSharp language.</maml:para> <maml:para>The first command in the example uses the Add-Type cmdlet with the Path parameter to specify an assembly. Add-Type gets the types in the assembly.</maml:para> <maml:para>The second command uses the New-Object cmdlet to create an instance of the FSharp code provider and saves the result in the $Provider variable.</maml:para> <maml:para>The third command saves the FSharp code that defines the Loop method in the $FSharpCode variable.</maml:para> <maml:para>The fourth command uses the Add-Type cmdlet to save the public types defined in $fSharpCode in the $fSharpType variable. The TypeDefinition parameter specifies the source code that defines the types. The CodeDomProvider parameter specifies the source code compiler.</maml:para> <maml:para>The PassThru parameter directs Add-Type to return a Runtime object that represents the types and a pipeline operator (|) sends the Runtime object to the Where-Object cmdlet, which returns only the public types. The Where-Object cmdlet is used because the FSharp provider generates non-public types to support the resulting public type.</maml:para> <maml:para>The fifth command calls the Loop method as a static method of the type stored in the $fSharpType variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293943</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Add-Member</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Clear-Variable</command:name> <maml:description> <maml:para>Deletes the value of a variable.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Clear</command:verb> <command:noun>Variable</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Clear-Variable cmdlet deletes the data stored in a variable, but it does not delete the variable. As a result, the value of the variable is NULL (empty). If the variable has a specified data or object type, Clear-Variable preserves the type of the object stored in the variable.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Clear-Variable</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the variable to be cleared. Wildcards are permitted. This parameter is required, but the parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to clear a variable even if it is read-only. Even using the Force parameter, the cmdlet cannot clear constants.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Clears only the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the cleared variable. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to clear a variable even if it is read-only. Even using the Force parameter, the cmdlet cannot clear constants.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Clears only the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the variable to be cleared. Wildcards are permitted. This parameter is required, but the parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the cleared variable. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to Clear-Variable.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.PSVariable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Clear-Variable generates a System.Management.Automation.PSVariable object representing the cleared variable. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>To delete a variable, along with its value, use Remove-Variable or Remove-Item.</maml:para> <maml:para>Clear-Variable will not delete the values of variables that are set as constants or owned by the system, even if you use the -Force parameter.</maml:para> <maml:para>If the variable that you are clearing does not exist, the cmdlet has no effect. It does not create a variable with a null value.</maml:para> <maml:para>You can also refer to Clear-Variable by its built-in alias, "clv". For more information, see about_Aliases.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Clear-Variable my* -Scope Global </dev:code> <dev:remarks> <maml:para>This command deletes the value of global variables that have names that begin with "my".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a=3 PS C:\>&{ Clear-Variable a } PS C:\>$a 3 </dev:code> <dev:remarks> <maml:para>These commands demonstrate that clearing a variable in a child scope does not clear the value in the parent scope. The first command sets the value of the variable $a to "3". The second command uses the invoke operator (&) to run a Clear-Variable command in a new scope. The variable is cleared in the child scope (although it did not exist), but it is not cleared in the local scope. The third command, which gets the value of $a, shows that the value "3" is unaffected.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Clear-variable -Name Processes </dev:code> <dev:remarks> <maml:para>This command deletes the value of the $processes variable. The $processes variable still exists, but the value is null.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293944</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Compare-Object</command:name> <maml:description> <maml:para>Compares two sets of objects.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Compare</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Compare-Object cmdlet compares two sets of objects. One set of objects is the "reference set," and the other set is the "difference set."</maml:para> <maml:para>The result of the comparison indicates whether a property value appeared only in the object from the reference set (indicated by the <= symbol), only in the object from the difference set (indicated by the => symbol) or, if the IncludeEqual parameter is specified, in both objects (indicated by the == symbol).</maml:para> <maml:para>NOTE: If the reference set or the difference set is null ($null), Compare-Object generates a terminating error.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Compare-Object</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ReferenceObject</maml:name> <maml:description> <maml:para>Objects used as a reference for comparison.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="2" aliases="none"> <maml:name>DifferenceObject</maml:name> <maml:description> <maml:para>Specifies the objects that are compared to the reference objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Indicates that comparisons should be case-sensitive.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Culture</maml:name> <maml:description> <maml:para>Specifies the culture to use for comparisons.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ExcludeDifferent</maml:name> <maml:description> <maml:para>Displays only the characteristics of compared objects that are equal.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IncludeEqual</maml:name> <maml:description> <maml:para>Displays characteristics of compared objects that are equal. By default, only characteristics that differ between the reference and difference objects are displayed.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Passes the objects that differed to the pipeline. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties of the reference and difference objects to compare.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SyncWindow</maml:name> <maml:description> <maml:para>Specifies the number of adjacent objects that Compare-Object inspects while looking for an match in a collection of objects. Compare-Object examines adjacent objects when it doesn't find the object in the same position in a collection. The default value is [Int32]::MaxValue, which means that Compare-Object examines the entire object collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Indicates that comparisons should be case-sensitive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Culture</maml:name> <maml:description> <maml:para>Specifies the culture to use for comparisons.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="2" aliases="none"> <maml:name>DifferenceObject</maml:name> <maml:description> <maml:para>Specifies the objects that are compared to the reference objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ExcludeDifferent</maml:name> <maml:description> <maml:para>Displays only the characteristics of compared objects that are equal.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IncludeEqual</maml:name> <maml:description> <maml:para>Displays characteristics of compared objects that are equal. By default, only characteristics that differ between the reference and difference objects are displayed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Passes the objects that differed to the pipeline. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties of the reference and difference objects to compare.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ReferenceObject</maml:name> <maml:description> <maml:para>Objects used as a reference for comparison.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SyncWindow</maml:name> <maml:description> <maml:para>Specifies the number of adjacent objects that Compare-Object inspects while looking for an match in a collection of objects. Compare-Object examines adjacent objects when it doesn't find the object in the same position in a collection. The default value is [Int32]::MaxValue, which means that Compare-Object examines the entire object collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a DifferenceObject object to Compare-Object.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None, or the objects that are different</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Compare-Object returns the objects that differed. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>compare-object -referenceobject $(get-content C:\test\testfile1.txt) -differenceobject $(get-content C:\test\testfile2.txt) </dev:code> <dev:remarks> <maml:para>This command compares the contents of two text files. It displays only the lines that appear in one file or in the other file, not lines that appear in both files.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>compare-object -referenceobject $(get-content C:\Test\testfile1.txt) -differenceobject $(get-content C:\Test\testfile2.txt) -includeequal </dev:code> <dev:remarks> <maml:para>This command compares each line of content in two text files. It displays all lines of content from both files, indicating whether each line appears in only Textfile1.txt or Textfile2.txt or whether each line appears in both files.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$processes_before = get-process PS C:\>notepad PS C:\>$processes_after = get-process PS C:\>compare-object -referenceobject $processes_before -differenceobject $processes_after </dev:code> <dev:remarks> <maml:para>These commands compare two sets of process objects.</maml:para> <maml:para>The first command uses the Get-Process cmdlet to get the processes on the computer. It stores them in the $processes_before variable.</maml:para> <maml:para>The second command starts Notepad.</maml:para> <maml:para>The third command uses the Get-Process cmdlet again and stores the resulting processes in the $processes_after variable.</maml:para> <maml:para>The fourth command uses the Compare-Object cmdlet to compare the two sets of process objects. It displaysthe differences between them, which include the new instance of Notepad.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293945</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ForEach-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Group-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Measure-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Sort-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Tee-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Where-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-Csv</command:name> <maml:description> <maml:para>Converts object properties in comma-separated value (CSV) format into CSV versions of the original objects.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertFrom</command:verb> <command:noun>Csv</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertFrom-CSV cmdlet creates objects from CSV variable-length strings that are generated by the ConvertTo-CSV cmdlet.</maml:para> <maml:para>You can use the parameters of the ConvertFrom-CSV cmdlet to specify the column header row, which determines the property names of the resulting objects, to specify the item delimiter, or to direct ConvertFrom-CSV to use the list separator for the current culture as the delimiter.</maml:para> <maml:para>The objects that ConvertFrom-CSV creates are CSV versions of the original objects. The property values of the CSV objects are string versions of the property values of the original objects. The CSV versions of the objects do not have any methods.</maml:para> <maml:para>You can also use the Export-CSV and Import-CSV cmdlets to convert objects to CSV strings in a file (and back). These cmdlets are the same as the ConvertTo-CSV and ConvertFrom-CSV cmdlets, except that they save the CSV strings in a file.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-Csv</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the CSV strings to be converted to objects. Enter a variable that contains the CSV strings or type a command or expression that gets the CSV strings. You can also pipe the CSV strings to ConvertFrom-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies the delimiter that separates the property values in the CSV strings. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.</maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:description> <maml:para>Specifies an alternate column header row for the imported string. The column header determines the names of the properties of the object that ConvertFrom-CSV creates.</maml:para> <maml:para>Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no headers. If you enter more headers than there are columns, the extra headers are ignored.</maml:para> <maml:para>When using the Header parameter, omit the column header string from the CSV strings. Otherwise, ConvertFrom-CSV creates an extra object from the items in the header row.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertFrom-Csv</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the CSV strings to be converted to objects. Enter a variable that contains the CSV strings or type a command or expression that gets the CSV strings. You can also pipe the CSV strings to ConvertFrom-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:description> <maml:para>Specifies an alternate column header row for the imported string. The column header determines the names of the properties of the object that ConvertFrom-CSV creates.</maml:para> <maml:para>Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no headers. If you enter more headers than there are columns, the extra headers are ignored.</maml:para> <maml:para>When using the Header parameter, omit the column header string from the CSV strings. Otherwise, ConvertFrom-CSV creates an extra object from the items in the header row.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Use the list separator for the current culture as the string delimiter. The default is a comma (,).</maml:para> <maml:para>To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator. If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies the delimiter that separates the property values in the CSV strings. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.</maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> <dev:type> <maml:name>Char</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:description> <maml:para>Specifies an alternate column header row for the imported string. The column header determines the names of the properties of the object that ConvertFrom-CSV creates.</maml:para> <maml:para>Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no headers. If you enter more headers than there are columns, the extra headers are ignored.</maml:para> <maml:para>When using the Header parameter, omit the column header string from the CSV strings. Otherwise, ConvertFrom-CSV creates an extra object from the items in the header row.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the CSV strings to be converted to objects. Enter a variable that contains the CSV strings or type a command or expression that gets the CSV strings. You can also pipe the CSV strings to ConvertFrom-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Use the list separator for the current culture as the string delimiter. The default is a comma (,).</maml:para> <maml:para>To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator. If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe CSV strings to ConvertFrom-CSV.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>ConvertFrom-CSV returns the objects described by the properties in the CSV strings.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Because the imported objects are CSV versions of the object type, they are not recognized and formatted by the Windows PowerShell type formatting entries that format the non-CSV versions of the object type.</maml:para> <maml:para>In CSV format, each object is represented by a comma-separated list of the property values of the object. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. ConvertTo-Csv does not export the methods of the object.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$p = get-process | convertto-csv PS C:\>$p | convertfrom-csv </dev:code> <dev:remarks> <maml:para>These commands convert the processes on the local computer into CSV format and then restore them to object form.</maml:para> <maml:para>The first command uses the Get-Process cmdlet to get the processes on the local computer. A pipeline operator (|) sends them to the ConvertTo-CSV cmdlet, which converts the process object to CSV format. The CSV strings are saved in the $p variable.</maml:para> <maml:para>The second command uses a pipeline operator to send the CSV strings in the $p variable to the ConvertFrom-CSV cmdlet. The cmdlet converts the CSV strings into CSV versions of the original process objects.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$date = get-date | convertto-csv -delimiter ";" PS C:\>convertfrom-csv -inputobject $date -delimiter ";" </dev:code> <dev:remarks> <maml:para>These commands convert a data object to CSV format and then to CSV object format.</maml:para> <maml:para>The first command uses the Get-Date cmdlet to get the current date and time. A pipeline object (|) sends the date to the ConvertTo-CSV cmdlets, which converts the date object to a series of CSV strings. The command uses the Delimiter parameter to specify a semicolon delimiter. The strings are saved in the $date variable.</maml:para> <maml:para>The second command uses the ConvertFrom-CSV cmdlet to convert the CSV strings in the $date variable back to object format. The command uses the InputObject parameter to specify the CSV strings and the Delimiter parameter to specify the semicolon delimiter.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$j = start-job -scriptblock { get-process } | convertto-csv PS C:\>$header = "MoreData","StatusMessage","Location","Command","State","Finished","InstanceId","SessionId","Name","ChildJobs","Output","Error","Progress","Verbose","Debug","Warning","StateChanged" # Delete header from $j PS C:\>$j = $j[0], $j[2..($j.count - 1)] $j | convertfrom-csv -header $header MoreData : True StatusMessage : Location : localhost Command : get-process State : Running Finished : System.Threading.ManualResetEvent InstanceId : 6fcb6578-7f42-4d93-9f23-9937f6aac1a2 SessionId : 1 Name : Job1 ChildJobs : System.Collections.Generic.List`1[System.Management.Automation.Job] Output : System.Management.Automation.PSDataCollection`1[System.Management.Automation.PSObject] Error : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ErrorRecord] Progress : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ProgressRecord] Verbose : System.Management.Automation.PSDataCollection`1[System.String] Debug : System.Management.Automation.PSDataCollection`1[System.String] Warning : System.Management.Automation.PSDataCollection`1[System.String] StateChanged : </dev:code> <dev:remarks> <maml:para>This example shows how to use the Header parameter of ConvertFrom-Csv to change the names of properties in the resulting imported object.</maml:para> <maml:para>The first command uses the Start-Job cmdlet to start a background job that runs a Get-Process command on the local computer. A pipeline operator (|) sends the resulting job object to the ConvertTo-CSV cmdlet, which converts the job object to CSV format. An assignment operator (=) saves the resulting CSV in the $j variable.</maml:para> <maml:para>The second command saves a header in the $header variable. Unlike the default header, this header uses "MoreData" instead of "HasMoreData" and "State" instead of "JobStateInfo".</maml:para> <maml:para>The third command deletes the original header (the second line) from the CSV strings and returns it to the $j variable.</maml:para> <maml:para>The fourth command uses the ConvertFrom-CSV cmdlet to convert the CSV strings to a CSV version of the job object. The command uses a pipeline operator to send the content in $j to ConvertFrom-CSV. The resulting object has "MoreData" and "State" properties, as specified by the header.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-culture).textinfo.listseparator PS C:\>ConvertFrom-Csv -inputobject $services -UseCulture </dev:code> <dev:remarks> <maml:para>The command uses the ConvertFrom-CSV cmdlet to convert CSV strings of service objects that had been converted by the ConvertTo-CSV cmdlet. The command uses the UseCulture parameter to direct ConvertFrom-CSV to use the delimiter (list separator) of the current culture.</maml:para> <maml:para>When using the UseCulture parameter, be sure that the list separator of the current culture matches the delimiter used in the CSV strings. Otherwise, ConvertFrom-CSV cannot generate objects from the CSV strings.</maml:para> <maml:para>In this example, a Get-Culture command was used to verify the list separator, before the ConvertFrom-CSV command was used.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293946</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-Json</command:name> <maml:description> <maml:para>Converts a JSON-formatted string to a custom object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertFrom</command:verb> <command:noun>Json</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertFrom-Json cmdlet converts a JSON-formatted string to a custom object (PSCustomObject) that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects.</maml:para> <maml:para>To generate a JSON string from any object, use the ConvertTo-Json cmdlet.</maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-Json</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string, or type a command or expression that gets the string. You can also pipe a string to ConvertFrom-Json.</maml:para> <maml:para>The InputObject parameter is required, but its value can be an empty string. When the input object is an empty string, ConvertFrom-Json does not generate any output. The InputObject value cannot be null ($null).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The InputObject parameter is required, but its value can be an empty string. When the input object is an empty string, ConvertFrom-Json does not generate any output. The InputObject value cannot be null ($null).</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The InputObject parameter is required, but its value can be an empty string. When the input object is an empty string, ConvertFrom-Json does not generate any output. The InputObject value cannot be null ($null).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The InputObject parameter is required, but its value can be an empty string. When the input object is an empty string, ConvertFrom-Json does not generate any output. The InputObject value cannot be null ($null).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The InputObject parameter is required, but its value can be an empty string. When the input object is an empty string, ConvertFrom-Json does not generate any output. The InputObject value cannot be null ($null).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the JSON strings to convert to JSON objects. Enter a variable that contains the string, or type a command or expression that gets the string. You can also pipe a string to ConvertFrom-Json.</maml:para> <maml:para>The InputObject parameter is required, but its value can be an empty string. When the input object is an empty string, ConvertFrom-Json does not generate any output. The InputObject value cannot be null ($null).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri>http://msdn.microsoft.com/en-us/library/system.string.aspx</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a JSON string to ConvertFrom-Json.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSCustomObject</maml:name> <maml:uri>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.pscustomobject(v=vs.85).aspx</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The ConvertFrom-Json cmdlet is implemented by using the JavaScriptSerializer class (http://msdn.microsoft.com/en-us/library/system.web.script.serialization.javascriptserializer(VS.100).aspx).</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json DisplayHint : 2 DateTime : Friday, January 13, 2012 8:06:31 PM Date : 1/13/2012 8:00:00 AM Day : 13 DayOfWeek : 5 DayOfYear : 13 Hour : 20 Kind : 2 Millisecond : 400 Minute : 6 Month : 1 Second : 31 Ticks : 634620819914009002 TimeOfDay : @{Ticks=723914009002; Days=0; Hours=20; Milliseconds=400; Minutes=6; Seconds=31; TotalDays=0.83786343634490734; TotalHours=20.108722472277776; TotalMilliseconds=72391400.900200009; TotalMinutes=1206.5233483366667;TotalSeconds=72391.4009002} Year : 2012 </dev:code> <dev:remarks> <maml:para>This command uses the ConvertTo-Json and ConvertFrom-Json cmdlets to convert a DateTime object from the Get-Date cmdlet to a JSON object.</maml:para> <maml:para>The command uses the Select-Object cmdlet to get all of the properties of the DateTime object. It uses the ConvertTo-Json cmdlet to convert the DateTime object to a JSON-formatted string and the ConvertFrom-Json cmdlet to convert the JSON-formatted string to a JSON object..</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$j = Invoke-WebRequest -Uri http://search.twitter.com/search.json?q=PowerShell | ConvertFrom-Json </dev:code> <dev:remarks> <maml:para>This command uses the Invoke-WebRequest cmdlet to get JSON strings from a web service and then it uses the ConvertFrom-Json cmdlet to convert JSON content to objects that can be managed in Windows PowerShell.</maml:para> <maml:para>You can also use the Invoke-RestMethod cmdlet, which automatically converts JSON content to objects.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(Get-Content JsonFile.JSON) -join "`n" | ConvertFrom-Json </dev:code> <dev:remarks> <maml:para>This example shows how to use the ConvertFrom-Json cmdlet to convert a JSON file to a Windows PowerShell custom object.</maml:para> <maml:para>The command uses Get-Content cmdlet to get the strings in a JSON file. It uses the Join operator to join the strings in the file into a single string that is delimited by newline characters (`n). Then it uses the pipeline operator to send the delimited string to the ConvertFrom-Json cmdlet, which converts it to a custom object.</maml:para> <maml:para>The Join operator is required, because the ConvertFrom-Json cmdlet expects a single string.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293947</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Json</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-WebRequest</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-RestMethod</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-String</command:name> <maml:description> <maml:para>Extracts and parses structured objects from string content.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertFrom</command:verb> <command:noun>String</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>You can run the ConvertFrom-String cmdlet to add structure to unstructured string content. ConvertFrom-String generates an object by parsing text from a traditional text stream. For each string in the pipeline, the cmdlet splits the input by either a delimiter or a parse expression, and then assigns property names to each of the resulting split elements. You can provide these property names; if you do not, they are automatically generated for you. </maml:para> <maml:para>The cmdlet�s default parameter set, FromDelimiter, splits exactly on the regular expression delimiter. It does not perform quote matching or delimiter escaping as the Import-Csv cmdlet does. </maml:para> <maml:para>The cmdlet�s alternate parameter set, FromParseExpression, generates elements from the groups that are captured by a regular expression.</maml:para> <maml:para>This cmdlet supports two modes: basic delimited parsing, and automatically-generated, example-driven parsing.</maml:para> <maml:para>Delimited parsing, by default, splits the input at white space, and assigns property names to the resulting groups. You can customize the delimiter by piping the ConvertFrom-String results into one of the Format-* cmdlets, or by adding the Delimiter parameter.</maml:para> <maml:para>The cmdlet also supports automatically-generated, example-driven parsing based on the <maml:navigationLink><maml:linkText>FlashExtract</maml:linkText><maml:uri></maml:uri></maml:navigationLink> research work by <maml:navigationLink><maml:linkText>Microsoft Research</maml:linkText><maml:uri></maml:uri></maml:navigationLink>.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-String</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="DEL"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>A regular expression that identifies the boundary between elements. Elements that are created by the split become properties in the resulting object. The delimiter is ultimately used in a call to System.Text.RegularExpressions.RegularExpression.Split().</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PN"> <maml:name>PropertyNames</maml:name> <maml:description> <maml:para>One or more property names to which to assign split values in the resulting object. Every line of text that you split or parse generates elements that represent property values. If the element is the result of a capture group, and that capture group is named (for example, (?<name>) or (?'name') ), then the name of that capture group is assigned to the property.</maml:para> <maml:para>If you provide any elements in the PropertyName array, those names are assigned to properties that have not yet been named. </maml:para> <maml:para> </maml:para> <maml:para>If you provide more property names than there are fields, Windows PowerShell ignores the extra property names. If you do not specify enough property names to name all fields, Windows PowerShell automatically assigns numerical property names to any properties that are not named: P1, P2, etc.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies strings received from the pipeline, or a variable that contains a string object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertFrom-String</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TC"> <maml:name>TemplateContent</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TF"> <maml:name>TemplateFile</maml:name> <maml:description> <maml:para>Specifies a file that contains a template for the desired parsing of the string. In the template file, properties and their values are enclosed in brackets, as shown in the following example. If a property (such as the Name property in this example) (and its associated otherproperties) can appear multiple times, add an asterisk (*) to indicate that this results in multiple records (rather than extracting multiple properties into a single record.</maml:para> <maml:para>{Name*:Ana Trujillo}</maml:para> <maml:para>��� {City:Redmond}, {State:WA}</maml:para> <maml:para>��� {Name*:Antonio Moreno}</maml:para> <maml:para>��� {City:Renton}, {State:WA}</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies strings received from the pipeline, or a variable that contains a string object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="DEL"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>A regular expression that identifies the boundary between elements. Elements that are created by the split become properties in the resulting object. The delimiter is ultimately used in a call to System.Text.RegularExpressions.RegularExpression.Split().</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies strings received from the pipeline, or a variable that contains a string object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PN"> <maml:name>PropertyNames</maml:name> <maml:description> <maml:para>One or more property names to which to assign split values in the resulting object. Every line of text that you split or parse generates elements that represent property values. If the element is the result of a capture group, and that capture group is named (for example, (?<name>) or (?'name') ), then the name of that capture group is assigned to the property.</maml:para> <maml:para>If you provide any elements in the PropertyName array, those names are assigned to properties that have not yet been named. </maml:para> <maml:para> </maml:para> <maml:para>If you provide more property names than there are fields, Windows PowerShell ignores the extra property names. If you do not specify enough property names to name all fields, Windows PowerShell automatically assigns numerical property names to any properties that are not named: P1, P2, etc.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TC"> <maml:name>TemplateContent</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TF"> <maml:name>TemplateFile</maml:name> <maml:description> <maml:para>Specifies a file that contains a template for the desired parsing of the string. In the template file, properties and their values are enclosed in brackets, as shown in the following example. If a property (such as the Name property in this example) (and its associated otherproperties) can appear multiple times, add an asterisk (*) to indicate that this results in multiple records (rather than extracting multiple properties into a single record.</maml:para> <maml:para>{Name*:Ana Trujillo}</maml:para> <maml:para>��� {City:Redmond}, {State:WA}</maml:para> <maml:para>��� {Name*:Antonio Moreno}</maml:para> <maml:para>��� {City:Renton}, {State:WA}</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title>Example 1: Split a two-word string into two properties and values</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"Hello World" | ConvertFrom-String </dev:code> <dev:remarks> <maml:para>The following example generates an object with default property names, P1 and P2. The results are "P1=Hello" and "P2=World".</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2: Split a two-word string into two properties and values</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"Hello World" | ConvertFrom-String -Delimiter "ll" </dev:code> <dev:remarks> <maml:para>The following example generates an object with "P1=He" and "P2=o World", by specifying the "ll" in "Hello " as the delimiter.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3: Split a string by using a parse expression</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"Hello World" | ConvertFrom-String -ParseExpression "He(ll.*o)r(?<Captured>ld)" </dev:code> <dev:remarks> <maml:para>The following example generates an object with "P1=llo Wo" and "Captured=ld". There is no property name specified for the first property, so Windows PowerShell applies the default property name, P1; but the name Captured is specified in the expression for the second property. </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 4: Split a string specifying property names</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"Hello World" | ConvertFrom-String -PropertyName FirstWord,SecondWord </dev:code> <dev:remarks> <maml:para>The following example generates an object that contains two properties, FirstWord and SecondWord. The results are "FirstWord=Hello" and "SecondWord=World.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 5: Split a string specifying property types</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"123 456" | ConvertFrom-String -PropertyType String,Int </dev:code> <dev:remarks> <maml:para>The following example generates an object with default property names P1 and P2, but property types String and Int (for Integer) are identified. The results are "P1=123" and "P2=456". The second property is an integer, not a string.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/?LinkID=507579</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-StringData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Xml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-StringData</command:name> <maml:description> <maml:para>Converts a string containing one or more key and value pairs to a hash table.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertFrom</command:verb> <command:noun>StringData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertFrom-StringData cmdlet converts a string that contains one or more key and value pairs into a hash table. Because each key/value pair must be on a separate line, here-strings are often used as the input format.</maml:para> <maml:para>The ConvertFrom-StringData cmdlet is considered to be a safe cmdlet that can be used in the DATA section of a script or function. When used in a DATA section, the contents of the string must conform to the rules for a DATA section. For more information, see about_Data_Sections.</maml:para> <maml:para>ConvertFrom-StringData supports escape character sequences that are allowed by conventional machine translation tools. That is, the cmdlet can interpret backslashes (\) as escape characters in the string data by using the <maml:navigationLink><maml:linkText>Regex.Unescape Method</maml:linkText><maml:uri></maml:uri></maml:navigationLink>, instead of the Windows PowerShell backtick character (`) that would normally signal the end of a line in a script. Inside the here-string, the backtick character does not work. You can also preserve a literal backslash in your results by escaping it with a preceding backslash, like this: \\. Unescaped backslash characters, such as those that are commonly used in file paths, can render as illegal escape sequences in your results.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-StringData</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>StringData</maml:name> <maml:description> <maml:para>Specifies the string to be converted. You can use this parameter or pipe a string to ConvertFrom-StringData. The parameter name is optional.</maml:para> <maml:para>The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by newline characters (`n).</maml:para> <maml:para>You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The comments are not included in the hash table.</maml:para> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by newline characters (`n).</maml:para> <maml:para>You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The comments are not included in the hash table.</maml:para> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by newline characters (`n).</maml:para> <maml:para>You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The comments are not included in the hash table.</maml:para> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by newline characters (`n).</maml:para> <maml:para>You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The comments are not included in the hash table.</maml:para> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by newline characters (`n).</maml:para> <maml:para>You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The comments are not included in the hash table.</maml:para> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>StringData</maml:name> <maml:description> <maml:para>Specifies the string to be converted. You can use this parameter or pipe a string to ConvertFrom-StringData. The parameter name is optional.</maml:para> <maml:para>The value of this parameter must be a string that is enclosed in single quotation marks (a single-quoted string) or a string that is enclosed in double quotation marks (a double-quoted string) or a here-string containing one or more key/value pairs. Each key/value pair must be on a separate line, or each pair must be separated by newline characters (`n).</maml:para> <maml:para>You can include comments in the string, but the comments cannot be on the same line as a key/value pair. The comments are not included in the hash table.</maml:para> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string containing a key/value pair to ConvertFrom-StringData.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>ConvertFrom-StringData returns a hash table that it creates from the key/value pairs.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. For more information, see about_Quoting_Rules.</maml:para> <maml:para>ConvertFrom-StringData can be useful in scripts that display user messages in multiple spoken languages. You can use the dictionary-style hash tables to isolate text strings from code, such as in resource files, and to format the text strings for use in translation tools.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. Msg3 = The specified variable does not exist. '@ PS C:\>convertfrom-stringdata -stringdata $here Name Value ---- ----- Msg3 The specified variable does not exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. </dev:code> <dev:remarks> <maml:para>These commands convert a single-quoted here-string of user messages into a hash table. In a single-quoted string, values are not substituted for variables and expressions are not evaluated.</maml:para> <maml:para>The first command creates a here-string and saves it in the $here variable.</maml:para> <maml:para>The second command uses the ConvertFrom-StringData cmdlet to convert the here-string in the $here variable to a hash table.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$p = @" ISE = Windows PowerShell Integrated Scripting Environment "@ PS C:\>$p | get-member TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() ... PS C:\>$hash = convertfrom-stringdata -stringdata $p PS C:\>$hash | get-member TypeName: System.Collections.Hashtable Name MemberType Definition ---- ---------- ---------- Add Method System.Void Add(Object key, Object ... </dev:code> <dev:remarks> <maml:para>These commands demonstrate that ConvertFrom-StringData actually converts a here-string to a hash table.</maml:para> <maml:para>The first command creates a double-quoted here-string that includes one key/value pair and saves it in the $p variable.</maml:para> <maml:para>The second command uses a pipeline operator (|) to send the $p variable to the Get-Member cmdlet. The result shows that $p is a string (System.String).</maml:para> <maml:para>The third command uses the ConvertFrom-StringData cmdlet to convert the here-string in $p to a hash table. The command stores the result in the $hash variable.</maml:para> <maml:para>The final command uses a pipeline operator (|) to send the $hash variable to the Get-Member cmdlet. The result shows that the content of the $hash variable is a hash table (System.Collections.Hashtable).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>convertfrom-stringdata -stringdata @' Name = Disks.ps1 # Category is optional. Category = Storage Cost = Free '@ Name Value ---- ----- Cost Free Category Storage Name Disks.ps1 </dev:code> <dev:remarks> <maml:para>This command converts a single-quoted here-string that contains multiple key/value pairs into a hash table.</maml:para> <maml:para>In this command, the value of the StringData parameter is a here-string, instead of a variable that contains a here-string. Either format is valid.</maml:para> <maml:para>The here-string includes a comment about one of the strings. Comments are valid in strings, provided that the comment is on a different line than a key/value pair.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = convertfrom-stringdata -stringdata "Top = Red `n Bottom = Blue" PS C:\>"Top = " + $a.Top Top = Red PS C:\>"Bottom = " + $a.Bottom Bottom = Blue </dev:code> <dev:remarks> <maml:para>This example converts a regular double-quoted string (not a here-string) into a hash table and saves it in the $a variable.</maml:para> <maml:para>To satisfy the condition that each key/value pair must be on a separate line, it uses the Windows PowerShell newline character (`n) to separate the pairs.</maml:para> <maml:para>The result is a hash table of the input. The remaining commands display the output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$TextMsgs = DATA { ConvertFrom-StringData @' Text001 = The $Notebook variable contains the name of the user's system notebook. Text002 = The $MyNotebook variable contains the name of the user's private notebook. '@ } PS C:\>$TextMsgs.Text001 The $Notebook variable contains the name of the user's system notebook. PS C:\>$TextMsgs.Text002 The $MyNotebook variable contains the name of the user's private notebook. </dev:code> <dev:remarks> <maml:para>This example shows a ConvertFrom-StringData command used in the DATA section of a script. The statements below the DATA section display the text to the user.</maml:para> <maml:para>Because the text includes variable names, it must be enclosed in a single-quoted string so that the variables are interpreted literally and not expanded. Variables are not permitted in the DATA section.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$here = @' Msg1 = The string parameter is required. Msg2 = Credentials are required for this command. Msg3 = The specified variable does not exist. '@ PS C:\>$hash = $here | convertfrom-stringdata PS C:\>$hash Name Value ---- ----- Msg3 The specified variable does not exist. Msg2 Credentials are required for this command. Msg1 The string parameter is required. </dev:code> <dev:remarks> <maml:para>This example shows that you can use a pipeline operator (|) to send a string to ConvertFrom-StringData.</maml:para> <maml:para>The first command saves a here-string in the $here variable. The second command uses a pipeline operator (|) to send the $here variable to ConvertFrom-StringData. The command saves the result in the $hash variable.</maml:para> <maml:para>The final command displays the contents of the $hash variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>ConvertFrom-StringData @" Vincentio = Heaven doth with us as we with torches do,\nNot light them for themselves; for if our virtues\nDid not go forth of us, 'twere all alike\nAs if we had them not. Angelo = Let there be some more test made of my metal,\nBefore so noble and so great a figure\nBe stamp'd upon it. "@ | Format-List Name : Angelo Value : Let there be some more test made of my metal, Before so noble and so great a figure Be stamp'd upon it. Name : Vincentio Value : Heaven doth with us as we with torches do, Not light them for themselves; for if our virtues Did not go forth of us, 'twere all alike As if we had them not. </dev:code> <dev:remarks> <maml:para>This example shows the use of escape characters to create new lines and return characters in ConvertFrom-StringData. In this example, the escape sequence \n is used to create new lines within a block of text (the value, in the resulting hash table) that is associated with a name or item (the name, in the resulting hash table).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>ConvertFrom-StringData "Message=Look in c:\\Windows\\System32" Name Value ---- ----- Message Look in c:\Windows\System32 </dev:code> <dev:remarks> <maml:para>This example shows how to use of the backslash escape character in the string data to allow a file path to render correctly in the resulting ConvertFrom-StringData hash table. The double backslash ensures that the literal backslash characters render correctly in the hash table output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293948</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Quoting_Rules</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Script_Internationalization</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Data_Sections</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-Csv</command:name> <maml:description> <maml:para>Converts objects into a series of comma-separated value (CSV) variable-length strings. </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertTo</command:verb> <command:noun>Csv</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertTo-CSV cmdlet returns a series of comma-separated (CSV) strings that represents the objects that you submit. You can then use the ConvertFrom-CSV cmdlet to re-create objects from the CSV strings. The resulting objects are CSV versions of the original objects that consist of string representations of the property values and no methods.</maml:para> <maml:para>You can also use the T:Microsoft.PowerShell.Commands.Export-Csv and T:Microsoft.PowerShell.Commands.Import-Csv cmdlets to convert objects to CSV strings (and back). Export-CSV is the same as ConvertTo-CSV, except that it saves the CSV strings in a file.</maml:para> <maml:para>You can use the parameters of the ConvertTo-CSV cmdlet to specify a delimiter other than a comma or to direct ConvertTo-CSV to use the default delimiter for the current culture.</maml:para> <maml:para>For more information, see Export-CSV, and see the Notes section.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-Csv</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies a delimiter to separate the property values. The default is a comma (,). Enter a character, such as a colon (:).</maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the type information header from the output. By default, the string in the output contains "#TYPE " followed by the fully-qualified name of the object type.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-Csv</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the type information header from the output. By default, the string in the output contains "#TYPE " followed by the fully-qualified name of the object type.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Uses the list separator for the current culture as the data delimiter. The default is a comma (,).</maml:para> <maml:para>This parameter is very useful in scripts that are being distributed to users worldwide. To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies a delimiter to separate the property values. The default is a comma (,). Enter a character, such as a colon (:).</maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> <dev:type> <maml:name>Char</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>To specify a semicolon (;), enclose it in quotation marks. Otherwise, it will be interpreted as the command delimiter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the type information header from the output. By default, the string in the output contains "#TYPE " followed by the fully-qualified name of the object type.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Uses the list separator for the current culture as the data delimiter. The default is a comma (,).</maml:para> <maml:para>This parameter is very useful in scripts that are being distributed to users worldwide. To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object that has an Extended Type System (ETS) adapter to ConvertTo-CSV.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The CSV output is returned as a collection of strings.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>In CSV format, each object is represented by a comma-separated list of its property value. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. ConvertTo-CSV does not export the methods of the object.</maml:para> <maml:para>The format of the resulting CSV strings is as follows:</maml:para> <maml:para>-- The first string consists of '#TYPE ' followed by the fully-qualified name of the object type, such as #TYPE System.Diagnostics.Process. To suppress this string, use the NoTypeInformation parameter.</maml:para> <maml:para>-- The next string represents the column headers. It contains a comma-separated list of the names of all the properties of the first object.</maml:para> <maml:para>-- The remaining strings consist of comma-separated lists of the property values of each object.</maml:para> </maml:alert> <maml:alert> <maml:para>When you submit multiple objects to ConvertTo-CSV, ConvertTo-CSV orders the strings based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are ignored.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process powershell | convertto-csv #TYPE System.Diagnostics.Process "__NounName","Name","Handles","VM","WS","PM","NPM","Path","Company","CPU","FileVersion","ProductVersion","Description", "Product","BasePriority","ExitCode","HasExited","ExitTime","Handle","HandleCount","Id","MachineName","MainWindowHandle" ,"MainWindowTitle","MainModule","MaxWorkingSet","MinWorkingSet","Modules","NonpagedSystemMemorySize","NonpagedSystemMem orySize64","PagedMemorySize","PagedMemorySize64","PagedSystemMemorySize","PagedSystemMemorySize64","PeakPagedMemorySize ","PeakPagedMemorySize64","PeakWorkingSet","PeakWorkingSet64","PeakVirtualMemorySize","PeakVirtualMemorySize64","Priori tyBoostEnabled","PriorityClass","PrivateMemorySize","PrivateMemorySize64","PrivilegedProcessorTime","ProcessName","Proc essorAffinity","Responding","SessionId","StartInfo","StartTime","SynchronizingObject","Threads","TotalProcessorTime","U serProcessorTime","VirtualMemorySize","VirtualMemorySize64","EnableRaisingEvents","StandardInput","StandardOutput","Sta ndardError","WorkingSet","WorkingSet64","Site","Container" "Process","powershell","216","597544960","60399616","63197184","21692","C:\WINDOWS\system32\WindowsPowerShell\v1.0\powe rshell.exe","Microsoft Corporation","3.4788223","6.1.6587.1 (fbl_srv_powershell(nigels).070711-0102)","6.1.6587.1","Win dows PowerShell","Microsoft� Windows� Operating System","8",,"False",,"860","216","5132",".","5636936","Windows PowerSh ell 2.0 (04/17/2008 00:10:40)","System.Diagnostics.ProcessModule (powershell.exe)","1413120","204800","System.Diagnosti cs.ProcessModuleCollection","21692","21692","63197184","63197184","320080","320080","63868928","63868928","60715008","6 0715008","598642688","598642688","True","Normal","63197184","63197184","00:00:00.2028013","powershell","15","True","1", "System.Diagnostics.ProcessStartInfo","4/21/2008 3:49:19 PM",,"System.Diagnostics.ProcessThreadCollection","00:00:03.51 00225","00:00:03.3072212","597544960","597544960","False",,,,"60399616","60399616",, </dev:code> <dev:remarks> <maml:para>This command converts a single process object to CSV format. The command uses the Get-Process cmdlet to get the PowerShell process on the local computer. It uses a pipeline operator (|) to send the command to the ConvertTo-CSV cmdlet, which converts it to a series of comma-separated strings.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$date = get-date PS C:\>convertto-csv -inputobject $date -delimiter ";" -notypeinformation </dev:code> <dev:remarks> <maml:para>This example converts a date object to CSV format.</maml:para> <maml:para>The first command uses the Get-Date cmdlet to get the current date. It saves it in the $date variable.</maml:para> <maml:para>The second command uses the ConvertTo-CSV cmdlet to convert the DateTime object in the $date variable to CSV format. The command uses the InputObject parameter to specify the object to be converted. It uses the Delimiter parameter to specify the delimiter that separates the object properties. It uses the NoTypeInformation parameter to suppress the #TYPE string.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventlog -log "windows powershell" | convertto-csv -useculture </dev:code> <dev:remarks> <maml:para>This command converts the Windows PowerShell event log on the local computer to a series of CSV strings.</maml:para> <maml:para>The command uses the Get-EventLog cmdlet to get the events in the Windows PowerShell log. A pipeline operator (|) sends the events to the ConvertTo-CSV cmdlet, which converts the events to CSV format. The command uses the UseCulture parameter, which uses the list separator for the current culture as the delimiter.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293949</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-Html</command:name> <maml:description> <maml:para>Converts Microsoft .NET Framework objects into HTML that can be displayed in a Web browser. </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertTo</command:verb> <command:noun>Html</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertTo-Html cmdlet converts .NET Framework objects into HTML that can be displayed in a Web browser. You can use this cmdlet to display the output of a command in a Web page.</maml:para> <maml:para>You can use the parameters of ConvertTo-Html to select object properties, to specify a table or list format, to specify the HTML page title, to add text before and after the object, and to return only the table or list fragment, instead of a strict DTD page.</maml:para> <maml:para>When you submit multiple objects to ConvertTo-Html, Windows PowerShell creates the table (or list) based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is an empty cell. If the remaining objects have additional properties, those property values are not included in the file.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-Html</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Includes the specified properties of the objects in the HTML. The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Label <string> (unlike with Select-Object or Format-Table, the Name key is not supported)</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Head</maml:name> <maml:description> <maml:para>Specifies the content of the <HEAD> tag. The default is "<title>HTML TABLE</title>". If you use the Head parameter, the Title parameter is ignored.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies a title for the HTML file, that is, the text that appears between the <TITLE> tags.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the text to add after the opening <BODY> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines whether the object is formatted as a table or a list. Valid values are TABLE and LIST. The default value is TABLE.</maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Table</command:parameterValue> <command:parameterValue required="false" variableLength="false">List</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="cu,uri"> <maml:name>CssUri</maml:name> <maml:description> <maml:para>Specifies the Uniform Resource Identifier (URI) of the cascading style sheet (CSS) that is applied to the HTML file. The URI is included in a style sheet link in the output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Uri</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be represented in HTML. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> <maml:para>If you use this parameter to submit multiple objects, such as all of the services on a computer, ConvertTo-Html creates a table that displays the properties of a collection or of an array of objects (System.Object[]). To create a table of the individual objects, use the pipeline operator to pipe the objects to ConvertTo-Html.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PostContent</maml:name> <maml:description> <maml:para>Specifies text to add after the closing </TABLE> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PreContent</maml:name> <maml:description> <maml:para>Specifies text to add before the opening <TABLE> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>ConvertTo-Html</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Includes the specified properties of the objects in the HTML. The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Label <string> (unlike with Select-Object or Format-Table, the Name key is not supported)</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines whether the object is formatted as a table or a list. Valid values are TABLE and LIST. The default value is TABLE.</maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Table</command:parameterValue> <command:parameterValue required="false" variableLength="false">List</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Fragment</maml:name> <maml:description> <maml:para>Generates only an HTML table. The HTML, HEAD, TITLE, and BODY tags are omitted.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be represented in HTML. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> <maml:para>If you use this parameter to submit multiple objects, such as all of the services on a computer, ConvertTo-Html creates a table that displays the properties of a collection or of an array of objects (System.Object[]). To create a table of the individual objects, use the pipeline operator to pipe the objects to ConvertTo-Html.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PostContent</maml:name> <maml:description> <maml:para>Specifies text to add after the closing </TABLE> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PreContent</maml:name> <maml:description> <maml:para>Specifies text to add before the opening <TABLE> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines whether the object is formatted as a table or a list. Valid values are TABLE and LIST. The default value is TABLE.</maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the text to add after the opening <BODY> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="cu,uri"> <maml:name>CssUri</maml:name> <maml:description> <maml:para>Specifies the Uniform Resource Identifier (URI) of the cascading style sheet (CSS) that is applied to the HTML file. The URI is included in a style sheet link in the output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Fragment</maml:name> <maml:description> <maml:para>Generates only an HTML table. The HTML, HEAD, TITLE, and BODY tags are omitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Head</maml:name> <maml:description> <maml:para>Specifies the content of the <HEAD> tag. The default is "<title>HTML TABLE</title>". If you use the Head parameter, the Title parameter is ignored.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The TABLE value generates an HTML table that resembles the Windows PowerShell table format. The header row displays the property names. Each table row represents an object and displays the object's values for each property.</maml:para> <maml:para>The LIST value generates a two-column HTML table for each object that resembles the Windows PowerShell list format. The first column displays the property name; the second column displays the property value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be represented in HTML. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> <maml:para>If you use this parameter to submit multiple objects, such as all of the services on a computer, ConvertTo-Html creates a table that displays the properties of a collection or of an array of objects (System.Object[]). To create a table of the individual objects, use the pipeline operator to pipe the objects to ConvertTo-Html.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PostContent</maml:name> <maml:description> <maml:para>Specifies text to add after the closing </TABLE> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PreContent</maml:name> <maml:description> <maml:para>Specifies text to add before the opening <TABLE> tag. By default, there is no text in that position.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Includes the specified properties of the objects in the HTML. The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Label <string> (unlike with Select-Object or Format-Table, the Name key is not supported)</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies a title for the HTML file, that is, the text that appears between the <TITLE> tags.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any .NET object to ConvertTo-Html.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>ConvertTo-Html returns series of strings that comprise valid HTML.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>To use this cmdlet, pipe one or more objects to the cmdlet or use the InputObject parameter to specify the object. When the input consists of multiple objects, the output of these two methods is quite different.</maml:para> <maml:para>-- When you pipe multiple objects to a cmdlet, Windows PowerShell sends the objects to the cmdlet one at a time. As a result, ConvertTo-Html creates a table that displays the individual objects. For example, if you pipe the processes on a computer to ConvertTo-Html, the resulting table displays all of the processes.</maml:para> <maml:para>-- When you use the InputObject parameter to submit multiple objects, ConvertTo-Html receives these objects as a collection or as an array. As a result, it creates a table that displays the array and its properties, not the items in the array. For example, if you use InputObject to submit the processes on a computer to ConvertTo-Html, the resulting table displays an object array (System.Object[]) and its properties.</maml:para> <maml:para>To comply with the XHTML Strict DTD,the DOCTYPE tag is modified accordingly:</maml:para> <maml:para> (<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">)</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>convertto-html -inputobject (get-date) </dev:code> <dev:remarks> <maml:para>This command creates an HTML page that displays the properties of the current date. It uses the InputObject parameter to submit the results of a Get-Date command to the ConvertTo-Html cmdlet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-alias | convertto-html > aliases.htm PS C:\>invoke-item aliases.htm </dev:code> <dev:remarks> <maml:para>This command creates an HTML page that lists the Windows PowerShell aliases in the current console.</maml:para> <maml:para>The command uses the Get-Alias cmdlet to get the aliases. It uses the pipeline operator (|) to send the aliases to the ConvertTo-Html cmdlet, which creates the HTML page.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventlog -logname "Windows PowerShell" | convertto-html > pslog.htm </dev:code> <dev:remarks> <maml:para>This command creates an HTML page called pslog.htm that displays the events in the Windows PowerShell event log on the local computer.</maml:para> <maml:para>It uses the Get-EventLog cmdlet to get the events in the Windows PowerShell log and then uses the pipeline operator (|) to send the events to the ConvertTo-Html cmdlet.</maml:para> <maml:para>The command also uses the redirection operator (>) to send the HTML code to the pslog.htm file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | convertto-html -property Name, Path, Company -title "Process Information" > proc.htm; ii proc.htm </dev:code> <dev:remarks> <maml:para>These commands create and open an HTML page that lists the name, path, and company of the processes on the local computer.</maml:para> <maml:para>The first command uses the Get-Process cmdlet to get objects that represent the processes running on the computer. The command uses the pipeline operator (|) to send the process objects to the ConvertTo-Html cmdlet.</maml:para> <maml:para>The command uses the Property parameter to select three properties of the process objects to be included in the table. The command uses the Title parameter to specify a title for the HTML page. The command also uses the redirection operator (>) to send the resulting HTML to a file named Proc.htm.</maml:para> <maml:para>The second command uses the Invoke-Item cmdlet (alias = ii) to open the Proc.htm in the default browser. The two commands are separated by a semicolon (;).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | convertto-html -CssUri "test.css" <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <title>HTML TABLE</title> <link rel="stylesheet" type="text/css" href="test.css" /> ... </dev:code> <dev:remarks> <maml:para>This command creates an HTML page of the service objects that the Get-Service cmdlet returns. The command uses the CssUri parameter to specify a cascading style sheet for the HTML page.</maml:para> <maml:para>The CssUri parameter adds an additional "<link rel="stylesheet" type="text/css" tag to the resulting HTML. The HREF attribute in the tag contains the name of the style sheet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | convertto-html -as LIST > services.htm </dev:code> <dev:remarks> <maml:para>This command creates an HTML page of the service objects that the Get-Service cmdlet returns. The command uses the As parameter to specify a list format. The redirection operator (>) sends the resulting HTML to the Services.htm file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-date | cth -fragment <table> <colgroup>...</colgroup> <tr><th>DisplayHint</th><th>DateTime</th><th>Date</th><th>Day</th><th>DayOfWeek</th><th>DayOfYear</th><th>Hour</th> <th>Kind</th><th>Millisecond</th><th>Minute</th><th>Month</th><th>Second</th><th>Ticks</th><th>TimeOfDay</th><th>Year</th></tr> <tr><td>DateTime</td><td>Monday, May 05, 2008 10:40:04 AM</td><td>5/5/2008 12:00:00 AM</td><td>5</td><td>Monday</td> <td>126</td><td>10</td><td>Local</td><td>123</td><td>40</td><td>5</td><td>4</td><td>633455808041237213</td><td>10:40:04.12 37213</td><td>2008</td></tr> </table> </dev:code> <dev:remarks> <maml:para>This command uses ConvertTo-Html to generate an HTML table of the current date. The command uses the Get-Date cmdlet to get the current date. It uses a pipeline operator (|) to send the results to the ConvertTo-Html cmdlet (aliased as "cth").</maml:para> <maml:para>The ConvertTo-Html command includes the Fragment parameter, which limits the output to an HTML table. As a result, the other elements of an HTML page, such as the <HEAD> and <BODY> tags, are omitted.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventlog -log "Windows PowerShell" | convertto-html -property id, level, task </dev:code> <dev:remarks> <maml:para>This command uses the Get-EventLog cmdlet to get events from the "Windows PowerShell" event log.</maml:para> <maml:para>It uses a pipeline operator (|) to send the events to the ConvertTo-Html cmdlet, which converts the events to HTML format.</maml:para> <maml:para>The ConvertTo-Html command uses the Property parameter to select only the ID, Level, and Task properties of the event.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service A* | ConvertTo-Html -title "Windows Services: Server01" -body (get-date) -pre "<P>Generated by Corporate IT</P>" -post "For details, contact Corporate IT." > services.htm; ii services.htm </dev:code> <dev:remarks> <maml:para>This command creates and opens a Web page that displays the services on the computer that begin with "A". It uses the Title, Body, PreContent, and PostContent parameters of ConvertTo-Html to customize the output.</maml:para> <maml:para>The first part of the command uses the Get-Service cmdlet to get the services on the computer that begin with "A". The command uses a pipeline operator (|) to send the results to the ConvertTo-Html cmdlet. The command uses a redirection operator (>) to send the output to the Services.htm file.</maml:para> <maml:para>A semicolon (;) ends the first command and starts a second command, which uses the Invoke-Item cmdlet (alias = "ii") to open the Services.htm file in the default browser.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293950</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Xml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-Json</command:name> <maml:description> <maml:para>Converts an object to a JSON-formatted string</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertTo</command:verb> <command:noun>Json</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertTo-Json cmdlet converts any object to a string in JavaScript Object Notation (JSON) format. The properties are converted to field names, the field values are converted to property values, and the methods are removed.</maml:para> <maml:para>You can then use the ConvertFrom-Json cmdlet to convert a JSON-formatted string to a JSON object, which is easily managed in Windows PowerShell.</maml:para> <maml:para>Many web sites use JSON instead of XML to serialize data for communication between servers and web-based apps.</maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-Json</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to convert to JSON format. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe an object to ConvertTo-Json.</maml:para> <maml:para>The InputObject parameter is required, but its value can be null ($null) or an empty string. When the input object is $null, ConvertTo-Json does not generate any output. When the input object is an empty string, ConvertTo-Json returns an empty string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Compress</maml:name> <maml:description> <maml:para>Omits white space and indented formatting in the output string.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the JSON representation. The default value is 2.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Compress</maml:name> <maml:description> <maml:para>Omits white space and indented formatting in the output string.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the JSON representation. The default value is 2.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to convert to JSON format. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe an object to ConvertTo-Json.</maml:para> <maml:para>The InputObject parameter is required, but its value can be null ($null) or an empty string. When the input object is $null, ConvertTo-Json does not generate any output. When the input object is an empty string, ConvertTo-Json returns an empty string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to ConvertTo-Json.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The ConvertTo-Json cmdlet is implemented by using the JavaScriptSerializer class (http://msdn.microsoft.com/en-us/library/system.web.script.serialization.javascriptserializer(VS.100).aspx).</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(Get-UICulture).Calendar | ConvertTo-Json { "MinSupportedDateTime": "\/Date(-62135568000000)\/", "MaxSupportedDateTime": "\/Date(253402300799999)\/", "AlgorithmType": 1, "CalendarType": 1, "Eras": [ 1 ], "TwoDigitYearMax": 2029, "IsReadOnly": false } </dev:code> <dev:remarks> <maml:para>This command uses the ConvertTo-Json cmdlet to convert a GregorianCalendar object to a JSON-formatted string.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>@{Account="User01";Domain="Domain01";Admin="True"} | ConvertTo-Json - Compress {"Admin":"True","Account":"User01","Domain":"Domain01"} </dev:code> <dev:remarks> <maml:para>This command shows the effect of using the Compress parameter of ConvertTo-Json. The compression affects only the appearance of the string, not its validity.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the ConvertTo-Json cmdlet to convert a System.DateTime object from the Get-Date cmdlet to a JSON-formatted string. The command uses the Select-Object cmdlet to get all (*) of the properties of the DateTime object.The output shows the JSON string that ConvertTo-Json returned. PS C:\>Get-Date | Select-Object -Property * | ConvertTo-Json { "DisplayHint": 2, "DateTime": "Friday, January 13, 2012 8:06:16 PM", "Date": "\/Date(1326441600000)\/", "Day": 13, "DayOfWeek": 5, "DayOfYear": 13, "Hour": 20, "Kind": 2, "Millisecond": 221, "Minute": 6, "Month": 1, "Second": 16, "Ticks": 634620819762218083, "TimeOfDay": { "Ticks": 723762218083, "Days": 0, "Hours": 20, "Milliseconds": 221, "Minutes": 6, "Seconds": 16, "TotalDays": 0.83768775241087956, "TotalHours": 20.104506057861109, "TotalMilliseconds": 72376221.8083, "TotalMinutes": 1206.2703634716668, "TotalSeconds": 72376.22180829999 }, "Year": 2012 } The second command uses ConvertFrom-Json to convert the JSON string to a JSON object. PS C:\>Get-Date | Select-Object -Property * | ConvertTo-Json | ConvertFrom-Json DisplayHint : 2 DateTime : Friday, January 13, 2012 8:06:31 PM Date : 1/13/2012 8:00:00 AM Day : 13 DayOfWeek : 5 DayOfYear : 13 Hour : 20 Kind : 2 Millisecond : 400 Minute : 6 Month : 1 Second : 31 Ticks : 634620819914009002 TimeOfDay : @{Ticks=723914009002; Days=0; Hours=20; Milliseconds=400; Minutes=6; Seconds=31; TotalDays=0.83786343634490734; TotalHours=20.108722472277776; TotalMilliseconds=72391400.900200009; TotalMinutes=1206.5233483366667; TotalSeconds=72391.4009002} Year : 2012 </dev:code> <dev:remarks> <maml:para>This command shows how to use the ConvertTo-Json and ConvertFrom-Json cmdlet to convert an object to a JSON string and a JSON object.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 4</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$JsonSecurityHelp = Get-Content $pshome\Modules\Microsoft.PowerShell.Security\en-US\Microsoft.PowerShell.Security.dll-Help.xml | ConvertTo-Json </dev:code> <dev:remarks> <maml:para>This command uses the ConvertTo-Json cmdlet to convert a Windows PowerShell help file from XML format to JSON format. You can use a command like this to use the help topic content in a web service application.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293951</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>An Introduction to JavaScript Object Notation (JSON) in JavaScript and .NET</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Json</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-WebRequest</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-RestMethod</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-Xml</command:name> <maml:description> <maml:para>Creates an XML-based representation of an object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>ConvertTo</command:verb> <command:noun>Xml</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ConvertTo-Xml cmdlet creates an XML-based representation of one or more Microsoft .NET Framework objects. To use this cmdlet, pipe one or more objects to the cmdlet, or use the InputObject parameter to specify the object.</maml:para> <maml:para>When you pipe multiple objects to ConvertTo-XML or use the InputObject parameter to submit multiple objects, ConvertTo-XML returns a single XML document that includes representations of all of the objects.</maml:para> <maml:para>This cmdlet is similar to Export-Clixml except that Export-Clixml stores the resulting XML in a file. ConvertTo-XML returns the XML, so you can continue to process it in Windows PowerShell.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-Xml</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-XML.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines the output format. Valid values are:</maml:para> <maml:para>-- String: Returns a single string.</maml:para> <maml:para>-- Stream: Returns an array of strings.</maml:para> <maml:para>-- Document: Returns an XmlDocument object.</maml:para> <maml:para>The default is Document.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Stream</command:parameterValue> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <command:parameterValue required="false" variableLength="false">Document</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the XML representation. The default value is 1.</maml:para> <maml:para>For example, if the object's properties also contain objects, to save an XML representation of the properties of the contained objects, you must specify a depth of 2.</maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>-- String: Returns a single string.</maml:para> <maml:para>-- Stream: Returns an array of strings.</maml:para> <maml:para>-- Document: Returns an XmlDocument object.</maml:para> <maml:para>The default is Document.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>-- String: Returns a single string.</maml:para> <maml:para>-- Stream: Returns an array of strings.</maml:para> <maml:para>-- Document: Returns an XmlDocument object.</maml:para> <maml:para>The default is Document.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the Type attribute from the object nodes.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines the output format. Valid values are:</maml:para> <maml:para>-- String: Returns a single string.</maml:para> <maml:para>-- Stream: Returns an array of strings.</maml:para> <maml:para>-- Document: Returns an XmlDocument object.</maml:para> <maml:para>The default is Document.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the XML representation. The default value is 1.</maml:para> <maml:para>For example, if the object's properties also contain objects, to save an XML representation of the properties of the contained objects, you must specify a depth of 2.</maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>-- String: Returns a single string.</maml:para> <maml:para>-- Stream: Returns an array of strings.</maml:para> <maml:para>-- Document: Returns an XmlDocument object.</maml:para> <maml:para>The default is Document.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>-- String: Returns a single string.</maml:para> <maml:para>-- Stream: Returns an array of strings.</maml:para> <maml:para>-- Document: Returns an XmlDocument object.</maml:para> <maml:para>The default is Document.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to ConvertTo-XML.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the Type attribute from the object nodes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to ConvertTo-XML.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String or System.Xml.XmlDocument</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The value of the As parameter determines the type of object that ConvertTo-XML returns.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-date | convertto-xml </dev:code> <dev:remarks> <maml:para>This command converts the current date (a DateTime object) to XML.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>convertto-xml -as Document -inputObject (get-process) -depth 3 </dev:code> <dev:remarks> <maml:para>This command converts the process objects that represent all of the processes on the computer into an XML document. The objects are expanded to a depth of three levels.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293952</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Html</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Clixml</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Clixml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Debug-Runspace</command:name> <maml:description> <maml:para>Starts an interactive debugging session with a runspace.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Debug</command:verb> <command:noun>Runspace</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>Debug-Runspace starts an interactive debugging session with a local or remote active runspace. You can find a runspace that you want to debug by first running Get-Process to find processes associated with Windows PowerShell, then Enter-PSHostProcess with the process ID specified in the Id parameter to attach to the process, and then Get-Runspace to list runspaces within the Windows PowerShell host process.</maml:para> <maml:para>After you have selected a runspace to debug, if the runspace is currently running a command or script, or if the script has stopped at a breakpoint, Windows PowerShell opens a remote debugger session for the runspace. You can debug the runspace script in the same way remote session scripts are debugged.</maml:para> <maml:para>You can only attach to a Windows PowerShell host process if you are an administrator on the computer that is running the process, or you are running the script that you want to debug. Also, you cannot enter the host process that is running the current Windows PowerShell session; you can only enter a host process that is running a different Windows PowerShell session. For example, if you are working in a PowerShell.exe session, you can�t enter the host process for that session, but you can enter the host process of a running Windows PowerShell ISE session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Debug-Runspace</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para>Specifies a runspace object. The simplest way to provide a value for this parameter is to specify a variable that contains the results of a filtered Get-Runspace command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Runspace</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Debug-Runspace</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Specifies the ID number of a runspace. You can run Get-Runspace to show runspace IDs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Debug-Runspace</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies a runspace by its name. You can run Get-Runspace to show the names of runspaces.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Debug-Runspace</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>InstanceId</maml:name> <maml:description> <maml:para>Specifies a runspace by its instance ID, a GUID that you can show by running Get-Runspace.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Guid</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Specifies the ID number of a runspace. You can run Get-Runspace to show runspace IDs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>InstanceId</maml:name> <maml:description> <maml:para>Specifies a runspace by its instance ID, a GUID that you can show by running Get-Runspace.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Guid</command:parameterValue> <dev:type> <maml:name>Guid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies a runspace by its name. You can run Get-Runspace to show the names of runspaces.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para>Specifies a runspace object. The simplest way to provide a value for this parameter is to specify a variable that contains the results of a filtered Get-Runspace command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Runspace</command:parameterValue> <dev:type> <maml:name>Runspace</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.Runspaces.Runspace</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the results of a Get-Runspace command to Debug-Runspace.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Debug-Runspace works on runspaces that are in the Opened state. If a runspace state changes from Opened to another state, that runspace is automatically removed from the running list. A runspace is added to the running list only if it meets the following criteria.</maml:para> <maml:para>-- If it is coming from Invoke-Command; that is, it has an Invoke-Command GUID Id.</maml:para> <maml:para>-- If it is coming from Debug-Runspace; that is, it has a Debug-Runspace GUID Id.</maml:para> <maml:para>-- If it is coming from a Windows PowerShell workflow, and its workflow job ID is the same as the current active debugger workflow job ID.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Debug a remote runspace</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process �ComputerName WS10TestServer �Name *powershell* Handles WS(K) VM(M) CPU(s) Id ProcessName ------- ----- ----- ------ -- ----------- 377 69912 63 2.09 2420 powershell 399 123396 829 4.48 1152 powershell_ise PS C:\> Enter-PSSession �ComputerName WS10TestServer [WS10TestServer]:PS C:\> Enter-PSHostProcess �Id 1152 [WS10TestServer:][Process:1152]: PS C:\Users\Test\Documents> Get-Runspace Id Name ComputerName Type State Availability -- ---- ------------ ---- ----- ------------ 1 Runspace1 WS10TestServer Remote Opened Available 2 RemoteHost WS10TestServer Remote Opened Busy [WS10TestServer][Process:1152]: PS C:\Users\Test\Documents> Debug-Runspace �Id 2 Hit Line breakpoint on 'C:\TestWFVar1.ps1:83' At C:\TestWFVar1.ps1:83 char:1 + $scriptVar = "Script Variable" + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Process:1152]: [RSDBG: 2]: PS C:\>> </dev:code> <dev:remarks> <maml:para>In this example, you debug a runspace that is open on a remote computer, WS10TestServer. In the first line of the command, you run Get-Process on the remote computer, and filter for Windows PowerShell host processes. In this example, you want to debug process ID 1152, the Windows PowerShell ISE host process.</maml:para> <maml:para>In the second command, you run Enter-PSSession to open a remote session on WS10TestServer. In the third command, you attach to the Windows PowerShell ISE host process running on the remote server by running Enter-PSHostProcess, and specifying the ID of the host process that you obtained in the first command, 1152.</maml:para> <maml:para>In the fourth command, you list available runspaces for process ID 1152 by running Get-Runspace. You note the ID number of the Busy runspace; it is running a script that you want to debug.</maml:para> <maml:para>In the last command, you start debugging an opened runspace that is running a script, TestWFVar1.ps1, by running Debug-Runspace, and identifying the runspace by its ID, 2, by adding the Id parameter. Because there�s a breakpoint in the script, the debugger opens.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/?LinkID=403731</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Process</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enter-PSHostProcess</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Runspace</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Debug-Job</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Disable-PSBreakpoint</command:name> <maml:description> <maml:para>Disables the breakpoints in the current console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Disable</command:verb> <command:noun>PSBreakpoint</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Disable-PSBreakpoint cmdlet disables breakpoints, which assures that they are not hit when the script runs. You can use it to disable all breakpoints, or you can specify breakpoints by submitting breakpoint objects or breakpoint IDs.</maml:para> <maml:para>Technically, this cmdlet changes the value of the Enabled property of a breakpoint object to False. To re-enable a breakpoint, use the Enable-PSBreakpoint cmdlet. Breakpoints are enabled by default when you create them by using the Set-PSBreakpoint cmdlet.</maml:para> <maml:para>A breakpoint is a point in a script where execution stops temporarily so that you can examine the instructions in the script. Disable-PSBreakpoint is one of several cmdlets designed for debugging Windows PowerShell scripts. For more information about the Windows PowerShell debugger, see about_Debuggers.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Disable-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>Specifies the breakpoints to disable. Enter a variable that contains breakpoint objects or a command that gets breakpoint objects, such as a Get-PSBreakpoint command. You can also pipe breakpoint objects to the Disable-PSBreakpoint cmdlet.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Breakpoint[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the enabled breakpoints. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Disable-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Disables the breakpoints with the specified breakpoint IDs. Enter the IDs or a variable that contains the IDs. You cannot pipe IDs to Disable-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the enabled breakpoints. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>Specifies the breakpoints to disable. Enter a variable that contains breakpoint objects or a command that gets breakpoint objects, such as a Get-PSBreakpoint command. You can also pipe breakpoint objects to the Disable-PSBreakpoint cmdlet.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Breakpoint[]</command:parameterValue> <dev:type> <maml:name>Breakpoint[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Disables the breakpoints with the specified breakpoint IDs. Enter the IDs or a variable that contains the IDs. You cannot pipe IDs to Disable-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the enabled breakpoints. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.Breakpoint</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a breakpoint object to Disable-PSBreakpoint.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.Breakpoint</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Disable-PSBreakpoint returns an object that represents the disabled breakpoint. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$b = set-psbreakpoint -script sample.ps1 -variable name PS C:\>$b | disable-psbreakpoint </dev:code> <dev:remarks> <maml:para>These commands disable a newly-created breakpoint.</maml:para> <maml:para>The first command uses the Set-PSBreakpoint cmdlet to create a breakpoint on the Name variable in the Sample.ps1 script. Then, it saves the breakpoint object in the $b variable.</maml:para> <maml:para>The second command uses the Disable-PSBreakpoint cmdlet to disable the new breakpoint. It uses a pipeline operator (|) to send the breakpoint object in $b to the Disable-PSBreakpoint cmdlet.</maml:para> <maml:para>As a result of this command, the value of the Enabled property of the breakpoint object in $b is False.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>disable-psbreakpoint -id 0 </dev:code> <dev:remarks> <maml:para>This command disables the breakpoint with breakpoint ID 0.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>disable-psbreakpoint -breakpoint ($b = set-psbreakpoint -script sample.ps1 -line 5) PS C:\>$b </dev:code> <dev:remarks> <maml:para>This command creates a new breakpoint that is disabled until you enable it.</maml:para> <maml:para>It uses the Disable-PSBreakpoint cmdlet to disable the breakpoint. The value of the Breakpoint parameter is a Set-PSBreakpoint command that sets a new breakpoint, generates a breakpoint object, and saves the object in the $b variable.</maml:para> <maml:para>Cmdlet parameters that take objects as their values can accept a variable that contains the object or a command that gets or generates the object. In this case, because Set-PSBreakpoint generates a breakpoint object, it can be used as the value of the Breakpoint parameter.</maml:para> <maml:para>The second command displays the breakpoint object in the value of the $b variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint | disable-psbreakpoint </dev:code> <dev:remarks> <maml:para>This command disables all breakpoints in the current console. You can abbreviate this command as: "gbp | dbp".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293953</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSCallStack</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Disable-RunspaceDebug</command:name> <maml:description> <maml:para>Disables debugging on one or more runspaces, and releases any pending debugger stop.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Disable</command:verb> <command:noun>RunspaceDebug</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This content is coming in a future release.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Disable-RunspaceDebug</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Disable-RunspaceDebug</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ProcessName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>AppDomainName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Disable-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Runspace[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Disable-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Disable-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceInstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>AppDomainName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ProcessName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Runspace[]</command:parameterValue> <dev:type> <maml:name>Runspace[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceInstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> <dev:type> <maml:name>Guid[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> 2: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Enable-PSBreakpoint</command:name> <maml:description> <maml:para>Enables the breakpoints in the current console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Enable</command:verb> <command:noun>PSBreakpoint</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Enable-PSBreakpoint cmdlet re-enables disabled breakpoints. You can use it to enable all breakpoints, or you can specify breakpoints by submitting breakpoint objects or breakpoint IDs.</maml:para> <maml:para>A breakpoint is a point in a script where execution stops temporarily so that you can examine the instructions in the script. Newly created breakpoints are automatically enabled, but you can disable them by using the Disable-PSBreakpoint cmdlet.</maml:para> <maml:para>Technically, this cmdlet changes the value of the Enabled property of a breakpoint object to True.</maml:para> <maml:para>Enable-PSBreakpoint is one of several cmdlets designed for debugging Windows PowerShell scripts. For more information about the Windows PowerShell debugger, see about_Debuggers.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Enable-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Enables breakpoints that have the specified breakpoint IDs. The default value is all breakpoints. Enter the IDs or a variable that contains the IDs. (You cannot pipe IDs to Enable-PSBreakpoint.) To find the ID of a breakpoint, use the Get-PSBreakpoint cmdlet.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the enabled breakpoint. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Enable-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>Specifies the breakpoints to enable. Enter a variable that contains breakpoint objects or a command that gets breakpoint objects, such as a Get-PSBreakpoint command. You can also pipe breakpoint objects to Enable-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Breakpoint[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the enabled breakpoint. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>Specifies the breakpoints to enable. Enter a variable that contains breakpoint objects or a command that gets breakpoint objects, such as a Get-PSBreakpoint command. You can also pipe breakpoint objects to Enable-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Breakpoint[]</command:parameterValue> <dev:type> <maml:name>Breakpoint[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Enables breakpoints that have the specified breakpoint IDs. The default value is all breakpoints. Enter the IDs or a variable that contains the IDs. (You cannot pipe IDs to Enable-PSBreakpoint.) To find the ID of a breakpoint, use the Get-PSBreakpoint cmdlet.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the enabled breakpoint. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.Breakpoint</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a breakpoint object to Enable-PSBreakpoint.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.Breakpoint</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Enable-PSBreakpoint returns a breakpoint object that represent that breakpoint that was enabled. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The Enable-PSBreakpoint cmdlet does not generate an error if you try to enable a breakpoint that is already enabled. As such, you can enable all breakpoints without error, even when only a few are disabled.</maml:para> <maml:para>Breakpoints are enabled when you create them by using the Set-PSBreakpoint cmdlet. You do not need to enable newly created breakpoints.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint | enable-psbreakpoint </dev:code> <dev:remarks> <maml:para>This command enables all breakpoints in the current console. You can abbreviate the command as "gbp | ebp".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>enable-psbreakpoint -id 0, 1, 5 </dev:code> <dev:remarks> <maml:para>This command enables breakpoints with breakpoint IDs 0, 1, and 5.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$b = set-psbreakpoint -script sample.ps1 -variable Name PS C:\>$b | disable-psbreakpoint -passthru AccessMode : Write Variable : Name Action : Enabled : False HitCount : 0 Id : 0 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 PS C:\>$b | enable-psbreakpoint -passthru AccessMode : Write Variable : Name Action : Enabled : True HitCount : 0 Id : 0 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 </dev:code> <dev:remarks> <maml:para>These commands re-enable a breakpoint that has been disabled.</maml:para> <maml:para>The first command uses the Set-PSBreakpoint cmdlet to create a breakpoint on the "Name" variable in the Sample.ps1 script. Then, it saves the breakpoint object in the $b variable.</maml:para> <maml:para>The second command uses the Disable-PSBreakpoint cmdlet to disable the new breakpoint. It uses a pipeline operator (|) to send the breakpoint object in $b to the Disable-PSBreakpoint cmdlet, and it uses the PassThru parameter of Disable-PSBreakpoint to display the disabled breakpoint object. This lets you verify that the value of the Enabled property of the breakpoint object is False.</maml:para> <maml:para>The third command uses the Enable-PSBreakpoint cmdlet to re-enable the breakpoint. It uses a pipeline operator (|) to send the breakpoint object in $b to the Enable-PSBreakpoint cmdlet, and it uses the PassThru parameter of Enable-PSBreakpoint to display the breakpoint object. This lets you verify that the value of the Enabled property of the breakpoint object is True.</maml:para> <maml:para>The results are shown in the following sample output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$b = get-psbreakpoint -id 3, 5 PS C:\>enable-psbreakpoint -breakpoint $b </dev:code> <dev:remarks> <maml:para>These commands enable a set of breakpoints by specifying their breakpoint objects.</maml:para> <maml:para>The first command uses the Get-PSBreakpoint cmdlet to get the breakpoints and saves them in the $b variable.</maml:para> <maml:para>The second command uses the Enable-PSBreakpoint cmdlet and its Breakpoint parameter to enable the breakpoints.</maml:para> <maml:para>This command is the equivalent of "enable-psbreakpoint -id 3, 5".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293954</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Disable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSCallStack</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Enable-RunspaceDebug</command:name> <maml:description> <maml:para>Enables debugging on runspaces where any breakpoint is preserved until a debugger is attached.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Enable</command:verb> <command:noun>RunspaceDebug</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This content is coming in a future release.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Enable-RunspaceDebug</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>BreakAll</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Enable-RunspaceDebug</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ProcessName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>AppDomainName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Enable-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Runspace[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>BreakAll</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Enable-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>BreakAll</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Enable-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceInstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>AppDomainName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>BreakAll</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ProcessName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Runspace[]</command:parameterValue> <dev:type> <maml:name>Runspace[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceInstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> <dev:type> <maml:name>Guid[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> 2: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Export-Alias</command:name> <maml:description> <maml:para>Exports information about currently defined aliases to a file.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Export</command:verb> <command:noun>Alias</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Export-Alias cmdlet exports the aliases in the current session to a file. If the output file does not exist, the cmdlet will create it.</maml:para> <maml:para>Export-Alias can export the aliases in a particular scope or all scopes, it can generate the data in CSV format or as a series of Set-Alias commands that you can add to a session or to a Windows PowerShell profile.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Export-Alias</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the output file. Wildcards are permitted, but the resulting path value must resolve to a single file name. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the names of the aliases to export. Wildcards are permitted.</maml:para> <maml:para>By default, Export-Alias exports all aliases in the session or scope.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Appends the output to the specified file, rather than overwriting the existing contents of that file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines the output format. CSV is the default.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- CSV: Comma-separated value (CSV) format.</maml:para> <maml:para>-- Script: Creates a Set-Alias command for each exported alias. If you name the output file with a .ps1 file name extension, you can run it as a script to add the aliases to any session.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Csv</command:parameterValue> <command:parameterValue required="false" variableLength="false">Script</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Adds a description to the exported file. The description appears as a comment at the top of the file, following the header information.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites the output file, even if the read-only attribute is set on the file.</maml:para> <maml:para>By default, Export-Alias overwrites files without warning, unless the read-only or hidden attribute is set or the NoClobber parameter is used in the command. The NoClobber parameter takes precedence over the Force parameter when both are used in a command.</maml:para> <maml:para>The Force parameter cannot force Export-Alias to overwrite files with the hidden attribute.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Prevents Export-Alias from overwriting any files, even if the Force parameter is used in the command.</maml:para> <maml:para>If the NoClobber parameter is omitted, Export-Alias will overwrite an existing file without warning, unless the read-only attribute is set on the file. NoClobber takes precedence over the Force parameter, which permits Export-Alias to overwrite a file with the read-only attribute.</maml:para> <maml:para>NoClobber does not prevent the Append parameter from adding content to an existing file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns objects that represent the aliases that were exported. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope from which the aliases should be exported.</maml:para> <maml:para>Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Export-Alias</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the names of the aliases to export. Wildcards are permitted.</maml:para> <maml:para>By default, Export-Alias exports all aliases in the session or scope.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Appends the output to the specified file, rather than overwriting the existing contents of that file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines the output format. CSV is the default.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- CSV: Comma-separated value (CSV) format.</maml:para> <maml:para>-- Script: Creates a Set-Alias command for each exported alias. If you name the output file with a .ps1 file name extension, you can run it as a script to add the aliases to any session.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Csv</command:parameterValue> <command:parameterValue required="false" variableLength="false">Script</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Adds a description to the exported file. The description appears as a comment at the top of the file, following the header information.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites the output file, even if the read-only attribute is set on the file.</maml:para> <maml:para>By default, Export-Alias overwrites files without warning, unless the read-only or hidden attribute is set or the NoClobber parameter is used in the command. The NoClobber parameter takes precedence over the Force parameter when both are used in a command.</maml:para> <maml:para>The Force parameter cannot force Export-Alias to overwrite files with the hidden attribute.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Prevents Export-Alias from overwriting any files, even if the Force parameter is used in the command.</maml:para> <maml:para>If the NoClobber parameter is omitted, Export-Alias will overwrite an existing file without warning, unless the read-only attribute is set on the file. NoClobber takes precedence over the Force parameter, which permits Export-Alias to overwrite a file with the read-only attribute.</maml:para> <maml:para>NoClobber does not prevent the Append parameter from adding content to an existing file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns objects that represent the aliases that were exported. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope from which the aliases should be exported.</maml:para> <maml:para>Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the output file. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Appends the output to the specified file, rather than overwriting the existing contents of that file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>As</maml:name> <maml:description> <maml:para>Determines the output format. CSV is the default.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- CSV: Comma-separated value (CSV) format.</maml:para> <maml:para>-- Script: Creates a Set-Alias command for each exported alias. If you name the output file with a .ps1 file name extension, you can run it as a script to add the aliases to any session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ExportAliasFormat</command:parameterValue> <dev:type> <maml:name>ExportAliasFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Adds a description to the exported file. The description appears as a comment at the top of the file, following the header information.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites the output file, even if the read-only attribute is set on the file.</maml:para> <maml:para>By default, Export-Alias overwrites files without warning, unless the read-only or hidden attribute is set or the NoClobber parameter is used in the command. The NoClobber parameter takes precedence over the Force parameter when both are used in a command.</maml:para> <maml:para>The Force parameter cannot force Export-Alias to overwrite files with the hidden attribute.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the output file. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the names of the aliases to export. Wildcards are permitted.</maml:para> <maml:para>By default, Export-Alias exports all aliases in the session or scope.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Prevents Export-Alias from overwriting any files, even if the Force parameter is used in the command.</maml:para> <maml:para>If the NoClobber parameter is omitted, Export-Alias will overwrite an existing file without warning, unless the read-only attribute is set on the file. NoClobber takes precedence over the Force parameter, which permits Export-Alias to overwrite a file with the read-only attribute.</maml:para> <maml:para>NoClobber does not prevent the Append parameter from adding content to an existing file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns objects that represent the aliases that were exported. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the output file. Wildcards are permitted, but the resulting path value must resolve to a single file name. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope from which the aliases should be exported.</maml:para> <maml:para>Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None.</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.AliasInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the Passthru parameter, Export-Alias returns a System.Management.Automation.AliasInfo object that represents the alias. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can only Export-Aliases to a file.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>export-alias -path alias.csv </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command exports current alias information to a file named Alias.csv in the current directory.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>export-alias -path alias.csv -noclobber </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command exports the aliases in the current session to an Alias.csv file.</maml:para> <maml:para>Because the NoClobber parameter is specified, the command will fail if an Alias.csv file already exists in the current directory.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>export-alias -path alias.csv -append -description "Appended Aliases" -force </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command appends the aliases in the current session to the Alias.csv file.</maml:para> <maml:para>The command uses the Description parameter to add a description to the comments at the top of the file.</maml:para> <maml:para>The command also uses the Force parameter to overwrite any existing Alias.csv files, even if they have the read-only attribute.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>export-alias -path alias.ps1 -as script PS C:\> add-content -path $profile -value (get-content alias.ps1) PS C:\> $s = new-pssession -computername Server01 PS C:\> invoke-command -session $s -filepath .\alias.ps1 </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This example shows how to use the script file format that Export-Alias generates.</maml:para> <maml:para>The first command exports the aliases in the session to the Alias.ps1 file. It uses the As parameter with a value of Script to generate a file that contains a Set-Alias command for each alias.</maml:para> <maml:para>The second command adds the aliases in the Alias.ps1 file to the CurrentUser-CurrentHost profile. (The path to the profile is saved in the $profile variable.) The command uses the Get-Content cmdlet to get the aliases from the Alias.ps1 file and the Add-Content cmdlet to add them to the profile. For more information, see about_Profiles.</maml:para> <maml:para>The third and fourth commands add the aliases in the Alias.ps1 file to a remote session on the Server01 computer. The third command uses the New-PSSession cmdlet to create the session. The fourth command uses the FilePath parameter of the Invoke-Command cmdlet to run the Alias.ps1 file in the new session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293955</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Export-Clixml</command:name> <maml:description> <maml:para>Creates an XML-based representation of an object or objects and stores it in a file.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Export</command:verb> <command:noun>Clixml</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Export-CliXml cmdlet creates an XML-based representation of an object or objects and stores it in a file. You can then use the Import-CliXml cmdlet to re-create the saved object based on the contents of that file.</maml:para> <maml:para>This cmdlet is similar to ConvertTo-XML, except that Export-CliXml stores the resulting XML in a file. ConvertTo-XML returns the XML, so you can continue to process it in Windows PowerShell.</maml:para> <maml:para>A valuable use of Export-CliXml is to export credentials and secure strings securely as XML. For an example of how to do this, see Example 3 in this topic.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Export-Clixml</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the file where the XML representation of the object will be stored.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the XML representation. The default value is 2.</maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of encoding for the target file. Valid values are ASCII, UTF8, UTF7, UTF32, Unicode, BigEndianUnicode, Default, and OEM. Unicode is the default.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Causes the cmdlet to clear the read-only attribute of the output file if necessary. The cmdlet will attempt to reset the read-only attribute when the command completes.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Ensures that the cmdlet does not overwrite the contents of an existing file. By default, if a file exists in the specified path, Export-Clixml overwrites the file without warning.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to Export-Clixml.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Export-Clixml</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the XML representation. The default value is 2.</maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of encoding for the target file. Valid values are ASCII, UTF8, UTF7, UTF32, Unicode, BigEndianUnicode, Default, and OEM. Unicode is the default.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Causes the cmdlet to clear the read-only attribute of the output file if necessary. The cmdlet will attempt to reset the read-only attribute when the command completes.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Ensures that the cmdlet does not overwrite the contents of an existing file. By default, if a file exists in the specified path, Export-Clixml overwrites the file without warning.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to Export-Clixml.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the file where the XML representation of the object will be stored. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the XML representation. The default value is 2.</maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of encoding for the target file. Valid values are ASCII, UTF8, UTF7, UTF32, Unicode, BigEndianUnicode, Default, and OEM. Unicode is the default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Causes the cmdlet to clear the read-only attribute of the output file if necessary. The cmdlet will attempt to reset the read-only attribute when the command completes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be converted. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe objects to Export-Clixml.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Ensures that the cmdlet does not overwrite the contents of an existing file. By default, if a file exists in the specified path, Export-Clixml overwrites the file without warning.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the file where the XML representation of the object will be stored.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the file where the XML representation of the object will be stored. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Export-Clixml.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.IO.FileInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Export-Clixml creates a file that contains the XML.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"This is a test" | export-clixml sample.xml </dev:code> <dev:remarks> <maml:para>This command creates an XML file that stores a representation of the string, "This is a test".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-acl C:\test.txt | export-clixml -Path fileacl.xml PS C:\>$fileacl = import-clixml fileacl.xml </dev:code> <dev:remarks> <maml:para>This example shows how to export an object to an XML file and then create an object by importing the XML from the file.</maml:para> <maml:para>The first command uses the Get-ACL cmdlet to get the security descriptor of the Test.txt file. It uses a pipeline operator to pass the security descriptor to Export-Clixml, which stores an XML-based representation of the object in a file named FileACL.xml.</maml:para> <maml:para>The second command uses the Import-Clixml cmdlet to create an object from the XML in the FileACL.xml file. Then, it saves the object in the $FileAcl variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$credxmlpath = Join-Path (Split-Path $profile) TestScript.ps1.credential PS C:\>$credential | Export-CliXml $credPath </dev:code> <dev:code>PS C:\>$credxmlpath = Join-Path (Split-Path $profile) TestScript.ps1.credential PS C:\>$credential = Import-CliXml $credxmlpath </dev:code> <dev:remarks> <maml:para>The Export-CliXml cmdlet encrypts credential objects by using the <maml:navigationLink><maml:linkText>Windows Data Protection API</maml:linkText><maml:uri></maml:uri></maml:navigationLink>. This ensures that only your user account can decrypt the contents of the credential object.</maml:para> <maml:para>In this example, given a credential that you�ve stored in the $credential variable by running the Get-Credential cmdlet, you can run the Export-CliXml cmdlet to save the credential to disk.In the example, the file in which the credential is stored is represented by TestScript.ps1.credential. Replace TestScript with the name of the script with which you are loading the credential.</maml:para> <maml:para>In the second command, pipe the credential object to Export-CliXml, and save it to the path, $credxmlpath, that you specified in the first command.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para>To import the credential automatically into your script, run the final two commands. This time, you are running Import-CliXml to import the secured credential object into your script. This eliminates the risk of exposing plain-text passwords in your script.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293956</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Use PowerShell to Pass Credentials to Legacy Systems</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Securely Store Credentials on Disk</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Html</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Xml</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Clixml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Export-Csv</command:name> <maml:description> <maml:para>Converts objects into a series of comma-separated (CSV) strings and saves the strings in a CSV file. </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Export</command:verb> <command:noun>Csv</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Export-CSV cmdlet creates a CSV file of the objects that you submit. Each object is represented as a line or row of the CSV. The row consists of a comma-separated list of the values of object properties. You can use this cmdlet to create spreadsheets and share data with programs that take CSV files as input.</maml:para> <maml:para>NOTE: Do not format objects before sending them to the Export-CSV cmdlet. If you do, the format properties are represented in the CSV file, instead of the properties of the original objects. To export only selected properties of an object, use the Select-Object cmdlet.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Export-Csv</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the CSV output file. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies a delimiter to separate the property values. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Adds the CSV output to the end of the specified file. Without this parameter, Export-CSV replaces the file contents without warning.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding for the exported CSV file. Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. The default is ASCII.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites the file specified in path without prompting.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the CSV output file. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Do not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Export-CSV overwrites the file without warning.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the type information from the CSV file. By default, the first line of the CSV file contains "#TYPE " followed by the fully-qualified name of the type of the object.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to Export-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Export-Csv</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the CSV output file. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Adds the CSV output to the end of the specified file. Without this parameter, Export-CSV replaces the file contents without warning.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding for the exported CSV file. Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. The default is ASCII.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites the file specified in path without prompting.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the CSV output file. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Do not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Export-CSV overwrites the file without warning.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the type information from the CSV file. By default, the first line of the CSV file contains "#TYPE " followed by the fully-qualified name of the type of the object.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Use the list separator for the current culture as the item delimiter. The default is a comma (,).</maml:para> <maml:para>This parameter is very useful in scripts that are being distributed to users worldwide. To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to Export-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Adds the CSV output to the end of the specified file. Without this parameter, Export-CSV replaces the file contents without warning.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies a delimiter to separate the property values. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> <dev:type> <maml:name>Char</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding for the exported CSV file. Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. The default is ASCII.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites the file specified in path without prompting.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to export as CSV strings. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe objects to Export-CSV.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Do not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Export-CSV overwrites the file without warning.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NTI"> <maml:name>NoTypeInformation</maml:name> <maml:description> <maml:para>Omits the type information from the CSV file. By default, the first line of the CSV file contains "#TYPE " followed by the fully-qualified name of the type of the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the CSV output file. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Use the list separator for the current culture as the item delimiter. The default is a comma (,).</maml:para> <maml:para>This parameter is very useful in scripts that are being distributed to users worldwide. To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the CSV output file. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object with an Extended Type System (ETS) adapter to Export-CSV.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The CSV list is sent to the file designated in the Path parameter.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The Export-CSV cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. You can use Export-CSV to save objects in a CSV file and then use the Import-CSV cmdlet to create objects from the text in the CSV file.</maml:para> <maml:para>In the CSV file, each object is represented by a comma-separated list of the property values of the object. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. Export-CSV does not export the methods of the object.</maml:para> <maml:para>The format of an exported file is as follows:</maml:para> <maml:para>-- The first line of the CSV file contains the string '#TYPE ' followed by the fully qualified name of the object, such as #TYPE System.Diagnostics.Process. To suppress this line, use the NoTypeInformation parameter.</maml:para> <maml:para>-- The next line of the CSV file represents the column headers. It contains a comma-separated list of the names of all the properties of the first object.</maml:para> <maml:para>-- Additional lines of the file consist of comma-separated lists of the property values of each object.</maml:para> </maml:alert> <maml:alert> <maml:para>When you submit multiple objects to Export-CSV, Export-CSV organizes the file based on the properties of the first object that you submit. If the remaining objects do not have one of the specified properties, the property value of that object is null, as represented by two consecutive commas. If the remaining objects have additional properties, those property values are not included in the file.</maml:para> </maml:alert> <maml:alert> <maml:para>You can use the Import-Csv cmdlet to re-create objects from the CSV strings in the files. The resulting objects are CSV versions of the original objects that consist of string representations of the property values and no methods.</maml:para> </maml:alert> <maml:alert> <maml:para>The ConvertTo-Csv and ConvertFrom-Csv cmdlets to convert objects to CSV strings (and back). Export-CSV is the same as ConvertTo-CSV, except that it saves the CSV strings in a file.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process wmiprvse | select-object basePriority,ID,SessionID,WorkingSet | export-csv -path data.csv </dev:code> <dev:remarks> <maml:para>This command selects a few properties of the WmiPrvse process and exports them to a CSV file named Data.csv.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | export-csv processes.csv PS C:\>get-process | export-csv processes.csv # In processes.csv #TYPE System.Diagnostics.Process __NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... </dev:code> <dev:remarks> <maml:para>This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. Because it does not specify a delimiter, a comma (,) is used to separate the fields in the file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | export-csv processes.csv -Delimiter ";" # In processes.csv #TYPE System.Diagnostics.Process __NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... Process;powershell;257;151920640;38322176;37052416;7836;C:\WINDOWS\... </dev:code> <dev:remarks> <maml:para>This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. It uses the Delimiter parameter to specify the semicolon (;). As a result, the fields in the file are separated by semicolons.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | export-csv processes.csv -UseCulture </dev:code> <dev:remarks> <maml:para>This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. It uses the UseCulture parameter to direct Export-CSV to use the delimiter specified by the ListSeparator property of the current culture.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | export-csv processes.csv -NoTypeInformation PS C:\>get-process | export-csv processes.csv -NoTypeInformation # In processes.csv __NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... </dev:code> <dev:remarks> <maml:para>This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. It uses the NoTypeInformation parameter to suppress the type information in the file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Get-ChildItem cmdlet to do a recursive search in the D: drive for files with the .ps1 file name extension. It uses a pipeline operator to sends the results to the Where-Object cmdlet, which gets only files that were created after January 1, 2011, and then saves them in the ScriptFiles variable. PS C:\>$scriptFiles = Get-ChildItem D:\* -include *.ps1 �recurse | where-object {$_.creationtime �gt "01/01/2011"} The second command uses the Select-Object cmdlet to select the relevant properties of the script files. It saves the revised results in the ScriptFiles variable. PS C:\>$scriptFiles = $scriptFiles | select-object �property Name, CreationTime, LastWriteTime, IsReadOnly The third command uses a pipeline operator (|) to send the script file information in the ScriptFiles variable to the Export-CSV cmdlet. The command uses the Path parameter to specify the output file and the Append parameter to add the new script data to the end of the output file, instead of replacing the existing file contents. PS C:\>$scriptFiles | export-csv �append �path \\Archive01\Scripts\Scripts.csv </dev:code> <dev:remarks> <maml:para>These commands add information about new Windows PowerShell scripts to a script inventory file.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command shows how to select properties of an object and export them to a CSV file. This command uses the Get-Date cmdlet to get the current date and time. It uses the Select-Object cmdlet to select the desired properties, and the Export-CSV cmdlet to export the object and its properties to the Date.csv file. The output shows the expected content in the Date.csv file. PS C:\>get-date | select-object �property DateTime, Day, DayOfWeek, DayOfYear | export-csv �path Date.csv #In Date.csv:"DateTime","Day","DayOfWeek","DayOfYear""Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" The second command shows that when you use the Format-Table cmdlet to format your data before exporting it, the output is not useful. PS C:\>get-date | format-table �property DateTime, Day, DayOfWeek, DayOfYear | export-csv �path Date.csv #In Date.csv: "ClassId2e4f51ef21dd47e99d3c952918aff9cd","pageHeaderEntry","pageFooterEntry","autosizeInfo","shapeInfo","groupingEntry""033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo","9e210fe47d09416682b841769c78b8a3",,,,,"27c87ef9bbda4f709f6b4002fa4af63c",,,,,"4ec4f0187cb04f4cb6973460dfe252df",,,,,"cf522b78d86c486691226b40aa69e95c",,,,, </dev:code> <dev:remarks> <maml:para>This example demonstrates one of most common problems that users encounter when using the Export-CSV cmdlet. It explains how to recognize and avoid this error.</maml:para> <maml:para>Because a CSV file has a table format, it might seem natural to use the Format-Table cmdlet to format the data in a table to prepare it for export as a CSV file. Also, the Format-Table cmdlet allows you to select object properties easily.</maml:para> <maml:para>However, when you format the data in a table and then export it, you are exporting a table object, not your original data object. The resulting CSV file is not useful.</maml:para> <maml:para>This example shows how to select object properties by using the Select-Object cmdlet, and it shows the Export-CSV formats the data correctly in a CSV file without any preparatory formatting by another cmdlet.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293957</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Format-Table</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Export-FormatData</command:name> <maml:description> <maml:para>Saves formatting data from the current session in a formatting file. </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Export</command:verb> <command:noun>FormatData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Export-FormatData cmdlet creates Windows PowerShell formatting files (format.ps1xml) from the formatting objects in the current session. It takes the ExtendedTypeDefinition objects that Get-FormatData returns and saves them in a file in XML format.</maml:para> <maml:para>Windows PowerShell uses the data in formatting files (format.ps1xml) to generate the default display of Microsoft .NET Framework objects in the session. You can view and edit the formatting files and use the Update-FormatData cmdlet to add the formatting data to a session.</maml:para> <maml:para>For more information about formatting files in Windows PowerShell, see about_Format.ps1xml.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Export-FormatData</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites an existing output file, even if the file has the read-only attribute.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IncludeScriptBlock</maml:name> <maml:description> <maml:para>Determines whether script blocks in the format data are exported.</maml:para> <maml:para>Because script blocks contain code and can be used maliciously, they are not exported by default.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Prevents the cmdlet from overwriting existing files. By default, Export-FormatData overwrites files without warning unless the file has the read-only attribute.</maml:para> <maml:para>To direct Export-FormatData to overwrite read-only files, use the Force parameter.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the format data objects to be exported. Enter a variable that contains the objects or a command that gets the objects, such as a Get-FormatData command. You can also pipe the objects from Get-FormatData to Export-FormatData.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">ExtendedTypeDefinition[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies a location for the output file. Enter a path (optional) and file name with a format.ps1xml file name extension. If you omit the path, Export-FormatData creates the file in the current directory.</maml:para> <maml:para>If you use a file name extension other than .ps1xml, the Update-FormatData cmdlet will not recognize the file.</maml:para> <maml:para>If you specify an existing file, Export-FormatData overwrites the file without warning, unless the file has the read-only attribute. To overwrite a read-only file, use the Force parameter. To prevent files from being overwritten, use the NoClobber parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Export-FormatData</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites an existing output file, even if the file has the read-only attribute.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IncludeScriptBlock</maml:name> <maml:description> <maml:para>Determines whether script blocks in the format data are exported.</maml:para> <maml:para>Because script blocks contain code and can be used maliciously, they are not exported by default.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Prevents the cmdlet from overwriting existing files. By default, Export-FormatData overwrites files without warning unless the file has the read-only attribute.</maml:para> <maml:para>To direct Export-FormatData to overwrite read-only files, use the Force parameter.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the format data objects to be exported. Enter a variable that contains the objects or a command that gets the objects, such as a Get-FormatData command. You can also pipe the objects from Get-FormatData to Export-FormatData.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">ExtendedTypeDefinition[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies a location for the output file. Unlike the Path parameter, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites an existing output file, even if the file has the read-only attribute.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IncludeScriptBlock</maml:name> <maml:description> <maml:para>Determines whether script blocks in the format data are exported.</maml:para> <maml:para>Because script blocks contain code and can be used maliciously, they are not exported by default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the format data objects to be exported. Enter a variable that contains the objects or a command that gets the objects, such as a Get-FormatData command. You can also pipe the objects from Get-FormatData to Export-FormatData.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">ExtendedTypeDefinition[]</command:parameterValue> <dev:type> <maml:name>ExtendedTypeDefinition[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Prevents the cmdlet from overwriting existing files. By default, Export-FormatData overwrites files without warning unless the file has the read-only attribute.</maml:para> <maml:para>To direct Export-FormatData to overwrite read-only files, use the Force parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies a location for the output file. Enter a path (optional) and file name with a format.ps1xml file name extension. If you omit the path, Export-FormatData creates the file in the current directory.</maml:para> <maml:para>If you use a file name extension other than .ps1xml, the Update-FormatData cmdlet will not recognize the file.</maml:para> <maml:para>If you specify an existing file, Export-FormatData overwrites the file without warning, unless the file has the read-only attribute. To overwrite a read-only file, use the Force parameter. To prevent files from being overwritten, use the NoClobber parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies a location for the output file. Unlike the Path parameter, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.ExtendedTypeDefinition </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe ExtendedTypeDefinition objects from Get-FormatData to Export-FormatData.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Export-FormatData does not return any objects. It generates a file and saves it in the specified path.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>To use any formatting file, including an exported formatting file, the execution policy for the session must allow scripts and configuration files to run. For more information, see about_Execution_Policies.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-formatdata -typename * | export-formatdata -path allformat.ps1xml -IncludeScriptBlock </dev:code> <dev:remarks> <maml:para>This command exports all of the format data in the session to the AllFormat.ps1xml file.</maml:para> <maml:para>The command uses the Get-FormatData cmdlet to get the format data in the session. A value of * (all) for the TypeName parameter directs the cmdlet to get all of the data in the session.</maml:para> <maml:para>The command uses a pipeline operator (|) to send the format data from the Get-FormatData command to the Export-FormatData cmdlet, which exports the format data to the AllFormat.ps1 file.</maml:para> <maml:para>The Export-FormatData command uses the IncludeScriptBlock parameter to include script blocks in the format data in the file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$f = get-formatdata -typename helpinfoshort PS C:\>export-formatdata -inputObject $f -path c:\test\help.format.ps1xml -IncludeScriptBlock </dev:code> <dev:remarks> <maml:para>These commands export the format data for the HelpInfoShort type to the Help.format.ps1xml file.</maml:para> <maml:para>The first command uses the Get-FormatData cmdlet to get the format data for the HelpInfoShort type, and it saves it in the $f variable.</maml:para> <maml:para>The second command uses the InputObject parameter of the Export-FormatData to enter the format data saved in the $f variable. It also uses the IncludeScriptBlock parameter to include script blocks in the output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-formatdata -typename System.Diagnostics.Process | export-FormatData -path process.format.ps1xml PS C:\>Update-FormatData -prependPath .\process.format.ps1xml PS C:\>get-process p* Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 323 5600 powershell 336 3900 powershell_ise 138 4076 PresentationFontCache </dev:code> <dev:remarks> <maml:para>This example shows the effect of omitting the IncludeScriptBlock parameter from an Export-FormatData command.</maml:para> <maml:para>The first command uses the Get-FormatData cmdlet to get the format data for the System.Diagnostics.Process object that the Get-Process cmdlet returns. The command uses a pipeline operator (|) to send the formatting data to the Export-FormatData cmdlet, which exports it to the Process.format.ps1xml file in the current directory.</maml:para> <maml:para>In this case, the Export-FormatData command does not use the IncludeScriptBlock parameter.</maml:para> <maml:para>The second command uses the Update-FormatData cmdlet to add the Process.format.ps1xml file to the current session. The command uses the PrependPath parameter to ensure that the formatting data for process objects in the Process.format.ps1xml file is found before the standard formatting data for process objects.</maml:para> <maml:para>The third command shows the effects of this change. The command uses the Get-Process cmdlet to get processes that have names that begin with "P". The output shows that property values that are calculated by using script blocks are missing from the display.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293958</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-FormatData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Update-FormatData</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Export-PSSession</command:name> <maml:description> <maml:para>Imports commands from another session and saves them in a Windows PowerShell module.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Export</command:verb> <command:noun>PSSession</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Export-PSSession cmdlet gets cmdlets, functions, aliases, and other command types from another PSSession on a local or remote computer and saves them in a Windows PowerShell module. To add the commands from the module to the current session, use the Import-Module cmdlet.</maml:para> <maml:para>Unlike Import-PSSession, which imports commands from another PSSession into the current session, Export-PSSession saves the commands in a module. The commands are not imported into the current session.</maml:para> <maml:para>To export commands, first use the New-PSSession cmdlet to create a PSSession that has the commands that you want to export. Then use the Export-PSSession cmdlet to export the commands. By default, Export-PSSession exports all commands, except for commands that exist in the current session, but you can use the CommandName parameters to specify the commands to export.</maml:para> <maml:para>The Export-PSSession cmdlet uses the implicit remoting feature of Windows PowerShell. When you import commands into the current session, they run implicitly in the original session or in a similar session on the originating computer.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Export-PSSession</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>Specifies the PSSession from which the commands are exported. Enter a variable that contains a session object or a command that gets a session object, such as a Get-PSSession command. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSSession</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="PSPath,ModuleName"> <maml:name>OutputModule</maml:name> <maml:description> <maml:para>Specifies a path (optional) and name for the module that Export-PSSession creates. The default path is $home\Documents\WindowsPowerShell\Modules. This parameter is required.</maml:para> <maml:para>If the module subdirectory or any of the files that Export-PSSession creates already exist, the command fails. To overwrite existing files, use the Force parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="3" aliases="Name"> <maml:name>CommandName</maml:name> <maml:description> <maml:para>Exports only the commands with the specified names or name patterns. Wildcards are permitted. Use "CommandName" or its alias, "Name".</maml:para> <maml:para>By default, Export-PSSession exports all commands from the PSSession except for commands that have the same names as commands in the current session. This prevents imported commands from hiding or replacing commands in the current session. To export all commands, even those that hide or replace other commands, use the AllowClobber parameter.</maml:para> <maml:para>If you use the CommandName parameter, the formatting files for the commands are not exported unless you use the FormatTypeName parameter. Similarly, if you use the FormatTypeName parameter, no commands are exported unless you use the CommandName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>FormatTypeName</maml:name> <maml:description> <maml:para>Exports formatting instructions only for the specified Microsoft .NET Framework types. Enter the type names. By default, Export-PSSession exports formatting instructions for all .NET Framework types that are not in the System.Management.Automation namespace.</maml:para> <maml:para>The value of this parameter must be the name of a type that is returned by a Get-FormatData command in the session from which the commands are being imported. To get all of the formatting data in the remote session, type *.</maml:para> <maml:para>If you use the FormatTypeName parameter, no commands are exported unless you use the CommandName parameter.</maml:para> <maml:para>Similarly, if you use the CommandName parameter, the formatting files for the commands are not exported unless you use the FormatTypeName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllowClobber</maml:name> <maml:description> <maml:para>Exports the specified commands, even if they have the same names as commands in the current session.</maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Exports the variant of the command that results from using the specified arguments (parameter values).</maml:para> <maml:para>For example, to export the variant of the Get-Item command in the certificate (Cert:) drive in the PSSession in $s, type "export-pssession -session $s -command get-item -argumentlist cert:".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used to sign the format files (*.Format.ps1xml) or script module files (.psm1) in the module that Export-PSSession creates. Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use the Get-PfxCertificate cmdlet or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate2</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Type"> <maml:name>CommandType</maml:name> <maml:description> <maml:para>Exports only the specified types of command objects. Use "CommandType" or its alias, "Type".</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Alias: All Windows PowerShell aliases in the current session.</maml:para> <maml:para>-- All: All command types. It is the equivalent of "get-command *".</maml:para> <maml:para>-- Application: All files other than Windows PowerShell files in paths listed in the Path environment variable ($env:path), including .txt, .exe, and .dll files.</maml:para> <maml:para>-- Cmdlet: The cmdlets in the current session. "Cmdlet" is the default.</maml:para> <maml:para>-- ExternalScript: All .ps1 files in the paths listed in the Path environment variable ($env:path).</maml:para> <maml:para>-- Filter and Function: All Windows PowerShell functions.</maml:para> <maml:para>-- Script: Script blocks in the current session.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Alias</command:parameterValue> <command:parameterValue required="false" variableLength="false">Function</command:parameterValue> <command:parameterValue required="false" variableLength="false">Filter</command:parameterValue> <command:parameterValue required="false" variableLength="false">Cmdlet</command:parameterValue> <command:parameterValue required="false" variableLength="false">ExternalScript</command:parameterValue> <command:parameterValue required="false" variableLength="false">Application</command:parameterValue> <command:parameterValue required="false" variableLength="false">Script</command:parameterValue> <command:parameterValue required="false" variableLength="false">Workflow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Configuration</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding for the output files. Valid values are "Unicode", "UTF7", "UTF8", "ASCII", "UTF32", "BigEndianUnicode", "Default", and "OEM". The default is "UTF-8".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites one or more existing output files, even if the file has the read-only attribute.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>FullyQualifiedModule</maml:name> <maml:description> <maml:para>Specifies modules with names that are specified in the form of ModuleSpecification objects (described by the Remarks section of <maml:navigationLink><maml:linkText>Module Specification Constructor (Hashtable)</maml:linkText><maml:uri></maml:uri></maml:navigationLink> on MSDN). For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format @{ModuleName = "modulename"; ModuleVersion = "version_number"} or @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. ModuleName and ModuleVersion are required, but Guid is optional.</maml:para> <maml:para>You cannot specify the FullyQualifiedModule parameter in the same command as a Module parameter; the two parameters are mutually exclusive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">ModuleSpecification[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PSSnapin"> <maml:name>Module</maml:name> <maml:description> <maml:para>Exports only the commands in the specified Windows PowerShell snap-ins and modules. Enter the snap-in and module names. Wildcards are not permitted.</maml:para> <maml:para>For more information, see about_PSSnapins and Import-Module.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllowClobber</maml:name> <maml:description> <maml:para>Exports the specified commands, even if they have the same names as commands in the current session.</maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Exports the variant of the command that results from using the specified arguments (parameter values).</maml:para> <maml:para>For example, to export the variant of the Get-Item command in the certificate (Cert:) drive in the PSSession in $s, type "export-pssession -session $s -command get-item -argumentlist cert:".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="3" aliases="Name"> <maml:name>CommandName</maml:name> <maml:description> <maml:para>Exports only the commands with the specified names or name patterns. Wildcards are permitted. Use "CommandName" or its alias, "Name".</maml:para> <maml:para>By default, Export-PSSession exports all commands from the PSSession except for commands that have the same names as commands in the current session. This prevents imported commands from hiding or replacing commands in the current session. To export all commands, even those that hide or replace other commands, use the AllowClobber parameter.</maml:para> <maml:para>If you use the CommandName parameter, the formatting files for the commands are not exported unless you use the FormatTypeName parameter. Similarly, if you use the FormatTypeName parameter, no commands are exported unless you use the CommandName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Type"> <maml:name>CommandType</maml:name> <maml:description> <maml:para>Exports only the specified types of command objects. Use "CommandType" or its alias, "Type".</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Alias: All Windows PowerShell aliases in the current session.</maml:para> <maml:para>-- All: All command types. It is the equivalent of "get-command *".</maml:para> <maml:para>-- Application: All files other than Windows PowerShell files in paths listed in the Path environment variable ($env:path), including .txt, .exe, and .dll files.</maml:para> <maml:para>-- Cmdlet: The cmdlets in the current session. "Cmdlet" is the default.</maml:para> <maml:para>-- ExternalScript: All .ps1 files in the paths listed in the Path environment variable ($env:path).</maml:para> <maml:para>-- Filter and Function: All Windows PowerShell functions.</maml:para> <maml:para>-- Script: Script blocks in the current session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CommandTypes</command:parameterValue> <dev:type> <maml:name>CommandTypes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding for the output files. Valid values are "Unicode", "UTF7", "UTF8", "ASCII", "UTF32", "BigEndianUnicode", "Default", and "OEM". The default is "UTF-8".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites one or more existing output files, even if the file has the read-only attribute.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>FormatTypeName</maml:name> <maml:description> <maml:para>Exports formatting instructions only for the specified Microsoft .NET Framework types. Enter the type names. By default, Export-PSSession exports formatting instructions for all .NET Framework types that are not in the System.Management.Automation namespace.</maml:para> <maml:para>The value of this parameter must be the name of a type that is returned by a Get-FormatData command in the session from which the commands are being imported. To get all of the formatting data in the remote session, type *.</maml:para> <maml:para>If you use the FormatTypeName parameter, no commands are exported unless you use the CommandName parameter.</maml:para> <maml:para>Similarly, if you use the CommandName parameter, the formatting files for the commands are not exported unless you use the FormatTypeName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>FullyQualifiedModule</maml:name> <maml:description> <maml:para>Specifies modules with names that are specified in the form of ModuleSpecification objects (described by the Remarks section of <maml:navigationLink><maml:linkText>Module Specification Constructor (Hashtable)</maml:linkText><maml:uri></maml:uri></maml:navigationLink> on MSDN). For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format @{ModuleName = "modulename"; ModuleVersion = "version_number"} or @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. ModuleName and ModuleVersion are required, but Guid is optional.</maml:para> <maml:para>You cannot specify the FullyQualifiedModule parameter in the same command as a Module parameter; the two parameters are mutually exclusive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">ModuleSpecification[]</command:parameterValue> <dev:type> <maml:name>ModuleSpecification[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PSSnapin"> <maml:name>Module</maml:name> <maml:description> <maml:para>Exports only the commands in the specified Windows PowerShell snap-ins and modules. Enter the snap-in and module names. Wildcards are not permitted.</maml:para> <maml:para>For more information, see about_PSSnapins and Import-Module.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="PSPath,ModuleName"> <maml:name>OutputModule</maml:name> <maml:description> <maml:para>Specifies a path (optional) and name for the module that Export-PSSession creates. The default path is $home\Documents\WindowsPowerShell\Modules. This parameter is required.</maml:para> <maml:para>If the module subdirectory or any of the files that Export-PSSession creates already exist, the command fails. To overwrite existing files, use the Force parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>Specifies the PSSession from which the commands are exported. Enter a variable that contains a session object or a command that gets a session object, such as a Get-PSSession command. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSSession</command:parameterValue> <dev:type> <maml:name>PSSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used to sign the format files (*.Format.ps1xml) or script module files (.psm1) in the module that Export-PSSession creates. Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use the Get-PfxCertificate cmdlet or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to Export-PSSession.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.IO.FileInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Export-PSSession returns a list of files that comprise the module that it created.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Export-PSSession relies on the Windows PowerShell remoting infrastructure. To use this cmdlet, the computer must be configured for remoting. For more information, see about_Remote_Requirements.</maml:para> <maml:para>You cannot use Export-PSSession to export a Windows PowerShell provider.</maml:para> <maml:para>Exported commands run implicitly in the PSSession from which they were exported. However, the details of running the commands remotely are handled entirely by Windows PowerShell. You can run the exported commands just as you would run local commands.</maml:para> <maml:para>Export-Module captures and saves information about the PSSession in the module that it exports. If the PSSession from which the commands were exported is closed when you import the module, and there are no active PSSessions to the same computer, the commands in the module attempt to re-create the PSSession. If attempts to re-create the PSSession fail, the exported commands will not run.</maml:para> <maml:para>The session information that Export-Module captures and saves in the module does not include session options, such as those that you specify in the $PSSessionOption preference variable or by using the SessionOption parameters of the New-PSSession, Enter-PSSession, or Invoke-Command cmdlet. If the original PSSession is closed when you import the module, the module will use another PSSession to the same computer, if one is available. To enable the imported commands to run in a correctly configured session, create a PSSession with the options that you want before you import the module.</maml:para> <maml:para>To find the commands to export, Export-PSSession uses the Invoke-Command cmdlet to run a Get-Command command in the PSSession. To get and save formatting data for the commands, it uses the Get-FormatData and Export-FormatData cmdlets. You might see error messages from Invoke-Command, Get-Command, Get-FormatData, and Export-FormatData when you run an Export-PSSession command. Also, Export-PSSession cannot export commands from a session that does not include the Get-Command, Get-FormatData, Select-Object, and Get-Help cmdlets.</maml:para> <maml:para>Export-PSSession uses the Write-Progress cmdlet to display the progress of the command. You might see the progress bar while the command is running.</maml:para> <maml:para>Exported commands have the same limitations as other remote commands, including the inability to start a program with a user interface, such as Notepad.</maml:para> <maml:para>Because Windows PowerShell profiles are not run in PSSessions, the commands that a profile adds to a session are not available to Export-PSSession. To export commands from a profile, use an Invoke-Command command to run the profile in the PSSession manually before exporting commands.</maml:para> <maml:para>The module that Export-PSSession creates might include a formatting file, even if the command does not import formatting data. If the command does not import formatting data, any formatting files that are created will not contain formatting data.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = new-pssession -computerName Server01 PS C:\>export-pssession -session $s -outputModule Server01 </dev:code> <dev:remarks> <maml:para>The commands in this example export all commands from a PSSession on the Server01 computer to the Server01 module on the local computer except for commands that have the same names as commands in the current session. It also exports the formatting data for the commands.</maml:para> <maml:para>The first command creates a PSSession on the Server01 computer. The second command exports the commands and formatting data from the session into the Server01 module.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = new-pssession -ConnectionUri http://exchange.microsoft.com/mailbox -credential exchangeadmin01@hotmail.com -authentication negotiate PS C:\>export-pssession -session $r -module exch* -commandname get-*, set-* -formattypename * -outputModule $pshome\Modules\Exchange -encoding ASCII </dev:code> <dev:remarks> <maml:para>These commands export the Get and Set commands from a Microsoft Exchange Server snap-in on a remote computer to an Exchange module in the $pshome\Modules directory on the local computer.</maml:para> <maml:para>Placing the module in the $pshome\Module directory makes it accessible to all users of the computer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = new-pssession -computerName Server01 -credential Server01\User01 PS C:\>export-pssession -session $s -outputModule TestCmdlets -type cmdlet -commandname *test* -formattypename * PS C:\>remove-pssession $s PS C:\>import-module TestCmdlets PS C:\>get-help test* PS C:\>test-files </dev:code> <dev:remarks> <maml:para>These commands export cmdlets from a PSSession on a remote computer and save them in a module on the local computer. Then, the commands add the cmdlets from the module to the current session so that they can be used.</maml:para> <maml:para>The first command creates a PSSession on the Server01 computer and saves it in the $s variable.</maml:para> <maml:para>The second command exports the cmdlets whose names begin with "Test" from the PSSession in $s to the TestCmdlets module on the local computer.</maml:para> <maml:para>The third command uses the Remove-PSSession cmdlet to delete the PSSession in $s from the current session. This command shows that the PSSession need not be active to use the commands that were imported from it.</maml:para> <maml:para>The fourth command, which can be run in any session at any time, uses the Import-Module cmdlet to add the cmdlets in the TestCmdlets module to the current session.</maml:para> <maml:para>The fifth command uses the Get-Help cmdlet to get help for cmdlets whose names begin with "Test." After the commands in a module are added to the current session, you can use the Get-Help and Get-Command cmdlets to learn about the imported commands, just as you would use them for any command in the session.</maml:para> <maml:para>The sixth command uses the Test-Files cmdlet, which was exported from the Server01 computer and added to the session.</maml:para> <maml:para>Although it is not evident, the Test-Files command actually runs in a remote session on the computer from which the command was imported. Windows PowerShell creates a session from information that is stored in the module.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>export-pssession -session $s -AllowClobber -outputModule AllCommands </dev:code> <dev:remarks> <maml:para>This command exports all commands and all formatting data from the PSSession in the $s variable into the current session. The command uses the AllowClobber parameter to include commands with the same names as commands in the current session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$options = New-PSSessionOption -NoMachineProfile PS C:\>$s = new-pssession -computername Server01 -sessionoption $options PS C:\>export-pssession -session $s -outputModule Server01 PS C:\>remove-pssession $s PS C:\>new-pssession -computername Server01 -sessionoption $options PS C:\>import-module Server01 </dev:code> <dev:remarks> <maml:para>This example shows how to run the exported commands in a session with particular options when the PSSession from which the commands were exported is closed.</maml:para> <maml:para>When you use Export-PSSession, it saves information about the original PSSession in the module that it creates. When you import the module, if the original remote session is closed, the module will use any open remote session that connects to originating computer.</maml:para> <maml:para>If the current session does not include a remote session to the originating computer, the commands in the module will re-establish a session to that computer. However, Export-PSSession does not save special options, such as those set by using the SessionOption parameter of New-PSSession, in the module.</maml:para> <maml:para>Therefore, if you want to run the exported commands in a remote session with particular options, you need to create a remote session with the options that you want before you import the module.</maml:para> <maml:para>The first command uses the New-PSSessionOption cmdlet to create a PSSessionOption object, and it saves the object in the $options variable.</maml:para> <maml:para>The second command creates a PSSession that includes the specified options. The command uses the New-PSSession cmdlet to create a PSSession on the Server01 computer. It uses the SessionOption parameter to submit the option object in $options.</maml:para> <maml:para>The third command uses the Export-PSSession cmdlet to export commands from the PSSession in $s to the Server01 module.</maml:para> <maml:para>The fourth command uses the Remove-PSSession cmdlet to delete the PSSession in the $s variable.</maml:para> <maml:para>The fifth command uses the New-PSSession cmdlet to create a new PSSession that connects to the Server01 computer. This PSSession also uses the session options in the $options variable.</maml:para> <maml:para>The sixth command uses the Import-Module cmdlet to import the commands from the Server01 module. The commands in the module run in the PSSession on the Server01 computer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293959</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Module</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-PSSession</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-Command</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-PSSession</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Command_Precedence</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_PSSessions</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Format-Custom</command:name> <maml:description> <maml:para>Uses a customized view to format the output.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Format</command:verb> <command:noun>Custom</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Format-Custom cmdlet formats the output of a command as defined in an alternate view. Format-Custom is designed to display views that are not just tables or just lists. You can use the views defined in the *format.PS1XML files in the Windows PowerShell directory, or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to add them to Windows PowerShell.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Format-Custom</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- Depth <int32></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies the number of columns in the display.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">CoreOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">EnumOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Both</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate format or "view." If you omit this parameter, Format-Custom uses a default custom view. You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies the number of columns in the display.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- Depth <int32></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate format or "view." If you omit this parameter, Format-Custom uses a default custom view. You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Format-Custom</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.Internal.Format</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Format-Custom returns the format objects that represent the display.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Format-Custom is designed to display views that are not just tables or just lists. To display an alternate table view, use Format-Table. To display an alternate list view, use Format-List.</maml:para> <maml:para>You can also refer to Format-Custom by its built-in alias, "fc". For more information, see about_Aliases.</maml:para> <maml:para>The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-command start-transcript | format-custom -view MyView </dev:code> <dev:remarks> <maml:para>This command formats information about the Start-Transcript cmdlet in the format defined by the MyView view, a custom view created by the user. To run this command successfully, you must first create a new PS1XML file, define the MyView view, and then use the Update-FormatData command to add the PS1XML file to Windows PowerShell.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process Winlogon | format-custom </dev:code> <dev:remarks> <maml:para>This command formats information about the Winlogon process in an alternate customized view. Because the command does not use the View parameter, Format-Custom uses a default custom view to format the data.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293960</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Format-List</command:name> <maml:description> <maml:para>Formats the output as a list of properties in which each property appears on a new line.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Format</command:verb> <command:noun>List</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Format-List cmdlet formats the output of a command as a list of properties in which each property is displayed on a separate line. You can use Format-List to format and display all or selected properties of an object as a list (format-list *).</maml:para> <maml:para>Because more space is available for each item in a list than in a table, Windows PowerShell displays more properties of the object in the list, and the property values are less likely to be truncated.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Format-List</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-List command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">CoreOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">EnumOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Both</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-List command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate list format or "view." You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-List command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-List command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-List DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate list format or "view." You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Format-List.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.Internal.Format</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Format-List returns the format objects that represent the list.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also refer to Format-List by its built-in alias, "FL". For more information, see about_Aliases.</maml:para> <maml:para>The format cmdlets, such as Format-List, arrange the data to be displayed but do not display it. The data is displayed by the output features of Windows PowerShell and by the cmdlets that contain the Out verb (the Out cmdlets), such as Out-Host, Out-File, and Out-Printer.</maml:para> <maml:para>If you do not use a format cmdlet, Windows PowerShell applies that default format for each object that it displays.</maml:para> <maml:para>The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.</maml:para> <maml:para>The View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory, or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to include them in Windows PowerShell.</maml:para> <maml:para>The alternate view for the View parameter must use the list format; if not, the command fails. If the alternate view is a table, use Format-Table. If the alternate view is neither a list nor a table, use Format-Custom.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | format-list </dev:code> <dev:remarks> <maml:para>This command formats information about services on the computer as a list. By default, the services are formatted as a table. The Get-Service cmdlet gets objects representing the services on the computer. The pipeline operator (|) passes the results through the pipeline to Format-List. Then, the Format-List command formats the service information in a list and sends it to the default output cmdlet for display.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = get-childitem $pshome\*.ps1xml PS C:\>format-list -InputObject $a </dev:code> <dev:remarks> <maml:para>These commands display information about the PS1XML files in the Windows PowerShell directory as a list.</maml:para> <maml:para>The first command gets the objects representing the files and stores them in the $a variable.</maml:para> <maml:para>The second command uses Format-List to format information about objects stored in $a. This command uses the InputObject parameter to pass the variable to Format-List, which then sends the formatted output to the default output cmdlet for display.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | format-list -property name, basepriority, priorityclass </dev:code> <dev:remarks> <maml:para>This command displays the name, base priority, and priority class of each process on the computer. It uses the Get-Process cmdlet to get an object representing each process. The pipeline operator (|) passes the process objects through the pipeline to Format-List. Format-List formats the processes as a list of the specified properties. The "Property" parameter name is optional, so you can omit it.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process winlogon | format-list -property * </dev:code> <dev:remarks> <maml:para>This command displays all of the properties of the Winlogon process. It uses the Get-Process cmdlet to get an object representing the Winlogon process. The pipeline operator (|) passes the Winlogon process object through the pipeline to Format-List. The command uses the Property parameter to specify the properties and the * to indicate all properties. Because the name of the Property parameter is optional, you can omit it and type the command as: "format-list *". Format-List automatically sends the results to the default output cmdlet for display.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293961</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Format-Table</command:name> <maml:description> <maml:para>Formats the output as a table.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Format</command:verb> <command:noun>Table</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Format-Table cmdlet formats the output of a command as a table with the selected properties of the object in each column. The object type determines the default layout and properties that are displayed in each column, but you can use the Property parameter to select the properties that you want to see.</maml:para> <maml:para>You can also use a hash table to add calculated properties to an object before displaying it and to specify the column headings in the table. To add a calculated property, use the Property or GroupBy parameters.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Format-Table</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Type one or more property names (separated by commas), or use a hash table to display a calculated property. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> <maml:para>-- Width <int32></maml:para> <maml:para>-- Alignment (value can be "Left", "Center", or "Right")</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AutoSize</maml:name> <maml:description> <maml:para>Adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">CoreOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">EnumOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Both</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Arranges sorted output in separate tables based on a property value. For example, you can use GroupBy to list services in separate tables based on their status.</maml:para> <maml:para>Enter an expression or a property of the output. The output must be sorted before you send it to Format-Table.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>HideTableHeaders</maml:name> <maml:description> <maml:para>Omits the column headings from the table.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringameter</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate table format or "view." You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wrap</maml:name> <maml:description> <maml:para>Displays text that exceeds the column width on the next line. By default, text that exceeds the column width is truncated.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AutoSize</maml:name> <maml:description> <maml:para>Adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Arranges sorted output in separate tables based on a property value. For example, you can use GroupBy to list services in separate tables based on their status.</maml:para> <maml:para>Enter an expression or a property of the output. The output must be sorted before you send it to Format-Table.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>HideTableHeaders</maml:name> <maml:description> <maml:para>Omits the column headings from the table.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreferenceameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreferenceameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringameter</command:parameterValue> <dev:type> <maml:name>System.Stringameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Type one or more property names (separated by commas), or use a hash table to display a calculated property. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> <maml:para>-- Width <int32></maml:para> <maml:para>-- Alignment (value can be "Left", "Center", or "Right")</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate table format or "view." You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wrap</maml:name> <maml:description> <maml:para>Displays text that exceeds the column width on the next line. By default, text that exceeds the column width is truncated.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Format-Table.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.Internal.Format</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Format-Table returns format objects that represent the table.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The GroupBy parameter assumes that the objects are sorted. Before using Format-Table to group the objects, use the Sort-Object cmdlet to sort them.</maml:para> </maml:alert> <maml:alert> <maml:para>The View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory or you can create your own views in new PS1XML files and then use the TUpdate-FormatData cmdlet to include them in Windows PowerShell.</maml:para> </maml:alert> <maml:alert> <maml:para>The alternate views for the View parameter must use the table format. If it does not, the command fails. If the alternate view is a list, use the Format-List cmdlet. If the alternate view is neither a list nor a table, use the T:Microsoft.PowerShell.Commands.Format-Custom cmdlet.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-pssnapin | format-table -auto </dev:code> <dev:remarks> <maml:para>This command formats information about Windows PowerShell snap-ins in a table. By default, they are formatted in a list. The Get-PSSnapin cmdlet gets objects representing the snap-ins. The pipeline operator (|) passes the object to the Format-Table command. Format-Table formats the objects in a table. The Autosize parameter adjusts the column widths to minimize truncation.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | sort-object -property basepriority | format-table -groupby basepriority -wrap </dev:code> <dev:remarks> <maml:para>This command displays the processes on the computer in groups with the same base priority.</maml:para> <maml:para>The Get-Process cmdlet gets objects representing each process on the computer. The pipeline operator (|) passes the object to the Sort-Object cmdlet, which sorts the objects in order of their base priority.</maml:para> <maml:para>Another pipeline operator passes the results to the Format-Table cmdlet. The GroupBy parameter arranges the data about the processes into groups based on the value of their BasePriority property. The Wrap parameter ensures that data is not truncated.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | sort-object starttime | format-table -view starttime </dev:code> <dev:remarks> <maml:para>This command displays information about the processes on the computer in group based on the start date of the process. It uses the Get-Process cmdlet to get objects representing the processes on the computer. The pipeline operator (|) sends the output of Get-Process to the Sort-Object cmdlet, which sorts it based on the StartTime property. Another pipeline operator sends the sorted results to Format-Table.</maml:para> <maml:para>The View parameter is used to select the StartTime view that is defined in the DotNetTypes.format.ps1xml formatting file for System.Diagnostics.Process objects, such as those returned by Get-Process. This view converts the StartTime of the process to a short date and then groups the processes by start date.</maml:para> <maml:para>The DotNetTypes.format.ps1xml formatting file also contains a Priority view for processes, and you can create your own format.ps1xml files with customized views.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | format-table -property Name, DependentServices </dev:code> <dev:remarks> <maml:para>This command displays all of the services on the computer in a table with two columns, Name and DependentServices. The command uses the Get-Service cmdlet to get all of the services on the computer. The pipeline operator (|) sends the results to the Format-Table cmdlet, which formats the output in a table. The Property parameter specifies the properties that appear in the table as columns. The name of the Property parameter is optional, so you can omit it ("format-table name, dependentservices").</maml:para> <maml:para>Property and DependentServices are just two of the properties of service objects. To view all of the properties, type "get-service | get-member".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process notepad | format-table ProcessName, @{Label="TotalRunningTime"; Expression={(get-date) - $_.StartTime}} </dev:code> <dev:remarks> <maml:para>This command shows how to use a calculated property in a table. The command displays a table with the process name and total running time of all Notepad processes on the local computer. The total running time is calculated by subtracting the start time of each process from the current time.</maml:para> <maml:para>The command uses the Get-Process cmdlet to get all processes named "Notepad" on the local computer. The pipeline operator (|) sends the results to Format-Table, which displays a table with two columns: ProcessName, a standard property of processes, and TotalRunningTime, a calculated property.</maml:para> <maml:para>The TotalRunningTime property is specified by a hash table with two keys, Label and Expression. The name of the property is assigned to the Label key. The calculation is assigned to the Expression key. The expression gets the StartTime property of each process object and subtracts it from the result of a Get-Date command, which gets the current date (and time).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$processes = get-wmiobject -ComputerName Server01 win32_process -filter "name='notepad.exe'" PS C:\>$processes | format-table ProcessName, @{ Label = "Total Running Time"; Expression={(get-date) - $_.ConvertToDateTime($_.CreationDate)}} </dev:code> <dev:remarks> <maml:para>These commands are similar to the previous command, except that these commands use the Get-WmiObject cmdlet and the Win32_Process class to display information about Notepad processes on a remote computer.</maml:para> <maml:para>The first command uses the Get-WmiObject cmdlet to get instances of the Windows Management Instrumentation (WMI) Win32_Process class that describes all of the processes on the Server01 computer that are named Notepad.exe. The command stores the process information in the $processes variable.</maml:para> <maml:para>The second command uses a pipeline operator (|) to send the process information in the $processes variable to the Format-Table cmdlet, which displays the ProcessName of each process along with a new calculated property.</maml:para> <maml:para>The command assigns the name of the new calculated property, Total Running Time, to the Label key. The script block that is assigned to the Expression key calculates how long the process has been running by subtracting the creation date of the process from the current date. The Get-Date cmdlet gets the current date. The ConvertToDateTime method converts the CreationDate property of the Win32_Process object from a WMI CIM_DATETIME object to a Microsoft .NET Framework DateTime object that can be compared with the output of Get-Date. Then, the converted creation date is subtracted from the current date. The result is the value of Total Running Time.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293962</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Format-Custom</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Format-List</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Format-Wide</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Format-Wide</command:name> <maml:description> <maml:para>Formats objects as a wide table that displays only one property of each object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Format</command:verb> <command:noun>Wide</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Format-Wide cmdlet formats objects as a wide table that displays only one property of each object. You can use the Property parameter to determine which property is displayed.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Format-Wide</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AutoSize</maml:name> <maml:description> <maml:para>Adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view. You cannot use the AutoSize and Column parameters in the same command.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Column</maml:name> <maml:description> <maml:para>Specifies the number of columns in the display. You cannot use the AutoSize and Column parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">CoreOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">EnumOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Both</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate table format or "view." You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AutoSize</maml:name> <maml:description> <maml:para>Adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view. You cannot use the AutoSize and Column parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Column</maml:name> <maml:description> <maml:para>Specifies the number of columns in the display. You cannot use the AutoSize and Column parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayError</maml:name> <maml:description> <maml:para>Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError DayOfWeek� $_ / $null --------- ------------ Wednesday #ERR</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Expand</maml:name> <maml:description> <maml:para>Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- EnumOnly: Displays the properties of the objects in the collection.</maml:para> <maml:para>-- CoreOnly: Displays the properties of the collection object.</maml:para> <maml:para>-- Both: Displays the properties of the collection object and the properties of objects in the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>GroupBy</maml:name> <maml:description> <maml:para>Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.</maml:para> <maml:para>The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be formatted. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.</maml:para> <maml:para>If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name ("Property") is optional. You cannot use the Property and View parameters in the same command.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- FormatString <string></maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ShowError</maml:name> <maml:description> <maml:para>Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. The following shows an example of the results of adding the ShowError parameter with an expression.</maml:para> <maml:para>PS > Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday</maml:para> <maml:para>Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Specifies the name of an alternate table format or "view." You cannot use the Property and View parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Format-Wide.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.Internal.Format</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Format-Wide returns format objects that represent the table.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also refer to Format-Wide by its built-in alias, "fw". For more information, see about_Aliases. The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them. The -View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to include them in Windows PowerShell. The alternate view for the View parameter must use table format; if it does not, the command fails. If the alternate view is a list, use Format-List. If the alternate view is neither a list nor a table, use Format-Custom.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | format-wide -column 3 </dev:code> <dev:remarks> <maml:para>This command displays the names of files in the current directory in three columns across the screen. The Get-ChildItem cmdlet gets objects representing each file in the directory. The pipeline operator (|) passes the file objects through the pipeline to Format-Wide, which formats them for output. The Column parameter specifies the number of columns.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem HKCU:\software\microsoft | format-wide -property pschildname -autosize </dev:code> <dev:remarks> <maml:para>This command displays the names of registry keys in the HKEY_CURRENT_USER\Software\Microsoft key. The Get-ChildItem cmdlet gets objects representing the keys. The path is specified as "HKCU:", one of the drives exposed by the Windows PowerShell Registry provider, followed by the key path. The pipeline operator (|) passes the registry key objects through the pipeline to Format-Wide, which formats them for output. The Property parameter specifies the name of the property, and the AutoSize parameter adjusts the columns for readability.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293963</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Alias</command:name> <maml:description> <maml:para>Gets the aliases for the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Alias</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Alias cmdlet gets the aliases (alternate names for commands and executable files) in the current session. This includes built-in aliases, aliases that you have set or imported, and aliases that you have added to your Windows PowerShell profile.</maml:para> <maml:para>By default, Get-Alias takes an alias and returns the command name. When you use the Definition parameter, Get-Alias takes a command name and returns its aliases.</maml:para> <maml:para>Beginning in Windows PowerShell 3.0, Get-Alias displays non-hyphenated alias names in an "<alias> -> <definition>" format to make it even easier to find the information that you need.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Alias</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the aliases to retrieve. Wildcards are permitted. By default, Get-Alias retrieves all aliases defined for the current session. The parameter name ("Name") is optional. You can also pipe alias names to Get-Alias.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name and Definition parameters. Enter a name, a definition, or a pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Gets only the aliases in the specified scope. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Alias</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Definition</maml:name> <maml:description> <maml:para>Gets the aliases for the specified item. Enter the name of a cmdlet, function, script, file, or executable file.</maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name and Definition parameters. Enter a name, a definition, or a pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Gets only the aliases in the specified scope. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Definition</maml:name> <maml:description> <maml:para>Gets the aliases for the specified item. Enter the name of a cmdlet, function, script, file, or executable file.</maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name and Definition parameters. Enter a name, a definition, or a pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the aliases to retrieve. Wildcards are permitted. By default, Get-Alias retrieves all aliases defined for the current session. The parameter name ("Name") is optional. You can also pipe alias names to Get-Alias.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Gets only the aliases in the specified scope. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe alias names to Get-Alias.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.AliasInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Alias returns an object that represents each alias. Get-Alias returns the same object for every alias, but Windows PowerShell uses an arrow-based format to display the names of non-hyphenated aliases.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>To create a new alias, use Set-Alias or New-Alias. To delete an alias, use Remove-Item.</maml:para> </maml:alert> <maml:alert> <maml:para>The arrow-based alias name format is not used for aliases that include a hyphen. These are likely to be preferred substitute names for cmdlets and functions, instead of typical abbreviations or nicknames.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Alias CommandType Name ----------- ---- Alias % -> ForEach-Object Alias ? -> Where-Object Alias ac -> Add-Content Alias asnp -> Add-PSSnapin Alias cat -> Get-Content Alias cd -> Set-Location Alias chdir -> Set-Location Alias clc -> Clear-Content Alias clear -> Clear-Host Alias clhy -> Clear-History � </dev:code> <dev:remarks> <maml:para>This command gets all aliases in the current session.</maml:para> <maml:para>The output shows the "<alias> -> <definition>" format that was introduced in Windows PowerShell 3.0. This format is used only for aliases that do not include hyphens, because aliases with hyphens are typically preferred names for cmdlets and functions, rather than nicknames.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Alias -Name g*, s* -Exclude Get-* </dev:code> <dev:remarks> <maml:para>This command gets all aliases that begin with "g" or "s", except for aliases that begin with "get-".</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Alias -Definition Get-ChildItem </dev:code> <dev:remarks> <maml:para>This command gets the aliases for the Get-ChildItem cmdlet.</maml:para> <maml:para>By default, the Get-Alias cmdlet gets the item name when you know the alias. The Definition parameter gets the alias when you know the item name.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Alias | Where-Object {$_.Options -Match "ReadOnly"} </dev:code> <dev:remarks> <maml:para>This command retrieves all aliases in which the value of the Options property is ReadOnly. This command provides a quick way to find the aliases that are built into Windows PowerShell, because they have the ReadOnly option.</maml:para> <maml:para>Options is just one property of the AliasInfo objects that Get-Alias gets. To find all properties and methods of AliasInfo objects, type "Get-Alias | get-member".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Alias -Definition "*-PSSession" -Exclude e* -Scope Global </dev:code> <dev:remarks> <maml:para>This example gets aliases for commands that have names that end in "-PSSession", except for those that begin with "e".</maml:para> <maml:para>The command uses the Scope parameter to apply the command in the global scope. This is useful in scripts when you want to get the aliases in the session.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293964</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Alias Provider</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Aliases</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Culture</command:name> <maml:description> <maml:para>Gets the current culture set in the operating system.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Culture</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Culture cmdlet gets information about the current culture settings. This includes information about the current language settings on the system, such as the keyboard layout, and the display format of items such as numbers, currency, and dates.</maml:para> <maml:para>You can also use the Get-UICulture cmdlet, which gets the current user interface culture on the system, and the <maml:navigationLink><maml:linkText>Set-Culture</maml:linkText><maml:uri></maml:uri></maml:navigationLink> cmdlet in the International module. The user-interface (UI) culture determines which text strings are used for user interface elements, such as menus and messages.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Culture</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Globalization.CultureInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Culture returns an object that represents the current culture.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also use the $PsCulture and $PsUICulture variables. The $PsCulture variable stores the name of the current culture and the $PsUICulture variable stores the name of the current UI culture.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-culture </dev:code> <dev:remarks> <maml:para>This command displays information about the regional settings on the computer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$c = get-culture PS C:\>$c | format-list -property * Parent : en LCID : 1033 KeyboardLayoutId : 1033 Name : en-US IetfLanguageTag : en-US DisplayName : English (United States) NativeName : English (United States) EnglishName : English (United States) TwoLetterISOLanguageName : en ThreeLetterISOLanguageName : eng ThreeLetterWindowsLanguageName : ENU CompareInfo : CompareInfo - 1033 TextInfo : TextInfo - 1033 IsNeutralCulture : False CultureTypes : SpecificCultures, InstalledWin32Cultures, FrameworkCultures NumberFormat : System.Globalization.NumberFormatInfo DateTimeFormat : System.Globalization.DateTimeFormatInfo Calendar : System.Globalization.GregorianCalendar OptionalCalendars : {System.Globalization.GregorianCalendar, System.Globalization.GregorianCalendar} UseUserOverride : True IsReadOnly : False PS C:\>$c.calendar MinSupportedDateTime : 1/1/0001 12:00:00 AM MaxSupportedDateTime : 12/31/9999 11:59:59 PM AlgorithmType : SolarCalendar CalendarType : Localized Eras : {1} TwoDigitYearMax : 2029 IsReadOnly : False PS C:\>$c.datetimeformat AMDesignator : AM Calendar : System.Globalization.GregorianCalendar DateSeparator : / FirstDayOfWeek : Sunday CalendarWeekRule : FirstDay FullDateTimePattern : dddd, MMMM dd, yyyy h:mm:ss tt LongDatePattern : dddd, MMMM dd, yyyy LongTimePattern : h:mm:ss tt MonthDayPattern : MMMM dd PMDesignator : PM RFC1123Pattern : ddd, dd MMM yyyy HH':'mm':'ss 'GMT' ShortDatePattern : M/d/yyyy ShortTimePattern : h:mm tt SortableDateTimePattern : yyyy'-'MM'-'dd'T'HH':'mm':'ss TimeSeparator : : UniversalSortableDateTimePattern : yyyy'-'MM'-'dd HH':'mm':'ss'Z' YearMonthPattern : MMMM, yyyy AbbreviatedDayNames : {Sun, Mon, Tue, Wed...} ShortestDayNames : {Su, Mo, Tu, We...} DayNames : {Sunday, Monday, Tuesday, Wednesday...} AbbreviatedMonthNames : {Jan, Feb, Mar, Apr...} MonthNames : {January, February, March, April...} IsReadOnly : False NativeCalendarName : Gregorian Calendar AbbreviatedMonthGenitiveNames : {Jan, Feb, Mar, Apr...} MonthGenitiveNames : {January, February, March, April...} PS C:\>$c.datetimeformat.firstdayofweek Sunday </dev:code> <dev:remarks> <maml:para>This example demonstrates the vast amount of data in the culture object. It shows how to display the properties and sub-properties of the object.</maml:para> <maml:para>The first command uses the Get-Culture cmdlet to get the current culture settings on the computer. It stores the resulting culture object in the $c variable.</maml:para> <maml:para>The second command displays all of the properties of the culture object. It uses a pipeline operator (|) to send the culture object in $c to the Format-List cmdlet. It uses the Property parameter to display all (*) properties of the object. (This command can be abbreviated as "$c | fl *".)</maml:para> <maml:para>The remaining commands explore the properties of the culture object by using dot notation to display the values of the object properties. You can use this notation to display the value of any property of the object.</maml:para> <maml:para>The third command uses dot notation to display the value of the Calendar property of the culture object.</maml:para> <maml:para>The fourth command uses dot notation to display the value of the DataTimeFormat property of the culture object.</maml:para> <maml:para>Many object properties have properties. The fifth command uses dot notation to display the value of the FirstDayOfWeek property of the DateTimeFormat property.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293965</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Culture</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-UICulture</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Date</command:name> <maml:description> <maml:para>Gets the current date and time.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Date</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Date cmdlet gets a DateTime object that represents the current date or a date that you specify. It can format the date and time in several Windows and UNIX formats. You can use Get-Date to generate a date or time character string, and then send the string to other cmdlets or programs.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Date</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue, ByPropertyName)" position="1" aliases="LastWriteTime"> <maml:name>Date</maml:name> <maml:description> <maml:para>Specifies a date and time. By default, Get-Date gets the current system date and time.</maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Day</maml:name> <maml:description> <maml:para>Specifies the day of the month that is displayed. Enter a value from 1 to 31. The default is the current day. </maml:para> <maml:para>If you specify a value that is greater than the number of days in the month, Windows PowerShell adds the number of days to the month and displays the result. For example, "Get-Date -Month 2 -Day 31" displays "March 3", not "February 31".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayHint</maml:name> <maml:description> <maml:para>Determines which elements of the date and time are displayed. </maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Date: displays only the date</maml:para> <maml:para>-- Time: displays only the time</maml:para> <maml:para>-- DateTime: displays the date and time</maml:para> <maml:para>DateTime is the default. This parameter does not affect the DateTime object that Get-Date gets.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Date</command:parameterValue> <command:parameterValue required="false" variableLength="false">Time</command:parameterValue> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Format</maml:name> <maml:description> <maml:para>Displays the date and time in the Microsoft .NET Framework format indicated by the format specifier. Enter a format specifier. For a list of available format specifiers, see "DateTimeFormatInfo Class" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143638. </maml:para> <maml:para>When you use the Format parameter, Windows PowerShell gets only the properties of the DateTime object that it needs to display the date in the format that you specify. As a result, some of the properties and methods of DateTime objects might not be available.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Hour</maml:name> <maml:description> <maml:para>Specifies the hour that is displayed. Enter a value from 1 to 23. The default is the current hour.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Millisecond</maml:name> <maml:description> <maml:para>Specifies the milliseconds in the date. Enter a value from 0 to 999. The default is the current number of milliseconds.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minute</maml:name> <maml:description> <maml:para>Specifies the minute that is displayed. Enter a value from 1 to 59. The default value is the current minutes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Month</maml:name> <maml:description> <maml:para>Specifies the month that is displayed. Enter a value from 1 to 12. The default is the current month.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Second</maml:name> <maml:description> <maml:para>Specifies the second that is displayed. Enter a value from 1 to 59. The default is the current second.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Year</maml:name> <maml:description> <maml:para>Specifies the year that is displayed. Enter a value from 1 to 9999. The default is the current year.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Date</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue, ByPropertyName)" position="1" aliases="LastWriteTime"> <maml:name>Date</maml:name> <maml:description> <maml:para>Specifies a date and time. By default, Get-Date gets the current system date and time.</maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Day</maml:name> <maml:description> <maml:para>Specifies the day of the month that is displayed. Enter a value from 1 to 31. The default is the current day. </maml:para> <maml:para>If you specify a value that is greater than the number of days in the month, Windows PowerShell adds the number of days to the month and displays the result. For example, "Get-Date -Month 2 -Day 31" displays "March 3", not "February 31".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayHint</maml:name> <maml:description> <maml:para>Determines which elements of the date and time are displayed. </maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Date: displays only the date</maml:para> <maml:para>-- Time: displays only the time</maml:para> <maml:para>-- DateTime: displays the date and time</maml:para> <maml:para>DateTime is the default. This parameter does not affect the DateTime object that Get-Date gets.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Date</command:parameterValue> <command:parameterValue required="false" variableLength="false">Time</command:parameterValue> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Hour</maml:name> <maml:description> <maml:para>Specifies the hour that is displayed. Enter a value from 1 to 23. The default is the current hour.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Millisecond</maml:name> <maml:description> <maml:para>Specifies the milliseconds in the date. Enter a value from 0 to 999. The default is the current number of milliseconds.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minute</maml:name> <maml:description> <maml:para>Specifies the minute that is displayed. Enter a value from 1 to 59. The default value is the current minutes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Month</maml:name> <maml:description> <maml:para>Specifies the month that is displayed. Enter a value from 1 to 12. The default is the current month.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Second</maml:name> <maml:description> <maml:para>Specifies the second that is displayed. Enter a value from 1 to 59. The default is the current second.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UFormat</maml:name> <maml:description> <maml:para>Displays the date and time in UNIX format. For a list of the format specifiers, see the Notes section. </maml:para> <maml:para>When you use the UFormat parameter, Windows PowerShell gets only the properties of the DateTime object that it needs to display the date in the format that you specify. As a result, some of the properties and methods of DateTime objects might not be available.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Year</maml:name> <maml:description> <maml:para>Specifies the year that is displayed. Enter a value from 1 to 9999. The default is the current year.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue, ByPropertyName)" position="1" aliases="LastWriteTime"> <maml:name>Date</maml:name> <maml:description> <maml:para>Specifies a date and time. By default, Get-Date gets the current system date and time.</maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> <dev:type> <maml:name>DateTime</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Day</maml:name> <maml:description> <maml:para>Specifies the day of the month that is displayed. Enter a value from 1 to 31. The default is the current day. </maml:para> <maml:para>If you specify a value that is greater than the number of days in the month, Windows PowerShell adds the number of days to the month and displays the result. For example, "Get-Date -Month 2 -Day 31" displays "March 3", not "February 31".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayHint</maml:name> <maml:description> <maml:para>Determines which elements of the date and time are displayed. </maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Date: displays only the date</maml:para> <maml:para>-- Time: displays only the time</maml:para> <maml:para>-- DateTime: displays the date and time</maml:para> <maml:para>DateTime is the default. This parameter does not affect the DateTime object that Get-Date gets.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DisplayHintType</command:parameterValue> <dev:type> <maml:name>DisplayHintType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Format</maml:name> <maml:description> <maml:para>Displays the date and time in the Microsoft .NET Framework format indicated by the format specifier. Enter a format specifier. For a list of available format specifiers, see "DateTimeFormatInfo Class" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143638. </maml:para> <maml:para>When you use the Format parameter, Windows PowerShell gets only the properties of the DateTime object that it needs to display the date in the format that you specify. As a result, some of the properties and methods of DateTime objects might not be available.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Hour</maml:name> <maml:description> <maml:para>Specifies the hour that is displayed. Enter a value from 1 to 23. The default is the current hour.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Type the date in a format that is standard for the system locale, such as dd-MM-yyyy (German [Germany]) or MM/dd/yyyy (English [United States]).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Millisecond</maml:name> <maml:description> <maml:para>Specifies the milliseconds in the date. Enter a value from 0 to 999. The default is the current number of milliseconds.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minute</maml:name> <maml:description> <maml:para>Specifies the minute that is displayed. Enter a value from 1 to 59. The default value is the current minutes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Month</maml:name> <maml:description> <maml:para>Specifies the month that is displayed. Enter a value from 1 to 12. The default is the current month.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Second</maml:name> <maml:description> <maml:para>Specifies the second that is displayed. Enter a value from 1 to 59. The default is the current second.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UFormat</maml:name> <maml:description> <maml:para>Displays the date and time in UNIX format. For a list of the format specifiers, see the Notes section. </maml:para> <maml:para>When you use the UFormat parameter, Windows PowerShell gets only the properties of the DateTime object that it needs to display the date in the format that you specify. As a result, some of the properties and methods of DateTime objects might not be available.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Year</maml:name> <maml:description> <maml:para>Specifies the year that is displayed. Enter a value from 1 to 9999. The default is the current year.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.DateTime or System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the Format or UFormat parameters, Get-Date returns a string. Otherwise, it returns a DateTime object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>By default, the date-time is displayed in long-date and long-time formats for the system locale.</maml:para> <maml:para>When you pipe a date to cmdlets that expect string input, such as the Add-Content cmdlet, Windows PowerShell converts the DateTime object to a string before adding it to the file. The default ToString() format is short date and long time. To specify an alternate format, use the Format or UFormat parameters of Get-Date.</maml:para> <maml:para>Uformat Values:</maml:para> <maml:para>The following are the values of the UFormat parameter. The format for the command is:</maml:para> <maml:para>Get-Date -UFormat %<value></maml:para> <maml:para>For example,</maml:para> <maml:para>Get-Date -UFormat %d</maml:para> <maml:para>Date-Time:</maml:para> <maml:para>Date and time - full</maml:para> <maml:para>(default) (Friday, June 16, 2006 10:31:27 AM)</maml:para> <maml:para>c Date and time - abbreviated (Fri Jun 16 10:31:27 2006)</maml:para> <maml:para> </maml:para> <maml:para>Date:</maml:para> <maml:para>D Date in mm/dd/yy format (06/14/06)</maml:para> <maml:para>x Date in standard format for locale (09/12/07 for English-US)</maml:para> <maml:para>Year:</maml:para> <maml:para>C Century (20 for 2006)</maml:para> <maml:para>Y Year in 4-digit format (2006)</maml:para> <maml:para>y Year in 2-digit format (06)</maml:para> <maml:para>G Same as 'Y'</maml:para> <maml:para>g Same as 'y'</maml:para> <maml:para>Month:</maml:para> <maml:para>b Month name - abbreviated (Jan)</maml:para> <maml:para>B Month name - full (January)</maml:para> <maml:para>h Same as 'b'</maml:para> <maml:para>m Month number (06)</maml:para> <maml:para>Week:</maml:para> <maml:para>W Week of the year (00-52)</maml:para> <maml:para>V Week of the year (01-53)</maml:para> <maml:para>U Same as 'W'</maml:para> <maml:para>Day:</maml:para> <maml:para>a Day of the week - abbreviated name (Mon)</maml:para> <maml:para>A Day of the week - full name (Monday)</maml:para> <maml:para>u Day of the week - number (Monday = 1)</maml:para> <maml:para>d Day of the month - 2 digits (05)</maml:para> <maml:para>e Day of the month - digit preceded by a space ( 5)</maml:para> <maml:para>j Day of the year - (1-366)</maml:para> <maml:para>w Same as 'u'</maml:para> <maml:para>Time:</maml:para> <maml:para>p AM or PM</maml:para> <maml:para>r Time in 12-hour format (09:15:36 AM)</maml:para> <maml:para>R Time in 24-hour format - no seconds (17:45)</maml:para> <maml:para>T Time in 24 hour format (17:45:52)</maml:para> <maml:para>X Same as 'T'</maml:para> <maml:para>Z Time zone offset from Universal Time Coordinate (UTC) (-07)</maml:para> <maml:para>Hour:</maml:para> <maml:para>H Hour in 24-hour format (17)</maml:para> <maml:para>I Hour in 12 hour format (05)</maml:para> <maml:para>k Same as 'H'</maml:para> <maml:para>l Same as 'I' (Upper-case I = Lower-case L)</maml:para> <maml:para>Minutes & Seconds:</maml:para> <maml:para>M Minutes (35)</maml:para> <maml:para>S Seconds (05)</maml:para> <maml:para>s Seconds elapsed since January 1, 1970 00:00:00 (1150451174.95705)</maml:para> <maml:para>Special Characters:</maml:para> <maml:para>n newline character (\n)</maml:para> <maml:para>t Tab character (\t)</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Date -DisplayHint Date Tuesday, June 13, 2006 </dev:code> <dev:remarks> <maml:para>This command gets a DateTime object, but it displays only the date. It uses the DisplayHint parameter to indicate that only the date is to be displayed.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Date -Format g 6/13/2006 12:43 PM </dev:code> <dev:remarks> <maml:para>This command gets the current date and time and formats it in short-date and short-time format. It uses the .NET Framework "g" format specifier (General [short date and short time]) to specify the format.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Date -UFormat "%Y / %m / %d / %A / %Z" 2006 / 06 / 13 / Tuesday / -07 </dev:code> <dev:remarks> <maml:para>This command gets the current date and time and formats it as specified by the command. In this case, the format includes the full year (%Y), the two-digit numeric month (%m), the date (%d), the full day of the week (%A), and the offset from UTC ("Zulu").</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(Get-Date -Year 2000 -Month 12 -Day 31).DayOfYear 366 </dev:code> <dev:remarks> <maml:para>This command displays the day of the year for the current date. For example, December 31 is the 365th day of 2006, but it is the 366th day of 2000.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = Get-Date PS C:\>$a.IsDaylightSavingTime() True </dev:code> <dev:remarks> <maml:para>These commands tell you whether the current date and time are adjusted for daylight savings time in the current locale.</maml:para> <maml:para>The first command creates a variable named $a and then assigns the object retrieved by Get-Date to the $a variable. Then, it uses the IsDaylightSavingTime method on the object in $a.</maml:para> <maml:para>To see the properties and methods of the DateTime object, type:</maml:para> <maml:para>"Get-Date | get-member".</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = Get-Date PS C:\>$a.ToUniversalTime() Tuesday, June 13, 2006 8:09:19 PM </dev:code> <dev:remarks> <maml:para>These commands convert the current date and time to UTC time.</maml:para> <maml:para>The first command creates a variable named $a and then assigns the object retrieved by Get-Date to the $a variable. Then, it uses the ToUniversalTime method on the object in $a.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = Get-WmiObject Win32_Bios -Computer Server01 PS C:\>$a | Format-List -Property Name, @{Label="BIOS Age";Expression={(Get-Date) - $_.ConvertToDateTime($_.ReleaseDate)}} Name : Default System BIOS BIOS Age : 1345.17:31:07.1091047 </dev:code> <dev:remarks> <maml:para>Windows Management Instrumentation (WMI) uses a different date-time object than the .NET Framework date-time object that Get-Date returns. To use date-time information from WMI in a command with date-time information from Get-Date, you have to use the ConvertToDateTime method to convert WMI CIM_DATETIME objects to .NET Framework DateTime objects.</maml:para> <maml:para>The commands in this example display the name and age of the BIOS on a remote computer, Server01.</maml:para> <maml:para>The first command uses the Get-WmiObject cmdlet to get an instance of the Win32_BIOS class on Server01 and then stores it in the $a variable.</maml:para> <maml:para>The second command uses the pipeline operator (|) to send the WMI object stored in $a to the Format-List cmdlet. The Property parameter of Format-List specifies two properties to display in the list, "Name" and "BIOS Age". The "BIOS Age" property is specified in a hash table. The table includes the Label key, which specifies the name of the property, and the Expression key, which contains the expression that calculates the BIOS age. The expression uses the ConvertToDateTime method to convert each instance of ReleaseDate to a .NET Framework DateTime object. Then, the value is subtracted from the value of the Get-Date cmdlet, which, without parameters, gets the current date.</maml:para> <maml:para>The backtick character (`) is the line continuation character in Windows PowerShell.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Date Tuesday, June 13, 2006 12:43:42 PM </dev:code> <dev:remarks> <maml:para>This command gets a DateTime object and displays the current date and time in the long date and long time formats for the system locale, as though you typed "Get-Date -Format F".</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Date Tuesday, September 26, 2006 11:25:31 AM PS C:\>(Get-Date).ToString() 9/26/2006 11:25:31 AM PS C:\>Get-Date | Add-Content Test.txt # Adds 9/26/2006 11:25:31 AM PS C:\>Get-Date -Format F | Add-Content Test.txt # Adds Tuesday, September 26, 2006 11:25:31 AM </dev:code> <dev:remarks> <maml:para>These commands demonstrate how to use Get-Date with Add-Content and other cmdlets that convert the DateTime object that Get-Date generates to a string.</maml:para> <maml:para>The first command shows that the default display from a "Get-Date" command is in long-date and long-time format.</maml:para> <maml:para>The second command shows that the default display from the ToString() method of the DateTime object is in short-date and short-time format.</maml:para> <maml:para>The third command uses a pipeline operator to send the DateTime object to the Add-Content cmdlet, which adds the content to the Test.txt file. Because Add-Content uses the ToString() method of the DateTime object, the date that is added is in short-date and short-time format.</maml:para> <maml:para>The fourth command uses the Format parameter of Get-Date to specify the format. When you use the Format or UFormat parameters, Get-Date generates a string, not a DateTime object. Then, when you send the string to Add-Content, it adds the string to the Test.txt file without changing it.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 10 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Format parameter with a value of "o" to generate a timestamp string. PS C:\>Get-Date -Format o 2012-03-08T10:55:55.6083839-08:00 The second command prepares the timestamp to be used in a directory name. The command replaces the colon characters (:) in the string with dots (.) and saves the result in the $timestamp variable. Replacing the colons prevents the characters that precede each colon from being interpreted as a drive name. PS C:\>$timestamp = Get-Date -Format o | foreach {$_ -replace ":", "."} The third command uses the Mkdir function to create a directory with the name in the $timestamp variable. PS C:\>mkdir C:\ps-test\$timestamp Directory: C:\ps-test Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 3/8/2012 11:01 AM 2012-03-08T11.00.24.4192623-08.00 </dev:code> <dev:remarks> <maml:para>This example shows how to use the Get-Date cmdlet to create a timestamp and how to use the timestamp in or as part of a directory name.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293966</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-TimeSpan</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Date</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Event</command:name> <maml:description> <maml:para>Gets the events in the event queue.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Event</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Event cmdlet gets events in the Windows PowerShell event queue for the current session. You can get all events or use the EventIdentifier or SourceIdentifier parameters to specify the events.</maml:para> <maml:para>When an event occurs, it is added to the event queue. The event queue includes events for which you have registered, events created by using the New-Event cmdlet, and the event that is raised when Windows PowerShell exits. You can use Get-Event or Wait-Event to get the events.</maml:para> <maml:para>This cmdlet does not get events from the Event Viewer logs. To get those events, use Get-WinEvent or Get-EventLog.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Event</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Gets only events with the specified source identifier. The default is all events in the event queue. Wildcards are not permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Event</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="Id"> <maml:name>EventIdentifier</maml:name> <maml:description> <maml:para>Gets only the events with the specified event identifier.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="Id"> <maml:name>EventIdentifier</maml:name> <maml:description> <maml:para>Gets only the events with the specified event identifier.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Gets only events with the specified source identifier. The default is all events in the event queue. Wildcards are not permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSEventArgs</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Event returns a PSEventArgs object for each event. To see a description of this object, type "get-help get-event -full" and see the Notes section of the help topic.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> <maml:para>The Get-Event cmdlet returns a PSEventArgs object (System.Management.Automation.PSEventArgs) with the following properties.</maml:para> <maml:para>-- ComputerName: The name of the computer on which the event occurred. This property value is populated only when the event is forwarded from a remote computer.</maml:para> <maml:para>-- RunspaceId: A GUID that uniquely identifies the session in which the event occurred. This property value is populated only when the event is forwarded from a remote computer.</maml:para> <maml:para>-- EventIdentifier: An integer (Int32) that uniquely identifies the event notification in the current session.</maml:para> <maml:para>-- Sender: The object that generated the event. In the value of the Action parameter, the $Sender automatic variable contains the sender object.</maml:para> <maml:para>-- SourceEventArgs: The first parameter that derives from EventArgs, if it exists. For example, in a timer elapsed event in which the signature has the form "Object sender, Timers.ElapsedEventArgs e", the SourceEventArgs property would contain the Timers.ElapsedEventArgs. In the value of the Action parameter, the $EventArgs automatic variable contains this value.</maml:para> <maml:para>-- SourceArgs: All parameters of the original event signature. For a standard event signature, $Args[0] represents the sender, and $Args[1] represents the SourceEventArgs. In the value of the Action parameter, the $Args automatic variable contains this value.</maml:para> <maml:para>-- SourceIdentifier: A string that identifies the event subscription. In the value of the Action parameter, the SourceIdentifier property of the $Event automatic variable contains this value.</maml:para> <maml:para>-- TimeGenerated: A DateTime object that represents the time at which the event was generated. In the value of the Action parameter, the TimeGenerated property of the $Event automatic variable contains this value.</maml:para> <maml:para>--MessageData: Data associated with the event subscription. Users specify this data when they register an event. In the value of the Action parameter, the MessageData property of the $Event automatic variable contains this value.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-event </dev:code> <dev:remarks> <maml:para>This command gets all events in the event queue.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-event -sourceIdentifier "PowerShell.ProcessCreated" </dev:code> <dev:remarks> <maml:para>This command gets events in which the value of the SourceIdentifier property is "PowerShell.ProcessCreated".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$events = get-event PS C:\>$events[0] | format-list -property * ComputerName : RunspaceId : c2153740-256d-46c0-a57c-b805917d1b7b EventIdentifier : 1 Sender : System.Management.ManagementEventWatcher SourceEventArgs : System.Management.EventArrivedEventArgs SourceArgs : {System.Management.ManagementEventWatcher, System.Management.EventArrivedEventArgs} SourceIdentifier : ProcessStarted TimeGenerated : 11/13/2008 12:09:32 PM MessageData : PS C:\>get-event | where {$_.TimeGenerated -ge "11/13/2008 12:15:00 PM"} ComputerName : RunspaceId : c2153740-256d-46c0-a57c-b8059325d1a0 EventIdentifier : 1 Sender : System.Management.ManagementEventWatcher SourceEventArgs : System.Management.EventArrivedEventArgs SourceArgs : {System.Management.ManagementEventWatcher, System.Management.EventArrivedEventArgs} SourceIdentifier : ProcessStarted TimeGenerated : 11/13/2008 12:15:00 PM MessageData : </dev:code> <dev:remarks> <maml:para>This example shows how to get events by using properties other than SourceIdentifier.</maml:para> <maml:para>The first command gets all events in the event queue and saves them in the $events variable.</maml:para> <maml:para>The second command uses array notation to get the first (0-index) event in the array in the $events variable. The command uses a pipeline operator (|) to send the event to the Format-List command, which displays all properties of the event in a list. This allows you to examine the properties of the event object.</maml:para> <maml:para>The third command shows how to use the Where-Object cmdlet to get an event</maml:para> <maml:para>based on the time that it was generated.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-event -eventIdentifier 2 </dev:code> <dev:remarks> <maml:para>This command gets the event with an event identifier of 2.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293967</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-EventSubscriber</command:name> <maml:description> <maml:para>Gets the event subscribers in the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>EventSubscriber</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-EventSubscriber cmdlet gets the event subscribers in the current session.</maml:para> <maml:para>When you subscribe to an event by using a Register event cmdlet, an event subscriber is added to your Windows PowerShell session, and the events to which you subscribed are added to your event queue whenever they are raised. To cancel an event subscription, delete the event subscriber by using the Unregister-Event cmdlet.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-EventSubscriber</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Gets only the event subscribers with the specified SourceIdentifier property value. By default, Get-EventSubscriber gets all event subscribers in the session. Wildcards are not permitted. This parameter is case-sensitive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Gets all event subscribers, including subscribers for events that are hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-EventSubscriber</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="Id"> <maml:name>SubscriptionId</maml:name> <maml:description> <maml:para>Gets only the specified subscription identifier. By default, Get-EventSubscriber gets all event subscribers in the session.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Gets all event subscribers, including subscribers for events that are hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Gets all event subscribers, including subscribers for events that are hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Gets only the event subscribers with the specified SourceIdentifier property value. By default, Get-EventSubscriber gets all event subscribers in the session. Wildcards are not permitted. This parameter is case-sensitive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="Id"> <maml:name>SubscriptionId</maml:name> <maml:description> <maml:para>Gets only the specified subscription identifier. By default, Get-EventSubscriber gets all event subscribers in the session.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSEventSubscriber</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-EventSubscriber returns an object that represents each event subscriber.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The New-Event cmdlet, which creates a custom event, does not generate a subscriber. Therefore, the Get-EventSubscriber cmdlet will not find a subscriber object for these events. However, if you use the Register-EngineEvent cmdlet to subscribe to a custom event (in order to forward the event or to specify an action), Get-EventSubscriber will find the subscriber that Register-EngineEvent generates.</maml:para> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$timer = New-Object Timers.Timer PS C:\>$timer | Get-Member -Type Event PS C:\>Register-ObjectEvent -inputObject $timer -EventName Elapsed -SourceIdentifier Timer.Elapsed PS C:\>Get-EventSubscriber PS C:\>$timer = New-Object Timers.Timer PS C:\>$timer | Get-Member -Type Event TypeName: System.Timers.Timer Name MemberType Definition ---- ---------- ---------- Disposed Event System.EventHandler Disposed(System.Object, System.EventArgs) Elapsed Event System.Timers.ElapsedEventHandler Elapsed(System.Object, System.Timers.ElapsedEventArgs) PS C:\>Register-ObjectEvent -InputObject $timer -EventName Elapsed -SourceIdentifier Timer.Elapsed PS C:\>Get-EventSubscriber SubscriptionId : 4 SourceObject : System.Timers.Timer EventName : Elapsed SourceIdentifier : Timer.Elapsed Action : HandlerDelegate : SupportEvent : False ForwardEvent : False </dev:code> <dev:remarks> <maml:para>This example uses a Get-EventSubscriber command to get the event subscriber for a timer event.</maml:para> <maml:para>The first command uses the New-Object cmdlet to create an instance of a timer object. It saves the new timer object in the $timer variable.</maml:para> <maml:para>The second command uses the Get-Member cmdlet to display the events that are available for timer objects. The command uses the Type parameter of the Get-Member cmdlet with a value of Event.</maml:para> <maml:para>The third command uses the Register-ObjectEvent cmdlet to register for the Elapsed event on the timer object.</maml:para> <maml:para>The fourth command uses the Get-EventSubscriber cmdlet to get the event subscriber for the Elapsed event.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$timer = New-Object Timers.Timer PS C:\>$timer.Interval = 500 PS C:\>Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action { $random = Get-Random -Min 0 -Max 100 } Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 3 Timer.Random NotStarted False $random = Get-Random ... PS C:\>$timer.Enabled = $true PS C:\>$subscriber = Get-EventSubcriber -sourceIdentifer Timer.Random PS C:\>($subscriber.action).gettype().fullname PSEventJob PS C:\>$subscriber.action | format-list -property * State : Running Module : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0 StatusMessage : HasMoreData : True Location : Command : $random = Get-Random -Min 0 -Max 100 JobStateInfo : Running Finished : System.Threading.ManualResetEvent InstanceId : 88944290-133d-4b44-8752-f901bd8012e2 Id : 1 Name : Timer.Random ChildJobs : {} ... PS C:\>& $subscriber.action.module {$random} 96 PS C:\>& $subscriber.action.module {$random} 23 </dev:code> <dev:remarks> <maml:para>This example shows how to use the dynamic module in the PSEventJob object in the Action property of the event subscriber.</maml:para> <maml:para>The first command uses the New-Object cmdlet to create a timer object. The second command sets the interval of the timer to 500 (milliseconds).</maml:para> <maml:para>The third command uses the Register-ObjectEvent cmdlet to register the Elapsed event of the timer object. The command includes an action that handles the event. Whenever the timer interval elapses, an event is raised and the commands in the action run. In this case, the Get-Random cmdlet generates a random number between 0 and 100 and saves it in the $random variable. The source identifier of the event is Timer.Random.</maml:para> <maml:para>When you use an Action parameter in a Register-ObjectEvent command, the command returns a PSEventJob object that represents the action.</maml:para> <maml:para>The fourth command enables the timer.</maml:para> <maml:para>The fifth command uses the Get-EventSubscriber cmdlet to get the event subscriber of the Timer.Random event. It saves the event subscriber object in the $subscriber variable.</maml:para> <maml:para>The sixth command shows that the Action property of the event subscriber object contains a PSEventJob object. In fact, it contains the same PSEventJob object that the Register-ObjectEvent command returned.</maml:para> <maml:para>The seventh command uses the Format-List cmdlet to display all of the properties of the PSEventJob object in the Action property in a list. The result reveal that the PSEventJob object has a Module property that contains a dynamic script module that implements the action.</maml:para> <maml:para>The remaining commands use the call operator (&) to invoke the command in the module and display the value of the $random variable. You can use the call operator to invoke any command in a module, including commands that are not exported. In this case, the commands show the random number that is being generated when the Elapsed event occurs.</maml:para> <maml:para>For more information about modules, see about_Modules.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293968</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-FileHash</command:name> <maml:description> <maml:para>Computes the hash value for a file by using a specified hash algorithm.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>FileHash</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>Get-FileHash computes the hash value for a file by using a specified hash algorithm. A hash value is a unique value that corresponds to the content of the file. Rather than identifying the contents of a file by its file name, extension, or other designation, a hash assigns a unique value to the contents of a file. File names and extensions can be changed without altering the content of the file, and without changing the hash value. Similarly, the file�s content can be changed without changing the name or extension. However, changing even a single character in the contents of a file changes the hash value of the file.</maml:para> <maml:para>The purpose of hash values is to provide a cryptographically-secure way to verify that the contents of a file have not been changed. While some hash algorithms, including MD5 and SHA1, are no longer considered secure against attack, the goal of a secure hash algorithm is to render it impossible to change the contents of a file�either by accident, or by malicious or unauthorized attempt�and maintain the same hash value. You can also use hash values to determine if two different files have exactly the same content. If the hash values of two files are identical, the contents of the files are also identical.</maml:para> <maml:para>By default, the Get-FileHash cmdlet uses the SHA256 algorithm, although any hash algorithm that is supported by the target operating system can be used.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-FileHash</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to one or more files. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Algorithm</maml:name> <maml:description> <maml:para>Specifies the cryptographic hash function to use for computing the hash value of the contents of the specified file. A cryptographic hash function includes the property that it is not possible to find two distinct inputs that generate the same hash values. Hash functions are commonly used with digital signatures and for data integrity. Valid values for this parameter are SHA1, SHA256, SHA384, SHA512, MACTripleDES, MD5, and RIPEMD160. If no value is specified, or if the parameter is omitted, the default value is SHA256.</maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SHA1</command:parameterValue> <command:parameterValue required="false" variableLength="false">SHA256</command:parameterValue> <command:parameterValue required="false" variableLength="false">SHA384</command:parameterValue> <command:parameterValue required="false" variableLength="false">SHA512</command:parameterValue> <command:parameterValue required="false" variableLength="false">MACTripleDES</command:parameterValue> <command:parameterValue required="false" variableLength="false">MD5</command:parameterValue> <command:parameterValue required="false" variableLength="false">RIPEMD160</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-FileHash</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Algorithm</maml:name> <maml:description> <maml:para>Specifies the cryptographic hash function to use for computing the hash value of the contents of the specified file. A cryptographic hash function includes the property that it is not possible to find two distinct inputs that generate the same hash values. Hash functions are commonly used with digital signatures and for data integrity. Valid values for this parameter are SHA1, SHA256, SHA384, SHA512, MACTripleDES, MD5, and RIPEMD160. If no value is specified, or if the parameter is omitted, the default value is SHA256.</maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SHA1</command:parameterValue> <command:parameterValue required="false" variableLength="false">SHA256</command:parameterValue> <command:parameterValue required="false" variableLength="false">SHA384</command:parameterValue> <command:parameterValue required="false" variableLength="false">SHA512</command:parameterValue> <command:parameterValue required="false" variableLength="false">MACTripleDES</command:parameterValue> <command:parameterValue required="false" variableLength="false">MD5</command:parameterValue> <command:parameterValue required="false" variableLength="false">RIPEMD160</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a file. Unlike the Path parameter, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes escape characters, enclose the path in single quotation marks. Single quotation marks instruct Windows PowerShell not to interpret characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-FileHash</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InputStream</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.IO.Stream</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Algorithm</maml:name> <maml:description> <maml:para>Specifies the cryptographic hash function to use for computing the hash value of the contents of the specified file. A cryptographic hash function includes the property that it is not possible to find two distinct inputs that generate the same hash values. Hash functions are commonly used with digital signatures and for data integrity. Valid values for this parameter are SHA1, SHA256, SHA384, SHA512, MACTripleDES, MD5, and RIPEMD160. If no value is specified, or if the parameter is omitted, the default value is SHA256.</maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InputStream</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For security reasons, MD5 and SHA1, which are no longer considered secure, should only be used for simple change validation, and should not be used to generate hash values for files that require protection from attack or tampering.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">System.IO.Stream</command:parameterValue> <dev:type> <maml:name>System.IO.Stream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a file. Unlike the Path parameter, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcard characters. If the path includes escape characters, enclose the path in single quotation marks. Single quotation marks instruct Windows PowerShell not to interpret characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to one or more files. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string to the Get-FileHash cmdlet that contains a path to one or more files.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.Powershell.Utility.FileHash</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-FileHash returns an object that represents the path to the specified file, the value of the computed hash, and the algorithm used to compute the hash.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> Get-FileHash $pshome\powershell.exe | Format-List Algorithm : SHA256 Hash : 6A785ADC0263238DAB3EB37F4C185C8FBA7FEB5D425D034CA9864F1BE1C1B473 Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe </dev:code> <dev:remarks> <maml:para>This example uses the Get-FileHash cmdlet to compute the hash value for the Powershell.exe file. The hash algorithm used is the default, SHA256. The output is piped to the Format-List cmdlet to format the output as a list.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> Get-FileHash C:\Users\Andris\Downloads\Contoso8_1_ENT.iso -Algorithm SHA384 | Format-List Algorithm : SHA384 Hash : 20AB1C2EE19FC96A7C66E33917D191A24E3CE9DAC99DB7C786ACCE31E559144FEAFC695C58E508E2EBBC9D3C96F21FA3 Path : C:\Users\Andris\Downloads\Contoso8_1_ENT.iso </dev:code> <dev:remarks> <maml:para>This command uses the Get-FileHash cmdlet and the SHA384 algorithm to compute the hash value for an ISO file that an administrator has downloaded from the Internet. The output is piped to the Format-List cmdlet to format the output as a list.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/?LinkId=325249</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-FormatData</command:name> <maml:description> <maml:para>Gets the formatting data in the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>FormatData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-FormatData cmdlet gets the formatting data in the current session.</maml:para> <maml:para>The formatting data in the session includes formatting data from Format.ps1xml formatting files (such as those in the $pshome directory), formatting data for modules that you import into the session, and formatting data for commands that you import into your session by using the Import-PSSession cmdlet.</maml:para> <maml:para>You can use this cmdlet to examine the formatting data. Then, you can use the Export-FormatData cmdlet to serialize the objects (convert them to XML) and save them in Format.ps1xml files.</maml:para> <maml:para>For more information about formatting files in Windows PowerShell, see about_Format.ps1xml.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-FormatData</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Gets only the formatting data with the specified type names. Enter the type names. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Gets only the formatting data with the specified type names. Enter the type names. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.ExtendedTypeDefinition </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-formatdata </dev:code> <dev:remarks> <maml:para>This command gets all the formatting data in the session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-formatdata -typename Microsoft.Wsman* </dev:code> <dev:remarks> <maml:para>This command gets the formatting data items whose names begin with "Microsoft.Wsman".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$f = get-formatdata -typename helpinfoshort PS C:\>$f TypeName FormatViewDefinition -------- -------------------- HelpInfoShort {help , TableControl} PS C:\>$f.FormatViewDefinition[0].control Headers Rows ------- ---- {System.Management.Automation.TableControlColumnHeader, System.Manageme... {System.Management.Automation.TableControlRow} PS C:\>$f.FormatViewDefinition[0].control.headers Label Alignment Width ----- --------- ----- Name Left 33 Category Left 9 Undefined 0 </dev:code> <dev:remarks> <maml:para>This example shows how to get a formatting data object and examine its properties.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = get-formatdata PS C:\>import-module bitstransfer PS C:\>$b = get-formatdata PS C:\>compare-object $a $b InputObject SideIndicator ----------- ------------- Microsoft.BackgroundIntelligentTransfer.Management.BitsJob => PS C:\>get-formatdata *bits* | export-formatdata -filepath c:\test\bits.format.ps1xml PS C:\>get-content c:\test\bits.format.ps1xml <?xml version="1.0" encoding="utf-8"?><Configuration><ViewDefinitions> <View><Name>Microsoft.BackgroundIntelligentTransfer.Management.BitsJob</Name> ... </dev:code> <dev:remarks> <maml:para>This example shows how to use Get-FormatData and Export-FormatData to export the formatting data that is added by a module.</maml:para> <maml:para>The first four commands use the Get-FormatData, Import-Module, and Compare-Object cmdlets to identify the format type that the BitsTransfer module adds to the session.</maml:para> <maml:para>The fifth command uses the Get-FormatData cmdlet to get the format type that the BitsTransfer module adds. It uses a pipeline operator (|) to send the format type object to the Export-FormatData cmdlet, which converts it back to XML and saves it in the specified format.ps1xml file.</maml:para> <maml:para>The final command shows an excerpt of the format.ps1xml file content.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293969</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-FormatData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Update-FormatData</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Host</command:name> <maml:description> <maml:para>Gets an object that represents the current host program.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Host</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Host cmdlet gets an object that represents the program that is hosting Windows PowerShell.</maml:para> <maml:para>The default display includes the Windows PowerShell version number and the current region and language settings that the host is using, but the host object contains a wealth of information, including detailed information about the version of Windows PowerShell that is currently running and the current culture and UI culture of Windows PowerShell. You can also use this cmdlet to customize features of the host program user interface, such as the text and background colors.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Host</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.Internal.Host.InternalHost</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Host returns a System.Management.Automation.Internal.Host.InternalHost object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The $host automatic variable contains the same object that Get-Host returns, and you can use it in the same way. Similarly, the $PSCulture and $PSUICulture automatic variables contain the same objects that the CurrentCulture and CurrentUICulture properties of the host object contain. You can use these features interchangeably.</maml:para> <maml:para>For more information, see about_Automatic_Variables.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-host Name : ConsoleHost Version : 2.0 InstanceId : e4e0ab54-cc5e-4261-9117-4081f20ce7a2 UI : System.Management.Automation.Internal.Host.InternalHostUserInterface CurrentCulture : en-US CurrentUICulture : en-US PrivateData : Microsoft.PowerShell.ConsoleHost+ConsoleColorProxy IsRunspacePushed : False Runspace : System.Management.Automation.Runspaces.LocalRunspace </dev:code> <dev:remarks> <maml:para>This command displays information about the Windows PowerShell console, which is the current host program for Windows PowerShell in this example. It includes the name of the host, the version of Windows PowerShell that is running in the host, and current culture and UI culture.</maml:para> <maml:para>The Version, UI, CurrentCulture, CurrentUICulture, PrivateData, and Runspace properties each contain an object with very useful properties. Later examples examine these properties.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$h = get-host PS C:\>$win = $h.ui.rawui.windowsize PS C:\>$win.height = 10 PS C:\>$win.width = 10 PS C:\>$h.ui.rawui.set_windowsize($win) </dev:code> <dev:remarks> <maml:para>This command resizes the Windows PowerShell window to 10 pixels by 10 pixels.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-host).version | format-list -property * Major : 2 Minor : 0 Build : -1 Revision : -1 MajorRevision : -1 MinorRevision : -1 </dev:code> <dev:remarks> <maml:para>This command gets detailed information about the version of Windows PowerShell running in the host. You can view, but not change, these values.</maml:para> <maml:para>The Version property of Get-Host contains a System.Version object. This command uses a pipeline operator (|) to send the version object to the Format-List cmdlet. The Format-List command uses the Property parameter with a value of all (*) to display all of the properties and property values of the version object.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-host).currentculture | format-list -property * Parent : en LCID : 1033 KeyboardLayoutId : 1033 Name : en-US IetfLanguageTag : en-US DisplayName : English (United States) NativeName : English (United States) EnglishName : English (United States) TwoLetterISOLanguageName : en ThreeLetterISOLanguageName : eng ThreeLetterWindowsLanguageName : ENU CompareInfo : CompareInfo - 1033 TextInfo : TextInfo - 1033 IsNeutralCulture : False CultureTypes : SpecificCultures, InstalledWin32Cultures, FrameworkCultures NumberFormat : System.Globalization.NumberFormatInfo DateTimeFormat : System.Globalization.DateTimeFormatInfo Calendar : System.Globalization.GregorianCalendar OptionalCalendars : {System.Globalization.GregorianCalendar, System.Globalization.GregorianCalendar} UseUserOverride : True IsReadOnly : False </dev:code> <dev:remarks> <maml:para>This command gets detailed information about the current culture set for Windows PowerShell running in the host. This is the same information that is returned by the Get-Culture cmdlet.</maml:para> <maml:para>(Similarly, the CurrentUICulture property returns the same object that Get-UICulture returns.)</maml:para> <maml:para>The CurrentCulture property of the host object contains a System.Globalization.CultureInfo object. This command uses a pipeline operator (|) to send the CultureInfo object to the Format-List cmdlet. The Format-List command uses the Property parameter with a value of all (*) to display all of the properties and property values of the CultureInfo object.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-host).currentculture.DateTimeFormat | format-list -property * AMDesignator : AM Calendar : System.Globalization.GregorianCalendar DateSeparator : / FirstDayOfWeek : Sunday CalendarWeekRule : FirstDay FullDateTimePattern : dddd, MMMM dd, yyyy h:mm:ss tt LongDatePattern : dddd, MMMM dd, yyyy LongTimePattern : h:mm:ss tt MonthDayPattern : MMMM dd PMDesignator : PM RFC1123Pattern : ddd, dd MMM yyyy HH':'mm':'ss 'GMT' ShortDatePattern : M/d/yyyy ShortTimePattern : h:mm tt SortableDateTimePattern : yyyy'-'MM'-'dd'T'HH':'mm':'ss TimeSeparator : : UniversalSortableDateTimePattern : yyyy'-'MM'-'dd HH':'mm':'ss'Z' YearMonthPattern : MMMM, yyyy AbbreviatedDayNames : {Sun, Mon, Tue, Wed...} ShortestDayNames : {Su, Mo, Tu, We...} DayNames : {Sunday, Monday, Tuesday, Wednesday...} AbbreviatedMonthNames : {Jan, Feb, Mar, Apr...} MonthNames : {January, February, March, April...} IsReadOnly : False NativeCalendarName : Gregorian Calendar AbbreviatedMonthGenitiveNames : {Jan, Feb, Mar, Apr...} MonthGenitiveNames : {January, February, March, April...} </dev:code> <dev:remarks> <maml:para>This command returns detailed information about the DateTimeFormat of the current culture that is being used for Windows PowerShell.</maml:para> <maml:para>The CurrentCulture property of the host object contains a CultureInfo object that, in turn, has many useful properties. Among them, the DateTimeFormat property contains a DateTimeFormatInfo object with many useful properties.</maml:para> <maml:para>To find the type of an object that is stored in an object property, use the Get-Member cmdlet. To display the property values of the object, use the Format-List cmdlet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-host).ui.rawui | format-list -property * ForegroundColor : DarkYellow BackgroundColor : DarkBlue CursorPosition : 0,390 WindowPosition : 0,341 CursorSize : 25 BufferSize : 120,3000 WindowSize : 120,50 MaxWindowSize : 120,81 MaxPhysicalWindowSize : 182,81 KeyAvailable : False WindowTitle : Windows PowerShell 2.0 (04/11/2008 00:08:14) </dev:code> <dev:remarks> <maml:para>This command displays the properties of the RawUI property of the host object. By changing these values, you can change the appearance of the host program.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-host).ui.rawui.backgroundcolor = "Black" PS C:\>cls </dev:code> <dev:remarks> <maml:para>These commands change the background color of the Windows PowerShell console to black. The "cls" command is an alias for the Clear-Host function, which clears the screen and changes the whole screen to the new color.</maml:para> <maml:para>This change is effective only in the current session. To change the background color of the console for all sessions, add the command to your Windows PowerShell profile.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$host.privatedata.errorbackgroundcolor = "white" </dev:code> <dev:remarks> <maml:para>This command changes the background color of error messages to white.</maml:para> <maml:para>This command uses the $host automatic variable, which contains the host object for the current host program. Get-Host returns the same object that $host contains, so you can use them interchangeably.</maml:para> <maml:para>This command uses the PrivateData property of $host as its ErrorBackgroundColor property. To see all of the properties of the object in the $host.privatedata property, type "$host.privatedata | format-list * ".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293970</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Host</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Read-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Member</command:name> <maml:description> <maml:para>Gets the properties and methods of objects.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Member</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Member cmdlet gets the "members" (properties and methods) of objects.</maml:para> <maml:para>To specify the object, use the InputObject parameter or pipe an object to Get-Member. To retrieve information about static members (members of the class, not of the instance), use the Static parameter. To get only certain types of members, such as NoteProperties, use the MemberType parameter.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Member</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the names of one or more properties or methods of the object. Get-Member gets only the specified properties and methods.</maml:para> <maml:para>If you use the Name parameter with the MemberType, View, or Static parameters, Get-Member gets only the members that satisfy the criteria of all parameters.</maml:para> <maml:para>To get a static member by name, use the Static parameter with the Name parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Adds the intrinsic members (PSBase, PSAdapted, PSObject, PSTypeNames) and the compiler-generated get_ and set_ methods to the display. By default, Get-Member gets these properties in all views other than "Base" and "Adapted," but it does not display them.</maml:para> <maml:para>The following list describes the properties that are added when you use the Force parameter:</maml:para> <maml:para>-- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN.</maml:para> <maml:para>-- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object.</maml:para> <maml:para>-- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The following list describes the properties that are added when you use the Force parameter:</maml:para> <maml:para>-- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN.</maml:para> <maml:para>-- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object.</maml:para> <maml:para>-- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The following list describes the properties that are added when you use the Force parameter:</maml:para> <maml:para>-- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN.</maml:para> <maml:para>-- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object.</maml:para> <maml:para>-- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object whose members are retrieved.</maml:para> <maml:para>Using the InputObject parameter is not the same as piping an object to Get-Member. The differences are as follows:</maml:para> <maml:para>-- When you pipe a collection of objects to Get-Member, Get-Member gets the members of the individual objects in the collection, such as the properties of each string in an array of strings.</maml:para> <maml:para>-- When you use InputObject to submit a collection of objects, Get-Member gets the members of the collection, such as the properties of the array in an array of strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Type"> <maml:name>MemberType</maml:name> <maml:description> <maml:para>Gets only members with the specified member type. The default is All.</maml:para> <maml:para>The valid values for this parameter are: AliasProperty, All, CodeMethod, CodeProperty, Event, MemberSet, Method, Methods, Noteproperty, ParameterizedProperty, Properties, Property, PropertySet, ScriptMethod, and ScriptProperty.</maml:para> <maml:para>For information about these values, see "PSMemberTypes Enumeration" in MSDN at http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.psmembertypes(v=vs.85).aspx.</maml:para> <maml:para>Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns a null value.</maml:para> <maml:para>To get related types of members, such as all extended members, use the View parameter. If you use the MemberType parameter with the Static or View parameters, Get-Member gets the members that belong to both sets.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">AliasProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">CodeProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">Property</command:parameterValue> <command:parameterValue required="false" variableLength="false">NoteProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">ScriptProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">Properties</command:parameterValue> <command:parameterValue required="false" variableLength="false">PropertySet</command:parameterValue> <command:parameterValue required="false" variableLength="false">Method</command:parameterValue> <command:parameterValue required="false" variableLength="false">CodeMethod</command:parameterValue> <command:parameterValue required="false" variableLength="false">ScriptMethod</command:parameterValue> <command:parameterValue required="false" variableLength="false">Methods</command:parameterValue> <command:parameterValue required="false" variableLength="false">ParameterizedProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">MemberSet</command:parameterValue> <command:parameterValue required="false" variableLength="false">Event</command:parameterValue> <command:parameterValue required="false" variableLength="false">Dynamic</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Static</maml:name> <maml:description> <maml:para>Gets only the static properties and methods of the object.</maml:para> <maml:para>Static properties and methods are defined on the class of objects, not on any particular instance of the class.</maml:para> <maml:para>If you use the Static parameter with the View parameter, the View parameter is ignored. If you use the Static parameter with the MemberType parameter, Get-Member gets only the members that belong to both sets.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Gets only particular types of members (properties and methods). Specify one or more of the values. The default is "Adapted, Extended".</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Base: Gets only the original properties and methods of the .NET Framework object (without extension or adaptation).</maml:para> <maml:para>-- Adapted: Gets only the properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- Extended: Gets only the properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- All: Gets the members in the Base, Adapted, and Extended views.</maml:para> <maml:para>The View parameter determines the members retrieved, not just the display of those members.</maml:para> <maml:para>To get particular member types, such as script properties, use the MemberType parameter. If you use the MemberType and View parameters in the same command, Get-Member gets the members that belong to both sets. If you use the Static and View parameters in the same command, the View parameter is ignored.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Extended</command:parameterValue> <command:parameterValue required="false" variableLength="false">Adapted</command:parameterValue> <command:parameterValue required="false" variableLength="false">Base</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Adds the intrinsic members (PSBase, PSAdapted, PSObject, PSTypeNames) and the compiler-generated get_ and set_ methods to the display. By default, Get-Member gets these properties in all views other than "Base" and "Adapted," but it does not display them.</maml:para> <maml:para>The following list describes the properties that are added when you use the Force parameter:</maml:para> <maml:para>-- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN.</maml:para> <maml:para>-- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object.</maml:para> <maml:para>-- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The following list describes the properties that are added when you use the Force parameter:</maml:para> <maml:para>-- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN.</maml:para> <maml:para>-- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object.</maml:para> <maml:para>-- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The following list describes the properties that are added when you use the Force parameter:</maml:para> <maml:para>-- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN.</maml:para> <maml:para>-- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object.</maml:para> <maml:para>-- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object whose members are retrieved.</maml:para> <maml:para>Using the InputObject parameter is not the same as piping an object to Get-Member. The differences are as follows:</maml:para> <maml:para>-- When you pipe a collection of objects to Get-Member, Get-Member gets the members of the individual objects in the collection, such as the properties of each string in an array of strings.</maml:para> <maml:para>-- When you use InputObject to submit a collection of objects, Get-Member gets the members of the collection, such as the properties of the array in an array of strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Type"> <maml:name>MemberType</maml:name> <maml:description> <maml:para>Gets only members with the specified member type. The default is All.</maml:para> <maml:para>The valid values for this parameter are: AliasProperty, All, CodeMethod, CodeProperty, Event, MemberSet, Method, Methods, Noteproperty, ParameterizedProperty, Properties, Property, PropertySet, ScriptMethod, and ScriptProperty.</maml:para> <maml:para>For information about these values, see "PSMemberTypes Enumeration" in MSDN at http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.psmembertypes(v=vs.85).aspx.</maml:para> <maml:para>Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns a null value.</maml:para> <maml:para>To get related types of members, such as all extended members, use the View parameter. If you use the MemberType parameter with the Static or View parameters, Get-Member gets the members that belong to both sets.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSMemberTypes</command:parameterValue> <dev:type> <maml:name>PSMemberTypes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the names of one or more properties or methods of the object. Get-Member gets only the specified properties and methods.</maml:para> <maml:para>If you use the Name parameter with the MemberType, View, or Static parameters, Get-Member gets only the members that satisfy the criteria of all parameters.</maml:para> <maml:para>To get a static member by name, use the Static parameter with the Name parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Static</maml:name> <maml:description> <maml:para>Gets only the static properties and methods of the object.</maml:para> <maml:para>Static properties and methods are defined on the class of objects, not on any particular instance of the class.</maml:para> <maml:para>If you use the Static parameter with the View parameter, the View parameter is ignored. If you use the Static parameter with the MemberType parameter, Get-Member gets only the members that belong to both sets.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>View</maml:name> <maml:description> <maml:para>Gets only particular types of members (properties and methods). Specify one or more of the values. The default is "Adapted, Extended".</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Base: Gets only the original properties and methods of the .NET Framework object (without extension or adaptation).</maml:para> <maml:para>-- Adapted: Gets only the properties and methods defined in the Windows PowerShell extended type system.</maml:para> <maml:para>-- Extended: Gets only the properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet.</maml:para> <maml:para>-- All: Gets the members in the Base, Adapted, and Extended views.</maml:para> <maml:para>The View parameter determines the members retrieved, not just the display of those members.</maml:para> <maml:para>To get particular member types, such as script properties, use the MemberType parameter. If you use the MemberType and View parameters in the same command, Get-Member gets the members that belong to both sets. If you use the Static and View parameters in the same command, the View parameter is ignored.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSMemberViewTypes</command:parameterValue> <dev:type> <maml:name>PSMemberViewTypes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Get-Member</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.MemberDefinition</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Member returns an object for each property or method that its gets.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can get information about a collection object either by using the InputObject parameter or by piping the object, preceded by a comma, to Get-Member.</maml:para> <maml:para>You can use the $this automatic variable in script blocks that define the values of new properties and methods. The $this variable refers to the instance of the object to which the properties and methods are being added. For more information about the $this variable, see about_Automatic_Variables.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | get-member TypeName: System.ServiceProcess.ServiceController Name MemberType Definition ---- ---------- ---------- Name AliasProperty Name = ServiceName Close Method System.Void Close() Continue Method System.Void Continue() CreateObjRef Method System.Runtime.Remoting.ObjRef CreateObjRef(Type requestedType) Dispose Method System.Void Dispose() Equals Method System.Boolean Equals(Object obj) ExecuteCommand Method System.Void ExecuteCommand(Int32 command) GetHashCode Method System.Int32 GetHashCode() GetLifetimeService Method System.Object GetLifetimeService() GetType Method System.Type GetType() InitializeLifetimeService Method System.Object InitializeLifetimeService() Pause Method System.Void Pause() Refresh Method System.Void Refresh() Start Method System.Void Start(), System.Void Start(String[] args) Stop Method System.Void Stop() ToString Method System.String ToString() WaitForStatus Method System.Void WaitForStatus(ServiceControllerStatus desiredStatus), System.Voi... CanPauseAndContinue Property System.Boolean CanPauseAndContinue {get;} CanShutdown Property System.Boolean CanShutdown {get;} CanStop Property System.Boolean CanStop {get;} Container Property System.ComponentModel.IContainer Container {get;} DependentServices Property System.ServiceProcess.ServiceController[] DependentServices {get;} DisplayName Property System.String DisplayName {get;set;} MachineName Property System.String MachineName {get;set;} ServiceHandle Property System.Runtime.InteropServices.SafeHandle ServiceHandle {get;} ServiceName Property System.String ServiceName {get;set;} ServicesDependedOn Property System.ServiceProcess.ServiceController[] ServicesDependedOn {get;} ServiceType Property System.ServiceProcess.ServiceType ServiceType {get;} Site Property System.ComponentModel.ISite Site {get;set;} Status Property System.ServiceProcess.ServiceControllerStatus Status {get;} </dev:code> <dev:remarks> <maml:para>This command displays the properties and methods of the process objects (System.ServiceProcess.ServiceController) that are generated by the Get-Service cmdlet.</maml:para> <maml:para>The command uses the pipeline operator (|) to send the output of a Get-Service command to Get-Member.</maml:para> <maml:para>Because the Get-Member part of the command does not have any parameters, it uses all of the default values. As such, it gets all member types, but it does not get static members and does not display intrinsic members.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | get-member -force PS C:\>(get-service -schedule).psbase </dev:code> <dev:remarks> <maml:para>This example gets all of the members (properties and methods) of the service objects (System.ServiceProcess.ServiceController) retrieved by the Get-Service cmdlet, including the intrinsic members, such as PSBase and PSObject, and the get_ and set_ methods.</maml:para> <maml:para>The first command uses the Get-Service cmdlet to get objects that represent the services on the system. It uses a pipeline operator (|) to pass the service objects to the Get-Member cmdlet.</maml:para> <maml:para>The Get-Member command uses the Force parameter to add the intrinsic members and compiler-generated members of the objects to the display. Get-Member gets these members, but it hides them by default.</maml:para> <maml:para>You can use these properties and methods in the same way that you would use an adapted method of the object. The second command shows how to display the value of the PSBase property of the Schedule service.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service| get-member -view extended TypeName: System.ServiceProcess.ServiceController Name MemberType Definition ---- ---------- ---------- Name AliasProperty Name = ServiceName </dev:code> <dev:remarks> <maml:para>This command gets the methods and properties of service objects that were extended by using the Types.ps1xml file or the Add-Member cmdlet.</maml:para> <maml:para>The Get-Member command uses the View parameter to get only the extended members of the service objects. In this case, the extended member is the Name property, which is an alias property of the ServiceName property.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventlog -log system | gm -membertype scriptproperty TypeName: System.Diagnostics.EventLogEntry Name MemberType Definition ---- ---------- ---------- EventID ScriptProperty System.Object EventID {get=$this.get_EventID() -band 0xFFFF;} </dev:code> <dev:remarks> <maml:para>This command gets the script properties of event log objects in the System log in Event Viewer. In this case, the only script property is the EventID.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventlog -log system | get-member -membertype scriptproperty TypeName: System.Diagnostics.EventLogEntry Name MemberType Definition ---- ---------- ---------- EventID ScriptProperty System.Object EventID {get=$this.get_EventID() -band 0xFFFF;} </dev:code> <dev:remarks> <maml:para>This command gets the script properties of event log objects in the System log in Event Viewer.</maml:para> <maml:para>The command uses the MemberType parameter to get only objects with a value of AliasProperty for their MemberType property.</maml:para> <maml:para>The command returns the EventID property of the EventLog object.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = "get-process", "get-service", "get-culture", "get-psdrive", "get-executionpolicy" PS C:\>foreach ($cmdlet in $a) {invoke-command $cmdlet | get-member -name machinename} TypeName: System.Diagnostics.Process Name MemberType Definition ---- ---------- ---------- MachineName Property System.String MachineName {get;} TypeName: System.ServiceProcess.ServiceController Name MemberType Definition ---- ---------- ---------- MachineName Property System.String MachineName {get;set;} </dev:code> <dev:remarks> <maml:para>This command gets objects that have a MachineName property from a list of cmdlets.</maml:para> <maml:para>The first command stores the names of several cmdlets in the $a variable.</maml:para> <maml:para>The second command uses a ForEach statement to invoke each command, send the results to Get-Member, and limit the results from Get-Member to members that have the name "MachineName."</maml:para> <maml:para>The results show that only process objects (System.Diagnostics.Process) and service objects (System.ServiceProcess.ServiceController) have a MachineName property.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = get-member -inputobject @(1) PS C:\>$a.count 1 PS C:\>$a = get-member -inputobject 1,2,3 TypeName: System.Object[] Name MemberType Definition ---- ---------- ---------- Count AliasProperty Count = Length Address Method System.Object& Address(Int32 ) Clone Method System.Object Clone() ... PS C:\>$a.count 1 </dev:code> <dev:remarks> <maml:para>This example demonstrates how to find the properties and methods of an array of objects when you have only one object of the given type.</maml:para> <maml:para>Because the goal of the command is to find the properties of an array, the first command uses the InputObject parameter. It uses the "at" symbol (@) to indicate an array. In this case, the array contains only one object, the integer 1.</maml:para> <maml:para>The third command uses the Get-Member cmdlet to get the properties and methods of an array of integers, and the command saves them in the $a variable.</maml:para> <maml:para>The fourth command uses the Count property of the array to find the number of objects in the $a variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$file = get-item c:\test\textFile.txt PS C:\>$file.psobject.properties | where-object {$_.issettable} | format-table -property name Name ---- PSPath PSParentPath PSChildName PSDrive PSProvider PSIsContainer IsReadOnly CreationTime CreationTimeUtc LastAccessTime LastAccessTimeUtc LastWriteTime LastWriteTimeUtc Attributes PS C:\>[appdomain]::CurrentDomain.GetAssemblies() | foreach-object { $_.getexportedtypes() } | foreach-object {$_.getproperties() | where-object {$_.canwrite }} | select-object reflectedtype, name </dev:code> <dev:remarks> <maml:para>This example shows how to determine which properties of an object can be changed. The example uses a file, but you can use this command format to find the changeable properties of any object in Windows PowerShell.</maml:para> <maml:para>The first command uses the Get-Item cmdlet to get a text file, and then it saves the file object in the $file variable.</maml:para> <maml:para>The second command gets all of the changeable properties of the file object in the $file variable and displays the names of the properties in a table.</maml:para> <maml:para>The third command gets the changeable properties of all objects in your Windows PowerShell session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = get-service PS C:\>$s | get-member TypeName: System.ServiceProcess.ServiceController Name MemberType Definition ---- ---------- ---------- Name AliasProperty Name = ServiceName RequiredServices AliasProperty RequiredServices = ServicesDependedOn Disposed Event System.EventHandler Disposed(System.Object, System.EventArgs Close Method System.Void Close() Continue Method System.Void Continue() CreateObjRef Method System.Runtime.Remoting.ObjRef CreateObjRef(type requestedTy Dispose Method System.Void Dispose() ... PS C:\>get-member -inputObject $s TypeName: System.Object[] Name MemberType Definition ---- ---------- ---------- Count AliasProperty Count = Length Address Method System.Object&, mscorlib, Version=2.0.0.0, Cultu Clone Method System.Object Clone() CopyTo Method System.Void CopyTo(array array, int index), Syst Equals Method bool Equals(System.Object obj) Get Method System.Object Get(int ) GetEnumerator Method System.Collections.IEnumerator GetEnumerator() GetHashCode Method int GetHashCode() ... </dev:code> <dev:remarks> <maml:para>This example shows how the InputObject parameter works in the Get-Member cmdlet. When you use the InputObject parameter to get the members of a collection, Get-Member gets the members of the collection. When you pipe a collection of objects to Get-Member, Get-Member gets the members of each item in the collection.</maml:para> <maml:para>The first command gets the services on the local computer and saves the services in the $s variable.</maml:para> <maml:para>The second command pipes the $s variable to the Get-Member cmdlet. Get-Member gets the types of each member of $s and the members of that type. In this case, it gets ServiceController objects and lists the members, such as RequiredServices and Close.</maml:para> <maml:para>The third command uses the InputObject parameter of Get-Member to submit the $s variable. Get-Member gets the type (System.Object[]) and the members of the collection (or "array") of ServiceController objects, such as Count and Clone.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293971</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Add-Member</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Command</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Help</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSDrive</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Automatic_Variables</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Properties</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Methods</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Objects</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-PSBreakpoint</command:name> <maml:description> <maml:para>Gets the breakpoints that are set in the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>PSBreakpoint</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-PSBreakPoint cmdlet gets the breakpoints that are set in the current session. You can use the cmdlet parameters to get particular breakpoints. </maml:para> <maml:para>A breakpoint is a point in a command or script where execution stops temporarily so that you can examine the instructions. Get-PSBreakpoint is one of several cmdlets designed for debugging Windows PowerShell scripts and commands. For more information about the Windows PowerShell debugger, see about_Debuggers.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-PSBreakpoint</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Gets only the breakpoints in the specified scripts. Enter the path (optional) and names of one or more script files. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-PSBreakpoint</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Gets only the breakpoints in the specified scripts. Enter the path (optional) and names of one or more script files. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Gets command breakpoints that are set on the specified command names. Enter the command names, such as the name of a cmdlet or function.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Gets the breakpoints with the specified breakpoint IDs. Enter the IDs in a comma-separated list. You can also pipe breakpoint IDs to Get-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-PSBreakpoint</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Gets only the breakpoints in the specified scripts. Enter the path (optional) and names of one or more script files. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Variable</maml:name> <maml:description> <maml:para>Gets variable breakpoints that are set on the specified variable names. Enter the variable names without dollar signs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Type</maml:name> <maml:description> <maml:para>Gets only breakpoints of the specified types. Enter one or more types. Valid values are Line, Command, and Variable. You can also pipe breakpoint types to Get-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">BreakpointType[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Gets only the breakpoints in the specified scripts. Enter the path (optional) and names of one or more script files. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Gets command breakpoints that are set on the specified command names. Enter the command names, such as the name of a cmdlet or function.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Gets the breakpoints with the specified breakpoint IDs. Enter the IDs in a comma-separated list. You can also pipe breakpoint IDs to Get-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Gets only the breakpoints in the specified scripts. Enter the path (optional) and names of one or more script files. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>Type</maml:name> <maml:description> <maml:para>Gets only breakpoints of the specified types. Enter one or more types. Valid values are Line, Command, and Variable. You can also pipe breakpoint types to Get-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">BreakpointType[]</command:parameterValue> <dev:type> <maml:name>BreakpointType[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Variable</maml:name> <maml:description> <maml:para>Gets variable breakpoints that are set on the specified variable names. Enter the variable names without dollar signs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Int32, Microsoft.PowerShell.Commands.BreakpointType</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe breakpoint IDs and breakpoint types to Get-PSBreakpoint.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.Breakpoint</maml:name> <maml:uri>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.breakpoint(v=vs.85).aspx</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-PSBreakPoint returns objects that represent the breakpoints in the session.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can use Get-PSBreakpoint or its alias, "gbp".</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets all breakpoints set on all scripts and functions in the current session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint -Id 2 Function : IncrementAction : Enabled : TrueHitCount : 0 Id : 2 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets the breakpoint with breakpoint ID 2.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$b = set-psbreakpoint -script sample.ps1 -function increment PS C:\> $b.Id | get-psbreakpoint </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>These commands show how to get a breakpoint by piping a breakpoint ID to Get-PSBreakpoint.</maml:para> <maml:para>The first command uses the Set-PSBreakpoint cmdlet to create a breakpoint on the Increment function in the Sample.ps1 script. It saves the breakpoint object in the $b variable.</maml:para> <maml:para>The second command uses the dot operator (.) to get the Id property of the breakpoint object in the $b variable. It uses a pipeline operator (|) to send the ID to the Get-PSBreakpoint cmdlet.</maml:para> <maml:para>As a result, Get-PSBreakpoint gets the breakpoint with the specified ID.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint -script Sample.ps1, SupportScript.ps1 </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets all of the breakpoints in the Sample.ps1 and SupportScript.ps1 files.</maml:para> <maml:para>This command does not get other breakpointS that might be set in other scripts or on functions in the session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint -command Read-Host, Write-Host -script Sample.ps1 </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets all Command breakpoints that are set on Read-Host or Write-Host commands in the Sample.ps1 file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint -type Command -script Sample.ps1 </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets all Command breakpoints in the Sample.ps1 file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint -variable Index, Swap </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets breakpoints that are set on the $index and $swap variables in the current session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-psbreakpoint -type line, variable -script Sample.ps1 </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command gets all line and variable breakpoints in the Sample.ps1 script.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293972</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Disable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSCallStack</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-PSCallStack</command:name> <maml:description> <maml:para>Displays the current call stack.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>PSCallStack</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-PSCallStack cmdlet displays the current call stack.</maml:para> <maml:para>Although it is designed to be used with the Windows PowerShell debugger, you can use this cmdlet to display the call stack in a script or function outside of the debugger.</maml:para> <maml:para>To run a Get-PSCallStack command while in the debugger, type "k" or "get-pscallstack".</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-PSCallStack</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.CallStackFrame</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-PSCallStack returns an object that represents the items in the call stack.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>function my-alias { $p = $args[0] get-alias | where {$_.definition -like "*$p"} | ft definition, name -auto } PS C:\ps-test> set-psbreakpoint -command my-alias Command : my-alias Action : Enabled : True HitCount : 0 Id : 0 Script : prompt PS C:\ps-test> my-alias get-content Entering debug mode. Use h or ? for help. Hit Command breakpoint on 'prompt:my-alias' my-alias get-content [DBG]: PS C:\ps-test> s $p = $args[0] DEBUG: Stepped to ': $p = $args[0] ' [DBG]: PS C:\ps-test> s get-alias | Where {$_.Definition -like "*$p*"} | ft Definition, [DBG]: PS C:\ps-test>get-pscallstack Name CommandLineParameters UnboundArguments Location ---- --------------------- ---------------- -------- prompt {} {} prompt my-alias {} {get-content} prompt prompt {} {} prompt [DBG]: PS C:\ps-test> o Definition Name ---------- ---- Get-Content gc Get-Content cat Get-Content type </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command uses the Get-PSCallStack cmdlet to display the call stack for My-Alias, a simple function that gets the aliases for a cmdlet name.</maml:para> <maml:para>The first command enters the function at the Windows PowerShell prompt. The second command uses the Set-PSBreakpoint cmdlet to set a breakpoint on the My-Alias function. The third command uses the My-Alias function to get all of the aliases in the current session for the Get-Content cmdlet.</maml:para> <maml:para>The debugger breaks in at the function call. Two consecutive step-into (s) commands begin executing the function line by line. Then, a Get-PSCallStack command is used to retrieve the call stack.</maml:para> <maml:para>The final command is a Step-Out command (o) that exits the debugger and continues executing the script to completion.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293973</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Disable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Random</command:name> <maml:description> <maml:para>Gets a random number, or selects objects randomly from a collection.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Random</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Random cmdlet gets a randomly selected number. If you submit a collection of objects to Get-Random, it gets one or more randomly selected objects from the collection.</maml:para> <maml:para>Without parameters or input, a Get-Random command returns a randomly selected 32-bit unsigned integer between 0 (zero) and Int32.MaxValue (0x7FFFFFFF, 2,147,483,647).</maml:para> <maml:para>You can use the parameters of Get-Random to specify a seed number, minimum and maximum values, and the number of objects returned from a submitted collection.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Random</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Maximum</maml:name> <maml:description> <maml:para>Specifies a maximum value for the random number. Get-Random returns a value that is less than the maximum (not equal). Enter a 32-bit integer or a double-precision floating-point number, or an object that can be converted to an integer or double, such as a numeric string ("100"). On a 64-bit computer, you can also enter a 64-bit integer.</maml:para> <maml:para>The value of Maximum must be greater than (not equal to) the value of Minimum.</maml:para> <maml:para>If the value of Maximum or Minimum is a floating-point number, Get-Random returns a randomly selected floating-point number. If the value of Minimum is a double (a floating-point number), the default value of Maximum is Double.MaxValue. Otherwise, the default value is Int32.MaxValue. </maml:para> <maml:para>On a 64-bit computer, if the value of Minimum is a 32-bit integer, the default value of Maximum is Int32.MaxValue. If the value of Minimum is a double (a floating-point number), the default value of Maximum is Double.MaxValue. Otherwise, the default value is Int64.MaxValue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minimum</maml:name> <maml:description> <maml:para>Specifies a minimum value for the random number. Enter a 32-bit integer or a double-precision floating-point number, or an object that can be converted to an integer or double, such as a numeric string ("100"). On a 64-bit computer, you can enter a 64-bit integer. The default value is 0 (zero).</maml:para> <maml:para>The value of Minimum must be less than (not equal to) the value of Maximum. If the value of Maximum or Minimum is a floating-point number, Get-Random returns a randomly selected floating-point number.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SetSeed</maml:name> <maml:description> <maml:para>Specifies a seed value for the random number generator. This seed value is used for the current command and for all subsequent Get-Random commands in the current session until you use SetSeed again or close the session. You cannot reset the seed to its default, clock-based value.</maml:para> <maml:para>The SetSeed parameter is not required. By default, Get-Random uses the system clock to generate a seed value. Because SetSeed results in non-random behavior, it is typically used only when trying to reproduce behavior, such as when debugging or analyzing a script that includes Get-Random commands.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Random</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies a collection of objects. Get-Random gets randomly selected objects in random order from the collection. Enter the objects, a variable that contains the objects, or a command or expression that gets the objects. You can also pipe a collection of objects to Get-Random.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Count</maml:name> <maml:description> <maml:para>Determines how many objects are returned. The default is 1. If the value of Count exceeds the number of objects in the collection, Get-Random returns all of the objects in random order.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SetSeed</maml:name> <maml:description> <maml:para>Specifies a seed value for the random number generator. This seed value is used for the current command and for all subsequent Get-Random commands in the current session until you use SetSeed again or close the session. You cannot reset the seed to its default, clock-based value.</maml:para> <maml:para>The SetSeed parameter is not required. By default, Get-Random uses the system clock to generate a seed value. Because SetSeed results in non-random behavior, it is typically used only when trying to reproduce behavior, such as when debugging or analyzing a script that includes Get-Random commands.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Count</maml:name> <maml:description> <maml:para>Determines how many objects are returned. The default is 1. If the value of Count exceeds the number of objects in the collection, Get-Random returns all of the objects in random order.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies a collection of objects. Get-Random gets randomly selected objects in random order from the collection. Enter the objects, a variable that contains the objects, or a command or expression that gets the objects. You can also pipe a collection of objects to Get-Random.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Maximum</maml:name> <maml:description> <maml:para>Specifies a maximum value for the random number. Get-Random returns a value that is less than the maximum (not equal). Enter a 32-bit integer or a double-precision floating-point number, or an object that can be converted to an integer or double, such as a numeric string ("100"). On a 64-bit computer, you can also enter a 64-bit integer.</maml:para> <maml:para>The value of Maximum must be greater than (not equal to) the value of Minimum.</maml:para> <maml:para>If the value of Maximum or Minimum is a floating-point number, Get-Random returns a randomly selected floating-point number. If the value of Minimum is a double (a floating-point number), the default value of Maximum is Double.MaxValue. Otherwise, the default value is Int32.MaxValue. </maml:para> <maml:para>On a 64-bit computer, if the value of Minimum is a 32-bit integer, the default value of Maximum is Int32.MaxValue. If the value of Minimum is a double (a floating-point number), the default value of Maximum is Double.MaxValue. Otherwise, the default value is Int64.MaxValue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minimum</maml:name> <maml:description> <maml:para>Specifies a minimum value for the random number. Enter a 32-bit integer or a double-precision floating-point number, or an object that can be converted to an integer or double, such as a numeric string ("100"). On a 64-bit computer, you can enter a 64-bit integer. The default value is 0 (zero).</maml:para> <maml:para>The value of Minimum must be less than (not equal to) the value of Maximum. If the value of Maximum or Minimum is a floating-point number, Get-Random returns a randomly selected floating-point number.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SetSeed</maml:name> <maml:description> <maml:para>Specifies a seed value for the random number generator. This seed value is used for the current command and for all subsequent Get-Random commands in the current session until you use SetSeed again or close the session. You cannot reset the seed to its default, clock-based value.</maml:para> <maml:para>The SetSeed parameter is not required. By default, Get-Random uses the system clock to generate a seed value. Because SetSeed results in non-random behavior, it is typically used only when trying to reproduce behavior, such as when debugging or analyzing a script that includes Get-Random commands.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe one or more objects to Get-Random. Get-Random selects values randomly from the piped objects.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Int32, System.Int64, System.Double</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Random returns an integer or floating-point number, or an object selected randomly from a submitted collection.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Get-Random sets a default seed for each session based on the system time clock when the session starts.</maml:para> </maml:alert> <maml:alert> <maml:para>Beginning in Windows PowerShell 3.0, Get-Random supports 64-bit integers. In Windows PowerShell 2.0, all values are cast to System.Int32.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random 3951433 </dev:code> <dev:remarks> <maml:para>This command gets a random integer between 0 (zero) and Int32.MaxValue.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -Maximum 100 47 </dev:code> <dev:remarks> <maml:para>This command gets a random integer between 0 (zero) and 99.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -Minimum -100 -Maximum 100 56 </dev:code> <dev:remarks> <maml:para>This command gets a random integer between -100 and 99.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -Minimum 10.7 -Maximum 20.93 18.08467273887 </dev:code> <dev:remarks> <maml:para>This command gets a random floating-point number greater than or equal to 10.7 and less than 20.92.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -InputObject 1, 2, 3, 5, 8, 13 8 </dev:code> <dev:remarks> <maml:para>This command gets a randomly selected number from the specified array.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -InputObject 1, 2, 3, 5, 8, 13 -Count 3 3 1 13 </dev:code> <dev:remarks> <maml:para>This command gets three randomly selected numbers in random order from the array.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -InputObject 1, 2, 3, 5, 8, 13 -Count ([int]::MaxValue) 2 3 5 1 8 13 </dev:code> <dev:remarks> <maml:para>This command returns the entire collection in random order. The value of the Count parameter is the MaxValue static property of integers.</maml:para> <maml:para>To return an entire collection in random order, enter any number that is greater than or equal to the number of objects in the collection.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -InputObject "red", "yellow", "blue" yellow </dev:code> <dev:remarks> <maml:para>This command returns a random value from a non-numeric collection.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | Get-Random Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 144 4 2080 488 36 0.48 3164 wmiprvse </dev:code> <dev:remarks> <maml:para>This command gets a randomly selected process from the collection of processes on the computer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 10 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Content Servers.txt | Get-Random -Count (Get-Content Servers.txt).Count | foreach {Invoke-Command -ComputerName $_ -Command 'Get-Process PowerShell'} </dev:code> <dev:remarks> <maml:para>This command runs a command on a series of remote computers in random order.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 11 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -Maximum 100 -SetSeed 23 # Commands with the default seed are pseudorandom PS C:\>Get-Random -Maximum 100 59 PS C:\>Get-Random -Maximum 100 65 PS C:\>Get-Random -Maximum 100 21 # Commands with the same seed are not random PS C:\>Get-Random -Maximum 100 -SetSeed 23 74 PS C:\>Get-Random -Maximum 100 -SetSeed 23 74 PS C:\>Get-Random -Maximum 100 -SetSeed 23 74 # SetSeed results in a repeatable series PS C:\>Get-Random -Maximum 100 -SetSeed 23 74 PS C:\>Get-Random -Maximum 100 56 PS C:\>Get-Random -Maximum 100 84 PS C:\>Get-Random -Maximum 100 46 PS C:\>Get-Random -Maximum 100 -SetSeed 23 74 PS C:\>Get-Random -Maximum 100 56 PS C:\>Get-Random -Maximum 100 84 PS C:\>Get-Random -Maximum 100 46 </dev:code> <dev:remarks> <maml:para>This example shows the effect of using the SetSeed parameter. Because SetSeed produces non-random behavior, it is typically used only to reproduce results, such as when debugging or analyzing a script.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 12 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$files = dir -Path C:\* -Recurse PS C:\>$sample = $files | Get-Random -Count 50 </dev:code> <dev:remarks> <maml:para>These commands get a randomly selected sample of 50 files from the C: drive of the local computer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 13 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random 10001 7600 </dev:code> <dev:remarks> <maml:para>This command gets a random integer less than 10001. Because the Maximum parameter has position 1, you can omit the parameter name when the value is the first or only unnamed parameter in the command.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 14 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Random -Minimum ([Int64]::MinValue)3738173363251507200 PS C:\>Get-Random -Minimum ([Int32]::MaxValue) Minimum (2147483647) cannot be greater than or equal to Maximum (2147483647). + CategoryInfo : InvalidArgument: (:) [Get-Random], ArgumentException + FullyQualifiedErrorId : MinGreaterThanOrEqualMax,Microsoft.PowerShell.Commands.GetRandomCommand </dev:code> <dev:remarks> <maml:para>These commands attempt to get randomly generated 64-bit numbers.</maml:para> <maml:para>The first command succeeds, but the second command fails. When the value of Minimum is a 32-bit integer, the default value of Maximum is Int32.MaxValues. The command fails because the value of Maximum must be greater than the value of Minimum.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293974</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Runspace</command:name> <maml:description> <maml:para>Gets active runspaces within a Windows PowerShell host process.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Runspace</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This content is coming in a future release.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Runspace</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Runspace</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Runspace</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>InstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>InstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> <dev:type> <maml:name>Guid[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> 2: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-RunspaceDebug</command:name> <maml:description> <maml:para>Shows runspace debugging options.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>RunspaceDebug</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This content is coming in a future release.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-RunspaceDebug</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-RunspaceDebug</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ProcessName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>AppDomainName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Runspace[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-RunspaceDebug</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceInstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>AppDomainName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ProcessName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="1" aliases="none"> <maml:name>Runspace</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Runspace[]</command:parameterValue> <dev:type> <maml:name>Runspace[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceInstanceId</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Guid[]</command:parameterValue> <dev:type> <maml:name>Guid[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>RunspaceName</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> 2: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-SerializedCommand</command:name> <maml:description> <maml:para> </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>SerializedCommand</command:noun> <dev:version /> </command:details> <maml:description> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-SerializedCommand</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-TraceSource</command:name> <maml:description> <maml:para>Gets the Windows PowerShell components that are instrumented for tracing.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>TraceSource</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-TraceSource cmdlet gets the trace sources for Windows PowerShell components that are currently in use. You can use the data to determine which Windows PowerShell components you can trace. When tracing, the component generates detailed messages about each step in its internal processing. Developers use the trace data to monitor data flow, program execution, and errors. The tracing cmdlets were designed for Windows PowerShell developers, but they are available to all users.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-TraceSource</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Gets only the specified trace sources. Wildcards are permitted. The parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Gets only the specified trace sources. Wildcards are permitted. The parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains the name of a trace source to Get-TraceSource.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSTraceSource</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-TraceSource returns objects that represent the trace sources.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-traceSource *provider* </dev:code> <dev:remarks> <maml:para>This command gets all of the trace sources that have names that include "provider".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-tracesource </dev:code> <dev:remarks> <maml:para>This command gets all of the Windows PowerShell components that can be traced.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293975</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-TraceSource</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Trace-Command</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-TypeData</command:name> <maml:description> <maml:para>Gets the extended type data in the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>TypeData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-TypeData cmdlet gets the extended type data in the current session. This includes type data that was added to the session by Types.ps1xml file and dynamic type data that was added by using the parameter of the Update-TypeData cmdlet.</maml:para> <maml:para>You can use the extended type data that Get-TypeData returns to examine the type data in the session and send it to the Update-TypeData and Remove-TypeData cmdlets.</maml:para> <maml:para>Extended type data adds properties and methods to objects in Windows PowerShell. You can use the added properties and methods in the same ways that you would use the properties and methods that are defined in the object type. However, when writing scripts, be aware that the added properties and methods might not be present in every Windows PowerShell session.</maml:para> <maml:para>For more information about Types.ps1xml files, see about_Types.ps1xml (http://go.microsoft.com/fwlink/?LinkID=113274). For more information about dynamic type data that the Update-TypeData cmdlet adds, see Update-TypeData.</maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-TypeData</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Gets type data only for the types with the specified names. By default, Get-TypeData gets all types in the session.</maml:para> <maml:para>Enter type names or a name patterns. Full names (or name patterns with wildcard characters) are required, even for types in the System namespace. Wildcards are supported and the parameter name (-TypeName) is optional. You can also pipe type names to Get-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter type names or a name patterns. Full names (or name patterns with wildcard characters) are required, even for types in the System namespace. Wildcards are supported and the parameter name (-TypeName) is optional. You can also pipe type names to Get-TypeData.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter type names or a name patterns. Full names (or name patterns with wildcard characters) are required, even for types in the System namespace. Wildcards are supported and the parameter name (-TypeName) is optional. You can also pipe type names to Get-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter type names or a name patterns. Full names (or name patterns with wildcard characters) are required, even for types in the System namespace. Wildcards are supported and the parameter name (-TypeName) is optional. You can also pipe type names to Get-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter type names or a name patterns. Full names (or name patterns with wildcard characters) are required, even for types in the System namespace. Wildcards are supported and the parameter name (-TypeName) is optional. You can also pipe type names to Get-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Gets type data only for the types with the specified names. By default, Get-TypeData gets all types in the session.</maml:para> <maml:para>Enter type names or a name patterns. Full names (or name patterns with wildcard characters) are required, even for types in the System namespace. Wildcards are supported and the parameter name (-TypeName) is optional. You can also pipe type names to Get-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe type names to Get-TypeData.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.Runspaces.TypeData</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Get-TypeData gets only the extended type data in the current session. It does not get extended type data that is on the computer, but has not been added to the current session, such as extended types that are defined in modules that have not been imported into the current session.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-TypeData </dev:code> <dev:remarks> <maml:para>This command gets all extended type data in the current session.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"*Eventing*" | Get-TypeData TypeName Members-------- -------System.Diagnostics.Eventing.Reader.EventLogConfiguration {}System.Diagnostics.Eventing.Reader.EventLogRecord {}System.Diagnostics.Eventing.Reader.ProviderMetadata {[ProviderName, System.Management.Automation.Runspaces.AliasProper... </dev:code> <dev:remarks> <maml:para>This command gets all types in the current session that have names that contain "Eventing".</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(Get-TypeData *EventLogEntry*).Members.EventID GetScriptBlock SetScriptBlock IsHidden Name -------------- -------------- -------- ---- $this.get_EventID() -band 0xFFFF False EventID </dev:code> <dev:remarks> <maml:para>This command gets the script block that creates the value of the EventID property of EventLogEntry objects. </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(Get-TypeData -TypeName System.DateTime).Members["DateTime"].GetScriptBlock if ((& { Set-StrictMode -Version 1; $this.DisplayHint }) -ieq "Date") { "{0}" -f $this.ToLongDateString() } elseif ((& { Set-StrictMode -Version 1; $this.DisplayHint }) -ieq "Time") { "{0}" -f $this.ToLongTimeString() } else { "{0} {1}" -f $this.ToLongDateString(), $this.ToLongTimeString() } </dev:code> <dev:remarks> <maml:para>This command gets the script block that defines the DateTime property of System.DateTime objects in Windows PowerShell.</maml:para> <maml:para>The command uses the Get-TypeData cmdlet to get the extended type data for the System.DataTime type. The command gets the Members property of the TypeData object. </maml:para> <maml:para>The Members property contains a hash table of properties and methods that are defined by extended type data. Each key in the Members hash table is a property or method name and each value is the definition of the property or method value. </maml:para> <maml:para>The command gets the DateTime key in Members and its GetScriptBlock property value.</maml:para> <maml:para>The output shows the script block that creates the value of the DateTime property of every System.DateTime object in Windows PowerShell.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 4</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>dir $pshome\*types.ps1xml -Recurse | Select-String "EventLogEntry" C:\WINDOWS\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:180: <Name>System.Diagnostics.EventLogEntry</Name> C:\WINDOWS\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:182: <TypeName>System.Diagnostics.EventLogEntry</TypeName> C:\WINDOWS\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:801: <Name>System.Diagnostics.EventLogEntry</Name> C:\WINDOWS\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:803: <TypeName>System.Diagnostics.EventLogEntry</TypeName> C:\WINDOWS\System32\WindowsPowerShell\v1.0\types.ps1xml:433: <Name>System.Diagnostics.EventLogEntry</Name> </dev:code> <dev:remarks> <maml:para>This command finds the Types.ps1xml file that added extended type data for the EventLogEntry type to the session. This command uses the Get-ChildItem cmdlet (alias = "dir") to perform a recursive search for Types.ps1xml files in the Windows PowerShell installation directory ($pshome) and its subdirectories. The command sends the Types.ps1xml files to the Select-String cmdlet, which does a full-text search for the "EventLogEntry" type name in the files and returns the matches.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293976</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Types.ps1xml</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-TypeData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Update-TypeData</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-UICulture</command:name> <maml:description> <maml:para>Gets the current user interface (UI) culture settings in the operating system.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>UICulture</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-UICulture cmdlet gets information about the current UI culture settings for Windows. The UI culture determines which text strings are used for user interface elements, such as menus and messages.</maml:para> <maml:para>You can also use the Get-Culture cmdlet, which gets the current culture on the system. The culture determines the display format of items such as numbers, currency, and dates.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-UICulture</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Globalization.CultureInfo, Microsoft.PowerShell.VistaCultureInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-UICulture returns an object that represents the current UI culture. In Windows PowerShell 3.0, it returns a CultureInfo object. In Windows PowerShell 2.0, it returns a VistaCultureInfo object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also use the $PsCulture and $PsUICulture variables. The $PsCulture variable stores the name of the current culture, and the $PsUICulture variable stores the name of the current UI culture.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-uiculture </dev:code> <dev:remarks> <maml:para>This command gets the current UI culture information.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-uiculture | format-list * </dev:code> <dev:remarks> <maml:para>This command displays the values of all of the properties of the current UI culture in a list.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-uiculture).calendar </dev:code> <dev:remarks> <maml:para>This command displays the current values for the Calendar property of the current UI culture. Calendar is just one property of UI culture. To see all of the properties, type "get-uiculture | get-member".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(get-uiculture).datetimeformat.shortdatepattern </dev:code> <dev:remarks> <maml:para>This command displays the short date pattern for the current UI culture. To see all of the subproperties of the DateTimeFormat property of the UI culture, type "(get-uiculture).datetimeformat | gm".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293977</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Unique</command:name> <maml:description> <maml:para>Returns unique items from a sorted list.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Unique</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Unique cmdlet compares each item in a sorted list to the next item, eliminates duplicates, and returns only one instance of each item. The list must be sorted for the cmdlet to work properly.</maml:para> <maml:para>Get-Unique is case-sensitive. As a result, strings that differ only in character casing are considered to be unique.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Unique</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AsString</maml:name> <maml:description> <maml:para>Treats the data as a string. Without this parameter, data is treated as an object, so when you submit a collection of objects of the same type to Get-Unique, such as a collection of files, it returns just one (the first). You can use this parameter to find the unique values of object properties, such as the file names.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringarameter</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Get-Unique. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> <maml:para>Get-Unique treats the input submitted by using InputObject as a collection; it does not enumerate individual items in the collection. Because the collection is a single item, input submitted by using InputObject is always returned unchanged.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-Unique</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringarameter</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Get-Unique. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> <maml:para>Get-Unique treats the input submitted by using InputObject as a collection; it does not enumerate individual items in the collection. Because the collection is a single item, input submitted by using InputObject is always returned unchanged.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OnType</maml:name> <maml:description> <maml:para>Returns only one object of each type.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AsString</maml:name> <maml:description> <maml:para>Treats the data as a string. Without this parameter, data is treated as an object, so when you submit a collection of objects of the same type to Get-Unique, such as a collection of files, it returns just one (the first). You can use this parameter to find the unique values of object properties, such as the file names.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreferencearameter</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreferencearameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringarameter</command:parameterValue> <dev:type> <maml:name>System.Stringarameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Get-Unique. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> <maml:para>Get-Unique treats the input submitted by using InputObject as a collection; it does not enumerate individual items in the collection. Because the collection is a single item, input submitted by using InputObject is always returned unchanged.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OnType</maml:name> <maml:description> <maml:para>Returns only one object of each type.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any type of object to Get-Unique.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The type of object that Get-Unique returns is determined by the input.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also refer to Get-Unique by its built-in alias, "gu". For more information, see about_Aliases.</maml:para> <maml:para>To sort a list, use Sort-Object. You can also use the Unique parameter of Sort-Object to find the unique items in a list.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = $(foreach ($line in get-content C:\Test1\File1.txt) {$line.tolower().split(" ")}) | sort | get-unique PS C:\>$a.count </dev:code> <dev:remarks> <maml:para>These commands find the number of unique words in a text file.</maml:para> <maml:para>The first command gets the content of the File.txt file. It converts each line of text to lowercase letters and then splits each word onto a separate line at the space (" "). Then, it sorts the resulting list alphabetically (the default) and uses the Get-Unique cmdlet to eliminate any duplicate words. The results are stored in the $a variable.</maml:para> <maml:para>The second command uses the Count property of the collection of strings in $a to determine how many items are in $a.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>1,1,1,1,12,23,4,5,4643,5,3,3,3,3,3,3,3 | sort-object | Get-Unique </dev:code> <dev:remarks> <maml:para>This command finds the unique members of the set of integers. The first command takes an array of integers typed at the command line, pipes them to the Sort-Object cmdlet to be sorted, and then pipes them to Get-Unique, which eliminates duplicate entries.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | sort-object {$_.GetType()} | unique -OnType </dev:code> <dev:remarks> <maml:para>This command uses the Get-ChildItem cmdlet to retrieve the contents of the local directory, which includes files and directories. The pipeline operator (|) sends the results to the Sort-Object cmdlet. The "$_.GetType()" statement applies the GetType method to each file or directory. Then, Sort-Object sorts the items by type. Another pipeline operator sends the results to Get-Unique. The OnType parameter directs Get-Unique to return only one object of each type.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | sort-object | select processname | get-unique -asstring </dev:code> <dev:remarks> <maml:para>This command gets the names of processes running on the computer with duplicates eliminated.</maml:para> <maml:para>The Get-Process command gets all of the processes on the computer. The pipeline operator (|) passes the result to Sort-Object, which, by default, sorts the processes alphabetically by ProcessName. The results are piped to the Select-Object cmdlet, which selects only the values of the ProcessName property of each object. The results are then piped to Get-Unique to eliminate duplicates.</maml:para> <maml:para>The AsString parameter tells Get-Unique to treat the ProcessName values as strings. Without this parameter, Get-Unique treats the ProcessName values as objects and returns only one instance of the object, that is, the first process name in the list.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293978</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Sort-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-Variable</command:name> <maml:description> <maml:para>Gets the variables in the current console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Get</command:verb> <command:noun>Variable</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Get-Variable cmdlet gets the Windows PowerShell variables in the current console. You can retrieve just the values of the variables by specifying the ValueOnly parameter, and you can filter the variables returned by name.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-Variable</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the variable. Wildcards are permitted. You can also pipe a variable name to Get-Variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Specifies only the items upon which the cmdlet will act, excluding all others. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Gets only the variables in the specified scope. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ValueOnly</maml:name> <maml:description> <maml:para>Gets only the value of the variable.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Specifies only the items upon which the cmdlet will act, excluding all others. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the variable. Wildcards are permitted. You can also pipe a variable name to Get-Variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Gets only the variables in the specified scope. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ValueOnly</maml:name> <maml:description> <maml:para>Gets only the value of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains the variable name to Get-Variable.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSVariable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Get-Variable returns a System.Management.Automation variable object for each variable that it gets. The object type depends on the variable.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>This cmdlet does not manage environment variables. To manage environment variables, you can use the environment variable provider.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Variable m* </dev:code> <dev:remarks> <maml:para>This command gets variables with names that begin with the letter "m". The command also gets the value of the variables.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Variable m* -Valueonly </dev:code> <dev:remarks> <maml:para>This command gets only the values of the variables that have names that begin with "m".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Variable -Include M*,P* </dev:code> <dev:remarks> <maml:para>This command gets information about the variables that begin with either the letter "M" or the letter "P".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Variable -Scope 0 PS C:\>Compare-Object (Get-Variable -Scope 0) (Get-Variable -Scope 1) </dev:code> <dev:remarks> <maml:para>The first command gets only the variables that are defined in the local scope. It is equivalent to "Get-Variable -Scope Local" and can be abbreviated as "gv -s 0".</maml:para> <maml:para>The second command uses the Compare-Object cmdlet to find the variables that are defined in the parent scope (Scope 1) but are visible only in the local scope (Scope 0).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293979</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Group-Object</command:name> <maml:description> <maml:para>Groups objects that contain the same value for specified properties.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Group</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Group-Object cmdlet displays objects in groups based on the value of a specified property. Group-Object returns a table with one row for each property value and a column that displays the number of items with that value.</maml:para> <maml:para>If you specify more than one property, Group-Object first groups them by the values of the first property, and then, within each property group, it groups by the value of the next property.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Group-Object</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties for grouping. The objects are arranged into groups based on the value of the specified property.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, create a hash table with an Expression key that specifies a string or script block value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="AHT"> <maml:name>AsHashTable</maml:name> <maml:description> <maml:para>Returns the group as a hash table. The keys of the hash table are the property values by which the objects are grouped. The values of the hash table are the objects that have that property value.</maml:para> <maml:para>By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AsString</maml:name> <maml:description> <maml:para>Converts the hash table keys to strings. By default, the hash table keys are instances of the grouped object. This parameter is valid only when used with the AsHashTable parameter.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Makes the grouping case-sensitive. Without this parameter, the property values of objects in a group might have different cases.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Culture</maml:name> <maml:description> <maml:para>Specifies the culture to use when comparing strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to group. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> <maml:para>When you use the InputObject parameter to submit a collection of objects to Group-Object, Group-Object receives one object that represents the collection. As a result, it creates a single group with that object as its member.</maml:para> <maml:para>To group the objects in a collection, pipe the objects to Group-Object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoElement</maml:name> <maml:description> <maml:para>Omits the members of a group from the results.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="AHT"> <maml:name>AsHashTable</maml:name> <maml:description> <maml:para>Returns the group as a hash table. The keys of the hash table are the property values by which the objects are grouped. The values of the hash table are the objects that have that property value.</maml:para> <maml:para>By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AsString</maml:name> <maml:description> <maml:para>Converts the hash table keys to strings. By default, the hash table keys are instances of the grouped object. This parameter is valid only when used with the AsHashTable parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Makes the grouping case-sensitive. Without this parameter, the property values of objects in a group might have different cases.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Culture</maml:name> <maml:description> <maml:para>Specifies the culture to use when comparing strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to group. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> <maml:para>When you use the InputObject parameter to submit a collection of objects to Group-Object, Group-Object receives one object that represents the collection. As a result, it creates a single group with that object as its member.</maml:para> <maml:para>To group the objects in a collection, pipe the objects to Group-Object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoElement</maml:name> <maml:description> <maml:para>Omits the members of a group from the results.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties for grouping. The objects are arranged into groups based on the value of the specified property.</maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, create a hash table with an Expression key that specifies a string or script block value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Group-Object</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.GroupInfo or System.Collections.Hashtable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the AsHashTable parameter, Group-Object returns a hash table. Otherwise, it returns a GroupInfo object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also use the GroupBy parameter of the formatting cmdlets (such as Format-Table [m2] and Format-List [m2]) to group objects. Unlike Group-Object, which creates a single table with a row for each property value, the GroupBy parameters create a table for each property value with a row for each item that has the property value.</maml:para> <maml:para>Group-Object does not require that the objects being grouped be of the same Microsoft .NET Framework type. When grouping objects of different .NET Framework types, Group-Object uses the following rules:</maml:para> <maml:para>-- Same Property Names and Types: If the objects have a property with the specified name, and the property values have the same .NET Framework type, the property values are grouped by using the same rules that would be used for objects of the same type.</maml:para> <maml:para>-- Same Property Names, Different Types: If the objects have a property with the specified name, but the property values have a different .NET Framework type in different objects, Group-Object uses the .NET Framework type of the first occurrence of the property as the .NET Framework type for that property group. When an object has a property with a different type, the property value is converted to the type for that group. If the type conversion fails, the object is not included in the group.</maml:para> <maml:para>-- Missing Properties: Objects that do not have a specified property are considered ungroupable. Ungroupable objects appear in the final GroupInfo object output in a group named AutomationNull.Value.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem *.doc | group-object -property length </dev:code> <dev:remarks> <maml:para>This command gets the files in the current location that have a .doc extension and groups them by size.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | sort-object -property extension | group-object -property extension </dev:code> <dev:remarks> <maml:para>This command gets the files in the current location, sorts them by file name extension, and then groups them by file name extension. Note that the files are sorted before they are grouped.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>1..35 | group-object -property {$_ % 2},{$_ % 3} </dev:code> <dev:remarks> <maml:para>This example shows how to use script blocks as the value of the Property parameter.</maml:para> <maml:para>This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$events = get-eventlog -logname system -newest 1000 PS C:\>$events | group-object -property eventID Count Name Group ----- ---- ----- 44 Information {System.Diagnostics.EventLogEntry, 5 Error {System.Diagnostics.EventLogEntry, 1 Warning {System.Diagnostics.EventLogEntry} </dev:code> <dev:remarks> <maml:para>These commands display the 1,000 most recent entries in the System event log, grouped by Event ID.</maml:para> <maml:para>The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $events variable.</maml:para> <maml:para>The second command uses a pipeline operator (|) to send the events in the $events variable to the Group-Object cmdlet. The command uses the Property parameter to specify that the events should be grouped according to the value of their EventID property.</maml:para> <maml:para>In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | group-object -property priorityclass Count Name Group ----- ---- ----- 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia... 1 {System.Diagnostics.Process (Idle)} 3 High {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D... 2 BelowNormal {System.Diagnostics.Process (winperf), PS C:\>get-process | group-object -property company -noelement Count Name ----- ---- 55 Normal 1 3 High 2 BelowNormal </dev:code> <dev:remarks> <maml:para>This example demonstrates the effect of the NoElement parameter. These commands group the processes on the computer by priority class.</maml:para> <maml:para>The first command uses the Get-Process cmdlet to get the processes on the computer. It uses a pipeline operator (|) to send the results to Group-Object, which groups the objects by the value of the PriorityClass property of the process.</maml:para> <maml:para>The second command is identical to the first, except that it uses the NoElement parameter to eliminate the members of the group from the output. The result is a table with only the count and property value name.</maml:para> <maml:para>The results are shown in the following sample output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventlog -logname system -newest 1000 | group-object -property {$_.TimeWritten - $_.TimeGenerated} </dev:code> <dev:remarks> <maml:para>This command demonstrates how to provide the value of the Property parameter as a script block.</maml:para> <maml:para>This command displays the most recent 1,000 entries from the system event log, grouped according to the time between when they were generated and when they were written to the log.</maml:para> <maml:para>The command uses the Get-EventLog cmdlet to get the event log entries. It uses a pipeline operator (|) to send the entries to the Group-Object cmdlet. The value of the Property parameter is specified as a script block (an expression in braces). The result of evaluating the script block is the time between when the log entry was generated and when it was written to the log. That value is used to group the 1,000 most recent events.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | group-object extension -noelement Count Name ----- ---- 21 82 .txt 9 .cmd 5 .log 12 .xml 5 .htm 36 .ps1 1 .psc1 3 .exe 6 .csv 1 .psd1 2 .bat </dev:code> <dev:remarks> <maml:para>This command groups the items in the current directory by file name extension. It uses the NoElement parameter to omit the members of the group.</maml:para> <maml:para>The results are shown in the following sample output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"a", "b", "c", "c", "d" | get-unique a b c d PS C:\>"a", "b", "c", "c", "d" | group-object -noelement | where {$_.Count -gt 1} Count Name ----- ---- 2 c PS C:\>get-process | group-object -property Name -noelement | where {$_.count -gt 1} Count Name ----- ---- 2 csrss 5 svchost 2 winlogon 2 wmiprvse </dev:code> <dev:remarks> <maml:para>This example shows how to find the unique and non-unique (repeated) property values in a collection.</maml:para> <maml:para>The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet.</maml:para> <maml:para>The second command gets the non-unique elements of an array. It pipes the array to the Group-Object cmdlet, which groups the objects by value. The resulting groups are piped to the Where-Object cmdlet, which selects objects with groups with more than one member.</maml:para> <maml:para>The third command shows a practical use for this technique. It uses the same method to find processes on the computer that have the same process name.</maml:para> <maml:para>The results are shown in the following sample output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = get-command get-*, set-* -type cmdlet | group-object -property verb -ashashtable -asstring PS C:\>$a Name Value ---- ----- Get {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession...} Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} PS C:\>$a.get CommandType Name Definition ----------- ---- ---------- Cmdlet Get-PSCallStack Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction <ActionPrefer... Cmdlet Get-PSBreakpoint Get-PSBreakpoint [[-Id] <Int32[]>] [-Verbose] [-Debug] [-ErrorA... Cmdlet Get-PSDrive Get-PSDrive [[-Name] <String[]>] [-Scope <String>] [-PSProvider... ... </dev:code> <dev:remarks> <maml:para>This example uses the AsHashTable and AsString parameters to return the groups in a hash table, that is, as a collection of key-value pairs.</maml:para> <maml:para>In the resulting hash table, each property value is a key, and the group elements are the values. Because each key is a property of the hash table object, you can use dot notation to display the values.</maml:para> <maml:para>The first command gets the Get and Set cmdlets in the session, groups them by verb, returns the groups as a hash table, and saves the hash table in the $a variable.</maml:para> <maml:para>The second command displays the hash table in $a. There are two key-value pairs, one for the Get cmdlets and one for the Set cmdlets.</maml:para> <maml:para>The third command uses dot notation to display the values of the Get key in $a. The values are CmdletInfo object. The AsString parameter does not convert the objects in the groups to strings.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293980</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Import-Alias</command:name> <maml:description> <maml:para>Imports an alias list from a file.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Import</command:verb> <command:noun>Alias</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Import-Alias cmdlet imports an alias list from a file.</maml:para> <maml:para>Beginning in Windows PowerShell 3.0, as a security feature, Import-Alias does not overwrite existing aliases by default. To overwrite an existing alias, after assuring that the contents of the alias file is safe, use the Force parameter.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Import-Alias</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to a file that includes exported alias information. Wildcards are allowed but they must resolve to a single name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to import an alias that is already defined or is read only. You can use the following command to display information about the currently-defined aliases:</maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object that represents the alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope into which the aliases are imported. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Import-Alias</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to import an alias that is already defined or is read only. You can use the following command to display information about the currently-defined aliases:</maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object that represents the alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope into which the aliases are imported. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a file that includes exported alias information. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to import an alias that is already defined or is read only. You can use the following command to display information about the currently-defined aliases:</maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>get-alias | select-object name,Options</maml:para> <maml:para>If the corresponding alias is read-only, it will be displayed in the value of the Options property.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object that represents the alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to a file that includes exported alias information. Wildcards are allowed but they must resolve to a single name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope into which the aliases are imported. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a file that includes exported alias information. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains a path to Import-Alias.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.AliasInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the Passthru parameter, Import-Alias returns a System.Management.Automation.AliasInfo object that represents the alias. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>import-alias test.txt </dev:code> <dev:remarks> <maml:para>This command imports alias information from a file named test.txt.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293981</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Import-Clixml</command:name> <maml:description> <maml:para>Imports a CLIXML file and creates corresponding objects within Windows PowerShell.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Import</command:verb> <command:noun>Clixml</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Import-CliXml cmdlet imports a CLIXML file with data that represents Microsoft .NET Framework objects and creates the objects in Windows PowerShell.</maml:para> <maml:para>A valuable use of Import-CliXml is to import credentials and secure strings that have been exported as secure XML by running the Export-CliXml cmdlet. For an example of how to do this, see Example 2 in this topic.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Import-Clixml</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the XML files.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>First</maml:name> <maml:description> <maml:para>Gets only the specified number of objects. Enter the number of objects to get.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Skip</maml:name> <maml:description> <maml:para>Ignores the specified number of objects and then gets the remaining objects. Enter the number of objects to skip.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>IncludeTotalCount</maml:name> <maml:description> <maml:para>Reports the total number of objects in the data set (an integer) followed by the selected objects. If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value. The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Import-Clixml</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the XML files. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>First</maml:name> <maml:description> <maml:para>Gets only the specified number of objects. Enter the number of objects to get.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Skip</maml:name> <maml:description> <maml:para>Ignores the specified number of objects and then gets the remaining objects. Enter the number of objects to skip.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>IncludeTotalCount</maml:name> <maml:description> <maml:para>Reports the total number of objects in the data set (an integer) followed by the selected objects. If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value. The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the XML files.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the XML files. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>First</maml:name> <maml:description> <maml:para>Gets only the specified number of objects. Enter the number of objects to get.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Skip</maml:name> <maml:description> <maml:para>Ignores the specified number of objects and then gets the remaining objects. Enter the number of objects to skip.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>IncludeTotalCount</maml:name> <maml:description> <maml:para>Reports the total number of objects in the data set (an integer) followed by the selected objects. If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value. The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains a path to Import-Clixml.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Import-Clixml returns objects that have been deserialized from the stored XML files.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | export-clixml pi.xml PS C:\>$processes = import-clixml pi.xml </dev:code> <dev:remarks> <maml:para>This command uses the Export-Clixml cmdlet to save a serialized copy of the process information returned by Get-Process. It then uses Import-Clixml to retrieve the contents of the serialized file and re-create an object that is stored in the $processes variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$credxmlpath = Join-Path (Split-Path $profile) TestScript.ps1.credential PS C:\>$credential | Export-CliXml $credxmlpath </dev:code> <dev:code>PS C:\>$credxmlpath = Join-Path (Split-Path $profile) TestScript.ps1.credential PS C:\>$credential = Import-CliXml $credxmlpath </dev:code> <dev:remarks> <maml:para>The Export-CliXml cmdlet encrypts credential objects by using the <maml:navigationLink><maml:linkText>Windows Data Protection API</maml:linkText><maml:uri></maml:uri></maml:navigationLink>. This ensures that only your user account can decrypt the contents of the credential object.</maml:para> <maml:para>In this example, given a credential that you�ve stored in the $credential variable by running the Get-Credential cmdlet, you can run the Export-CliXml cmdlet to save the credential to disk.In the example, the file in which the credential is stored is represented by TestScript.ps1.credential. Replace TestScript with the name of the script with which you are loading the credential.</maml:para> <maml:para>In the second command, you pipe the credential object to Export-CliXml, and save it to the path, $credxmlpath, that you specified in the first command.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para>To import the credential automatically into your script, run the final two commands. This time, you are running Import-CliXml to import the secured credential object into your script. This eliminates the risk of exposing plain-text passwords in your script.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293982</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Use PowerShell to Pass Credentials to Legacy Systems</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Securely Store Credentials on Disk</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-CliXml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Import-Csv</command:name> <maml:description> <maml:para>Creates table-like custom objects from the items in a CSV file.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Import</command:verb> <command:noun>Csv</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Import-Csv cmdlet creates table-like custom objects from the items in CSV files. Each column in the CSV file becomes a property of the custom object and the items in rows become the property values. Import-Csv works on any CSV file, including files that are generated by the Export-Csv cmdlet.</maml:para> <maml:para>You can use the parameters of the Import-Csv cmdlet to specify the column header row and the item delimiter, or direct Import-Csv to use the list separator for the current culture as the item delimiter.</maml:para> <maml:para>You can also use the ConvertTo-Csv and ConvertFrom-Csv cmdlets to convert objects to CSV strings (and back). These cmdlets are the same as the Export-CSV and Import-Csv cmdlets, except that they do not deal with files. </maml:para> <maml:para>Beginning in Windows PowerShell 3.0, if a header row entry in a CSV file contains an empty or null value, Windows PowerShell inserts a default header row name and displays a warning message. In previous versions of Windows PowerShell, if a header row entry in a CSV file contains an empty or null value, the Import-Csv command fails.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Import-Csv</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the CSV file to import. You can also pipe a path to Import-Csv.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies the delimiter that separates the property values in the CSV file. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.</maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of character encoding that was used in the CSV file. Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. The default is ASCII.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:description> <maml:para>Specifies an alternate column header row for the imported file. The column header determines the names of the properties of the object that Import-Csv creates.</maml:para> <maml:para>Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no header. If you enter more headers than there are columns, the extra headers are ignored.</maml:para> <maml:para>When using the Header parameter, delete the original header row from the CSV file. Otherwise, Import-Csv creates an extra object from the items in the header row.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the CSV file to import. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Import-Csv</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the CSV file to import. You can also pipe a path to Import-Csv.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of character encoding that was used in the CSV file. Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. The default is ASCII.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF7</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF8</command:parameterValue> <command:parameterValue required="false" variableLength="false">ASCII</command:parameterValue> <command:parameterValue required="false" variableLength="false">UTF32</command:parameterValue> <command:parameterValue required="false" variableLength="false">BigEndianUnicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">OEM</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:description> <maml:para>Specifies an alternate column header row for the imported file. The column header determines the names of the properties of the object that Import-Csv creates.</maml:para> <maml:para>Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no header. If you enter more headers than there are columns, the extra headers are ignored.</maml:para> <maml:para>When using the Header parameter, delete the original header row from the CSV file. Otherwise, Import-Csv creates an extra object from the items in the header row.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the CSV file to import. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Use the list separator for the current culture as the item delimiter. The default is a comma (,).</maml:para> <maml:para>To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator. If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Delimiter</maml:name> <maml:description> <maml:para>Specifies the delimiter that separates the property values in the CSV file. The default is a comma (,). Enter a character, such as a colon (:). To specify a semicolon (;), enclose it in quotation marks.</maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Char</command:parameterValue> <dev:type> <maml:name>Char</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of character encoding that was used in the CSV file. Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. The default is ASCII.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Header</maml:name> <maml:description> <maml:para>Specifies an alternate column header row for the imported file. The column header determines the names of the properties of the object that Import-Csv creates.</maml:para> <maml:para>Enter a comma-separated list of the column headers. Enclose each item in quotation marks (single or double). Do not enclose the header string in quotation marks. If you enter fewer column headers than there are columns, the remaining columns will have no header. If you enter more headers than there are columns, the extra headers are ignored.</maml:para> <maml:para>When using the Header parameter, delete the original header row from the CSV file. Otherwise, Import-Csv creates an extra object from the items in the header row.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you specify a character other than the actual string delimiter in the file, Import-Csv cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the CSV file to import. You can also pipe a path to Import-Csv.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseCulture</maml:name> <maml:description> <maml:para>Use the list separator for the current culture as the item delimiter. The default is a comma (,).</maml:para> <maml:para>To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator. If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the CSV file to import. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains a path to Import-Csv.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Object. </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Import-Csv returns the objects described by the content in the CSV file.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Because the imported objects are CSV versions of the object type, they are not recognized and formatted by the Windows PowerShell type formatting entries that format the non-CSV versions of the object type. </maml:para> </maml:alert> <maml:alert> <maml:para>The result of an Import-Csv command is a collection of strings that form a table-like custom object. Each row is a separate string, so you can use the Count property of the object to count the table rows. The columns are the properties of the object and items in the rows are the property values.</maml:para> <maml:para>The column header row determines the number of columns and the column names. The column names are also the names of the properties of the objects. The first row is interpreted to be the column headers, unless you use the Header parameter to specify column headers. If any row has more values than the header row, the additional values are ignored.</maml:para> <maml:para>If the column header row is missing a value or contains a null or empty value, Import-Csv uses "H" followed by a number for the missing column header and property name.</maml:para> <maml:para>In the CSV file, each object is represented by a comma-separated list of the property values of the object. The property values are converted to strings (by using the ToString() method of the object), so they are generally represented by the name of the property value. Export-CSV does not export the methods of the object.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>This example shows how to export and then import a CSV file of objects.The first command uses the Get-Process cmdlet to get the process on the local computer. It uses a pipeline operator (|) to send the process objects to the Export-CSV cmdlet, which exports the process objects to the Processes.csv file in the current directory. PS C:\>get-process | export-csv processes.csv The second command uses the Import-Csv cmdlet to import the processes in the Import-Csv file. Then it saves the resulting process objects in the $p variable. PS C:\>$p = Import-Csv processes.csv The third command uses a pipeline operator to pipe the imported objects to the Get-Member cmdlets. The result shows that they are CSV:System.Diagnostic.Process objects, not the System.Diagnostic.Process objects that Get-Process returns.Also, because there is no entry type in the formatting files for the CSV version of the process objects, these objects are not formatted in the same way that standard process objects are formatted.To display the objects, use the formatting cmdlets, such as Format-Table and Format-List, or pipe the objects to Out-GridView. PS C:\>$p | get-member TypeName: CSV:System.Diagnostics.Process Name MemberType Definition ---- ---------- ---------- Equals Method System.Boolean Equals(Object obj) GetHashCode Method System.Int32 GetHashCode() GetType Method System.Type GetType() ToString Method System.String ToString() BasePriority NoteProperty System.String BasePriority=8 Company NoteProperty System.String Company=Microsoft Corporation ... PS C:\>$p | out-gridview </dev:code> <dev:remarks> <maml:para>This example shows how to export and then import a CSV file of objects.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | export-csv processes.csv -Delimiter : PS C:\>$p = Import-Csv processes.csv -Delimiter : </dev:code> <dev:remarks> <maml:para>This example shows how to use the Delimiter parameter of the Import-Csv cmdlet. In this example, the processes are exported to a file that uses a colon (:) as a delimiter.</maml:para> <maml:para>When importing, the Import-Csv file uses the Delimiter parameter to indicate the delimiter that is used in the file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$p = Import-Csv processes.csv -UseCulture PS C:\>(get-culture).textinfo.listseparator , </dev:code> <dev:remarks> <maml:para>This example shows how to use the UseCulture parameter of the Import-Csv cmdlet.</maml:para> <maml:para>The first command imports the objects in the Processes.csv file into the $p variable. It uses the UseCulture parameter to direct Import-Csv to use the list separator defined for the current culture.</maml:para> <maml:para>The second command displays the list separator for the current culture. It uses the Get-Culture cmdlet to get the current culture. It uses the dot (.) method to get the TextInfo property of the current culture and the ListSeparator property of the object in TextInfo. In this example, the command returns a comma.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Start-Job cmdlet to start a background job that runs a Get-Process command on the local computer. A pipeline operator (|) sends the resulting job object to the Export-CSV cmdlet, which converts the job object to CSV format. An assignment operator (=) saves the resulting CSV in the Jobs.csv file. PS C:\>start-job -scriptblock { get-process } | export-csv jobs.csv The second command saves a header in the $header variable. Unlike the default header, this header uses "MoreData" instead of "HasMoreData" and "State" instead of "JobStateInfo". PS C:\>$header = "MoreData","StatusMessage","Location","Command","State","Finished","InstanceId","SessionId","Name","ChildJobs","Output","Error","Progress","Verbose","Debug","Warning","StateChanged" The next three commands delete the original header (the second line) from the Jobs.csv file. PS C:\># Delete header from file PS C:\>$a = (get-content jobs.csv) PS C:\>$a = $a[0], $a[2..($a.count - 1)] PS C:\>$a > jobs.csv The sixth command uses the Import-Csv cmdlet to import the Jobs.csv file and convert the CSV strings into a CSV version of the job object. The command uses the Header parameter to submit the alternate header. The results are stored in the $j variable. PS C:\>$j = Import-Csv jobs.csv -header $header The seventh command displays the object in the $j variable. The resulting object has "MoreData" and "State" properties, as shown in the command output. PS C:\>$j MoreData : True StatusMessage : Location : localhost Command : get-process State : Running Finished : System.Threading.ManualResetEvent InstanceId : 135bdd25-40d6-4a20-bd68-05282a59abd6 SessionId : 1 Name : Job1 ChildJobs : System.Collections.Generic.List`1[System.Management.Automation.Job] Output : System.Management.Automation.PSDataCollection`1[System.Management.Automation.PSObject] Error : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ErrorRecord] Progress : System.Management.Automation.PSDataCollection`1[System.Management.Automation.ProgressRecord] Verbose : System.Management.Automation.PSDataCollection`1[System.String] Debug : System.Management.Automation.PSDataCollection`1[System.String] Warning : System.Management.Automation.PSDataCollection`1[System.String] StateChanged : </dev:code> <dev:remarks> <maml:para>This example shows how to use the Header parameter of Import-Csv to change the names of properties in the resulting imported object.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Get-Content cmdlet to get the Links.csv file. PS C:\>Get-Content .\Links.csv 113207,about_Aliases113208,about_Arithmetic_Operators113209,about_Arrays113210,about_Assignment_Operators113212, about_Automatic_Variables113213,about_Break113214,about_Command_Precedence113215,about_Command_Syntax144309, about_Comment_Based_Help113216,about_CommonParameters113217,about_Comparison_Operators113218,about_Continue113219, about_Core_Commands113220,about_Data_Section� The second command uses the Import-Csv cmdlet to import the Links.csv file. The command uses the Header parameter to specify LinkId and TopicTitle as property names for the new custom objects. The command saves the imported objects in the $a variable. PS C:\>$a = Import-Csv -Path .\Links.csv -Header LinkID, TopicTitle The third command uses the Get-Member cmdlet to get the type and members of the custom objects in the $a variable.The output shows that Import-Csv returns a collection of custom objects (PSCustomObject). In addition to some default properties, the custom objects have LinkID and TopicTitle note properties. PS C:\>$a | Get-Member TypeName: System.Management.Automation.PSCustomObject Name MemberType Definition ---- ---------- ---------- Equals Method bool Equals(System.Object obj) GetHashCode Method int GetHashCode()GetType Method type GetType()ToString Method string ToString()LinkID NoteProperty System.String LinkID=113207TopicTitle NoteProperty System.String TopicTitle=about_Aliases This command shows that you can use the custom object like you would any object in Windows PowerShell.The command pipes the custom objects in the $a variable to the Where-Object cmdlet, which gets only objects with a TopicTitle property that includes "alias".The Where-Object command uses the new simplified command format that does not require symbols, script blocks, or curly braces. PS C:\>$a | Where-Object TopicTitle -like "*alias*" LinkID TopicTitle ------ ---------- 113207 about_Aliases 113432 Alias Provider 113296 Export-Alias 113306 Get-Alias 113339 Import-Alias 113352 New-Alias 113390 Set-Alias </dev:code> <dev:remarks> <maml:para>This example shows how to create a custom object in Windows PowerShell by using a CSV file.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Get-Content cmdlet to get the Projects.csv file on the Server02 remote computer. The output shows that the header row of the file is missing a value between "ProjectName" and "Completed." PS C:\>Get-Content "\\Server2\c$\Test\Projects.csv" ProjectID, ProjectName,,Completed13, Inventory, Redmond, True440, , FarEast, True469, Marketing, Europe, False The second command uses the Import-Csv cmdlet to import the Projects.csv file.The output shows that Import-Csv generates a warning and substitutes a default name, H1, for the missing header row value. H1 is also used for the name of the object property. PS C:\>Import-Csv "\\Server2\c$\Test\Projects.csv" PS C:\>WARNING: One or more headers were not specified. Default names starting with "H" have been used in place of any missing headers. ProjectID ProjectName H1 Completed --------- ----------- -- --------- 13 Inventory Redmond True 440 FarEast True 469 Marketing Europe False The third command uses the dot method to get the value of the H1 property of the object that Import-Csv creates. PS C:\>(Import-Csv "\\Server2\c$\Test\Projects.csv").H1 RedmondFarEastEurope </dev:code> <dev:remarks> <maml:para>This example shows how the Import-Csv cmdlet in Windows PowerShell 3.0 responds when the header row in a CSV file includes a null or empty value. Import-Csv substitutes a default name for the header row. The default name becomes the name of the property of the object that Import-Csv returns.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293983</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Csv</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Import-LocalizedData</command:name> <maml:description> <maml:para>Imports language-specific data into scripts and functions based on the UI culture that is selected for the operating system.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Import</command:verb> <command:noun>LocalizedData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Import-LocalizedData cmdlet dynamically retrieves strings from a subdirectory whose name matches the UI language set for the current user of the operating system. It is designed to enable scripts to display user messages in the UI language selected by the current user.</maml:para> <maml:para>Import-LocalizedData imports data from .psd1 files in language-specific subdirectories of the script directory and saves them in a local variable that is specified in the command. The cmdlet selects the subdirectory and file based on the value of the $PSUICulture automatic variable. When you use the local variable in the script to display a user message, the message appears in the user's UI language.</maml:para> <maml:para>You can use the parameters of Import-LocalizedData to specify an alternate UI culture, path, and file name, to add supported commands, and to suppress the error message that appears if the .psd1 files are not found.</maml:para> <maml:para>The Import-LocalizedData cmdlet supports the script internationalization initiative that was introduced in Windows PowerShell 2.0. This initiative aims to better serve users worldwide by making it easy for scripts to display user messages in the UI language of the current user. For more information about this and about the format of the .psd1 files, see about_Script_Internationalization (http://go.microsoft.com/fwlink/?LinkID=113262).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Import-LocalizedData</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="Variable"> <maml:name>BindingVariable</maml:name> <maml:description> <maml:para>Specifies the variable into which the text strings are imported. Enter a variable name without a dollar sign ($). </maml:para> <maml:para>In Windows PowerShell 2.0, this parameter is required. In Windows PowerShell 3.0, this parameter is optional. If you omit this parameter, Import-LocalizedData returns a hash table of the text strings. The hash table is passed down the pipeline or displayed at the command line.</maml:para> <maml:para>When using Import-LocalizedData to replace default text strings specified in the DATA section of a script, assign the DATA section to a variable and enter the name of the DATA section variable in the value of the BindingVariable parameter. Then, when Import-LocalizedData saves the imported content in the BindingVariable, the imported data will replace the default text strings. If you are not specifying default text strings, you can select any variable name.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>UICulture</maml:name> <maml:description> <maml:para>Specifies an alternate UI culture. The default is the value of the $PsUICulture automatic variable. Enter a UI culture in "<language>-<region>" format, such as en-US, de-DE, or ar-SA.</maml:para> <maml:para>The value of the UICulture parameter determines the language-specific subdirectory (within the base directory) from which Import-LocalizedData gets the .psd1 file for the script.</maml:para> <maml:para>The cmdlet searches for a subdirectory with the same name as the value of the UICulture parameter or the $PsUICulture automatic variable, such as "de-DE" or "ar-SA". If it cannot find the directory, or the directory does not contain a .psd1 file for the script, it searches for a subdirectory with the name of the language code, such as "de" or "ar". If it cannot find the subdirectory or .psd1 file, the command fails and the data is displayed in the default language specified in the script.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>BaseDirectory</maml:name> <maml:description> <maml:para>Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>FileName</maml:name> <maml:description> <maml:para>Specifies the name of the data file (.psd1) to be imported. Enter a file name. You can specify a file name that does not include its .psd1 file name extension, or you can specify the file name including the .psd1 file name extension.</maml:para> <maml:para>The FileName parameter is required when Import-LocalizedData is not used in a script. Otherwise, the parameter is optional and the default value is the base name of the script. You can use this parameter to direct Import-LocalizedData to search for a different .psd1 file.</maml:para> <maml:para>For example, if the Filename is omitted and the script name is FindFiles.ps1, Import-LocalizedData searches for the FindFiles.psd1 data file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SupportedCommand</maml:name> <maml:description> <maml:para>Specifies cmdlets and functions that generate only data.</maml:para> <maml:para>Use this parameter to include cmdlets and functions that you have written or tested. For more information, see about_Script_Internationalization.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>BaseDirectory</maml:name> <maml:description> <maml:para>Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="Variable"> <maml:name>BindingVariable</maml:name> <maml:description> <maml:para>Specifies the variable into which the text strings are imported. Enter a variable name without a dollar sign ($). </maml:para> <maml:para>In Windows PowerShell 2.0, this parameter is required. In Windows PowerShell 3.0, this parameter is optional. If you omit this parameter, Import-LocalizedData returns a hash table of the text strings. The hash table is passed down the pipeline or displayed at the command line.</maml:para> <maml:para>When using Import-LocalizedData to replace default text strings specified in the DATA section of a script, assign the DATA section to a variable and enter the name of the DATA section variable in the value of the BindingVariable parameter. Then, when Import-LocalizedData saves the imported content in the BindingVariable, the imported data will replace the default text strings. If you are not specifying default text strings, you can select any variable name.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>FileName</maml:name> <maml:description> <maml:para>Specifies the name of the data file (.psd1) to be imported. Enter a file name. You can specify a file name that does not include its .psd1 file name extension, or you can specify the file name including the .psd1 file name extension.</maml:para> <maml:para>The FileName parameter is required when Import-LocalizedData is not used in a script. Otherwise, the parameter is optional and the default value is the base name of the script. You can use this parameter to direct Import-LocalizedData to search for a different .psd1 file.</maml:para> <maml:para>For example, if the Filename is omitted and the script name is FindFiles.ps1, Import-LocalizedData searches for the FindFiles.psd1 data file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SupportedCommand</maml:name> <maml:description> <maml:para>Specifies cmdlets and functions that generate only data.</maml:para> <maml:para>Use this parameter to include cmdlets and functions that you have written or tested. For more information, see about_Script_Internationalization.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>UICulture</maml:name> <maml:description> <maml:para>Specifies an alternate UI culture. The default is the value of the $PsUICulture automatic variable. Enter a UI culture in "<language>-<region>" format, such as en-US, de-DE, or ar-SA.</maml:para> <maml:para>The value of the UICulture parameter determines the language-specific subdirectory (within the base directory) from which Import-LocalizedData gets the .psd1 file for the script.</maml:para> <maml:para>The cmdlet searches for a subdirectory with the same name as the value of the UICulture parameter or the $PsUICulture automatic variable, such as "de-DE" or "ar-SA". If it cannot find the directory, or the directory does not contain a .psd1 file for the script, it searches for a subdirectory with the name of the language code, such as "de" or "ar". If it cannot find the subdirectory or .psd1 file, the command fails and the data is displayed in the default language specified in the script.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Import-LocalizedData saves the hash table in the variable that is specified by the value of the BindingVariable parameter.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Before using Import-LocalizedData, localize your user messages. Format the messages for each locale (UI culture) in a hash table of key/value pairs, and save the hash table in a file with the same name as the script and a .psd1 file name extension. Create a directory under the script directory for each supported UI culture, and then save the .psd1 file for each UI culture in the directory with the UI culture name.</maml:para> <maml:para>For example, localize your user messages for the de-DE locale and format them in a hash table. Save the hash table in a <ScriptName>.psd1 file. Then create a de-DE subdirectory under the script directory, and save the de-DE <ScriptName>.psd1 file in the de-DE subdirectory. Repeat this method for each locale that you support.</maml:para> </maml:alert> <maml:alert> <maml:para>Import-LocalizedData performs a structured search for the localized user messages for a script.</maml:para> <maml:para>Import-LocalizedData begins the search in the directory where the script file is located (or the value of the BaseDirectory parameter). It then searches within the base directory for a subdirectory with the same name as the value of the $PsUICulture variable (or the value of the UICulture parameter), such as "de-DE" or "ar-SA". Then, it searches in that subdirectory for a .psd1 file with the same name as the script (or the value of the FileName parameter).</maml:para> <maml:para>If Import-LocalizedData cannot find a subdirectory with the name of the UI culture, or the subdirectory does not contain a .psd1 file for the script, it searches for a .psd1 file for the script in a subdirectory with the name of the language code, such as "de" or "ar". If it cannot find the subdirectory or .psd1 file, the command fails, the data is displayed in the default language in the script, and an error message is displayed explaining that the data could not be imported. To suppress the message and fail gracefully, use the ErrorAction common parameter with a value of SilentlyContinue.</maml:para> <maml:para>If Import-LocalizedData finds the subdirectory and the .psd1 file, it imports the hash table of user messages into the value of the BindingVariable parameter in the command. Then, when you display a message from the hash table in the variable, the localized message is displayed.</maml:para> <maml:para>For more information, see about_Script_Internationalization (http://go.microsoft.com/fwlink/?LinkID=113262).</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Import-LocalizedData -BindingVariable Messages </dev:code> <dev:remarks> <maml:para>This command imports text strings into the $Messages variable. It uses the default values of all other cmdlet parameters.</maml:para> <maml:para>If the command is included in the Archives.ps1 script in the C:\Test directory, and the value of the $PsUICulture automatic variable is zh-CN, Import-LocalizedData imports the Archives.psd1 file in the C:\test\zh-CN directory into the $Messages variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Import-LocalizedData -FileName Test.psd1 -UICulture en-US Name Value ---- ----- Msg3 "Use $_ to represent the object that is being processed." Msg2 "This command requires the credentials of a member of the Administrators group on the... Msg1 "The Name parameter is missing from the command." </dev:code> <dev:remarks> <maml:para>This command is run at the command line; not in a script. It gets localized data strings from the Test.psd1 file and displays them at the command line. Because the command is not used in a script, the FileName parameter is required. The command uses the UICuture parameter to specify the en-US culture.</maml:para> <maml:para>Import-LocalizedData returns a hash table that contains the localized data strings.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Import-LocalizedData -BindingVariable msgTbl -UICulture ar-SA -FileName Simple -BaseDirectory C:\Data\Localized </dev:code> <dev:remarks> <maml:para>This command imports text strings into the $msgTbl variable of a script.</maml:para> <maml:para>It uses the UICulture parameter to direct the cmdlet to import data from the Simple.psd1 file in the ar-SA subdirectory of C:\Data\Localized.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\># In C:\Test\en-US\Test.psd1: ConvertFrom-StringData @' # English strings Msg1 = "The Name parameter is missing from the command." Msg2 = "This command requires the credentials of a member of the Administrators group on the computer." Msg3 = "Use $_ to represent the object that is being processed." '@ # In C:\Test\Test.ps1 Import-LocalizedData -Bindingvariable Messages Write-Host $Messages.Msg2 # In Windows PowerShell .\Test.ps1 This command requires the credentials of a member of the Administrators group on the computer. </dev:code> <dev:remarks> <maml:para>This example shows how to use localized data in a simple script.</maml:para> <maml:para>The first part of the example shows the contents of the Test.psd1 file. It contains a ConvertFrom-StringData command that converts a series of named text strings into a hash table. The Test.psd1 file is located in the en-US subdirectory of the C:\Test directory that contains the script.</maml:para> <maml:para>The second part of the example shows the contents of the Test.ps1 script. It contains an Import-LocalizedData command that imports the data from the matching .psd1 file into the $Messages variable and a Write-Host command that writes one of the messages in the $Messages variable to the host program.</maml:para> <maml:para>The last part of the example runs the script. The output shows that it displays the correct user message in the UI language set for the current user of the operating system.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\># In TestScript.ps1$UserMessages = DATA { ConvertFrom-StringData @' # English strings Msg1 = "Enter a name." Msg2 = "Enter your employee ID." Msg3 = "Enter your building number." '@ } Import-LocalizedData -BindingVariable UserMessages $UserMessages.Msg1... </dev:code> <dev:remarks> <maml:para>This example shows how to use Import-LocalizedData to replace default text strings defined in the DATA section of a script.</maml:para> <maml:para>In this example, the DATA section of the TestScript.ps1 script contains a ConvertFrom-StringData command that converts the contents of the DATA section to a hash table and stores in the value of the $UserMessages variable.</maml:para> <maml:para>The script also includes an Import-LocalizedData command, which imports a hash table of translated text strings from the TestScript.psd1 file in the subdirectory specified by the value of the $PsUICulture variable. If the command finds the .psd1 file, it saves the translated strings from the file in the value of the same $UserMessages variable, overwriting the hash table saved by the DATA section logic.</maml:para> <maml:para>The third command displays the first message in the $UserMessages variable.</maml:para> <maml:para>If the Import-LocalizedData command finds a .psd1 file for the $PsUICulture language, the value of the $UserMessages variable contains the translated text strings. If the command fails for any reason, the command displays the default text strings defined in the DATA section of the script.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\># In Day1.ps1 PS C:\>Import-LocalizedData -BindingVariable DayDay.MessageDate # In Day2.ps1 PS C:\>Import-LocalizedData -BindingVariable Day -ErrorAction:SilentlyContinue Day.MessageDate PS C:\>.\Day1.ps1 Import-LocalizedData : Cannot find PowerShell data file 'Day1.psd1' in directory 'C:\ps-test\fr-BE\' or any parent culture directories. At C:\ps-test\Day1.ps1:17 char:21+ Import-LocalizedData <<<< Day Today is Tuesday PS C:\>.\Day2.ps1 Today is Tuesday </dev:code> <dev:remarks> <maml:para>This example shows how to suppress the error messages that appear when Import-LocalizedData cannot find the directories that match the user's UI culture or cannot find a .psd1 file for the script in those directories.</maml:para> <maml:para>You can use the ErrorAction common parameter with a value of SilentlyContinue to suppress the error message. This is especially useful when you have provided user messages in a default or "fallback" language, and no error message is needed.</maml:para> <maml:para>This example compares two scripts, Day1.ps1 and Day2.ps1, that include an Import-LocalizedData command. The scripts are identical, except that Day2 uses the ErrorAction common parameter with a value of SilentlyContinue.</maml:para> <maml:para>The sample output shows the results of running both scripts when the UI culture is set to fr-BE and there are no matching files or directories for that UI culture. Day1.ps1 displays an error message and English output. Day2.ps1 just displays the English output.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293984</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Script_Internationalization</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Import-PSSession</command:name> <maml:description> <maml:para>Imports commands from another session into the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Import</command:verb> <command:noun>PSSession</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Import-PSSession cmdlet imports commands (such as cmdlets, functions, and aliases) from a PSSession on a local or remote computer into the current session. You can import any command that the Get-Command cmdlet can find in the PSSession.</maml:para> <maml:para>Use an Import-PSSession command to import commands from a customized shell, such as a Microsoft Exchange Server shell, or from a session that includes Windows PowerShell modules and snap-ins or other elements that are not in the current session.</maml:para> <maml:para>To import commands, first use the New-PSSession cmdlet to create a PSSession. Then, use the Import-PSSession cmdlet to import the commands. By default, Import-PSSession imports all commands except for commands that have the same names as commands in the current session. To import all the commands, use the AllowClobber parameter.</maml:para> <maml:para>You can use imported commands just as you would use any command in the session. When you use an imported command, the imported part of the command runs implicitly in the session from which it was imported. However, the remote operations are handled entirely by Windows PowerShell. You need not even be aware of them, except that you must keep the connection to the other session (PSSession) open. If you close it, the imported commands are no longer available.</maml:para> <maml:para>Because imported commands might take longer to run than local commands, Import-PSSession adds an AsJob parameter to every imported command. This parameter allows you to run the command as a Windows PowerShell background job. For more information, see about_Jobs.</maml:para> <maml:para>When you use Import-PSSession, Windows PowerShell adds the imported commands to a temporary module that exists only in your session and returns an object that represents the module. To create a persistent module that you can use in future sessions, use the Export-PSSession cmdlet.</maml:para> <maml:para>The Import-PSSession cmdlet uses the implicit remoting feature of Windows PowerShell. When you import commands into the current session, they run implicitly in the original session or in a similar session on the originating computer.</maml:para> <maml:para>Beginning in Windows PowerShell 3.0, you can use the Import-Module cmdlet to import modules from a remote session into the current session. This feature uses implicit remoting. It is equivalent to using Import-PSSession to import selected modules from a remote session into the current session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Import-PSSession</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>Specifies the PSSession from which the cmdlets are imported. Enter a variable that contains a session object or a command that gets a session object, such as a New-PSSession or Get-PSSession command. You can specify only one session. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSSession</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="3" aliases="Name"> <maml:name>CommandName</maml:name> <maml:description> <maml:para>Imports only the commands with the specified names or name patterns. Wildcards are permitted. Use "CommandName" or its alias, "Name".</maml:para> <maml:para>By default, Import-PSSession imports all commands from the session, except for commands that have the same names as commands in the current session. This prevents imported commands from hiding or replacing commands in the session. To import all commands, even those that hide or replace other commands, use the AllowClobber parameter.</maml:para> <maml:para>If you use the CommandName parameter, the formatting files for the commands are not imported unless you use the FormatTypeName parameter. Similarly, if you use the FormatTypeName parameter, no commands are imported unless you use the CommandName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>FormatTypeName</maml:name> <maml:description> <maml:para>Imports formatting instructions for the specified Microsoft .NET Framework types. Enter the type names. Wildcards are permitted.</maml:para> <maml:para>The value of this parameter must be the name of a type that is returned by a Get-FormatData command in the session from which the commands are being imported. To get all of the formatting data in the remote session, type *.</maml:para> <maml:para>If the command does not include either the CommandName or FormatTypeName parameters, Import-PSSessionimports formatting instructions for all .NET Framework types returned by a Get-FormatData command in the remote session.</maml:para> <maml:para>If you use the FormatTypeName parameter, no commands are imported unless you use the CommandName parameter.</maml:para> <maml:para>Similarly, if you use the CommandName parameter, the formatting files for the commands are not imported unless you use the FormatTypeName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllowClobber</maml:name> <maml:description> <maml:para>Imports the specified commands, even if they have the same names as commands in the current session.</maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>By default, Import-PSSession does not import commands that have the same name as commands in the current session.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Imports the variant of the command that results from using the specified arguments (parameter values).</maml:para> <maml:para>For example, to import the variant of the Get-Item command in the certificate (Cert:) drive in the PSSession in $s, type "Import-PSSession -Session $s -command get-item -argumentlist cert:".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used to sign the format files (*.Format.ps1xml) or script module files (.psm1) in the temporary module that Import-PSSession creates.</maml:para> <maml:para>Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use the Get-PfxCertificate cmdlet or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate2</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Type"> <maml:name>CommandType</maml:name> <maml:description> <maml:para>Imports only the specified types of command objects. The default value is Cmdlet. Use "CommandType" or its alias, "Type".</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Alias: The Windows PowerShell aliases in the remote session.</maml:para> <maml:para>-- All: The cmdlets and functions in the remote session.</maml:para> <maml:para>-- Application: All the files other than Windows-PowerShell files in the paths that are listed in the Path environment variable ($env:path) in the remote session, including .txt, .exe, and .dll files.</maml:para> <maml:para>-- Cmdlet: The cmdlets in the remote session. "Cmdlet" is the default.</maml:para> <maml:para>-- ExternalScript: The .ps1 files in the paths listed in the Path environment variable ($env:path) in the remote session.</maml:para> <maml:para>-- Filter and Function: The Windows PowerShell functions in the remote session.</maml:para> <maml:para>-- Script: The script blocks in the remote session.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Alias</command:parameterValue> <command:parameterValue required="false" variableLength="false">Function</command:parameterValue> <command:parameterValue required="false" variableLength="false">Filter</command:parameterValue> <command:parameterValue required="false" variableLength="false">Cmdlet</command:parameterValue> <command:parameterValue required="false" variableLength="false">ExternalScript</command:parameterValue> <command:parameterValue required="false" variableLength="false">Application</command:parameterValue> <command:parameterValue required="false" variableLength="false">Script</command:parameterValue> <command:parameterValue required="false" variableLength="false">Workflow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Configuration</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisableNameChecking</maml:name> <maml:description> <maml:para>Suppresses the message that warns you when you import a cmdlet or function whose name includes an unapproved verb or a prohibited character.</maml:para> <maml:para>By default, when a module that you import exports cmdlets or functions that have unapproved verbs in their names, the Windows PowerShell displays the following warning message:</maml:para> <maml:para>"WARNING: Some imported command names include unapproved verbs which might make them less discoverable. Use the Verbose parameter for more detail or type Get-Verb to see the list of approved verbs."</maml:para> <maml:para>This message is only a warning. The complete module is still imported, including the non-conforming commands. Although the message is displayed to module users, the naming problem should be fixed by the module author.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>FullyQualifiedModule</maml:name> <maml:description> <maml:para>Specifies modules with names that are specified in the form of ModuleSpecification objects (described by the Remarks section of <maml:navigationLink><maml:linkText>Module Specification Constructor (Hashtable)</maml:linkText><maml:uri></maml:uri></maml:navigationLink> on MSDN). For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format @{ModuleName = "modulename"; ModuleVersion = "version_number"} or @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. ModuleName and ModuleVersion are required, but Guid is optional.</maml:para> <maml:para>You cannot specify the FullyQualifiedModule parameter in the same command as a Module parameter; the two parameters are mutually exclusive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">ModuleSpecification[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>By default, Import-PSSession does not import commands that have the same name as commands in the current session.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>By default, Import-PSSession does not import commands that have the same name as commands in the current session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PSSnapin"> <maml:name>Module</maml:name> <maml:description> <maml:para>Imports only the commands in the specified Windows PowerShell snap-ins and modules. Enter the snap-in and module names. Wildcards are not permitted.</maml:para> <maml:para>Import-PSSession cannot import providers from a snap-in.</maml:para> <maml:para>For more information, see about_PSSnapins and about_Modules.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Prefix</maml:name> <maml:description> <maml:para>Adds the specified prefix to the nouns in the names of imported commands.</maml:para> <maml:para>Use this parameter to avoid name conflicts that might occur when different commands in the session have the same name.</maml:para> <maml:para>For example, if you specify the prefix "Remote" and then import a Get-Date cmdlet, the cmdlet is known in the session as "Get-RemoteDate" and it is not confused with the original Get-Date cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllowClobber</maml:name> <maml:description> <maml:para>Imports the specified commands, even if they have the same names as commands in the current session.</maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>By default, Import-PSSession does not import commands that have the same name as commands in the current session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Imports the variant of the command that results from using the specified arguments (parameter values).</maml:para> <maml:para>For example, to import the variant of the Get-Item command in the certificate (Cert:) drive in the PSSession in $s, type "Import-PSSession -Session $s -command get-item -argumentlist cert:".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="3" aliases="Name"> <maml:name>CommandName</maml:name> <maml:description> <maml:para>Imports only the commands with the specified names or name patterns. Wildcards are permitted. Use "CommandName" or its alias, "Name".</maml:para> <maml:para>By default, Import-PSSession imports all commands from the session, except for commands that have the same names as commands in the current session. This prevents imported commands from hiding or replacing commands in the session. To import all commands, even those that hide or replace other commands, use the AllowClobber parameter.</maml:para> <maml:para>If you use the CommandName parameter, the formatting files for the commands are not imported unless you use the FormatTypeName parameter. Similarly, if you use the FormatTypeName parameter, no commands are imported unless you use the CommandName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Type"> <maml:name>CommandType</maml:name> <maml:description> <maml:para>Imports only the specified types of command objects. The default value is Cmdlet. Use "CommandType" or its alias, "Type".</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Alias: The Windows PowerShell aliases in the remote session.</maml:para> <maml:para>-- All: The cmdlets and functions in the remote session.</maml:para> <maml:para>-- Application: All the files other than Windows-PowerShell files in the paths that are listed in the Path environment variable ($env:path) in the remote session, including .txt, .exe, and .dll files.</maml:para> <maml:para>-- Cmdlet: The cmdlets in the remote session. "Cmdlet" is the default.</maml:para> <maml:para>-- ExternalScript: The .ps1 files in the paths listed in the Path environment variable ($env:path) in the remote session.</maml:para> <maml:para>-- Filter and Function: The Windows PowerShell functions in the remote session.</maml:para> <maml:para>-- Script: The script blocks in the remote session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">CommandTypes</command:parameterValue> <dev:type> <maml:name>CommandTypes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisableNameChecking</maml:name> <maml:description> <maml:para>Suppresses the message that warns you when you import a cmdlet or function whose name includes an unapproved verb or a prohibited character.</maml:para> <maml:para>By default, when a module that you import exports cmdlets or functions that have unapproved verbs in their names, the Windows PowerShell displays the following warning message:</maml:para> <maml:para>"WARNING: Some imported command names include unapproved verbs which might make them less discoverable. Use the Verbose parameter for more detail or type Get-Verb to see the list of approved verbs."</maml:para> <maml:para>This message is only a warning. The complete module is still imported, including the non-conforming commands. Although the message is displayed to module users, the naming problem should be fixed by the module author.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>FormatTypeName</maml:name> <maml:description> <maml:para>Imports formatting instructions for the specified Microsoft .NET Framework types. Enter the type names. Wildcards are permitted.</maml:para> <maml:para>The value of this parameter must be the name of a type that is returned by a Get-FormatData command in the session from which the commands are being imported. To get all of the formatting data in the remote session, type *.</maml:para> <maml:para>If the command does not include either the CommandName or FormatTypeName parameters, Import-PSSessionimports formatting instructions for all .NET Framework types returned by a Get-FormatData command in the remote session.</maml:para> <maml:para>If you use the FormatTypeName parameter, no commands are imported unless you use the CommandName parameter.</maml:para> <maml:para>Similarly, if you use the CommandName parameter, the formatting files for the commands are not imported unless you use the FormatTypeName parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>FullyQualifiedModule</maml:name> <maml:description> <maml:para>Specifies modules with names that are specified in the form of ModuleSpecification objects (described by the Remarks section of <maml:navigationLink><maml:linkText>Module Specification Constructor (Hashtable)</maml:linkText><maml:uri></maml:uri></maml:navigationLink> on MSDN). For example, the FullyQualifiedModule parameter accepts a module name that is specified in the format @{ModuleName = "modulename"; ModuleVersion = "version_number"} or @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. ModuleName and ModuleVersion are required, but Guid is optional.</maml:para> <maml:para>You cannot specify the FullyQualifiedModule parameter in the same command as a Module parameter; the two parameters are mutually exclusive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">ModuleSpecification[]</command:parameterValue> <dev:type> <maml:name>ModuleSpecification[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>By default, Import-PSSession does not import commands that have the same name as commands in the current session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_Command_Precedence.</maml:para> <maml:para>By default, Import-PSSession does not import commands that have the same name as commands in the current session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="PSSnapin"> <maml:name>Module</maml:name> <maml:description> <maml:para>Imports only the commands in the specified Windows PowerShell snap-ins and modules. Enter the snap-in and module names. Wildcards are not permitted.</maml:para> <maml:para>Import-PSSession cannot import providers from a snap-in.</maml:para> <maml:para>For more information, see about_PSSnapins and about_Modules.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Prefix</maml:name> <maml:description> <maml:para>Adds the specified prefix to the nouns in the names of imported commands.</maml:para> <maml:para>Use this parameter to avoid name conflicts that might occur when different commands in the session have the same name.</maml:para> <maml:para>For example, if you specify the prefix "Remote" and then import a Get-Date cmdlet, the cmdlet is known in the session as "Get-RemoteDate" and it is not confused with the original Get-Date cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Session</maml:name> <maml:description> <maml:para>Specifies the PSSession from which the cmdlets are imported. Enter a variable that contains a session object or a command that gets a session object, such as a New-PSSession or Get-PSSession command. You can specify only one session. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSSession</command:parameterValue> <dev:type> <maml:name>PSSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used to sign the format files (*.Format.ps1xml) or script module files (.psm1) in the temporary module that Import-PSSession creates.</maml:para> <maml:para>Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use the Get-PfxCertificate cmdlet or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSModuleInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Import-PSSession returns the same module object that New-Module and Get-Module cmdlets return. However, the imported module is temporary and exists only in the current session. To create a permanent module on disk, use the Export-PSSession cmdlet.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Import-PSSession relies on the Windows PowerShell remoting infrastructure. To use this cmdlet, the computer must be configured for WS-Management remoting. For more information, see about_Remote and about_Remote_Requirements. </maml:para> </maml:alert> <maml:alert> <maml:para>Import-PSSession does not import variables or Windows PowerShell providers.</maml:para> </maml:alert> <maml:alert> <maml:para>When you import commands that have the same names as commands in the current session, the imported commands can hide aliases, functions, and cmdlets in the session and they can replace functions and variables in the session. To prevent name conflicts, use the Prefix parameter. For more information, see about_Command_Precedence.</maml:para> </maml:alert> <maml:alert> <maml:para>Import-PSSession converts all commands into functions before it imports them. As a result, imported commands behave a bit differently than they would if they retained their original command type. For example, if you import a cmdlet from a PSSession and then import a cmdlet with the same name from a module or snap-in, the cmdlet that is imported from the PSSession always runs by default because functions take precedence over cmdlets. Conversely, if you import an alias into a session that has an alias with the same name, the original alias is always used, because aliases take precedence over functions. For more information, see about_Command_Precedence. </maml:para> </maml:alert> <maml:alert> <maml:para>Import-PSSession uses the Write-Progress cmdlet to display the progress of the command. You might see the progress bar while the command is running. </maml:para> </maml:alert> <maml:alert> <maml:para>To find the commands to import, Import-PSSession uses the Invoke-Command cmdlet to run a Get-Command command in the PSSession. To get formatting data for the commands, it uses the Get-FormatData cmdlet. You might see error messages from these cmdlets when you run an Import-PSSession command. Also, Import-PSSession cannot import commands from a PSSession that does not include the Get-Command, Get-FormatData, Select-Object, and Get-Help cmdlets.</maml:para> </maml:alert> <maml:alert> <maml:para>Imported commands have the same limitations as other remote commands, including the inability to start a program with a user interface, such as Notepad. </maml:para> </maml:alert> <maml:alert> <maml:para>Because Windows PowerShell profiles are not run in PSSessions, the commands that a profile adds to a session are not available to Import-PSSession. To import commands from a profile, use an Invoke-Command command to run the profile in the PSSession manually before importing commands.</maml:para> </maml:alert> <maml:alert> <maml:para>The temporary module that Import-PSSession creates might include a formatting file, even if the command does not import formatting data. If the command does not import formatting data, any formatting files that are created will not contain formatting data. </maml:para> </maml:alert> <maml:alert> <maml:para>To use Import-PSSession, the execution policy in the current session cannot be Restricted or AllSigned, because the temporary module that Import-PSSession creates contains unsigned script files that are prohibited by these policies. To use Import-PSSession without changing the execution policy for the local computer, use the Scope parameter of Set-ExecutionPolicy to set a less restrictive execution policy for a single process.</maml:para> </maml:alert> <maml:alert> <maml:para>In Windows PowerShell 2.0, help topics for commands that are imported from another session do not include the prefix that you assign by using the Prefix parameter. To get help for an imported command in Windows PowerShell 2.0, use the original (non-prefixed) command name.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = New-PSSession -ComputerName Server01 PS C:\>Import-PSSession -Session $s </dev:code> <dev:remarks> <maml:para>This command imports all commands from a PSSession on the Server01 computer into the current session, except for commands that have the same names as commands in the current session.</maml:para> <maml:para>Because this command does not use the CommandName parameter, it also imports all of the formatting data required for the imported commands.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = New-PSSession https://ps.testlabs.com/powershell PS C:\>Import-PSSession -Session $s -CommandName *-test -FormatTypeName * PS C:\>New-Test -Name Test1 PS C:\>Get-Test test1 | Run-Test </dev:code> <dev:remarks> <maml:para>These commands import the commands with names that end in "-test" from a PSSession into the local session, and then they show how to use an imported cmdlet.</maml:para> <maml:para>The first command uses the New-PSSession cmdlet to create a PSSession. It saves the PSSession in the $s variable.</maml:para> <maml:para>The second command uses the Import-PSSession cmdlet to import commands from the PSSession in $s into the current session. It uses the CommandName parameter to specify commands with the Test noun and the FormatTypeName parameter to import the formatting data for the Test commands.</maml:para> <maml:para>The third and fourth commands use the imported commands in the current session. Because imported commands are actually added to the current session, you use the local syntax to run them. You do not need to use the Invoke-Command cmdlet to run an imported command.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s1 = New-PSSession -ComputerName s1 PS C:\>$s2 = New-PSSession -ComputerName s2 PS C:\>Import-PSSession -Session s1 -Type cmdlet -Name New-Test, Get-Test -FormatTypeName * PS C:\>Import-PSSession -Session s2 -Type Cmdlet -Name Set-Test -FormatTypeName * PS C:\>New-Test Test1 | Set-Test -RunType Full </dev:code> <dev:remarks> <maml:para>This example shows that you can use imported cmdlets just as you would use local cmdlets.</maml:para> <maml:para>These commands import the New-Test and Get-Test cmdlets from a PSSession on the Server01 computer and the Set-Test cmdlet from a PSSession on the Server02 computer.</maml:para> <maml:para>Even though the cmdlets were imported from different PSSessions, you can pipe an object from one cmdlet to another without error.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = New-PSSession -ComputerName Server01 PS C:\>Import-PSSession -Session $s -CommandName *-test* -FormatTypeName * PS C:\>$batch = New-Test -Name Batch -AsJob PS C:\>Receive-Job $batch </dev:code> <dev:remarks> <maml:para>This example shows how to run an imported command as a background job.</maml:para> <maml:para>Because imported commands might take longer to run than local commands, Import-PSSession adds an AsJob parameter to every imported command. The AsJob parameter lets you run the command as a background job.</maml:para> <maml:para>The first command creates a PSSession on the Server01 computer and saves the PSSession object in the $s variable.</maml:para> <maml:para>The second command uses Import-PSSession to import the Test cmdlets from the PSSession in $s into the current session.</maml:para> <maml:para>The third command uses the AsJob parameter of the imported New-Test cmdlet to run a New-Test command as a background job. The command saves the job object that New-Test returns in the $batch variable.</maml:para> <maml:para>The fourth command uses the Receive-Job cmdlet to get the results of the job in the $batch variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = New-PSSession -ComputerName Server01 PS C:\>Invoke-Command -Session $s {Import-Module TestManagement} PS C:\>Import-PSSession -Session $s -Module TestManagement </dev:code> <dev:remarks> <maml:para>This example shows how to import the cmdlets and functions from a Windows PowerShell module on a remote computer into the current session.</maml:para> <maml:para>The first command creates a PSSession on the Server01 computer and saves it in the $s variable.</maml:para> <maml:para>The second command uses the Invoke-Command cmdlet to run an Import-Module command in the PSSession in $s.</maml:para> <maml:para>Typically, the module would be added to all sessions by an Import-Module command in a Windows PowerShell profile, but profiles are not run in PSSessions.</maml:para> <maml:para>The third command uses the Module parameter of Import-PSSession to import the cmdlets and functions in the module into the current session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Import-PSSession $s -CommandName Get-Date, SearchHelp -FormatTypeName * -AllowClobber Name : tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf Path : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf\tmp_79468106-4e1d-4d90-af97-1154f9317239_ tcw1zunz.ttf.psm1 Description : Implicit remoting for http://server01.corp.fabrikam.com/wsman Guid : 79468106-4e1d-4d90-af97-1154f9317239 Version : 1.0 ModuleBase : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf ModuleType : Script PrivateData : {ImplicitRemoting} AccessMode : ReadWrite ExportedAliases : {} ExportedCmdlets : {} ExportedFunctions : {[Get-Date, Get-Date], [SearchHelp, SearchHelp]} ExportedVariables : {} NestedModules : {} </dev:code> <dev:remarks> <maml:para>This example shows that Import-PSSession creates a module in a temporary file on disk. It also shows that all commands are converted into functions before they are imported into the current session.</maml:para> <maml:para>The command uses the Import-PSSession cmdlet to import a Get-Date cmdlet and a SearchHelp function into the current session.</maml:para> <maml:para>The Import-PSSession cmdlet returns a PSModuleInfo object that represents the temporary module. The value of the Path property shows that Import-PSSession created a script module (.psm1) file in a temporary location. The ExportedFunctions property shows that the Get-Date cmdlet and the SearchHelp function were both imported as functions.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Import-PSSession $s -CommandName Get-Date -FormatTypeName * -AllowClobber PS C:\>Get-Command Get-Date -All CommandType Name Definition ----------- ---- ---------- Function Get-Date ... Cmdlet Get-Date Get-Date [[-Date] <DateTime>] [-Year <Int32>] [-Month <Int32>] PS C:\>Get-Date 09074 PS C:\>(Get-Command -Type Cmdlet -Name Get-Date).PSSnapin.Name Microsoft.PowerShell.Utility PS C:\>Microsoft.PowerShell.Utility\Get-Date Sunday, March 15, 2009 2:08:26 PM </dev:code> <dev:remarks> <maml:para>This example shows how to run a command that is hidden by an imported command.</maml:para> <maml:para>The first command imports a Get-Date cmdlet from the PSSession in the $s variable. Because the current session includes a Get-Date cmdlet, the AllowClobber parameter is required in the command.</maml:para> <maml:para>The second command uses the All parameter of the Get-Command cmdlet to get all Get-Date commands in the current session. The output shows that the session includes the original Get-Date cmdlet and a Get-Date function. The Get-Date function runs the imported Get-Date cmdlet in the PSSession in $s.</maml:para> <maml:para>The third command runs a Get-Date command. Because functions take precedence over cmdlets, Windows PowerShell runs the imported Get-Date function, which returns a Julian date.</maml:para> <maml:para>The fourth and fifth commands show how to use a qualified name to run a command that is hidden by an imported command.</maml:para> <maml:para>The fourth command gets the name of the Windows PowerShell snap-in that added the original Get-Date cmdlet to the current session.</maml:para> <maml:para>The fifth command uses the snap-in-qualified name of the Get-Date cmdlet to run a Get-Date command.</maml:para> <maml:para>For more information about command precedence and hidden commands, see about_Command_Precedence.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Import-PSSession -Session $s -CommandName *Item* -AllowClobber </dev:code> <dev:remarks> <maml:para>This command imports commands whose names include "Item" from the PSSession in $s. Because the command includes the CommandName parameter but not the FormatTypeData parameter, only the command is imported.</maml:para> <maml:para>Use this command when you are using Import-PSSession to run a command on a remote computer and you already have the formatting data for the command in the current session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$m = Import-PSSession -Session $s -CommandName *bits* -FormatTypeName *bits* PS C:\>Get-Command -Module $m CommandType Name ----------- ---- Function Add-BitsFile Function Complete-BitsTransfer Function Get-BitsTransfer Function Remove-BitsTransfer Function Resume-BitsTransfer Function Set-BitsTransfer Function Start-BitsTransfer Function Suspend-BitsTransfer </dev:code> <dev:remarks> <maml:para>This command shows how to use the Module parameter of Get-Command to find out which commands were imported into the session by an Import-PSSession command.</maml:para> <maml:para>The first command uses the Import-PSSession cmdlet to import commands whose names include "bits" from the PSSession in the $s variable. The Import-PSSession command returns a temporary module, and the command saves the module in the $m variable.</maml:para> <maml:para>The second command uses the Get-Command cmdlet to get the commands that are exported by the module in the $m variable.</maml:para> <maml:para>The Module parameter takes a string value, which is designed for the module name. However, when you submit a module object, Windows PowerShell uses the ToString method on the module object, which returns the module name.</maml:para> <maml:para>The Get-Command command is the equivalent of Get-Command $m.Name".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293985</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-PSSession</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-PSSession</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Command_Precedence</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_PSSessions</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Jobs</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-Expression</command:name> <maml:description> <maml:para>Runs commands or expressions on the local computer.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Invoke</command:verb> <command:noun>Expression</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Invoke-Expression cmdlet evaluates or runs a specified string as a command and returns the results of the expression or command. Without Invoke-Expression, a string submitted at the command line would be returned (echoed) unchanged.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-Expression</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies the command or expression to run. Type the command or expression or enter a variable that contains the command or expression. The Command parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies the command or expression to run. Type the command or expression or enter a variable that contains the command or expression. The Command parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String or PSObject </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe an object that represents the command to Invoke-Expression. Use the $input automatic variable to represent the input objects in the command.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSObject </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Returns the output that is generated by the invoked command (the value of the Command parameter).</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>-- An expression is a statement that can be evaluated and produces a result, such as a Windows PowerShell command.</maml:para> <maml:para>-- Take reasonable precautions when using the Invoke-Expression cmdlet in scripts. When using Invoke-Expression to run a command that the user enters, verify that the command is safe to run before running it. In general, it is best to design your script with predefined input options, rather than allowing freeform input.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$command = "Get-Process" PS C:\>$command Get-Process PS C:\>invoke-expression $command Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 296 4 1572 1956 20 0.53 1348 AdtAgent 270 6 1328 800 34 0.06 2396 alg 67 2 620 484 20 0.22 716 ati2evxx 1060 15 12904 11840 74 11.48 892 CcmExec 1400 33 25280 37544 223 38.44 2564 communicator ... </dev:code> <dev:remarks> <maml:para>This example demonstrates the use of Invoke-Expression to evaluate an expression. Without Invoke-Expression, the expression is printed, but not evaluated.</maml:para> <maml:para>The first command assigns a value of "Get-Process" (a string) to the $command variable.</maml:para> <maml:para>The second command shows the effect of typing the variable name at the command line. Windows PowerShell echoes the string.</maml:para> <maml:para>The third command uses Invoke-Expression to evaluate the string.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>invoke-expression -command "C:\ps-test\testscript.ps1" PS C:\>"C:\ps-test\testscript.ps1" | invoke-expression </dev:code> <dev:remarks> <maml:para>These commands use Invoke-Expression to run a script, TestScript.ps1, on the local computer. The two commands are equivalent. The first uses the Command parameter to specify the command to run. The second uses a pipeline operator (|) to send the command string to Invoke-Expression.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$Command = 'Get-Process | where {$_.cpu -gt 1000}' PS C:\>Invoke-Expression $Command </dev:code> <dev:remarks> <maml:para>This example runs a command string that is saved in the $Command variable.</maml:para> <maml:para>The command string is enclosed in single quotation marks because it includes a variable, $_, which represents the current object. If it were enclosed in double quotation marks, the $_ variable would be replaced by its value before it was saved in the $Command variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$cmdlet_name = "get-eventlog" PS C:\>$example_number = 1 PS C:\>$example_code = (get-help $cmdlet_name).examples.example[($example_number-1)].code PS C:\>invoke-expression $example_code </dev:code> <dev:remarks> <maml:para>This command retrieves and runs the first example in the Get-EventLog cmdlet help topic.</maml:para> <maml:para>To run an example of a different cmdlet, change the value of the $cmdlet_name variable to the name of the cmdlet. And, change the $example_number variable to the example number you want to run. The command will fail if the example number is not valid.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293986</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-Command</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-RestMethod</command:name> <maml:description> <maml:para>Sends an HTTP or HTTPS request to a RESTful web service.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Invoke</command:verb> <command:noun>RestMethod</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Invoke-RestMethod cmdlet sends HTTP and HTTPS requests to Representational State Transfer (REST) web services that returns richly structured data. </maml:para> <maml:para>Windows PowerShell formats the response based to the data type. For an RSS or ATOM feed, Windows PowerShell returns the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, Windows PowerShell converts (or deserializes) the content into objects.</maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-RestMethod</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Uri</maml:name> <maml:description> <maml:para>Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is sent. This parameter supports HTTP, HTTPS, FTP, and FILE values.</maml:para> <maml:para>This parameter is required. The parameter name (-Uri) is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Uri</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the body of the request. The body is the content of the request that follows the headers. You can also pipe a body value to Invoke-RestMethod.</maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request, and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other request types (such as POST), the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of another Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>Specifies the digital public key certificate (X509) of a user account that has permission to send the request. Enter the certificate thumbprint of the certificate.</maml:para> <maml:para>Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.</maml:para> <maml:para>To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ContentType</maml:name> <maml:description> <maml:para>Specifies the content type of the web request.</maml:para> <maml:para>If this parameter is omitted and the request method is POST, Invoke-RestMethod sets the content type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the call.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to send the request. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisableKeepAlive</maml:name> <maml:description> <maml:para>Sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Headers</maml:name> <maml:description> <maml:para>Specifies the headers of the web request. Enter a hash table or dictionary.</maml:para> <maml:para>To set UserAgent headers, use the UserAgent parameter. You cannot use this parameter to specify UserAgent or cookie headers.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InFile</maml:name> <maml:description> <maml:para>Gets the content of the web request from a file. </maml:para> <maml:para>Enter a path and file name. If you omit the path, the default is the current location.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request, and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other request types (such as POST), the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of another Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request, and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other request types (such as POST), the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of another Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaximumRedirection</maml:name> <maml:description> <maml:para>Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Method</maml:name> <maml:description> <maml:para>Specifies the method used for the web request. Valid values are Default, Delete, Get, Head, Merge, Options, Patch, Post, Put, and Trace.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">Get</command:parameterValue> <command:parameterValue required="false" variableLength="false">Head</command:parameterValue> <command:parameterValue required="false" variableLength="false">Post</command:parameterValue> <command:parameterValue required="false" variableLength="false">Put</command:parameterValue> <command:parameterValue required="false" variableLength="false">Delete</command:parameterValue> <command:parameterValue required="false" variableLength="false">Trace</command:parameterValue> <command:parameterValue required="false" variableLength="false">Options</command:parameterValue> <command:parameterValue required="false" variableLength="false">Merge</command:parameterValue> <command:parameterValue required="false" variableLength="false">Patch</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OutFile</maml:name> <maml:description> <maml:para>Saves the response body in the specified output file. Enter a path and file name. If you omit the path, the default is the current location.</maml:para> <maml:para>By default, Invoke-RestMethod returns the results to the pipeline. To send the results to a file and to the pipeline, use the Passthru parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the results, in addition to writing them to a file. This parameter is valid only when the OutFile parameter is also used in the command.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Proxy</maml:name> <maml:description> <maml:para>Uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Uri</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyCredential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyUseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="SV"> <maml:name>SessionVariable</maml:name> <maml:description> <maml:para>Creates a web request session and saves it in the value of the specified variable. Enter a variable name without the dollar sign ($) symbol.</maml:para> <maml:para>When you specify a session variable, Invoke-RestMethod creates a web request session object and assigns it to a variable with the specified name in your Windows PowerShell session. You can use the variable in your session as soon as the command completes.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To use the web request session in subsequent web requests, specify the session variable in the value of the WebSession parameter. Windows PowerShell uses the data in the web request session object when establishing the new connection. To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TimeoutSec</maml:name> <maml:description> <maml:para>Specifies how long the request can be pending before it times out. Enter a value in seconds. The default value, 0, specifies an indefinite time-out.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TransferEncoding</maml:name> <maml:description> <maml:para>Specifies a value for the transfer-encoding HTTP response header. Valid values are Chunked, Compress, Deflate, GZip and Identity.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">chunked</command:parameterValue> <command:parameterValue required="false" variableLength="false">compress</command:parameterValue> <command:parameterValue required="false" variableLength="false">deflate</command:parameterValue> <command:parameterValue required="false" variableLength="false">gzip</command:parameterValue> <command:parameterValue required="false" variableLength="false">identity</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to send the web request.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UserAgent</maml:name> <maml:description> <maml:para>Specifies a user agent string for the web request.</maml:para> <maml:para>The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" with slight variations for each operating system and platform.</maml:para> <maml:para>To test a website with the standard user agent string that is used by most Internet browsers, use the properties of the <maml:navigationLink><maml:linkText>PSUserAgent</maml:linkText><maml:uri></maml:uri></maml:navigationLink> class, such as Chrome, FireFox, InternetExplorer, Opera, and Safari.</maml:para> <maml:para>For example, the following command uses the user agent string for Internet.</maml:para> <maml:para>Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>WebSession</maml:name> <maml:description> <maml:para>Specifies a web request session. Enter the variable name, including the dollar sign ($).</maml:para> <maml:para>To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To create a web request session, enter a variable name (without a dollar sign) in the value of the SessionVariable parameter of an Invoke-RestMethod command. Invoke-RestMethod creates the session and saves it in the variable. In subsequent commands, use the variable as the value of the WebSession parameter.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">WebRequestSession</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the body of the request. The body is the content of the request that follows the headers. You can also pipe a body value to Invoke-RestMethod.</maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request, and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other request types (such as POST), the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of another Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate</command:parameterValue> <dev:type> <maml:name>X509Certificate</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>Specifies the digital public key certificate (X509) of a user account that has permission to send the request. Enter the certificate thumbprint of the certificate.</maml:para> <maml:para>Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.</maml:para> <maml:para>To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ContentType</maml:name> <maml:description> <maml:para>Specifies the content type of the web request.</maml:para> <maml:para>If this parameter is omitted and the request method is POST, Invoke-RestMethod sets the content type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the call.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to send the request. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisableKeepAlive</maml:name> <maml:description> <maml:para>Sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Headers</maml:name> <maml:description> <maml:para>Specifies the headers of the web request. Enter a hash table or dictionary.</maml:para> <maml:para>To set UserAgent headers, use the UserAgent parameter. You cannot use this parameter to specify UserAgent or cookie headers.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InFile</maml:name> <maml:description> <maml:para>Gets the content of the web request from a file. </maml:para> <maml:para>Enter a path and file name. If you omit the path, the default is the current location.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request, and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other request types (such as POST), the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of another Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request, and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other request types (such as POST), the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of another Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaximumRedirection</maml:name> <maml:description> <maml:para>Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Method</maml:name> <maml:description> <maml:para>Specifies the method used for the web request. Valid values are Default, Delete, Get, Head, Merge, Options, Patch, Post, Put, and Trace.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">WebRequestMethod</command:parameterValue> <dev:type> <maml:name>WebRequestMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OutFile</maml:name> <maml:description> <maml:para>Saves the response body in the specified output file. Enter a path and file name. If you omit the path, the default is the current location.</maml:para> <maml:para>By default, Invoke-RestMethod returns the results to the pipeline. To send the results to a file and to the pipeline, use the Passthru parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the results, in addition to writing them to a file. This parameter is valid only when the OutFile parameter is also used in the command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Proxy</maml:name> <maml:description> <maml:para>Uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyCredential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyUseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="SV"> <maml:name>SessionVariable</maml:name> <maml:description> <maml:para>Creates a web request session and saves it in the value of the specified variable. Enter a variable name without the dollar sign ($) symbol.</maml:para> <maml:para>When you specify a session variable, Invoke-RestMethod creates a web request session object and assigns it to a variable with the specified name in your Windows PowerShell session. You can use the variable in your session as soon as the command completes.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To use the web request session in subsequent web requests, specify the session variable in the value of the WebSession parameter. Windows PowerShell uses the data in the web request session object when establishing the new connection. To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TimeoutSec</maml:name> <maml:description> <maml:para>Specifies how long the request can be pending before it times out. Enter a value in seconds. The default value, 0, specifies an indefinite time-out.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TransferEncoding</maml:name> <maml:description> <maml:para>Specifies a value for the transfer-encoding HTTP response header. Valid values are Chunked, Compress, Deflate, GZip and Identity.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Uri</maml:name> <maml:description> <maml:para>Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is sent. This parameter supports HTTP, HTTPS, FTP, and FILE values.</maml:para> <maml:para>This parameter is required. The parameter name (-Uri) is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to send the web request.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UserAgent</maml:name> <maml:description> <maml:para>Specifies a user agent string for the web request.</maml:para> <maml:para>The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" with slight variations for each operating system and platform.</maml:para> <maml:para>To test a website with the standard user agent string that is used by most Internet browsers, use the properties of the <maml:navigationLink><maml:linkText>PSUserAgent</maml:linkText><maml:uri></maml:uri></maml:navigationLink> class, such as Chrome, FireFox, InternetExplorer, Opera, and Safari.</maml:para> <maml:para>For example, the following command uses the user agent string for Internet.</maml:para> <maml:para>Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>WebSession</maml:name> <maml:description> <maml:para>Specifies a web request session. Enter the variable name, including the dollar sign ($).</maml:para> <maml:para>To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To create a web request session, enter a variable name (without a dollar sign) in the value of the SessionVariable parameter of an Invoke-RestMethod command. Invoke-RestMethod creates the session and saves it in the variable. In subsequent commands, use the variable as the value of the WebSession parameter.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">WebRequestSession</command:parameterValue> <dev:type> <maml:name>WebRequestSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the body of a web request to Invoke-Rest-Method.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The output of the cmdlet depends upon the format of the content that is retrieved.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>If the request returns JSON strings, Invoke-RestMethod returns a PSObject that represents the strings.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Invoke-RestMethod -Uri http://blogs.msdn.com/powershell/rss.aspx | Format-Table -Property Title, pubDate Title pubDate----------- Another Holiday Gift from the PowerShell Team: PowerShell 3.0 CTP2... Thu, 22 Dec 2011 00:46:00 GMT More Videos from the First PowerShell Deep Dive Mon, 10 Oct 2011 19:59:00 GMT PowerShell Deep Dive Lineup Thu, 06 Oct 2011 00:42:00 GMT Windows Management Framework 3.0 Community Technology Preview (CTP... Mon, 19 Sep 2011 23:56:26 GMT Get-Help -Online Fails in German Tue, 23 Aug 2011 15:02:00 GMT PowerShell Deep Dive Registration Info & Call for Session Proposals Wed, 20 Jul 2011 00:25:00 GMT Invoke-Expression considered harmful Fri, 03 Jun 2011 15:43:00 GMT PowerShell at TechEd 2011 Thu, 28 Apr 2011 16:58:36 GMT PowerShell Language now licensed under the Community Promise Sat, 16 Apr 2011 00:13:00 GMT Scaling and Queuing PowerShell Background Jobs Mon, 04 Apr 2011 20:30:58 GMT More Deep Dive Info, Including Abstracts from the PowerShell Team Sun, 13 Mar 2011 01:35:42 GMT A Few Deep Dive Abstracts Sat, 05 Mar 2011 00:26:00 GMT Reminder: Register for the PowerShell Deep Dive Conference & submi... Wed, 23 Feb 2011 17:55:45 GMT </dev:code> <dev:remarks> <maml:para>This command uses the Invoke-RestMethod cmdlet to get information from the Windows PowerShell Blog RSS feed. The command uses the Format-Table cmdlet to display the values of the Title and pubDate properties of each blog in a table.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$cred = Get-Credential # Next, allow the use of self-signed SSL certificates. [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true } # Create variables to store the values consumed by the Invoke-RestMethod command. The search variable contents are later embedded in the body variable. $server = 'server.contoso.com' $url = "https://${server}:8089/services/search/jobs/export" $search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw" # The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as the output mode, and specifies a time period for returned data that starts two days ago and ends one day ago. The body variable specifies values for parameters that apply to the particular REST API with which Invoke-RestMethod is communicating. $body = @{ search = $search output_mode = "csv" earliest_time = "-2d@d" latest_time = "-1d@d" } # Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file name for the resulting CSV output file. Invoke-RestMethod -Method Post -Uri $url -Credential $cred -Body $body -OutFile output.csv cmdlet Get-Credential at command pipeline position 1 Supply values for the following parameters: {"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}} {"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}} {"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}} {"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}} </dev:code> <dev:remarks> <maml:para>In the following example, a user runs Invoke-RestMethod to perform a POST request on an intranet website in the user�s organization.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293987</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Json</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Json</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-WebRequest</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-WebRequest</command:name> <maml:description> <maml:para>Gets content from a web page on the Internet.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Invoke</command:verb> <command:noun>WebRequest</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Invoke-WebRequest cmdlet sends HTTP, HTTPS, FTP, and FILE requests to a web page or web service. It parses the response and returns collections of forms, links, images, and other significant HTML elements.</maml:para> <maml:para>This cmdlet was introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-WebRequest</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Uri</maml:name> <maml:description> <maml:para>Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is sent. Enter a URI. This parameter supports HTTP, HTTPS, FTP, and FILE values.</maml:para> <maml:para>This parameter is required. The parameter name (-Uri) is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Uri</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the body of the request. The body is the content of the request that follows the headers. You can also pipe a body value to Invoke-WebRequest.</maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>Specifies the digital public key certificate (X509) of a user account that has permission to send the request. Enter the certificate thumbprint of the certificate.</maml:para> <maml:para>Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.</maml:para> <maml:para>To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ContentType</maml:name> <maml:description> <maml:para>Specifies the content type of the web request.</maml:para> <maml:para>If this parameter is omitted and the request method is POST, Invoke-WebRequest sets the content type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the call.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to send the request. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisableKeepAlive</maml:name> <maml:description> <maml:para>Sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Headers</maml:name> <maml:description> <maml:para>Specifies the headers of the web request. Enter a hash table or dictionary.</maml:para> <maml:para>To set UserAgent headers, use the UserAgent parameter. You cannot use this parameter to specify UserAgent or cookie headers.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InFile</maml:name> <maml:description> <maml:para>Gets the content of the web request from a file. </maml:para> <maml:para>Enter a path and file name. If you omit the path, the default is the current location.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaximumRedirection</maml:name> <maml:description> <maml:para>Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Method</maml:name> <maml:description> <maml:para>Specifies the method used for the web request. Valid values are Default, Delete, Get, Head, Merge, Options, Patch, Post, Put, and Trace.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Default</command:parameterValue> <command:parameterValue required="false" variableLength="false">Get</command:parameterValue> <command:parameterValue required="false" variableLength="false">Head</command:parameterValue> <command:parameterValue required="false" variableLength="false">Post</command:parameterValue> <command:parameterValue required="false" variableLength="false">Put</command:parameterValue> <command:parameterValue required="false" variableLength="false">Delete</command:parameterValue> <command:parameterValue required="false" variableLength="false">Trace</command:parameterValue> <command:parameterValue required="false" variableLength="false">Options</command:parameterValue> <command:parameterValue required="false" variableLength="false">Merge</command:parameterValue> <command:parameterValue required="false" variableLength="false">Patch</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OutFile</maml:name> <maml:description> <maml:para>Saves the response body in the specified output file. Enter a path and file name. If you omit the path, the default is the current location.</maml:para> <maml:para>By default, Invoke-WebRequest returns the results to the pipeline. To send the results to a file and to the pipeline, use the Passthru parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the results, in addition to writing them to a file. This parameter is valid only when the OutFile parameter is also used in the command.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Proxy</maml:name> <maml:description> <maml:para>Uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Uri</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyCredential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyUseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="SV"> <maml:name>SessionVariable</maml:name> <maml:description> <maml:para>Creates a web request session and saves it in the value of the specified variable. Enter a variable name without the dollar sign ($) symbol.</maml:para> <maml:para>When you specify a session variable, Invoke-WebRequest creates a web request session object and assigns it to a variable with the specified name in your Windows PowerShell session. You can use the variable in your session as soon as the command completes.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To use the web request session in subsequent web requests, specify the session variable in the value of the WebSession parameter. Windows PowerShell uses the data in the web request session object when establishing the new connection. To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TimeoutSec</maml:name> <maml:description> <maml:para>Specifies how long the request can be pending before it times out. Enter a value in seconds. The default value, 0, specifies an indefinite time-out.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TransferEncoding</maml:name> <maml:description> <maml:para>Specifies a value for the transfer-encoding HTTP response header. Valid values are Chunked, Compress, Deflate, GZip and Identity.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">chunked</command:parameterValue> <command:parameterValue required="false" variableLength="false">compress</command:parameterValue> <command:parameterValue required="false" variableLength="false">deflate</command:parameterValue> <command:parameterValue required="false" variableLength="false">gzip</command:parameterValue> <command:parameterValue required="false" variableLength="false">identity</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseBasicParsing</maml:name> <maml:description> <maml:para>Uses the response object for HTML content without Document Object Model (DOM) parsing.</maml:para> <maml:para>This parameter is required when Internet Explorer is not installed on the computers, such as on a Server Core installation of a Windows Server operating system.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to send the web request.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UserAgent</maml:name> <maml:description> <maml:para>Specifies a user agent string for the web request.</maml:para> <maml:para>The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" with slight variations for each operating system and platform.</maml:para> <maml:para>To test a website with the standard user agent string that is used by most Internet browsers, use the properties of the <maml:navigationLink><maml:linkText>PSUserAgent</maml:linkText><maml:uri></maml:uri></maml:navigationLink> class, such as Chrome, FireFox, InternetExplorer, Opera, and Safari.</maml:para> <maml:para>For example, the following command uses the user agent string for Internet </maml:para> <maml:para>Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>WebSession</maml:name> <maml:description> <maml:para>Specifies a web request session. Enter the variable name, including the dollar sign ($).</maml:para> <maml:para>To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To create a web request session, enter a variable name (without a dollar sign) in the value of the SessionVariable parameter of an Invoke-WebRequest command. Invoke-WebRequest creates the session and saves it in the variable. In subsequent commands, use the variable as the value of the WebSession parameter.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">WebRequestSession</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the body of the request. The body is the content of the request that follows the headers. You can also pipe a body value to Invoke-WebRequest.</maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>Specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate or a command or expression that gets the certificate.</maml:para> <maml:para>To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:) drive. If the certificate is not valid or does not have sufficient authority, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">X509Certificate</command:parameterValue> <dev:type> <maml:name>X509Certificate</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CertificateThumbprint</maml:name> <maml:description> <maml:para>Specifies the digital public key certificate (X509) of a user account that has permission to send the request. Enter the certificate thumbprint of the certificate.</maml:para> <maml:para>Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.</maml:para> <maml:para>To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ContentType</maml:name> <maml:description> <maml:para>Specifies the content type of the web request.</maml:para> <maml:para>If this parameter is omitted and the request method is POST, Invoke-WebRequest sets the content type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the call.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to send the request. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisableKeepAlive</maml:name> <maml:description> <maml:para>Sets the KeepAlive value in the HTTP header to False. By default, KeepAlive is True. KeepAlive establishes a persistent connection to the server to facilitate subsequent requests.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Headers</maml:name> <maml:description> <maml:para>Specifies the headers of the web request. Enter a hash table or dictionary.</maml:para> <maml:para>To set UserAgent headers, use the UserAgent parameter. You cannot use this parameter to specify UserAgent or cookie headers.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InFile</maml:name> <maml:description> <maml:para>Gets the content of the web request from a file. </maml:para> <maml:para>Enter a path and file name. If you omit the path, the default is the current location.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The Body parameter can be used to specify a list of query parameters or specify the content of the response. </maml:para> <maml:para>When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format.</maml:para> <maml:para>When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields.</maml:para> <maml:para>For example:</maml:para> <maml:para>$r = Invoke-WebRequest http://website.com/login.aspx $r.Forms[0].Name = "MyName" $r.Forms[0].Password = "MyPassword" Invoke-RestMethod http://website.com/service.aspx -Body $r</maml:para> <maml:para>- or -</maml:para> <maml:para>Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0]</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaximumRedirection</maml:name> <maml:description> <maml:para>Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Method</maml:name> <maml:description> <maml:para>Specifies the method used for the web request. Valid values are Default, Delete, Get, Head, Merge, Options, Patch, Post, Put, and Trace.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">WebRequestMethod</command:parameterValue> <dev:type> <maml:name>WebRequestMethod</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OutFile</maml:name> <maml:description> <maml:para>Saves the response body in the specified output file. Enter a path and file name. If you omit the path, the default is the current location.</maml:para> <maml:para>By default, Invoke-WebRequest returns the results to the pipeline. To send the results to a file and to the pipeline, use the Passthru parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns the results, in addition to writing them to a file. This parameter is valid only when the OutFile parameter is also used in the command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Proxy</maml:name> <maml:description> <maml:para>Uses a proxy server for the request, rather than connecting directly to the Internet resource. Enter the URI of a network proxy server.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyCredential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to use the proxy server that is specified by the Proxy parameter. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ProxyUseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to access the proxy server that is specified by the Proxy parameter.</maml:para> <maml:para>This parameter is valid only when the Proxy parameter is also used in the command. You cannot use the ProxyCredential and ProxyUseDefaultCredentials parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="SV"> <maml:name>SessionVariable</maml:name> <maml:description> <maml:para>Creates a web request session and saves it in the value of the specified variable. Enter a variable name without the dollar sign ($) symbol.</maml:para> <maml:para>When you specify a session variable, Invoke-WebRequest creates a web request session object and assigns it to a variable with the specified name in your Windows PowerShell session. You can use the variable in your session as soon as the command completes.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To use the web request session in subsequent web requests, specify the session variable in the value of the WebSession parameter. Windows PowerShell uses the data in the web request session object when establishing the new connection. To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TimeoutSec</maml:name> <maml:description> <maml:para>Specifies how long the request can be pending before it times out. Enter a value in seconds. The default value, 0, specifies an indefinite time-out.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TransferEncoding</maml:name> <maml:description> <maml:para>Specifies a value for the transfer-encoding HTTP response header. Valid values are Chunked, Compress, Deflate, GZip and Identity.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Uri</maml:name> <maml:description> <maml:para>Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is sent. Enter a URI. This parameter supports HTTP, HTTPS, FTP, and FILE values.</maml:para> <maml:para>This parameter is required. The parameter name (-Uri) is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Uri</command:parameterValue> <dev:type> <maml:name>Uri</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseBasicParsing</maml:name> <maml:description> <maml:para>Uses the response object for HTML content without Document Object Model (DOM) parsing.</maml:para> <maml:para>This parameter is required when Internet Explorer is not installed on the computers, such as on a Server Core installation of a Windows Server operating system.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseDefaultCredentials</maml:name> <maml:description> <maml:para>Uses the credentials of the current user to send the web request.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UserAgent</maml:name> <maml:description> <maml:para>Specifies a user agent string for the web request.</maml:para> <maml:para>The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" with slight variations for each operating system and platform.</maml:para> <maml:para>To test a website with the standard user agent string that is used by most Internet browsers, use the properties of the <maml:navigationLink><maml:linkText>PSUserAgent</maml:linkText><maml:uri></maml:uri></maml:navigationLink> class, such as Chrome, FireFox, InternetExplorer, Opera, and Safari.</maml:para> <maml:para>For example, the following command uses the user agent string for Internet </maml:para> <maml:para>Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>WebSession</maml:name> <maml:description> <maml:para>Specifies a web request session. Enter the variable name, including the dollar sign ($).</maml:para> <maml:para>To override a value in the web request session, use a cmdlet parameter, such as UserAgent or Credential. Parameter values take precedence over values in the web request session.</maml:para> <maml:para>Unlike a remote session, the web request session is not a persistent connection. It is an object that contains information about the connection and the request, including cookies, credentials, the maximum redirection value, and the user agent string. You can use it to share state and data among web requests.</maml:para> <maml:para>To create a web request session, enter a variable name (without a dollar sign) in the value of the SessionVariable parameter of an Invoke-WebRequest command. Invoke-WebRequest creates the session and saves it in the variable. In subsequent commands, use the variable as the value of the WebSession parameter.</maml:para> <maml:para>You cannot use the SessionVariable and WebSession parameters in the same command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">WebRequestSession</command:parameterValue> <dev:type> <maml:name>WebRequestSession</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the body of a web request to Invoke-WebRequest</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.HtmlWebResponseObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$r = Invoke-WebRequest -URI http://www.bing.com?q=how+many+feet+in+a+mile PS C:\>$r.AllElements | where {$_.innerhtml -like "*=*"} | Sort { $_.InnerHtml.Length } | Select InnerText -First 5 innerText---------1 =5280 feet1 mile </dev:code> <dev:remarks> <maml:para>This command uses the Invoke-WebRequest cmdlet to send a web request to the Bing.com site.</maml:para> <maml:para>The first command issues the request and saves the response in the $r variable.</maml:para> <maml:para>The second command gets the InnerHtml property when it includes an equal sign, sorts the inner HTML by length and selects the 5 shortest values. Sorting by the shortest HTML value often helps you find the most specific element that matches that text.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Invoke-WebRequest cmdlet to send a sign-in request. The command specifies a value of "fb" for the value of the SessionVariable parameter, and saves the result in the $r variable.When the command completes, the $r variable contains an HtmlWebResponseObject and the $fb variable contains a WebRequestSession object. PS C:\>$r=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable fb The second command shows the WebRequestSession object in the $fb variable. PS C:\>$fb The third command gets the first form in the Forms property of the HTTP response object in the $r variable, and saves it in the $form variable. PS C:\>$form = $r.Forms[0] The fourth command pipes the properties of the form in the $form variable into a list by using the Format-List cmdlet. PS C:\>$form | Format-List The fifth command displays the keys and values in the hash table (dictionary) object in the Fields property of the form. PS C:\>$form.fields The sixth and seventh commands populate the values of the "email" and "pass" keys of the hash table in the Fields property of the form. You can replace the email and password with values that you want to use. PS C:\>$form.Fields["email"]="User01@Fabrikam.com" $form.Fields["pass"]="P@ssw0rd" The eighth command uses the Invoke-WebRequest cmdlet to sign into the Facebook web service.The value of the Uri parameter is the value of the Action property of the form. The WebRequestSession object in the $fb variable (the session variable specified in the first command) is now the value of the WebSession parameter. The value of the Body parameter is the hash table in the Fields property of the form and the value of the Method parameter is POST. The command saves the output in the $r variable. PS C:\>$r=Invoke-WebRequest -Uri ("https://www.facebook.com" + $form.Action) -WebSession $fb -Method POST -Body $form.Fields The full script, then, is as follows. PS C:\># Sends a sign-in request by running the Invoke-WebRequest cmdlet. The command specifies a value of "fb" for the SessionVariable parameter, and saves the results in the $r variable. $r=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable fb # Use the session variable that you created in Example 1. Output displays values for Headers, Cookies, Credentials, etc. $fb # Gets the first form in the Forms property of the HTTP response object in the $r variable, and saves it in the $form variable. $form = $r.Forms[0] # Pipes the form properties that are stored in the $forms variable into the Format-List cmdlet, to display those properties in a list. $form | Format-List # Displays the keys and values in the hash table (dictionary) object in the Fields property of the form. $form.fields # The next two commands populate the values of the "email" and "pass" keys of the hash table in the Fields property of the form. Of course, you can replace the email and password with values that you want to use. $form.Fields["email"] = "User01@Fabrikam.com" $form.Fields["pass"] = "P@ssw0rd" # The final command uses the Invoke-WebRequest cmdlet to sign in to the Facebook web service. $r=Invoke-WebRequest -Uri ("https://www.facebook.com" + $form.Action) -WebSession $fb -Method POST -Body $form.Fields When the command finishes, the StatusDescription property of the web response object in the $r variable indicates that the user is signed in successfully. PS C:\>$r.StatusDescription </dev:code> <dev:remarks> <maml:para>This example shows how to use the Invoke-WebRequest cmdlet with a stateful web service, such as Facebook.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>(Invoke-WebRequest -Uri "http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx").Links.Href </dev:code> <dev:remarks> <maml:para>This command gets the links in a web page. It uses the Invoke-WebRequest cmdlet to get the web page content. Then it users the Links property of the HtmlWebResponseObject that Invoke-WebRequest returns, and the Href property of each link.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293988</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-RestMethod</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-Json</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Json</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Measure-Command</command:name> <maml:description> <maml:para>Measures the time it takes to run script blocks and cmdlets.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Measure</command:verb> <command:noun>Command</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Measure-Command cmdlet runs a script block or cmdlet internally, times the execution of the operation, and returns the execution time.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Measure-Command</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Expression</maml:name> <maml:description> <maml:para>Specifies the expression that is being timed. Enclose the expression in braces ({}). The parameter name ("Expression") is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies objects representing the expressions to be measured. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Expression</maml:name> <maml:description> <maml:para>Specifies the expression that is being timed. Enclose the expression in braces ({}). The parameter name ("Expression") is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies objects representing the expressions to be measured. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe an object to Measure-Command.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.TimeSpan</maml:name> <maml:uri>http://msdn.microsoft.com/library/system.timespan.aspx</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Measure-Command returns a time span object that represents the result.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>For more information, type "Get-Help Measure-Command -detailed". For technical information, type "Get-Help Measure-Command -full".</maml:para> <maml:para>When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Measure-Command { Get-EventLog "windows powershell" } </dev:code> <dev:remarks> <maml:para>This command measures the time it takes to run a Get-EventLog command that gets the events in the Windows PowerShell event log.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command measures the time it takes to process a recursive Get-ChildItem command that uses the Path parameter to get only .txt files in the C:\Windows directory and its subdirectories. PS C:\>Measure-Command {Get-ChildItem �Path C:\Windows\*.txt -Recurse} Days : 0 Hours : 0 Minutes : 0 Seconds : 8 Milliseconds : 618 Ticks : 86182763 TotalDays : 9.9748568287037E-05 TotalHours : 0.00239396563888889 TotalMinutes : 0.143637938333333 TotalSeconds : 8.6182763 TotalMilliseconds : 8618.2763 The second command measures the time it takes to process a recursive Get-ChildItem command that uses the provider-specific Filter parameter. PS C:\>Measure-Command {Get-ChildItem C:\Windows -Filter "*.txt" -Recurse} PS C:\> Days : 0 Hours : 0 Minutes : 0 Seconds : 1 Milliseconds : 140 Ticks : 11409189 TotalDays : 1.32050798611111E-05 TotalHours : 0.000316921916666667 TotalMinutes : 0.019015315 TotalSeconds : 1.1409189 TotalMilliseconds : 1140.9189 </dev:code> <dev:remarks> <maml:para>These commands show the value of using a provider-specific filter in Windows PowerShell commands.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293989</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-Command</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Trace-Command</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Measure-Object</command:name> <maml:description> <maml:para>Calculates the numeric properties of objects, and the characters, words, and lines in string objects, such as files of text.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Measure</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Measure-Object cmdlet calculates the property values of certain types of object. Measure-Object performs three types of measurements, depending on the parameters in the command.</maml:para> <maml:para>The Measure-Object cmdlet performs calculations on the property values of objects. It can count objects and calculate the minimum, maximum, sum, and average of the numeric values. For text objects, it can count and calculate the number of lines, words, and characters.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Measure-Object</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies one or more numeric properties to measure. The default is the Count (Length) property of the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Average</maml:name> <maml:description> <maml:para>Displays the average value of the specified properties.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be measured. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> <maml:para>When you use the InputObject parameter with Measure-Object, instead of piping command results to Measure-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Measure-Object to measure a collection of objects for those objects that have specific values in defined properties, you use Measure-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Maximum</maml:name> <maml:description> <maml:para>Displays the maximum value of the specified properties.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minimum</maml:name> <maml:description> <maml:para>Displays the minimum value of the specified properties.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Sum</maml:name> <maml:description> <maml:para>Displays the sum of the values of the specified properties.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Measure-Object</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies one or more numeric properties to measure. The default is the Count (Length) property of the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Character</maml:name> <maml:description> <maml:para>Counts the number of characters in the input object.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWhiteSpace</maml:name> <maml:description> <maml:para>Ignores white space in word counts and character counts. By default, white space is not ignored.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be measured. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> <maml:para>When you use the InputObject parameter with Measure-Object, instead of piping command results to Measure-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Measure-Object to measure a collection of objects for those objects that have specific values in defined properties, you use Measure-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Line</maml:name> <maml:description> <maml:para>Counts the number of lines in the input object.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Word</maml:name> <maml:description> <maml:para>Counts the number of words in the input object.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Average</maml:name> <maml:description> <maml:para>Displays the average value of the specified properties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Character</maml:name> <maml:description> <maml:para>Counts the number of characters in the input object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>IgnoreWhiteSpace</maml:name> <maml:description> <maml:para>Ignores white space in word counts and character counts. By default, white space is not ignored.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be measured. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> <maml:para>When you use the InputObject parameter with Measure-Object, instead of piping command results to Measure-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Measure-Object to measure a collection of objects for those objects that have specific values in defined properties, you use Measure-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Line</maml:name> <maml:description> <maml:para>Counts the number of lines in the input object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Maximum</maml:name> <maml:description> <maml:para>Displays the maximum value of the specified properties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minimum</maml:name> <maml:description> <maml:para>Displays the minimum value of the specified properties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies one or more numeric properties to measure. The default is the Count (Length) property of the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Sum</maml:name> <maml:description> <maml:para>Displays the sum of the values of the specified properties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Word</maml:name> <maml:description> <maml:para>Counts the number of words in the input object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe objects to Measure-Object.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.GenericMeasureInfo, Microsoft.PowerShell.Commands.TextMeasureInfo, Microsoft.PowerShell.Commands.GenericObjectMeasureInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>If you use the Word parameter, Measure-Object returns a TextMeasureInfo object. Otherwise, it returns a GenericMeasureInfo object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | measure-object </dev:code> <dev:remarks> <maml:para>This command counts the files and folders in the current directory.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | measure-object -property length -minimum -maximum -average </dev:code> <dev:remarks> <maml:para>This command displays the minimum, maximum, and sum of the sizes of all files in the current directory, and the average size of a file in the directory.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-content C:\test.txt | measure-object -character -line -word </dev:code> <dev:remarks> <maml:para>This command displays the number of characters, words, and lines in the Text.txt file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | measure-object -property workingset -minimum -maximum -average </dev:code> <dev:remarks> <maml:para>This command displays the minimum, maximum, and average sizes of the working sets of the processes on the computer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>import-csv d:\test\serviceyrs.csv | measure-object -property years -minimum -maximum -average </dev:code> <dev:remarks> <maml:para>This command calculates the average years of service of the employees of a company.</maml:para> <maml:para>The ServiceYrs.csv file is a CSV file that contains the employee number and years of service of each employee. The first row in the table is a header row of "EmpNo, Years".</maml:para> <maml:para>When you use Import-Csv to import the file, the result is a PSCustomObject with note properties of EmpNo and Years. You can use Measure-Object to calculate the values of these properties, just like any other property of an object.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | measure-object -property psiscontainer -max -sum -min -average Count : 126 Average : 0.0634920634920635 Sum : 8 Maximum : 1 Minimum : 0 Property : PSIsContainer </dev:code> <dev:remarks> <maml:para>This example demonstrates the Measure-Object can measure Boolean values. In this case, it uses the PSIsContainer Boolean property to measure the incidence of folders (vs. files) in the current directory.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293990</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Compare-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ForEach-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Group-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Sort-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Tee-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Where-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-Alias</command:name> <maml:description> <maml:para>Creates a new alias.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>New</command:verb> <command:noun>Alias</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The New-Alias cmdlet creates a new alias in the current Windows PowerShell session. Aliases created by using New-Alias are not saved after you exit the session or close Windows PowerShell. You can use the Export-Alias cmdlet to save your alias information to a file. You can later use Import-Alias to retrieve that saved alias information.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-Alias</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the new alias. You can use any alphanumeric characters in an alias, but the first character cannot be a number.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the name of the cmdlet or command element that is being aliased.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies a description of the alias. You can type any string. If the description includes spaces, enclose it in quotation marks.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>If set, act like set-alias if the alias named already exists.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the alias.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed.</maml:para> <maml:para>-- Private: The alias is available only in the current scope.</maml:para> <maml:para>-- AllScope: The alias is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all aliases in the session, type "get-alias | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constant</command:parameterValue> <command:parameterValue required="false" variableLength="false">Private</command:parameterValue> <command:parameterValue required="false" variableLength="false">AllScope</command:parameterValue> <command:parameterValue required="false" variableLength="false">Unspecified</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the new alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope of the new alias. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies a description of the alias. You can type any string. If the description includes spaces, enclose it in quotation marks.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>If set, act like set-alias if the alias named already exists.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the new alias. You can use any alphanumeric characters in an alias, but the first character cannot be a number.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the alias.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed.</maml:para> <maml:para>-- Private: The alias is available only in the current scope.</maml:para> <maml:para>-- AllScope: The alias is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all aliases in the session, type "get-alias | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScopedItemOptions</command:parameterValue> <dev:type> <maml:name>ScopedItemOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the new alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope of the new alias. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the name of the cmdlet or command element that is being aliased.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.AliasInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the Passthru parameter, New-Alias generates a System.Management.Automation.AliasInfo object representing the new alias. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>To create a new alias, use Set-Alias or New-Alias. To change an alias, use Set-Alias. To delete an alias, use Remove-Item.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-alias list get-childitem </dev:code> <dev:remarks> <maml:para>This command creates an alias named "list" to represent the Get-ChildItem cmdlet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-alias -name w -value get-wmiobject -description "quick wmi alias" -option ReadOnly PS C:\>get-alias -name w | format-list * </dev:code> <dev:remarks> <maml:para>This command creates an alias named "w" to represent the Get-WMIObject cmdlet. It creates a description, "quick wmi alias", for the alias and makes it read only. The last line of the command uses Get-Alias to get the new alias and pipes it to Format-List to display all of the information about it.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293991</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-Event</command:name> <maml:description> <maml:para>Creates a new event.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>New</command:verb> <command:noun>Event</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The New-Event cmdlet creates a new custom event.</maml:para> <maml:para>You can use custom events to notify users about state changes in your program and any change that your program can detect, including hardware or system conditions, application status, disk status, network status, or the completion of a background job.</maml:para> <maml:para>Custom events are automatically added to the event queue in your session whenever they are raised; you do not need to subscribe to them. However, if you want to forward an event to the local session or specify an action to respond to the event, use the Register-EngineEvent cmdlet to subscribe to the custom event.</maml:para> <maml:para>When you subscribe to a custom event, the event subscriber is added to your session. If you cancel the event subscription by using the Unregister-Event cmdlet, the event subscriber and custom event are deleted from the session. If you do not subscribe to the custom event, to delete the event, you must change the program conditions or close the Windows PowerShell session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-Event</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name for the new event. This parameter is required, and it must be unique in the session.</maml:para> <maml:para>The value of this parameter appears in the SourceIdentifier property of the events.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Sender</maml:name> <maml:description> <maml:para>Specifies the object that raises the event. The default is the Windows PowerShell engine.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>EventArguments</maml:name> <maml:description> <maml:para>Specifies an object that contains options for the event.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">PSObject[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies additional data associated with the event. The value of this parameter appears in the MessageData property of the event object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>EventArguments</maml:name> <maml:description> <maml:para>Specifies an object that contains options for the event.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference[]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="4" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies additional data associated with the event. The value of this parameter appears in the MessageData property of the event object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Sender</maml:name> <maml:description> <maml:para>Specifies the object that raises the event. The default is the Windows PowerShell engine.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name for the new event. This parameter is required, and it must be unique in the session.</maml:para> <maml:para>The value of this parameter appears in the SourceIdentifier property of the events.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSEventArgs</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The new custom event, the event subscription, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-event -sourceidentifier Timer -sender windows.timer -messagedata "Test" </dev:code> <dev:remarks> <maml:para>This command creates a new event in the Windows PowerShell event queue. It uses a Windows.Timer object to send the event.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>function Enable-ProcessCreationEvent { $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" $processWatcher = New-Object System.Management.ManagementEventWatcher $query $identifier = "WMI.ProcessCreated" Register-ObjectEvent $processWatcher "EventArrived" -SupportEvent $identifier -Action { [void] (New-Event -sourceID "PowerShell.ProcessCreated" -Sender $args[0] �EventArguments $args[1].SourceEventArgs.NewEvent.TargetInstance) } } </dev:code> <dev:remarks> <maml:para>This sample function uses the New-Event cmdlet to raise an event in response to another event. The command uses the Register-ObjectEvent cmdlet to subscribe to the Windows Management Instrumentation (WMI) event that is raised when a new process is created. The command uses the Action parameter of the cmdlet to call the New-Event cmdlet, which creates the new event.</maml:para> <maml:para>Because the events that New-Event raises are automatically added to the Windows PowerShell event queue, you do not need to register for that event.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293992</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-Object</command:name> <maml:description> <maml:para>Creates an instance of a Microsoft .NET Framework or COM object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>New</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The New-Object cmdlet creates an instance of a .NET Framework or COM object.</maml:para> <maml:para>You can specify either the type of a .NET Framework class or a ProgID of a COM object. By default, you type the fully qualified name of a .NET Framework class and the cmdlet returns a reference to an instance of that class. To create an instance of a COM object, use the ComObject parameter and specify the ProgID of the object as its value.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-Object</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies the fully qualified name of the .NET Framework class. You cannot specify both the TypeName parameter and the ComObject parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Specifies a list of arguments to pass to the constructor of the .NET Framework class. Separate elements in the list by using commas (,). The alias for ArgumentList is Args.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Sets property values and invokes methods of the new object.</maml:para> <maml:para>Enter a hash table in which the keys are the names of properties or methods and the values are property values or method arguments. New-Object creates the object and sets each property value and invokes each method in the order that they appear in the hash table.</maml:para> <maml:para>If the new object is derived from the PSObject class, and you specify a property that does not exist on the object, New-Object adds the specified property to the object as a NoteProperty. If the object is not a PSObject, the command generates a non-terminating error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>New-Object</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ComObject</maml:name> <maml:description> <maml:para>Specifies the programmatic identifier (ProgID) of the COM object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Sets property values and invokes methods of the new object.</maml:para> <maml:para>Enter a hash table in which the keys are the names of properties or methods and the values are property values or method arguments. New-Object creates the object and sets each property value and invokes each method in the order that they appear in the hash table.</maml:para> <maml:para>If the new object is derived from the PSObject class, and you specify a property that does not exist on the object, New-Object adds the specified property to the object as a NoteProperty. If the object is not a PSObject, the command generates a non-terminating error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Strict</maml:name> <maml:description> <maml:para>Generates a non-terminating error when a COM object that you attempt to create uses an interop assembly. This feature distinguishes actual COM objects from .NET Framework objects with COM-callable wrappers.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Specifies a list of arguments to pass to the constructor of the .NET Framework class. Separate elements in the list by using commas (,). The alias for ArgumentList is Args.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>ComObject</maml:name> <maml:description> <maml:para>Specifies the programmatic identifier (ProgID) of the COM object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Sets property values and invokes methods of the new object.</maml:para> <maml:para>Enter a hash table in which the keys are the names of properties or methods and the values are property values or method arguments. New-Object creates the object and sets each property value and invokes each method in the order that they appear in the hash table.</maml:para> <maml:para>If the new object is derived from the PSObject class, and you specify a property that does not exist on the object, New-Object adds the specified property to the object as a NoteProperty. If the object is not a PSObject, the command generates a non-terminating error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Strict</maml:name> <maml:description> <maml:para>Generates a non-terminating error when a COM object that you attempt to create uses an interop assembly. This feature distinguishes actual COM objects from .NET Framework objects with COM-callable wrappers.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies the fully qualified name of the .NET Framework class. You cannot specify both the TypeName parameter and the ComObject parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>New-Object returns the object that is created.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>New-Object provides the most commonly-used functionality of the VBScript CreateObject function. A statement like Set objShell = CreateObject("Shell.Application") in VBScript can be translated to $objShell = New-Object -COMObject "Shell.Application" in Windows PowerShell.</maml:para> <maml:para>New-Object expands upon the functionality available in the Windows Script Host environment by making it easy to work with .NET Framework objects from the command line and within scripts.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>New-Object -TypeName System.Version -ArgumentList "1.2.3.4" Major Minor Build Revision ----- ----- ----- -------- 1 2 3 4 </dev:code> <dev:remarks> <maml:para>This command creates a System.Version object. It uses a "1.2.3.4" string as the constructor.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$ie = New-Object -COMObject InternetExplorer.Application -Property @{Navigate2="www.microsoft.com"; Visible = $true} </dev:code> <dev:remarks> <maml:para>This command creates an instance of the COM object that represents the Internet Explorer application. The value of the Property parameter is a hash table that calls the Navigate2 method and sets the Visible property of the object to $true to make the application visible.</maml:para> <maml:para>This command is the equivalent of the following:</maml:para> <maml:para>$ie = New-Object -COMObject InternetExplorer.Application</maml:para> <maml:para>$ie.Navigate2("www.microsoft.com")</maml:para> <maml:para>$ie.Visible = $true</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a=New-Object -COMObject Word.Application -Strict -Property @{Visible=$true} New-Object : The object written to the pipeline is an instance of the type "Microsoft.Office.Interop.Word.ApplicationClass" from the component's primary interop assembly. If this type exposes different members than the IDispatch members, scripts written to work with this object might not work if the primary interop assembly is not installed. At line:1 char:14 + $a=New-Object <<<< -COM Word.Application -Strict; $a.visible=$true </dev:code> <dev:remarks> <maml:para>This example demonstrates that adding the Strict parameter causes the New-Object cmdlet to generate a non-terminating error when the COM object uses an interop assembly.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the ComObject parameter of the New-Object cmdlet to create a COM object with the "Shell.Application" ProgID. It stores the resulting object in the $objShell variable. PS C:\>$objshell = New-Object -COMObject "Shell.Application" The second command pipes the $objShell variable to the Get-Member cmdlet, which displays the properties and methods of the COM object. Among the methods is the ToggleDesktop method. PS C:\>$objshell | Get-Member TypeName: System.__ComObject#{866738b9-6cf2-4de8-8767-f794ebe74f4e} Name MemberType Definition ---- ---------- ---------- AddToRecent Method void AddToRecent (Variant, string) BrowseForFolder Method Folder BrowseForFolder (int, string, int, Variant) CanStartStopService Method Variant CanStartStopService (string) CascadeWindows Method void CascadeWindows () ControlPanelItem Method void ControlPanelItem (string) EjectPC Method void EjectPC () Explore Method void Explore (Variant) ExplorerPolicy Method Variant ExplorerPolicy (string) FileRun Method void FileRun () FindComputer Method void FindComputer () FindFiles Method void FindFiles () FindPrinter Method void FindPrinter (string, string, string) GetSetting Method bool GetSetting (int) GetSystemInformation Method Variant GetSystemInformation (string) Help Method void Help () IsRestricted Method int IsRestricted (string, string) IsServiceRunning Method Variant IsServiceRunning (string) MinimizeAll Method void MinimizeAll () NameSpace Method Folder NameSpace (Variant) Open Method void Open (Variant) RefreshMenu Method void RefreshMenu () ServiceStart Method Variant ServiceStart (string, Variant) ServiceStop Method Variant ServiceStop (string, Variant) SetTime Method void SetTime () ShellExecute Method void ShellExecute (string, Variant, Variant, Variant, Variant) ShowBrowserBar Method Variant ShowBrowserBar (string, Variant) ShutdownWindows Method void ShutdownWindows () Suspend Method void Suspend () TileHorizontally Method void TileHorizontally () TileVertically Method void TileVertically () ToggleDesktop Method void ToggleDesktop () TrayProperties Method void TrayProperties () UndoMinimizeALL Method void UndoMinimizeALL () Windows Method IDispatch Windows () WindowsSecurity Method void WindowsSecurity () WindowSwitcher Method void WindowSwitcher () Application Property IDispatch Application () {get} Parent Property IDispatch Parent () {get} The third command calls the ToggleDesktop method of the object to minimize the open windows on your desktop. PS C:\>$objshell.ToggleDesktop() </dev:code> <dev:remarks> <maml:para>This example shows how to create and use a COM object to manage your Windows desktop.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293993</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Compare-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ForEach-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Group-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Measure-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Sort-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Tee-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Where-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-TimeSpan</command:name> <maml:description> <maml:para>Creates a TimeSpan object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>New</command:verb> <command:noun>TimeSpan</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The New-TimeSpan cmdlet creates a TimeSpan object that represents a time interval You can use a TimeSpan object to add or subtract time from DateTime objects.</maml:para> <maml:para>Without parameters, a "New-Timespan" command returns a timespan object that represents a time interval of zero.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-TimeSpan</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="LastWriteTime"> <maml:name>Start</maml:name> <maml:description> <maml:para>Indicates the start of a time span. Enter a string that represents the date and time, such as "3/15/09" or a DateTime object, such as one from a Get-Date command. The default is the current date and time.</maml:para> <maml:para>You can use Start or its alias, LastWriteTime. The LastWriteTime alias lets you pipe objects that have a LastWriteTime property, such as files in the file system (System.Io.FileIO), to the Start parameter of New-TimeSpan.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>End</maml:name> <maml:description> <maml:para>Indicates the end of a time span. The default is the current date and time.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>New-TimeSpan</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Days</maml:name> <maml:description> <maml:para>Indicates the days in the time span. The default is 0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Hours</maml:name> <maml:description> <maml:para>Indicates the hours in the time span. The default is zero.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minutes</maml:name> <maml:description> <maml:para>Indicates the minutes in the time span. The default is 0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Seconds</maml:name> <maml:description> <maml:para>Indicates the length of the time span in seconds. The default is 0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Days</maml:name> <maml:description> <maml:para>Indicates the days in the time span. The default is 0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>End</maml:name> <maml:description> <maml:para>Indicates the end of a time span. The default is the current date and time.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> <dev:type> <maml:name>DateTime</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Hours</maml:name> <maml:description> <maml:para>Indicates the hours in the time span. The default is zero.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Minutes</maml:name> <maml:description> <maml:para>Indicates the minutes in the time span. The default is 0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Seconds</maml:name> <maml:description> <maml:para>Indicates the length of the time span in seconds. The default is 0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="LastWriteTime"> <maml:name>Start</maml:name> <maml:description> <maml:para>Indicates the start of a time span. Enter a string that represents the date and time, such as "3/15/09" or a DateTime object, such as one from a Get-Date command. The default is the current date and time.</maml:para> <maml:para>You can use Start or its alias, LastWriteTime. The LastWriteTime alias lets you pipe objects that have a LastWriteTime property, such as files in the file system (System.Io.FileIO), to the Start parameter of New-TimeSpan.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> <dev:type> <maml:name>DateTime</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.DateTime</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a DateTime object that represents that start time to New-TimeSpan.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.TimeSpan</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>New-TimeSpan returns an object that represents the time span.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$timespan = new-timespan -hour 1 -minute 25 </dev:code> <dev:remarks> <maml:para>This command creates a TimeSpan object with a duration of 1 hour and 25 minutes and stores it in a variable named $timespan. It displays a representation of the TimeSpan object.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-timespan -end (get-date -year 2010 -month 1 -day 1) </dev:code> <dev:remarks> <maml:para>This example creates a new TimeSpan object that represents the interval between the time that the command is run and January 1, 2010.</maml:para> <maml:para>This command does not require the Start parameter, because the default value of the Start parameter is the current date and time.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$90days = new-timespan -days 90 PS C:\>(get-date) + $90days </dev:code> <dev:remarks> <maml:para>These commands return the date that is 90 days after the current date.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>dir $pshome\en-us\about_remote.help.txt | new-timespan Days : 321 Hours : 21 Minutes : 59 Seconds : 22 Milliseconds : 312 Ticks : 278135623127728 TotalDays : 321.916230471907 TotalHours : 7725.98953132578 TotalMinutes : 463559.371879547 TotalSeconds : 27813562.3127728 TotalMilliseconds : 27813562312.7728 # Equivalent to: PS C:\>new-timespan -start (dir $pshome\en-us\about_remote.help.txt).lastwritetime </dev:code> <dev:remarks> <maml:para>This command tells you how long it has been since the about_remote.help.txt file was last updated. You can use this command format on any file, and on any other object that has a LastWriteTime property.</maml:para> <maml:para>This command works because the Start parameter of New-TimeSpan has an alias of LastWriteTime. When you pipe an object that has a LastWriteTime property to New-TimeSpan, Windows PowerShell uses the value of the LastWriteTime property as the value of the Start parameter.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293994</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Date</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Date</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-Variable</command:name> <maml:description> <maml:para>Creates a new variable.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>New</command:verb> <command:noun>Variable</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The New-Variable cmdlet creates a new variable in Windows PowerShell. You can assign a value to the variable while creating it or assign or change the value after it is created.</maml:para> <maml:para>You can use the parameters of New-Variable to set the properties of the variable (such as those that create read-only or constant variables), set the scope of a variable, and determine whether variables are public or private.</maml:para> <maml:para>Typically, you create a new variable by typing the variable name and its value, such as "$var = 3", but you can use the New-Variable cmdlet to use its parameters.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-Variable</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies a name for the new variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the initial value of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies a description of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows you to create a new variable with the same name as an existing read-only variable.</maml:para> <maml:para>By default, you can overwrite a variable unless the variable has an option value of ReadOnly or Constant. For more information, see the Option parameter.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the variable.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed. "Constant" is valid only when you are creating a variable. You cannot change the options of an existing variable to "Constant".</maml:para> <maml:para>-- Private: The variable is available only in the current scope.</maml:para> <maml:para>-- AllScope: The variable is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all variables in the session, type "get-variable | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constant</command:parameterValue> <command:parameterValue required="false" variableLength="false">Private</command:parameterValue> <command:parameterValue required="false" variableLength="false">AllScope</command:parameterValue> <command:parameterValue required="false" variableLength="false">Unspecified</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the new variable. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Determines the scope of the new variable. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Visibility</maml:name> <maml:description> <maml:para>Determines whether the variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Public: The variable is visible. ("Public" is the default.)</maml:para> <maml:para>-- Private: The variable is not visible.</maml:para> <maml:para>When a variable is private, it does not appear in lists of variables, such as those returned by Get-Variable, or in displays of the Variable: drive. Commands to read or change the value of a private variable return an error. However, the user can run commands that use a private variable if the commands were written in the session in which the variable was defined.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Public</command:parameterValue> <command:parameterValue required="false" variableLength="false">Private</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies a description of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows you to create a new variable with the same name as an existing read-only variable.</maml:para> <maml:para>By default, you can overwrite a variable unless the variable has an option value of ReadOnly or Constant. For more information, see the Option parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies a name for the new variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the variable.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed. "Constant" is valid only when you are creating a variable. You cannot change the options of an existing variable to "Constant".</maml:para> <maml:para>-- Private: The variable is available only in the current scope.</maml:para> <maml:para>-- AllScope: The variable is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all variables in the session, type "get-variable | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScopedItemOptions</command:parameterValue> <dev:type> <maml:name>ScopedItemOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the new variable. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Determines the scope of the new variable. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the initial value of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Visibility</maml:name> <maml:description> <maml:para>Determines whether the variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Public: The variable is visible. ("Public" is the default.)</maml:para> <maml:para>-- Private: The variable is not visible.</maml:para> <maml:para>When a variable is private, it does not appear in lists of variables, such as those returned by Get-Variable, or in displays of the Variable: drive. Commands to read or change the value of a private variable return an error. However, the user can run commands that use a private variable if the commands were written in the session in which the variable was defined.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SessionStateEntryVisibility</command:parameterValue> <dev:type> <maml:name>SessionStateEntryVisibility</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a value to New-Variable.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.PSVariable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, New-Variable generates a System.Management.Automation.PSVariable object representing the new variable. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-variable days </dev:code> <dev:remarks> <maml:para>This command creates a new variable named "days". It has no value immediately following the command.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-variable zipcode -value 98033 </dev:code> <dev:remarks> <maml:para>This command creates a variable named "zipcode" and assigns it the value "98033".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-variable -name max -value 256 -option readonly PS C:\>new-variable -name max -value 1024 New-Variable : A variable with name 'max' already exists. At line:1 char:13 + new-variable <<<< -name max -value 1024 PS C:\>new-variable -name max -value 1024 -force </dev:code> <dev:remarks> <maml:para>This example shows how to use the ReadOnly option of New-Variable to protect a variable from being overwritten.</maml:para> <maml:para>The first command creates a new variable named Max and sets its value to "256". It uses the Option parameter with a value of ReadOnly.</maml:para> <maml:para>The second command tries to create a second variable with the same name. This command returns an error, because the read-only option is set on the variable.</maml:para> <maml:para>The third command uses the Force parameter to override the read-only protection on the variable. In this case, the command to create a new variable with the same name succeeds.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>new-variable -name counter -visibility private #Effect of private variable in a module. PS C:\>get-variable c* Name Value ---- ----- Culture en-US ConsoleFileName ConfirmPreference High CommandLineParameters {} PS C:\>$counter "Cannot access the variable '$counter' because it is a private variable" PS C:\>Get-Counter Name Value ---- ----- Counter1 3.1415 ... </dev:code> <dev:remarks> <maml:para>This command demonstrates the behavior of a private variable in a module. The module contains the Get-Counter cmdlet, which has a private variable named "Counter". The command uses the Visibility parameter with a value of "Private" to create the variable.</maml:para> <maml:para>The sample output shows the behavior of a private variable. The user who has loaded the module cannot view or change the value of the Counter variable, but the Counter variable can be read and changed by the commands in the module.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293995</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Out-File</command:name> <maml:description> <maml:para>Sends output to a file.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Out</command:verb> <command:noun>File</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (>) when you need to use its parameters.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Out-File</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Specifies the path to the output file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of character encoding used in the file. Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". "Unicode" is the default.</maml:para> <maml:para>"Default" uses the encoding of the system's current ANSI code page.</maml:para> <maml:para>"OEM" uses the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">unknown</command:parameterValue> <command:parameterValue required="false" variableLength="false">string</command:parameterValue> <command:parameterValue required="false" variableLength="false">unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">bigendianunicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf8</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf7</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf32</command:parameterValue> <command:parameterValue required="false" variableLength="false">ascii</command:parameterValue> <command:parameterValue required="false" variableLength="false">default</command:parameterValue> <command:parameterValue required="false" variableLength="false">oem</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Adds the output to the end of an existing file, instead of replacing the file contents.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to overwrite an existing read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Will not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Out-File overwrites the file without warning. If both Append and NoClobber are used, the output is appended to the existing file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If you omit this parameter, the width is determined by the characteristics of the host. The default for the Windows PowerShell console is 80 (characters).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Out-File</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of character encoding used in the file. Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". "Unicode" is the default.</maml:para> <maml:para>"Default" uses the encoding of the system's current ANSI code page.</maml:para> <maml:para>"OEM" uses the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">unknown</command:parameterValue> <command:parameterValue required="false" variableLength="false">string</command:parameterValue> <command:parameterValue required="false" variableLength="false">unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">bigendianunicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf8</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf7</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf32</command:parameterValue> <command:parameterValue required="false" variableLength="false">ascii</command:parameterValue> <command:parameterValue required="false" variableLength="false">default</command:parameterValue> <command:parameterValue required="false" variableLength="false">oem</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Adds the output to the end of an existing file, instead of replacing the file contents.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to overwrite an existing read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Will not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Out-File overwrites the file without warning. If both Append and NoClobber are used, the output is appended to the existing file.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If you omit this parameter, the width is determined by the characteristics of the host. The default for the Windows PowerShell console is 80 (characters).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the output file. Unlike FilePath, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Adds the output to the end of an existing file, instead of replacing the file contents.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the type of character encoding used in the file. Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". "Unicode" is the default.</maml:para> <maml:para>"Default" uses the encoding of the system's current ANSI code page.</maml:para> <maml:para>"OEM" uses the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Specifies the path to the output file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to overwrite an existing read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="NoOverwrite"> <maml:name>NoClobber</maml:name> <maml:description> <maml:para>Will not overwrite (replace the contents) of an existing file. By default, if a file exists in the specified path, Out-File overwrites the file without warning. If both Append and NoClobber are used, the output is appended to the existing file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If you omit this parameter, the width is determined by the characteristics of the host. The default for the Windows PowerShell console is 80 (characters).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the output file. Unlike FilePath, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Out-File.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Out-File does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it.</maml:para> <maml:para>The Out cmdlets do not have parameters for names or file paths. To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples.</maml:para> <maml:para>Out-File sends data, but it does not emit any output objects. If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | out-file -filepath C:\Test1\process.txt </dev:code> <dev:remarks> <maml:para>This command sends a list of processes on the computer to the Process.txt file. If the file does not exist, Out-File creates it. Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test1\process.txt".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | out-file C:\Test1\process.txt -noclobber Out-File : File C:\Test1\process.txt already exists and NoClobber was specified. At line:1 char:23 + get-process | out-file <<<< process.txt -noclobber </dev:code> <dev:remarks> <maml:para>This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. The output shows the error message that appears when NoClobber is used with an existing file.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = get-process PS C:\>out-file -filepath C:\Test1\process.txt -inputobject $a -encoding ASCII -width 50 </dev:code> <dev:remarks> <maml:para>These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. By default, Out-File uses Unicode format.</maml:para> <maml:para>The first command gets the list of processes and stores them in the $a variable. The second command uses the Out-File cmdlet to send the list to the Process.txt file.</maml:para> <maml:para>The command uses the InputObject parameter to specify that the input is in the $a variable. It uses the Encoding parameter to convert the output to ASCII format. It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-location hklm:\software PS C:\>get-acl mycompany\mykey | out-file -filepath c:\ps\acl.txt PS C:\>get-acl mycompany\mykey | out-file -filepath filesystem::acl.txt </dev:code> <dev:remarks> <maml:para>These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive.</maml:para> <maml:para>The first command sets the current location to the HKLM:\Software registry key.</maml:para> <maml:para>The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file.</maml:para> <maml:para>Because Out-File is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293996</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Default</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Null</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Printer</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-String</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Tee-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Out-GridView</command:name> <maml:description> <maml:para>Sends output to an interactive table in a separate window.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Out</command:verb> <command:noun>GridView</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Out-GridView cmdlet sends the output from a command to a grid view window where the output is displayed in an interactive table.</maml:para> <maml:para>Because this cmdlet requires a user interface, it does not work on Server Core installations of Windows Server.</maml:para> <maml:para>You can use the following features of the table to examine your data:</maml:para> <maml:para>-- Hide, Show, and Reorder Columns: To hide, show, or reorder a column, right-click a column header and then click "Select Columns."</maml:para> <maml:para> -- Sort. To sort the data, click a column header. Click again to toggle from ascending to descending order.</maml:para> <maml:para>-- Quick Filter. Use the "Filter" box at the top of the window to search the text in the table. You can search for text in a particular column, search for literals, and search for multiple words.</maml:para> <maml:para>-- Criteria Filter. Use the "Add criteria" drop-down menu to create rules to filter the data. This is very useful for very large data sets, such as event logs.</maml:para> <maml:para>-- Copy and paste. To copy rows of data from Out-GridView, press CTRL+C (copy). You can paste the data into any text or spreadsheet program.</maml:para> <maml:para>For instructions for using these features, type "Get-Help Out-GridView -Full" and see "How to Use the Grid View Window Features" in the NOTES section.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Out-GridView</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Out-GridView.</maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Sends items from the interactive window down the pipeline as input to other commands. By default, this cmdlet does not generate any output. This parameter is equivalent to using the Multiple value of the OutputMode parameter.</maml:para> <maml:para>To send items from the interactive window down the pipeline, click to select the items and then click OK. Shift-click and Ctrl-click are supported.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies the text that appears in the title bar of the Out-GridView window.</maml:para> <maml:para>By default, the title bar displays the command that invokes Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Out-GridView</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Out-GridView.</maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies the text that appears in the title bar of the Out-GridView window.</maml:para> <maml:para>By default, the title bar displays the command that invokes Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Suppresses the command prompt and prevents Windows PowerShell from closing until the Out-GridView window is closed. By default, the command prompt returns when the Out-GridView window opens.</maml:para> <maml:para>This feature lets you use the Out-GridView cmdlets in Windows shortcuts. When Out-GridView is used in a shortcut without the Wait parameter, the Out-GridView window appears only momentarily before Windows PowerShell closes. </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Out-GridView</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Out-GridView.</maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OutputMode</maml:name> <maml:description> <maml:para>Send items from the interactive window down the pipeline as input to other commands. By default, this cmdlet does not generate any output. To send items from the interactive window down the pipeline, click to select the items and then click OK.</maml:para> <maml:para>The values of this parameter determine how many items you can send down the pipeline.</maml:para> <maml:para>-- None: No items. This is the default value.</maml:para> <maml:para>-- Single: Zero items or one item. Use this value when the next command can take only one input object.</maml:para> <maml:para>-- Multiple: Zero, one, or many items. Use this value when the next command can take multiple input objects. This value is equivalent to the Passthru parameter.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">Single</command:parameterValue> <command:parameterValue required="false" variableLength="false">Multiple</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies the text that appears in the title bar of the Out-GridView window.</maml:para> <maml:para>By default, the title bar displays the command that invokes Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Accepts input for Out-GridView.</maml:para> <maml:para>When you use the InputObject parameter to send a collection (more than one) of objects to Out-GridView, Out-GridView treats the collection as one collection object, and it displays one row that represents the collection. To display the each object in the collection, use a pipeline operator (|) to send objects to Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>Specifies the text that appears in the title bar of the Out-GridView window.</maml:para> <maml:para>By default, the title bar displays the command that invokes Out-GridView.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>OutputMode</maml:name> <maml:description> <maml:para>Send items from the interactive window down the pipeline as input to other commands. By default, this cmdlet does not generate any output. To send items from the interactive window down the pipeline, click to select the items and then click OK.</maml:para> <maml:para>The values of this parameter determine how many items you can send down the pipeline.</maml:para> <maml:para>-- None: No items. This is the default value.</maml:para> <maml:para>-- Single: Zero items or one item. Use this value when the next command can take only one input object.</maml:para> <maml:para>-- Multiple: Zero, one, or many items. Use this value when the next command can take multiple input objects. This value is equivalent to the Passthru parameter.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">OutputModeOption</command:parameterValue> <dev:type> <maml:name>OutputModeOption</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Sends items from the interactive window down the pipeline as input to other commands. By default, this cmdlet does not generate any output. This parameter is equivalent to using the Multiple value of the OutputMode parameter.</maml:para> <maml:para>To send items from the interactive window down the pipeline, click to select the items and then click OK. Shift-click and Ctrl-click are supported.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Suppresses the command prompt and prevents Windows PowerShell from closing until the Out-GridView window is closed. By default, the command prompt returns when the Out-GridView window opens.</maml:para> <maml:para>This feature lets you use the Out-GridView cmdlets in Windows shortcuts. When Out-GridView is used in a shortcut without the Wait parameter, the Out-GridView window appears only momentarily before Windows PowerShell closes. </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can send any object to Out-GridView.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Out-GridView does not return any objects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>In Windows PowerShell 2.0, the Out-GridView cmdlet is installed by default on client versions of Windows, but is an optional feature on Server versions of Windows. In Windows PowerShell 3.0, it is installed on all systems by default. However, if you turn off or remove the Windows PowerShell ISE feature, the Out-GridView cmdlet is also turned off or removed.</maml:para> </maml:alert> <maml:alert> <maml:para>You cannot use a remote command to open a grid view window on another computer.</maml:para> </maml:alert> <maml:alert> <maml:para>The command output that you send to Out-GridView cannot be formatted, such as by using the Format-Table or Format-Wide cmdlets. To select properties, use the Select-Object cmdlet.</maml:para> </maml:alert> <maml:alert> <maml:para>Deserialized output from remote commands might not be formatted correctly in the grid view window.</maml:para> </maml:alert> <maml:alert> <maml:para>KEYBOARD SHORTCUTS FOR OUT-GRIDVIEW</maml:para> <maml:para>-----------------------------------</maml:para> <maml:para>By using the following keyboard shortcuts, you can perform many tasks quickly.</maml:para> <maml:para>Use this key: To perform this action:</maml:para> <maml:para>------------- ----------------------------------------------------------------</maml:para> <maml:para>TAB Moves the cursor from the Filter box to the Add criteria menu to the table and back.</maml:para> <maml:para>UP ARROW Move up one row. Will move to column headers.</maml:para> <maml:para>DOWN ARROW Move down one row.</maml:para> <maml:para>LEFT ARROW In column header row, move left one column.</maml:para> <maml:para>RIGHT ARROW In column header row, move right one column.</maml:para> <maml:para>CONTEXT MENU KEY In column header row, displays the "Select Columns" option.</maml:para> <maml:para>ENTER or SPACEBAR In column header row, sort column data (toggle A-Z, Z-A).</maml:para> <maml:para>HOW TO USE THE GRID VIEW WINDOW FEATURES</maml:para> <maml:para>----------------------------------------</maml:para> <maml:para>The following topics explain how to use the features of the window that Out-GridView displays.</maml:para> <maml:para>How to Hide, Show, and Reorder Columns</maml:para> <maml:para>--------------------------------------</maml:para> <maml:para>To hide or show a column:</maml:para> <maml:para>1. Right click any column header and click "Select Columns".</maml:para> <maml:para>2. In the "Select Columns" dialog box, use the arrow keys to move the columns between the "Selected columns" to the "Available columns" boxes. Only columns in the "Selected Columns" box appear in the grid view window.</maml:para> <maml:para>To reorder columns:</maml:para> <maml:para>-- Drag and drop the column into the desired location.</maml:para> <maml:para>- or-</maml:para> <maml:para>1. Right click any column header and click "Select Columns".</maml:para> <maml:para>2. In the "Select Columns" dialog box, use the "Move up" and "Move down" buttons to reorder the columns. Columns at the top of the list appear to the left of columns at the bottom of the list in the grid view window.</maml:para> <maml:para>How to Sort Table Data</maml:para> <maml:para>----------------------</maml:para> <maml:para>-- To sort the data, click a column header.</maml:para> <maml:para>-- To change the sort order, click the column header again. Each time you click the same header, the sort order toggles between ascending to descending order. The current order is indicated by a triangle in the column header.</maml:para> <maml:para>How to Select Table Data</maml:para> <maml:para>------------------------</maml:para> <maml:para>-- To select a row, click the row or use the up or down arrow to navigate to the row.</maml:para> <maml:para>-- To select all rows (except for the header row), press CTRL+A.</maml:para> <maml:para>-- To select consecutive rows, press and hold the SHIFT key while clicking the rows or using the arrow keys.</maml:para> <maml:para>-- To select nonconsecutive rows, press the CTRL key and click to add a row to the selection.</maml:para> <maml:para>You cannot select columns, and you cannot select the entire column header row.</maml:para> <maml:para>How to Copy Rows</maml:para> <maml:para>----------------------</maml:para> <maml:para>-- To copy one or more rows from the table, select the rows and then press CTRL+C.</maml:para> <maml:para>You can paste the data into any text or spreadsheet program. You cannot copy columns or parts of rows and you cannot copy the column header row.</maml:para> <maml:para>How to Search in the Table (Quick Filter)</maml:para> <maml:para>---------------------------------</maml:para> <maml:para>Use the "Filter" box to search for data in the table. When you type in the box, only items that include the typed text appear in the table.</maml:para> <maml:para>-- Search for text. To search for text in the table, in the "Filter" box, type the text to find.</maml:para> <maml:para>-- Search for multiple words. To search for multiple words in the table, type the words separated by spaces. Out-GridView displays rows that include all of the words (logical AND).</maml:para> <maml:para>-- Search for literal phrases. To search for phrases that include spaces or special characters, enclose the phrase in quotation marks. Out-GridView displays rows that include an exact match for the phrase.</maml:para> <maml:para>-- Search in columns. To search for text in one or more columns, use the following format:</maml:para> <maml:para><column>:<text> [<column>:<text>] ...</maml:para> <maml:para>For example, to find "Net" in the DisplayName column, in the "Filter" box, type:</maml:para> <maml:para>displayname:net</maml:para> <maml:para>To find rows with "Net" in the DisplayName and Name columns, in the "Filter" box, type:</maml:para> <maml:para>displayname:net name:net</maml:para> <maml:para>-- Turn off search. To display the entire table again, click the red X button in the top right corner of the "Filter" box or delete the text from the Filter box.</maml:para> <maml:para>Use Criteria to Filter the Table</maml:para> <maml:para>--------------------------------</maml:para> <maml:para>You can use rules or "criteria" to determine which items are displayed in the table. Items appear only when they satisfy all of the criteria that you establish. The available criteria are determined by the properties of the objects displayed in the grid view window and the .NET Framework types of those properties.</maml:para> <maml:para>Each criterion has the following format:</maml:para> <maml:para><column> <operator> <value></maml:para> <maml:para>Criteria for different properties are connected by AND. Criteria for the same property are connected by OR. You cannot change the logical connectors.</maml:para> <maml:para>The criteria only affects the display. It does not delete items from the table.</maml:para> <maml:para>How to Add Criteria</maml:para> <maml:para>---------------------------</maml:para> <maml:para>1. To display the "Add criteria" menu button, in the upper right corner of the window, click the "Expand" arrow.</maml:para> <maml:para>2. Click the "Add Criteria" menu button.</maml:para> <maml:para>3. Click to select columns (properties). You can select one or many properties.</maml:para> <maml:para>4. When you are finished selecting properties, click the Add button.</maml:para> <maml:para>5. To cancel the additions, click Cancel.</maml:para> <maml:para>6. To add more criteria, click the Add Criteria button again.</maml:para> <maml:para>How to Edit a Criterion</maml:para> <maml:para>--------------------</maml:para> <maml:para>-- To change an operator, click the blue operator value, and then click to select a different</maml:para> <maml:para>operator from the drop-down list.</maml:para> <maml:para>-- To enter or change a value, type a value in the value box. If you enter a value that is not valid, a circular X icon appears. To remove it, change the value.</maml:para> <maml:para>-- To create an OR statement, add a criteria with the same property.</maml:para> <maml:para>How to Delete Criteria</maml:para> <maml:para>-------------------------</maml:para> <maml:para>-- To delete selected criteria, click the red X beside each criterion.</maml:para> <maml:para>-- To delete all criteria, click the "Clear All" button.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process | Out-GridView </dev:code> <dev:remarks> <maml:para>This command gets the processes running on the local computer and sends them to a grid view window.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$p = Get-Process PS C:\>$p | Out-GridView </dev:code> <dev:remarks> <maml:para>This command also gets the processes running on the local computer and sends them to a grid view window.</maml:para> <maml:para>The first command uses the Get-Process cmdlet to get the processes on the computer and then saves the process objects in the $p variable.</maml:para> <maml:para>The second command uses a pipeline operator to send the $p variable to Out-GridView.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process | Select-Object -Property Name, WorkingSet, PeakWorkingSet | Sort-Object -Property WorkingSet -Descending | Out-GridView </dev:code> <dev:remarks> <maml:para>This command displays a formatted table in a grid view window.</maml:para> <maml:para>It uses the Get-Process cmdlet to get the processes on the computer.</maml:para> <maml:para>Then, it uses a pipeline operator (|) to send the process objects to the Select-Object cmdlet. The command uses the Property parameter of Select-Object to select the Name, WorkingSet, and PeakWorkingSet properties to be displayed in the table.</maml:para> <maml:para>Another pipeline operator sends the filtered objects to the Sort-Object cmdlet, which sorts them in descending order by the value of the WorkingSet property.</maml:para> <maml:para>The final part of the command uses a pipeline operator (|) to send the formatted table to Out-GridView.</maml:para> <maml:para>You can now use the features of the grid view to search, sort, and filter the data.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>($a = Get-ChildItem -Path $pshome -Recurse) | Out-GridView </dev:code> <dev:remarks> <maml:para>This command saves its output in a variable and sends it to Out-GridView.</maml:para> <maml:para>The command uses the Get-ChildItem cmdlet to get the files in the Windows PowerShell installation directory and its subdirectories. The path to the installation directory is saved in the $pshome automatic variable.</maml:para> <maml:para>The command uses the assignment operator (=) to save the output in the $a variable and the pipeline operator (|) to send the output to Out-GridView.</maml:para> <maml:para>The parentheses in the command establish the order of operations. As a result, the output from the Get-ChildItem command is saved in the $a variable before it is sent to Out-GridView.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process -ComputerName Server01| ogv -Title "Processes - Server01" </dev:code> <dev:remarks> <maml:para>This command displays the processes that are running on the Server01 computer in a grid view window.</maml:para> <maml:para>The command uses "ogv," which is the built-in alias for the Out-GridView cmdlet, it uses the Title parameter to specify the window title.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture} | Out-GridView </dev:code> <dev:remarks> <maml:para>This example shows the correct format for sending data collected from remote computers to the Out-GridView cmdlet.</maml:para> <maml:para>The command uses the Invoke-Command cmdlet to run a Get-Culture command on three remote computers. It uses a pipeline operator to send the data that is returned to the Out-GridView cmdlet.</maml:para> <maml:para>Notice that the script block that contains the commands that are run remotely does not include the Out-GridView command. If it did, the command would fail when it tried to open a grid view window on each of the remote computers.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process | Out-GridView -PassThru | Export-Csv -Path .\ProcessLog.csv </dev:code> <dev:remarks> <maml:para>This command lets you select multiple processes from the Out-GridView window. The processes that you select are passed to the Export-Csv command and written to the ProcessLog.csv file.</maml:para> <maml:para>The command uses the PassThru parameter of Out-GridView, which lets you send multiple items down the pipeline. The PassThru parameter is equivalent to using the Multiple value of the OutputMode parameter.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Powershell.exe �Command "Get-Service | Out-GridView �Wait" </dev:code> <dev:remarks> <maml:para>This command shows how to use the Wait parameter of Out-GridView to create a Windows shortcut to the Out-GridView window. Without the Wait parameter, Windows PowerShell would exit as soon as the Out-GridView window opened, which would close the Out-GridView window almost immediately.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293997</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Out-Printer</command:name> <maml:description> <maml:para>Sends output to a printer.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Out</command:verb> <command:noun>Printer</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Out-Printer cmdlet sends output to the default printer or to an alternate printer, if one is specified.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Out-Printer</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="PrinterName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the alternate printer. The parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be sent to the printer. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be sent to the printer. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="PrinterName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the alternate printer. The parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Out-Printer.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Out-Printer does not return any objects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also refer to Out-Printer by its built-in alias, "lp". For more information, see about_Aliases.</maml:para> <maml:para>The cmdlets that contain the Out verb (the Out cmdlets) do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it.</maml:para> <maml:para>The Out cmdlets do not have parameters for names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For more information, see the examples.</maml:para> <maml:para>Out-Printer sends data, but it does not emit any output objects. If you pipe the output of Out-Printer to Get-Member, Get-Member reports that no objects have been specified.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-content $pshome\about_signing.help.txt | Out-Printer </dev:code> <dev:remarks> <maml:para>This command prints the content of the about_Signing Help topic to the default printer. This example shows you how to print a file, even though Out-Printer does not have a Path parameter.</maml:para> <maml:para>The command uses the Get-Content cmdlet to get the contents of the Help topic. The path includes $pshome, a built-in variable that stores the installation directory for Windows PowerShell. A pipeline operator (|) passes the results to Out-Printer, which sends it to the default printer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"Hello, World" | out-printer -name "\\Server01\Prt-6B Color" </dev:code> <dev:remarks> <maml:para>This command prints "Hello, World" to the "Prt-6B Color" printer on Server01. This command uses the Name parameter to specify the alternate printer. Because the parameter name is optional, you can omit it.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$h = get-help -full get-wmiobject PS C:\>out-printer -inputobject $h </dev:code> <dev:remarks> <maml:para>These commands print the full version of the Help topic for Get-WmiObject. The first command uses the Get-Help cmdlet to get the full version of the Help topic for Get-WmiObject and stores it in the $h variable. The second command sends the content to the default printer. It uses the InputObject parameter to pass the value of the $h variable to Out-Printer.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293998</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Default</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-File</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Null</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-String</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Out-String</command:name> <maml:description> <maml:para>Sends objects to the host as a series of strings.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Out</command:verb> <command:noun>String</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Out-String cmdlet converts the objects that Windows PowerShell manages into an array of strings. By default, Out-String accumulates the strings and returns them as a single string, but you can use the stream parameter to direct Out-String to return one string at a time. This cmdlet lets you search and manipulate string output as you would in traditional shells when object manipulation is less convenient.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Out-String</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be written to a string. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Stream</maml:name> <maml:description> <maml:para>Sends the strings for each object separately. By default, the strings for each object are accumulated and sent as a single string.</maml:para> <maml:para>To use the Stream parameter, type "-Stream" or its alias, "ost".</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If you omit this parameter, the width is determined by the characteristics of the host program. The default value for the Windows PowerShell console is 80 (characters).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be written to a string. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Stream</maml:name> <maml:description> <maml:para>Sends the strings for each object separately. By default, the strings for each object are accumulated and sent as a single string.</maml:para> <maml:para>To use the Stream parameter, type "-Stream" or its alias, "ost".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the number of characters in each line of output. Any additional characters are truncated, not wrapped. If you omit this parameter, the width is determined by the characteristics of the host program. The default value for the Windows PowerShell console is 80 (characters).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe objects to Out-String.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Out-String returns the string that it creates from the input object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The cmdlets that contain the Out verb (the Out cmdlets) do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. </maml:para> </maml:alert> <maml:alert> <maml:para>The Out cmdlets do not have parameters that take names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For more information, see the examples.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-content C:\test1\testfile2.txt | out-string </dev:code> <dev:remarks> <maml:para>This command sends the content of the Testfile2.txt file to the console as a single string. It uses the Get-Content cmdlet to get the content of the file. The pipeline operator (|) sends the content to Out-String, which sends the content to the console as a string.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> The first command uses the Get-Culture cmdlet to get the regional settings. The pipeline operator (|) sends the result to the Select-Object cmdlet, which selects all properties (*) of the culture object that Get-Culture returned. The command then stores the results in the $c variable. PS C:\>$c = Get-Culture | Select-Object * The second command uses the Out-String cmdlet to convert the CultureInfo object to a series of strings (one string for each property). It uses the InputObject parameter to pass the $c variable to Out-String. The Width parameter is set to 100 characters per line to prevent truncation. PS C:\>Out-String -InputObject $c -Width 100 </dev:code> <dev:remarks> <maml:para>These commands get the regional settings for the current user and convert the data to strings.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-alias | out-string -stream | select-string "Get-Command" </dev:code> <dev:remarks> <maml:para>This example demonstrates the difference between working with objects and working with strings. The command displays aliases that include the phrase "Get-Command". It uses the Get-Alias cmdlet to get a set of AliasInfo objects (one for each alias in the current session).</maml:para> <maml:para>The pipeline operator (|) sends the output of the Get-Alias cmdlet to the Out-String cmdlet, which converts the objects to a series of strings. It uses the Stream parameter of Out-String to send each string individually, instead of concatenating them into a single string. Another pipeline operator sends the strings to the Select-String cmdlet, which selects the strings that include "Get-Command" anywhere in the string. </maml:para> <maml:para>If you omit the Stream parameter, the command displays all of the aliases, because Select-String finds "Get-Command" in the single string that Out-String returns, and the formatter displays the string as a table.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=293999</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Default</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-File</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Null</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Printer</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Read-Host</command:name> <maml:description> <maml:para>Reads a line of input from the console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Read</command:verb> <command:noun>Host</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Read-Host cmdlet reads a line of input from the console. You can use it to prompt a user for input. Because you can save the input as a secure string, you can use this cmdlet to prompt users for secure data, such as passwords, as well as shared data.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Read-Host</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Prompt</maml:name> <maml:description> <maml:para>Specifies the text of the prompt. Type a string. If the string includes spaces, enclose it in quotation marks. Windows PowerShell appends a colon (:) to the text that you enter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AsSecureString</maml:name> <maml:description> <maml:para>Displays asterisks (*) in place of the characters that the user types as input.</maml:para> <maml:para>When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringr</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AsSecureString</maml:name> <maml:description> <maml:para>Displays asterisks (*) in place of the characters that the user types as input.</maml:para> <maml:para>When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreferencer</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreferencer</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Stringr</command:parameterValue> <dev:type> <maml:name>System.Stringr</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Prompt</maml:name> <maml:description> <maml:para>Specifies the text of the prompt. Type a string. If the string includes spaces, enclose it in quotation marks. Windows PowerShell appends a colon (:) to the text that you enter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String or System.Security.SecureString</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>If the AsSecureString parameter is used, Read-Host returns a SecureString. Otherwise, it returns a string.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$age = read-host "Please enter your age" </dev:code> <dev:remarks> <maml:para>This command displays the string "Please enter your age:" as a prompt. When a value is entered and the Enter key is pressed, the value is stored in the $age variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$pwd_secure_string = read-host "Enter a Password" -assecurestring </dev:code> <dev:remarks> <maml:para>This command displays the string "Enter a Password:" as a prompt. As a value is being entered, asterisks (*) appear on the console in place of the input. When the Enter key is pressed, the value is stored as a SecureString object in the $pwd_secure_string variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294000</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Host</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertFrom-SecureString</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Register-EngineEvent</command:name> <maml:description> <maml:para>Subscribes to events that are generated by the Windows PowerShell engine and by the New-Event cmdlet.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Register</command:verb> <command:noun>EngineEvent</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Register-EngineEvent cmdlet subscribes to events that are generated by the Windows PowerShell engine and the New-Event cmdlet. Use the SourceIdentifier parameter to specify the event.</maml:para> <maml:para>You can use this cmdlet to subscribe to the "Exiting" engine event and events generated by the New-Event cmdlet. These events are automatically added to your event queue in your session without subscribing. However, subscribing lets you forward the events, specify an action to respond to the events, and cancel the subscription.</maml:para> <maml:para>When the subscribed event is raised, it is added to the event queue in your session. To get events in the event queue, use the Get-Event cmdlet.</maml:para> <maml:para>When you subscribe to a event, an event subcriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Register-EngineEvent</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="101" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies the source identifier of the event to which you are subscribing. The source identifier must be unique in the current session. This parameter is required.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription.</maml:para> <maml:para>Supported EngineEvent values include PowerShell.Exiting, PowerShell.OnIdle, and PowerShell.OnScriptBlockInvoke.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="102" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Sends events for this subscription to the session on the local computer. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies additional data associated with the event. The value of this parameter appears in the MessageData property of the event object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Hides the event subscription. Add this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, add the Force parameter to the Get-EventSubscriber or Unregister-Event cmdlets.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="102" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Sends events for this subscription to the session on the local computer. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables (http://go.microsoft.com/fwlink/?LinkID=113212).</maml:para> <maml:para>When you specify an action, Register-EngineEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Int32</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies additional data associated with the event. The value of this parameter appears in the MessageData property of the event object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="101" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies the source identifier of the event to which you are subscribing. The source identifier must be unique in the current session. This parameter is required.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and of all event objects associated with this subscription.</maml:para> <maml:para>Supported EngineEvent values include PowerShell.Exiting, PowerShell.OnIdle, and PowerShell.OnScriptBlockInvoke.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Hides the event subscription. Add this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, add the Force parameter to the Get-EventSubscriber or Unregister-Event cmdlets.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to Register-EngineEvent.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.PSEventJob</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>If you use the Action parameter, Register-EngineEvent returns a System.Management.Automation.PSEventJob object. Otherwise, it does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = New-PSSession -ComputerName Server01, Server02 PS C:\>Invoke-Command -Session $s { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward } </dev:code> <dev:remarks> <maml:para>This command registers for a Windows PowerShell engine event on two remote computers.</maml:para> <maml:para>The first command creates a user-managed session ("PSSession") on each of the remote computers.</maml:para> <maml:para>The second command uses the Invoke-Command cmdlet to run the Register-EngineEvent command in the remote sessions.</maml:para> <maml:para>The Register-EngineEvent command uses the SourceIdentifier parameter to identify the event. It uses the Forward parameter to forward the events from the remote session to the local session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action { Get-History | Export-Clixml $home\history.clixml } </dev:code> <dev:remarks> <maml:para>This command shows how to run Register-EngineEvent to take a specific action when the PowerShell.Exiting event occurs. The SupportEvent parameter is added to hide the event subscription. When Windows PowerShell exits, in this case, the command history from the exiting session is exported in XML format to a file name and path in the user�s $home directory.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294001</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Job</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Receive-Job</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Job</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Job</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Register-ObjectEvent</command:name> <maml:description> <maml:para>Subscribes to the events that are generated by a Microsoft .NET Framework object.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Register</command:verb> <command:noun>ObjectEvent</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Register-ObjectEvent cmdlet subscribes to events that are generated by .NET Framework objects on the local computer or on a remote computer.</maml:para> <maml:para>When the subscribed event is raised, it is added to the event queue in your session. To get events in the event queue, use the Get-Event cmdlet.</maml:para> <maml:para>You can use the parameters of Register-ObjectEvent to specify property values of the events that can help you to identify the event in the queue. You can also use the Action parameter to specify actions to take when a subscribed event is raised and the Forward parameter to send remote events to the event queue in the local session.</maml:para> <maml:para>When you subscribe to an event, an event subcriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber cmdlet. To cancel the subscription, use the Unregister-Event cmdlet, which deletes the event subscriber from the session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Register-ObjectEvent</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the .NET Framework object that generates the events. Enter a variable that contains the object, or type a command or expression that gets the object. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="101" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that Windows PowerShell assigns.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subcriber object and of all event objects associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="102" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>EventName</maml:name> <maml:description> <maml:para>Specifies the event to which you are subscribing. Enter the event name. This parameter is required.</maml:para> <maml:para>The value of this parameter is not a name that you select for the event subscription. It is the name of an event that the .NET Framework object exposes. For example, the ManagementEventWatcher class has events named "EventArrived" and "Stopped." To find the event name of an event, use the Get-Member cmdlet.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Sends events for this subscription to a remote session. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="102" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands to handle the events. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces ( { } ) to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>EventName</maml:name> <maml:description> <maml:para>Specifies the event to which you are subscribing. Enter the event name. This parameter is required.</maml:para> <maml:para>The value of this parameter is not a name that you select for the event subscription. It is the name of an event that the .NET Framework object exposes. For example, the ManagementEventWatcher class has events named "EventArrived" and "Stopped." To find the event name of an event, use the Get-Member cmdlet.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Sends events for this subscription to a remote session. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the .NET Framework object that generates the events. Enter a variable that contains the object, or type a command or expression that gets the object. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the Action parameter can include the $Event, $EventSubscriber, $Sender, $EventArgs, and $Args automatic variables, which provide information about the event to the Action script block. For more information, see about_Automatic_Variables.</maml:para> <maml:para>When you specify an action, Register-ObjectEvent returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Int32</command:parameterValue> <dev:type> <maml:name>System.Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="101" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that Windows PowerShell assigns.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subcriber object and of all event objects associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and it should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the Get-EventSubscriber and Unregister-Event cmdlets.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe objects to Register-ObjectEvent.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSEventJob</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" PS C:\>$processWatcher = New-Object System.Management.ManagementEventWatcher $query PS C:\>register-objectEvent -inputObject $processWatcher -eventName "EventArrived" </dev:code> <dev:remarks> <maml:para>This example subscribes to events generated when a new process starts.</maml:para> <maml:para>The command uses the ManagementEventWatcher object to get EventArrived events. A query object specifies that the events are instance creation events for the Win32_Process class.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'" PS C:\>$processWatcher = New-Object System.Management.ManagementEventWatcher $query PS C:\>$action = { New-Event "PowerShell.ProcessCreated" -Sender $sender -EventArguments $EventArgs.NewEvent.TargetInstance } PS C:\>register-objectEvent -inputObject $processWatcher -eventName "EventArrived" -action $action Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 2 422cfe5a-65e... Running True New-Event "PowerShe... </dev:code> <dev:remarks> <maml:para>This example shows how to specify an action to respond to an event. When you specify an action, events that are raised are not added to the event queue. Instead, the action responds to the event.</maml:para> <maml:para>In this example, when an instance creation event is raised indicating that a new process is started, a new ProcessCreated event is raised.</maml:para> <maml:para>The action uses the $Sender and $EventArgs automatic variables which are populated only for event actions.</maml:para> <maml:para>The Register-ObjectEvent command returns a job object that represents the action, which runs as a background job. You can use the Job cmdlets, such as Get-Job and Receive-Job, to manage the background job.</maml:para> <maml:para>For more information, see about_Jobs.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$s = new-pssession -computername Server01, Server02 PS C:\>invoke-command -session $s -filepath ProcessCreationEvent.ps1 PS C:\>invoke-command -session $s { get-event }# ProcessCreationEvent.ps1function Enable-ProcessCreationEvent{ $query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", ` (New-Object TimeSpan 0,0,1), ` "TargetInstance isa 'Win32_Process'" $processWatcher = New-Object System.Management.ManagementEventWatcher $query $identifier = "WMI.ProcessCreated" Register-ObjectEvent -input $processWatcher -eventName "EventArrived" ` -sourceIdentifier $identifier -messageData "Test" -forward}EnableProcessCreationEvent </dev:code> <dev:remarks> <maml:para>This example shows how to subscribe to object events on remote computers.</maml:para> <maml:para>The first command creates PSSessions on two remote computers and saves them in the $s variable.</maml:para> <maml:para>The second command uses the FilePath parameter of the Invoke-Command cmdlet to run the ProcessCreationEvent.ps1 script in the each of the PSSessions in $s.</maml:para> <maml:para>The script includes a Register-ObjectEvent command that subscribes to instance creation events on the Win32_Process object through the ManagementEventWatcher object and its EventArrived event.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$timer = New-Object Timers.Timer PS C:\>$timer.Interval = 500 PS C:\>$job = Register-ObjectEvent -inputObject $timer -eventName Elapsed -sourceIdentifier Timer.Random -Action {$random = Get-Random -Min 0 -Max 100} PS C:\>$job.gettype().fullnameSystem.Management.Automation.PSEventJob PS C:\>$job | format-list -property * State : RunningModule : __DynamicModule_6b5cbe82-d634-41d1-ae5e-ad7fe8d57fe0 StatusMessage : HasMoreData : True Location : Command : $random = Get-Random -Min 0 -Max 100 JobStateInfo : Running Finished : System.Threading.ManualResetEvent InstanceId : 88944290-133d-4b44-8752-f901bd8012e2 Id : 1 Name : Timer.Random ChildJobs : {}... PS C:\>$timer.Enabled = $true PS C:\>& $job.module {$random}60 PS C:\>& $job.module {$random}47 </dev:code> <dev:remarks> <maml:para>This example shows how to use the dynamic module in the PSEventJob object that is created when you include an Action in a event registration.</maml:para> <maml:para>The first command uses the New-Object cmdlet to create a timer object. The second command sets the interval of the timer to 500 (milliseconds).</maml:para> <maml:para>The third command uses the Register-ObjectEvent cmdlet to register the Elapsed event of the timer object. The command includes an action that handles the event. Whenever the timer interval elapses, an event is raised and the commands in the action run. In this case, the Get-Random cmdlet generates a random number between 0 and 100 and saves it in the $random variable.</maml:para> <maml:para>When you use an Action parameter in a Register-ObjectEvent command, the command returns a PSEventJob object that represents the action. The command saves the job object in the $job variable.</maml:para> <maml:para>The PSEventJob object that the Register-ObjectEvent cmdlet returns is also available in the Action property of the event subscriber. For more information, see Get-EventSubscriber.</maml:para> <maml:para>The fourth command shows that the $job variable contains a PSEventJob object. The fifth command uses the Format-List cmdlet to display all of the properties of the PSEventJob object in a list.</maml:para> <maml:para>The PSEventJob has a Module property that contains a dynamic script module that implements the action.</maml:para> <maml:para>The sixth command enables the timer.</maml:para> <maml:para>The remaining commands use the call operator (&) to invoke the command in the module and display the value of the $random variable. You can use the call operator to invoke any command in a module, including commands that are not exported. In this case, the commands show the random number that is being generated when the Elapsed event occurs.</maml:para> <maml:para>For more information about modules, see about_Modules.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294002</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-Event</command:name> <maml:description> <maml:para>Deletes events from the event queue.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Remove</command:verb> <command:noun>Event</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Remove-Event cmdlet deletes events from the event queue in the current session.</maml:para> <maml:para>This cmdlet deletes only the events currently in the queue. To cancel event registrations or unsubscribe, use the Unregister-Event cmdlet.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-Event</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Deletes only the events with the specified source identifier. Wildcards are not permitted. An EventIdentifier or SourceIdentifier parameter is required in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Remove-Event</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>EventIdentifier</maml:name> <maml:description> <maml:para>Deletes only the event with the specified event identifier. An EventIdentifier or SourceIdentifier parameter is required in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>EventIdentifier</maml:name> <maml:description> <maml:para>Deletes only the event with the specified event identifier. An EventIdentifier or SourceIdentifier parameter is required in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Deletes only the events with the specified source identifier. Wildcards are not permitted. An EventIdentifier or SourceIdentifier parameter is required in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSEventArgs</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe events from Get-Event to Remove-Event.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>remove-event -sourceIdentifier "ProcessStarted" </dev:code> <dev:remarks> <maml:para>This command deletes events with a source identifier of "Process Started" from the event queue.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>remove-event -eventIdentifier 30 </dev:code> <dev:remarks> <maml:para>This command deletes the event with an event ID of 30 from the event queue.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-event | remove-event </dev:code> <dev:remarks> <maml:para>This command deletes all events from the event queue.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294003</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-PSBreakpoint</command:name> <maml:description> <maml:para>Deletes breakpoints from the current console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Remove</command:verb> <command:noun>PSBreakpoint</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Remove-PSBreakpoint cmdlet deletes a breakpoint. Enter a breakpoint object or a breakpoint ID.</maml:para> <maml:para>When you remove a breakpoint, the breakpoint object is no longer available or functional. If you have saved a breakpoint object in a variable, the reference still exists, but the breakpoint does not function.</maml:para> <maml:para>Remove-PSBreakpoint is one of several cmdlets designed for debugging Windows PowerShell scripts. For more information about the Windows PowerShell debugger, see about_Debuggers.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>Specifies the breakpoints to delete. Enter a variable that contains breakpoint objects or a command that gets breakpoint objects, such as a Get-PSBreakpoint command. You can also pipe breakpoint objects to Remove-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Breakpoint[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Remove-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Deletes breakpoints with the specified breakpoint IDs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>Specifies the breakpoints to delete. Enter a variable that contains breakpoint objects or a command that gets breakpoint objects, such as a Get-PSBreakpoint command. You can also pipe breakpoint objects to Remove-PSBreakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Breakpoint[]</command:parameterValue> <dev:type> <maml:name>Breakpoint[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Deletes breakpoints with the specified breakpoint IDs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.Breakpoint</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe breakpoint objects to Remove-PSBreakpoint.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-breakpoint | remove-breakpoint </dev:code> <dev:remarks> <maml:para>This command deletes all of the breakpoints in the current console.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$b = set-psbreakpoint -script sample.ps1 -variable Name PS C:\>$b | remove-psbreakpoint </dev:code> <dev:remarks> <maml:para>This command deletes a breakpoint.</maml:para> <maml:para>The first command uses the Set-PSBreakpoint cmdlet to create a breakpoint on the Name variable in the Sample.ps1 script. Then, it saves the breakpoint object in the $b variable.</maml:para> <maml:para>The second command uses the Remove-PSBreakpoint cmdlet to delete the new breakpoint. It uses a pipeline operator (|) to send the breakpoint object in the $b variable to the Remove-PSBreakpoint cmdlet.</maml:para> <maml:para>As a result of this command, if you run the script, it runs to completion without stopping. Also, the Get-PSBreakpoint cmdlet does not return this breakpoint.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>remove-psbreakpoint -id 2 </dev:code> <dev:remarks> <maml:para>This command deletes the breakpoint with breakpoint ID 2.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>function del-psb { get-psbreakpoint | remove-psbreakpoint } </dev:code> <dev:remarks> <maml:para>This simple function deletes all of the breakpoints in the current console. It uses the Get-PSBreakpoint cmdlet to get the breakpoints. Then, it uses a pipeline operator (|) to send the breakpoints to the Remove-PSBreakpoint cmdlet, which deletes them.</maml:para> <maml:para>As a result, you can type "del-psb" instead of the longer command.</maml:para> <maml:para>To save the function, add it to your Windows PowerShell profile.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294004</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Disable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSCallStack</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-TypeData</command:name> <maml:description> <maml:para>Deletes extended types from the current session</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Remove</command:verb> <command:noun>TypeData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Remove-TypeData cmdlet deletes extended type data from the current session. This cmdlet affects only the current session and sessions that are created in the current session.</maml:para> <maml:para>You can add properties and methods to objects in Windows PowerShell by defining them in Update-TypeData commands and Types.ps1xml files. Remove-TypeData deletes those extended properties and methods from the current session. Remove-TypeData does not delete the Types.ps1xml files or delete any extended type definitions from the Types.ps1xml files. For more information about Types.ps1xml files, see about_Types.ps1xml (http://go.microsoft.com/fwlink/?LinkID=113274).</maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-TypeData</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>TypeData</maml:name> <maml:description> <maml:para>Delete the specified type data from the session. This parameter is required. Enter a variable that contains TypeData objects (System.Management.Automation.Runspaces.TypeData) or a command that gets TypeData objects, such as a Get-TypeData command. You can also pipe TypeData objects to Remove-TypeData.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TypeData</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Remove-TypeData</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Deletes all extended type data for the specified types. For types in the System namespace, enter the short name. Otherwise, the full type name is required. Wildcards are not supported. </maml:para> <maml:para>You can pipe type names to Remove-TypeData. When you pipe an object to Remove-TypeData, Remove-TypeData gets the type name of the object and removes all type data for the object type.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Remove-TypeData</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Deletes from the session extended type data that is defined in the specified files. This parameter is required.</maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Deletes from the session extended type data that is defined in the specified files. This parameter is required.</maml:para> <maml:para>Enter the paths and file names of one or more Types.ps1xml files. Wildcards are not supported. If you omit the path, the default location is the current directory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>TypeData</maml:name> <maml:description> <maml:para>Delete the specified type data from the session. This parameter is required. Enter a variable that contains TypeData objects (System.Management.Automation.Runspaces.TypeData) or a command that gets TypeData objects, such as a Get-TypeData command. You can also pipe TypeData objects to Remove-TypeData.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TypeData</command:parameterValue> <dev:type> <maml:name>TypeData</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Deletes all extended type data for the specified types. For types in the System namespace, enter the short name. Otherwise, the full type name is required. Wildcards are not supported. </maml:para> <maml:para>You can pipe type names to Remove-TypeData. When you pipe an object to Remove-TypeData, Remove-TypeData gets the type name of the object and removes all type data for the object type.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.Runspaces.TypeData</maml:name> <maml:uri>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.runspaces.typedata(v=vs.85).aspx</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe TypeData object, such as the ones that the Get-TypeData cmdlet returns, to Remove-TypeData.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the type names to Remove-TypeData. When you pipe an object to Remove-TypeData, Remove-TypeData gets the type name of the object and removes all type data for the object type.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Remove-TypeData can remove only the extended type data in the current session. It cannot remove extended type data that is on the computer, but has not been added to the current session, such as extended types that are defined in modules that have not been imported into the current session.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Remove-TypeData -TypeName System.Array </dev:code> <dev:remarks> <maml:para>This command deletes from the session all type data for the System.Array type, including type data that was added by a Types.ps1xml file and dynamic type data that was added to the session by using the Update-TypeData cmdlet.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Get-TypeData cmdlet to get extended type data for the System.DateTime type.The output shows that a DateTime property has been added to all System.DateTime objects in Windows PowerShell. PS C:\>Get-TypeData System.DateTime TypeName Members -------- ------- System.DateTime {[DateTime, System.Management.Automation.Runspaces.ScriptPropertyData]} The second command uses the Get-Date cmdlet, which returns a System.DateTime object. The command uses dot notation to get the value of the DateTime property of the System.DateTime object that Get-Date returns. PS C:\>(Get-Date).DateTime Friday, January 20, 2012 9:01:00 PM The third command uses the Get-TypeData cmdlet to get all extended type data for the System.DateTime type and the Remove-TypeData cmdlet to delete the extended type data. PS C:\>Get-TypeData System.DateTime | Remove-TypeData The fourth command shows the effect of deleting the extended type data for the System.DateTime type. The command repeats the second command. However, because the System.DateTime property no longer exists, a command to get its value returns nothing. PS C:\>(Get-Date).DateTime PS C:\> </dev:code> <dev:remarks> <maml:para>This command shows the effect of removing extended type data from a session.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Module | Remove-TypeData </dev:code> <dev:remarks> <maml:para>This command removes all extended type data for module objects. When you pipe an object to Remove-TypeData, Remove-TypeData gets the name of the object type and removes all type data for all objects of that type.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 4</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Remove-TypeData -Path C:\WINDOWS\System32\WindowsPowerShell\v1.0\Modules\PSScheduledJob, C:\WINDOWS\System32\WindowsPowerShell\v1.0\Modules\PSWorkflow\PSWorkflow.types.ps1xml </dev:code> <dev:remarks> <maml:para>This command uses the Path parameter of the Remove-TypeData cmdlet to remove the extended types that are defined in the Types.ps1xml files that are added by the PSScheduledJob and PSWorkflow modules. This command does not affect dynamic type data that is added by using the Update-TypeData cmdlet. The command succeeds only when the modules have been imported into the current session.</maml:para> <maml:para>For more information about modules, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311).</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 5</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Invoke-Command -Session $s {Get-TypeData -TypeName *CIM* | Remove-TypeData} </dev:code> <dev:remarks> <maml:para>This command removes extended types from a remote session. The command uses the Invoke-Command cmdlet to remove extended type data for all CIM types in the sessions in the $s variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294005</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-TypeData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Update-TypeData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Types.ps1xml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-Variable</command:name> <maml:description> <maml:para>Deletes a variable and its value.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Remove</command:verb> <command:noun>Variable</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Remove-Variable cmdlet deletes a variable and its value from the scope in which it is defined, such as the current session. You cannot use this cmdlet to delete variables that are set as constants or those that are owned by the system.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-Variable</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the variable to be removed. The parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to remove a variable even if it is read-only. Even using the Force parameter, the cmdlet cannot remove a constant.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Deletes only the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to remove a variable even if it is read-only. Even using the Force parameter, the cmdlet cannot remove a constant.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Deletes only the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the variable to be removed. The parameter name ("Name") is optional.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSVariable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a variable object to Remove-Variable.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not return any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Changes affect only the current scope, such as a session. To delete a variable from all sessions, add a Remove-Variable command to your Windows PowerShell profile.</maml:para> <maml:para>You can also refer to RemoveVariable by its built-in alias, "rv". For more information, see about_Aliases.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>remove-variable Smp </dev:code> <dev:remarks> <maml:para>This command deletes the $Smp variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294006</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Profiles</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Select-Object</command:name> <maml:description> <maml:para>Selects objects or object properties.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Select</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Select-Object cmdlet selects specified properties of an object or set of objects. It can also select unique objects, a specified number of objects, or objects in a specified position in an array.</maml:para> <maml:para>To select objects from a collection, use the First, Last, Unique, Skip, and Index parameters. To select object properties, use the Property parameter. When you select properties, Select-Object returns new objects that have only the specified properties. </maml:para> <maml:para>Beginning in Windows PowerShell 3.0, Select-Object includes an optimization feature that prevents commands from creating and processing objects that are not used. When you include a Select-Object command with the First or Index parameters in a command pipeline, Windows PowerShell stops the command that generates the objects as soon as the selected number of objects is generated, even when the command that generates the objects appears before the Select-Object command in the pipeline. To turn off this optimizing behavior, use the Wait parameter.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Select-Object</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties to select. Wildcards are permitted. </maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ExcludeProperty</maml:name> <maml:description> <maml:para>Removes the specifies properties from the selection. Wildcards are permitted. This parameter is effective only when the command also includes the Property parameter. </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ExpandProperty</maml:name> <maml:description> <maml:para>Specifies a property to select, and indicates that an attempt should be made to expand that property. Wildcards are permitted in the property name. </maml:para> <maml:para>For example, if the specified property is an array, each value of the array is included in the output. If the property contains an object, the properties of that object are displayed in the output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies objects to send to the cmdlet through the pipeline. This parameter enables you to pipe objects to Select-Object.</maml:para> <maml:para>When you use the InputObject parameter with Select-Object, instead of piping command results to Select-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Select-Object to filter a collection of objects for those objects that have specific values in defined properties, you use Select-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Last</maml:name> <maml:description> <maml:para>Specifies the number of objects to select from the end of an array of input objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Unique</maml:name> <maml:description> <maml:para>Specifies that if a subset of the input objects has identical properties and values, only a single member of the subset will be selected.</maml:para> <maml:para>This parameter is case-sensitive. As a result, strings that differ only in character casing are considered to be unique.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Turns off optimization. Windows PowerShell runs commands in the order that they appear in the command pipeline and lets them generate all objects. By default, if you include a Select-Object command with the First or Index parameters in a command pipeline, Windows PowerShell stops the command that generates the objects as soon as the selected number of objects is generated.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-Object</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Index</maml:name> <maml:description> <maml:para>Selects objects from an array based on their index values. Enter the indexes in a comma-separated list.</maml:para> <maml:para>Indexes in an array begin with 0, where 0 represents the first value and (n-1) represents the last value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies objects to send to the cmdlet through the pipeline. This parameter enables you to pipe objects to Select-Object.</maml:para> <maml:para>When you use the InputObject parameter with Select-Object, instead of piping command results to Select-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Select-Object to filter a collection of objects for those objects that have specific values in defined properties, you use Select-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Unique</maml:name> <maml:description> <maml:para>Specifies that if a subset of the input objects has identical properties and values, only a single member of the subset will be selected.</maml:para> <maml:para>This parameter is case-sensitive. As a result, strings that differ only in character casing are considered to be unique.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Turns off optimization. Windows PowerShell runs commands in the order that they appear in the command pipeline and lets them generate all objects. By default, if you include a Select-Object command with the First or Index parameters in a command pipeline, Windows PowerShell stops the command that generates the objects as soon as the selected number of objects is generated.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-Object</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SkipLast</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Int32]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ExcludeProperty</maml:name> <maml:description> <maml:para>Removes the specifies properties from the selection. Wildcards are permitted. This parameter is effective only when the command also includes the Property parameter. </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ExpandProperty</maml:name> <maml:description> <maml:para>Specifies a property to select, and indicates that an attempt should be made to expand that property. Wildcards are permitted in the property name. </maml:para> <maml:para>For example, if the specified property is an array, each value of the array is included in the output. If the property contains an object, the properties of that object are displayed in the output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Index</maml:name> <maml:description> <maml:para>Selects objects from an array based on their index values. Enter the indexes in a comma-separated list.</maml:para> <maml:para>Indexes in an array begin with 0, where 0 represents the first value and (n-1) represents the last value.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies objects to send to the cmdlet through the pipeline. This parameter enables you to pipe objects to Select-Object.</maml:para> <maml:para>When you use the InputObject parameter with Select-Object, instead of piping command results to Select-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Select-Object to filter a collection of objects for those objects that have specific values in defined properties, you use Select-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Last</maml:name> <maml:description> <maml:para>Specifies the number of objects to select from the end of an array of input objects.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties to select. Wildcards are permitted. </maml:para> <maml:para>The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Name (or Label) <string></maml:para> <maml:para>-- Expression <string> or <script block></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SkipLast</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:</maml:para> <maml:para>-- Name or Label <string></maml:para> <maml:para>-- Expression <string> or <scriptblock></maml:para> <maml:para>For more information, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Int32]</command:parameterValue> <dev:type> <maml:name>System.Int32]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Unique</maml:name> <maml:description> <maml:para>Specifies that if a subset of the input objects has identical properties and values, only a single member of the subset will be selected.</maml:para> <maml:para>This parameter is case-sensitive. As a result, strings that differ only in character casing are considered to be unique.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Turns off optimization. Windows PowerShell runs commands in the order that they appear in the command pipeline and lets them generate all objects. By default, if you include a Select-Object command with the First or Index parameters in a command pipeline, Windows PowerShell stops the command that generates the objects as soon as the selected number of objects is generated.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object to Select-Object.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also refer to the Select-Object cmdlet by its built-in alias, "select". For more information, see about_Aliases.</maml:para> </maml:alert> <maml:alert> <maml:para>The optimization feature of Select-Object is available only for commands that write objects to the pipeline as they are processed. It has no effect on commands that buffer processed objects and write them as a collection. Writing objects immediately is a cmdlet design best practice. For more information, see "Write Single Records to the Pipeline" in "Strongly Encouraged Development Guidelines" at <maml:navigationLink><maml:linkText>http://go.microsoft.com/fwlink/?LinkId=223385</maml:linkText><maml:uri></maml:uri></maml:navigationLink></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process | Select-Object -Property ProcessName, Id, WS </dev:code> <dev:remarks> <maml:para>This command creates objects that have the Name, ID, and working set (WS) properties of process objects.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process Explorer | Select-Object �Property ProcessName -ExpandProperty Modules | Format-List ProcessName : 00THotkey Size : 256 Company : TOSHIBA Corporation FileVersion : 1, 0, 0, 27 ProductVersion : 6, 2, 0, 0 Description : THotkey Product : TOSHIBA THotkey ModuleName : 00THotkey.exe FileName : C:\WINDOWS\system32\00THotkey.exe BaseAddress : 4194304 </dev:code> <dev:remarks> <maml:para>This command gets information about the modules used by the processes on the computer. It uses Get-Process cmdlet to get the process on the computer. It uses the Select-Object cmdlet to create new objects with only the selected properties. The command uses the Property parameter of the Select-Object cmdlet to select the process names. Because the Modules property contains an ModuleProcess object that has many properties, the command uses the ExpandProperty parameter to get the properties of the objects in the Modules property of each process. The command uses the Format-List parameter to display the name and modules in of each process in a list.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Process | Sort-Object -Property WS | Select-Object -Last 5 Handles NPM(K) PM(K) WS(K) VS(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 2866 320 33432 45764 203 222.41 1292 svchost 577 17 23676 50516 265 50.58 4388 WINWORD 826 11 75448 76712 188 19.77 3780 Ps 1367 14 73152 88736 216 61.69 676 Ps 1612 44 66080 92780 380 900.59 6132 INFOPATH </dev:code> <dev:remarks> <maml:para>This command gets the five processes that are using the most memory. The Get-Process cmdlet gets the processes on the computer. The Sort-Object cmdlet sorts the processes according to memory (working set) usage, and the Select-Object cmdlet selects only the last five members of the resulting array of objects.</maml:para> <maml:para>The Wait parameter is not required in commands that include the Sort-Object cmdlet because Sort-Object processes all objects and then returns a collection. The Select-Object optimization is available only for commands that return objects individually as they are processed.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-process | Select-Object -Property ProcessName,@{Name="Start Day"; Expression = {$_.StartTime.DayOfWeek}} ProcessName StartDay ---- -------- alg Wednesday ati2evxx Wednesday ati2evxx Thursday ... </dev:code> <dev:remarks> <maml:para>This command gets the name and start day of the processes running on a computer.</maml:para> <maml:para>The command uses the Get-Process cmdlet to get the processes on the computer. It passes the processes to the Select-Object cmdlet, which creates objects that have only the ProcessName parameter and a calculated property named "Start Day." The "Start Day" property is added by using a hash table with Name and Expression keys. The value of the Expression key is a script blocks that gets the StartTime property of each process and the DayofWeek property of the StartTime.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"a","b","c","a","a","a" | Select-Object -Unique a b c </dev:code> <dev:remarks> <maml:para>This command uses the Unique parameter of Select-Object to get unique characters from an array of characters.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = Get-Eventlog -Log "Windows PowerShell" PS C:\>$a | select-object -index 0, ($a.count - 1) </dev:code> <dev:remarks> <maml:para>These commands gets the first (newest) and last (oldest) events in the Windows Powershell event log.</maml:para> <maml:para>The command uses the Get-EventLog cmdlet to get all events in the Windows PowerShell log. It saves them in the $a variable.</maml:para> <maml:para>The second command uses a pipeline operator (|) to send the events in $a to the Select-Object cmdlet. The Select-Object command uses the Index parameter to select events from the array of events in the $a variable. The index of the first event is 0. The index of the last event is the number of items in $a minus 1.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>New-PSSession -ComputerName (Get-Content Servers.txt | Select-Object -Skip 1) </dev:code> <dev:remarks> <maml:para>This command creates a new PSSession on each of the computers listed in the Servers.txt files, except for the first one. </maml:para> <maml:para>This command uses the Select-Object cmdlet to select all but the first computer in a list of computer names. The resulting list of computers is set as the value of the ComputerName parameter of the New-PSSession cmdlet.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-ChildItem *.txt -ReadOnly | Rename-Item -NewName {$_.BaseName + "-ro.txt"} -PassThru | Select-Object -First 5 -Wait </dev:code> <dev:remarks> <maml:para>This command adds a "-ro" suffix to the base names of text files that have the read-only attribute and then displays the first five files so the user can see a sample of the effect. </maml:para> <maml:para>The command uses the ReadOnly dynamic parameter of the Get-ChildItem for FileSystem cmdlet to get read-only files. It uses a pipeline operator (|) to send the files to the Rename-Item cmdlet, which renames the file. It uses the Passthru parameter of Rename-Item to send the renamed files to the Select-Object cmdlet, which selects the first 5 for display.</maml:para> <maml:para>The Wait parameter of Select-Object prevents Windows PowerShell from stopping the Get-ChildItem cmdlet after it gets the first five read-only text files. Without this parameter, only the first five read-only files would be renamed.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294007</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Group-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Sort-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Where-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Select-String</command:name> <maml:description> <maml:para>Finds text in strings and files.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Select</command:verb> <command:noun>String</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Select-String cmdlet searches for text and text patterns in input strings and files. You can use it like Grep in UNIX and Findstr in Windows. You can type "Select-String" or its alias, "sls".</maml:para> <maml:para>Select-String is based on lines of text. By default, Select-String finds the first match in each line and, for each match, it displays the file name, line number, and all text in the line containing the match. However, you can direct it to detect multiple matches per line, display text before and after the match, or display only a Boolean value (true or false) that indicates whether a match is found.</maml:para> <maml:para>Select-String uses regular expression matching, but it can also perform a simple match that searches the input for the text that you specify. </maml:para> <maml:para>Select-String can display all of the text matches or stop after the first match in each input file. It can also display all text that does not match the specified pattern. You can also specify that Select-String should expect a particular character encoding, such as when you are searching files of Unicode text.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Select-String</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Pattern</maml:name> <maml:description> <maml:para>Specifies the text to find. Type a string or regular expression. If you type a string, use the SimpleMatch parameter.</maml:para> <maml:para>To learn about regular expressions, see about_Regular_Expressions.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the files to be searched. Wildcards are permitted. The default location is the local directory.</maml:para> <maml:para>Specify files in the directory, such as "log1.txt", "*.doc", or "*.*". If you specify only a directory, the command fails.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllMatches</maml:name> <maml:description> <maml:para>Searches for more than one match in each line of text. Without this parameter, Select-String finds only the first match in each line of text.</maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Makes matches case-sensitive. By default, matches are not case-sensitive.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>Captures the specified number of lines before and after the line with the match. This allows you to view the match in context.</maml:para> <maml:para>If you enter one number as the value of this parameter, that number determines the number of lines captured before and after the match. If you enter two numbers as the value, the first number determines the number of lines before the match and the second number determines the number of lines after the match.</maml:para> <maml:para>In the default display, lines with a match are indicated by a right angle bracket (ASCII 62) in the first column of the display. Unmarked lines are the context.</maml:para> <maml:para>This parameter does not change the number of objects generated by Select-String. Select-String generates one MatchInfo (Microsoft.PowerShell.Commands.MatchInfo) object for each match. The context is stored as an array of strings in the Context property of the object.</maml:para> <maml:para>When you pipe the output of a Select-String command to another Select-String command, the receiving command searches only the text in the matched line (the value of the Line property of the MatchInfo object), not the text in the context lines. As a result, the Context parameter is not valid on the receiving Select-String command.</maml:para> <maml:para>When the context includes a match, the MatchInfo object for each match includes all of the context lines, but the overlapping lines appear only once in the display.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the character encoding that Select-String should assume when searching the file. The default is UTF8.</maml:para> <maml:para>Valid values are "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode", "Default", and "OEM". "Default" is the encoding of the system's current ANSI code page. "OEM" is the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf7</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf8</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf32</command:parameterValue> <command:parameterValue required="false" variableLength="false">ascii</command:parameterValue> <command:parameterValue required="false" variableLength="false">bigendianunicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">default</command:parameterValue> <command:parameterValue required="false" variableLength="false">oem</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Exclude the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Include only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>List</maml:name> <maml:description> <maml:para>Returns only the first match in each input file. By default, Select-String returns a MatchInfo object for each match it finds.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NotMatch</maml:name> <maml:description> <maml:para>Finds text that does not match the specified pattern.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Quiet</maml:name> <maml:description> <maml:para>Returns a Boolean value (true or false), instead of a MatchInfo object. The value is "true" if the pattern is found; otherwise, the value is "false".</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SimpleMatch</maml:name> <maml:description> <maml:para>Uses a simple match rather than a regular expression match. In a simple match, Select-String searches the input for the text in the Pattern parameter. It does not interpret the value of the Pattern parameter as a regular expression statement.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-String</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Pattern</maml:name> <maml:description> <maml:para>Specifies the text to find. Type a string or regular expression. If you type a string, use the SimpleMatch parameter.</maml:para> <maml:para>To learn about regular expressions, see about_Regular_Expressions.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllMatches</maml:name> <maml:description> <maml:para>Searches for more than one match in each line of text. Without this parameter, Select-String finds only the first match in each line of text.</maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Makes matches case-sensitive. By default, matches are not case-sensitive.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>Captures the specified number of lines before and after the line with the match. This allows you to view the match in context.</maml:para> <maml:para>If you enter one number as the value of this parameter, that number determines the number of lines captured before and after the match. If you enter two numbers as the value, the first number determines the number of lines before the match and the second number determines the number of lines after the match.</maml:para> <maml:para>In the default display, lines with a match are indicated by a right angle bracket (ASCII 62) in the first column of the display. Unmarked lines are the context.</maml:para> <maml:para>This parameter does not change the number of objects generated by Select-String. Select-String generates one MatchInfo (Microsoft.PowerShell.Commands.MatchInfo) object for each match. The context is stored as an array of strings in the Context property of the object.</maml:para> <maml:para>When you pipe the output of a Select-String command to another Select-String command, the receiving command searches only the text in the matched line (the value of the Line property of the MatchInfo object), not the text in the context lines. As a result, the Context parameter is not valid on the receiving Select-String command.</maml:para> <maml:para>When the context includes a match, the MatchInfo object for each match includes all of the context lines, but the overlapping lines appear only once in the display.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the character encoding that Select-String should assume when searching the file. The default is UTF8.</maml:para> <maml:para>Valid values are "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode", "Default", and "OEM". "Default" is the encoding of the system's current ANSI code page. "OEM" is the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf7</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf8</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf32</command:parameterValue> <command:parameterValue required="false" variableLength="false">ascii</command:parameterValue> <command:parameterValue required="false" variableLength="false">bigendianunicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">default</command:parameterValue> <command:parameterValue required="false" variableLength="false">oem</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Exclude the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Include only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>List</maml:name> <maml:description> <maml:para>Returns only the first match in each input file. By default, Select-String returns a MatchInfo object for each match it finds.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NotMatch</maml:name> <maml:description> <maml:para>Finds text that does not match the specified pattern.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Quiet</maml:name> <maml:description> <maml:para>Returns a Boolean value (true or false), instead of a MatchInfo object. The value is "true" if the pattern is found; otherwise, the value is "false".</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SimpleMatch</maml:name> <maml:description> <maml:para>Uses a simple match rather than a regular expression match. In a simple match, Select-String searches the input for the text in the Pattern parameter. It does not interpret the value of the Pattern parameter as a regular expression statement.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the text to be searched. Enter a variable that contains the text, or type a command or expression that gets the text.</maml:para> <maml:para>Using the InputObject parameter is not the same as piping strings to Select-String. The differences are as follows:</maml:para> <maml:para>-- When you pipe more than one string (a "collection") to Select-String, Select-String searches for the specified text in each string and returns each string that contains the search text.</maml:para> <maml:para>-- When you use the InputObject parameter to submit a collection of strings, Select-String treats the collection as a single combined string and returns the strings as a unit if it finds the search text in any string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-String</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Pattern</maml:name> <maml:description> <maml:para>Specifies the text to find. Type a string or regular expression. If you type a string, use the SimpleMatch parameter.</maml:para> <maml:para>To learn about regular expressions, see about_Regular_Expressions.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllMatches</maml:name> <maml:description> <maml:para>Searches for more than one match in each line of text. Without this parameter, Select-String finds only the first match in each line of text.</maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Makes matches case-sensitive. By default, matches are not case-sensitive.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>Captures the specified number of lines before and after the line with the match. This allows you to view the match in context.</maml:para> <maml:para>If you enter one number as the value of this parameter, that number determines the number of lines captured before and after the match. If you enter two numbers as the value, the first number determines the number of lines before the match and the second number determines the number of lines after the match.</maml:para> <maml:para>In the default display, lines with a match are indicated by a right angle bracket (ASCII 62) in the first column of the display. Unmarked lines are the context.</maml:para> <maml:para>This parameter does not change the number of objects generated by Select-String. Select-String generates one MatchInfo (Microsoft.PowerShell.Commands.MatchInfo) object for each match. The context is stored as an array of strings in the Context property of the object.</maml:para> <maml:para>When you pipe the output of a Select-String command to another Select-String command, the receiving command searches only the text in the matched line (the value of the Line property of the MatchInfo object), not the text in the context lines. As a result, the Context parameter is not valid on the receiving Select-String command.</maml:para> <maml:para>When the context includes a match, the MatchInfo object for each match includes all of the context lines, but the overlapping lines appear only once in the display.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the character encoding that Select-String should assume when searching the file. The default is UTF8.</maml:para> <maml:para>Valid values are "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode", "Default", and "OEM". "Default" is the encoding of the system's current ANSI code page. "OEM" is the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">unicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf7</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf8</command:parameterValue> <command:parameterValue required="false" variableLength="false">utf32</command:parameterValue> <command:parameterValue required="false" variableLength="false">ascii</command:parameterValue> <command:parameterValue required="false" variableLength="false">bigendianunicode</command:parameterValue> <command:parameterValue required="false" variableLength="false">default</command:parameterValue> <command:parameterValue required="false" variableLength="false">oem</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Exclude the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Include only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>List</maml:name> <maml:description> <maml:para>Returns only the first match in each input file. By default, Select-String returns a MatchInfo object for each match it finds.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NotMatch</maml:name> <maml:description> <maml:para>Finds text that does not match the specified pattern.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Quiet</maml:name> <maml:description> <maml:para>Returns a Boolean value (true or false), instead of a MatchInfo object. The value is "true" if the pattern is found; otherwise, the value is "false".</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SimpleMatch</maml:name> <maml:description> <maml:para>Uses a simple match rather than a regular expression match. In a simple match, Select-String searches the input for the text in the Pattern parameter. It does not interpret the value of the Pattern parameter as a regular expression statement.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to be searched. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>AllMatches</maml:name> <maml:description> <maml:para>Searches for more than one match in each line of text. Without this parameter, Select-String finds only the first match in each line of text.</maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Makes matches case-sensitive. By default, matches are not case-sensitive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Context</maml:name> <maml:description> <maml:para>Captures the specified number of lines before and after the line with the match. This allows you to view the match in context.</maml:para> <maml:para>If you enter one number as the value of this parameter, that number determines the number of lines captured before and after the match. If you enter two numbers as the value, the first number determines the number of lines before the match and the second number determines the number of lines after the match.</maml:para> <maml:para>In the default display, lines with a match are indicated by a right angle bracket (ASCII 62) in the first column of the display. Unmarked lines are the context.</maml:para> <maml:para>This parameter does not change the number of objects generated by Select-String. Select-String generates one MatchInfo (Microsoft.PowerShell.Commands.MatchInfo) object for each match. The context is stored as an array of strings in the Context property of the object.</maml:para> <maml:para>When you pipe the output of a Select-String command to another Select-String command, the receiving command searches only the text in the matched line (the value of the Line property of the MatchInfo object), not the text in the context lines. As a result, the Context parameter is not valid on the receiving Select-String command.</maml:para> <maml:para>When the context includes a match, the MatchInfo object for each match includes all of the context lines, but the overlapping lines appear only once in the display.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the character encoding that Select-String should assume when searching the file. The default is UTF8.</maml:para> <maml:para>Valid values are "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode", "Default", and "OEM". "Default" is the encoding of the system's current ANSI code page. "OEM" is the current original equipment manufacturer code page identifier for the operating system.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Exclude the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Include only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When Select-String finds more than one match in a line of text, it still emits only one MatchInfo object for the line, but the Matches property of the object contains all of the matches.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the text to be searched. Enter a variable that contains the text, or type a command or expression that gets the text.</maml:para> <maml:para>Using the InputObject parameter is not the same as piping strings to Select-String. The differences are as follows:</maml:para> <maml:para>-- When you pipe more than one string (a "collection") to Select-String, Select-String searches for the specified text in each string and returns each string that contains the search text.</maml:para> <maml:para>-- When you use the InputObject parameter to submit a collection of strings, Select-String treats the collection as a single combined string and returns the strings as a unit if it finds the search text in any string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>List</maml:name> <maml:description> <maml:para>Returns only the first match in each input file. By default, Select-String returns a MatchInfo object for each match it finds.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NotMatch</maml:name> <maml:description> <maml:para>Finds text that does not match the specified pattern.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to the files to be searched. Wildcards are permitted. The default location is the local directory.</maml:para> <maml:para>Specify files in the directory, such as "log1.txt", "*.doc", or "*.*". If you specify only a directory, the command fails.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Pattern</maml:name> <maml:description> <maml:para>Specifies the text to find. Type a string or regular expression. If you type a string, use the SimpleMatch parameter.</maml:para> <maml:para>To learn about regular expressions, see about_Regular_Expressions.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Quiet</maml:name> <maml:description> <maml:para>Returns a Boolean value (true or false), instead of a MatchInfo object. The value is "true" if the pattern is found; otherwise, the value is "false".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SimpleMatch</maml:name> <maml:description> <maml:para>Uses a simple match rather than a regular expression match. In a simple match, Select-String searches the input for the text in the Pattern parameter. It does not interpret the value of the Pattern parameter as a regular expression statement.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to be searched. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe any object that has a ToString method to Select-String.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.MatchInfo or System.Boolean</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>By default, the output is a set of MatchInfo objects, one for each match found. If you use the Quiet parameter, the output is a Boolean value indicating whether the pattern was found.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Select-String is like the Grep command in UNIX and the FindStr command in Windows.</maml:para> </maml:alert> <maml:alert> <maml:para>The "sst" alias for the Select-String cmdlet was introduced in Windows PowerShell 3.0.</maml:para> </maml:alert> <maml:alert> <maml:para>To use Select-String, type the text that you want to find as the value of the Pattern parameter.</maml:para> <maml:para>To specify the text to be searched, do the following:</maml:para> <maml:para>-- Type the text in a quoted string, and then pipe it to Select-String.</maml:para> <maml:para>-- Store a text string in a variable, and then specify the variable as the value of the InputObject parameter.</maml:para> <maml:para>-- If the text is stored in files, use the Path parameter to specify the path to the files.</maml:para> </maml:alert> <maml:alert> <maml:para>By default, Select-String interprets the value of the Pattern parameter as a regular expression. (For more information, see about_Regular_Expressions.) However, you can use the SimpleMatch parameter to override the regular expression matching. The SimpleMatch parameter finds instances of the value of the Pattern parameter in the input.</maml:para> </maml:alert> <maml:alert> <maml:para>The default output of Select-String is a MatchInfo object, which includes detailed information about the matches. The information in the object is useful when you are searching for text in files, because MatchInfo objects have properties such as Filename and Line. When the input is not from the file, the value of these parameters is "InputStream".</maml:para> </maml:alert> <maml:alert> <maml:para>If you do not need the information in the MatchInfo object, use the Quiet parameter, which returns a Boolean value (true or false) to indicate whether it found a match, instead of a MatchInfo object.</maml:para> </maml:alert> <maml:alert> <maml:para>When matching phrases, Select-String uses the current culture that is set for the system. To find the current culture, use the T:Microsoft.PowerShell.Commands.Get-Culture cmdlet.</maml:para> </maml:alert> <maml:alert> <maml:para>To find the properties of a MatchInfo object, type the following:</maml:para> <maml:para>select-string -path test.txt -pattern "test" | get-member | format-list -property *</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>"Hello","HELLO" | select-string -pattern "HELLO" -casesensitive </dev:code> <dev:remarks> <maml:para>This command performs a case-sensitive match of the text that was piped to the Select-String command.</maml:para> <maml:para>As a result, Select-String finds only "HELLO", because "Hello" does not match.</maml:para> <maml:para>Because each of the quoted strings is treated as a line, without the CaseSensitive parameter, Select-String would recognize both of the strings as matches.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>select-string -path *.xml -pattern "the the" </dev:code> <dev:remarks> <maml:para>This command searches through all files with the .xml file name extension in the current directory and displays the lines in those files that include the string "the the".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>select-string -path $pshome\en-US\*.txt -pattern "@" </dev:code> <dev:remarks> <maml:para>This command searches the Windows PowerShell conceptual Help files (about_*.txt) for information about the use of the at sign (@).</maml:para> <maml:para>To indicate the path, this command uses the value of the $pshome automatic variable, which stores the path to the Windows PowerShell installation directory. In this example, the command searches the en-US subdirectory, which contains the English (US) language Help files for Windows PowerShell.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>function search-help { $pshelp = "$pshome\es\about_*.txt", "$pshome\en-US\*dll-help.xml" select-string -path $pshelp -pattern $args[0] } </dev:code> <dev:remarks> <maml:para>This simple function uses the Select-String cmdlet to search the Windows PowerShell Help files for a particular string. In this example, the function searches the "en-US" subdirectory for English-United States language files.</maml:para> <maml:para>To use the function to find a string, such as "psdrive", type search-help psdrive.</maml:para> <maml:para>To use this function in any Windows PowerShell console, change the path to point to the Windows PowerShell Help files on your system, and then paste the function in your Windows PowerShell profile.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$events = get-eventlog -logname application -newest 100 PS C:\>$events | select-string -inputobject {$_.message} -pattern "failed" </dev:code> <dev:remarks> <maml:para>This example searches for the string "failed" in the 100 newest events in the Application log in Event Viewer.</maml:para> <maml:para>The first command uses the Get-EventLog cmdlet to get the 100 most recent events from the Application event log. Then it stores the events in the $events variable.</maml:para> <maml:para>The second command uses a pipeline operator (|) to send the objects in the $events variable to Select-String. It uses the InputObject parameter to represent the input from the $events variable. The value of the InputObject parameter is the Message property of each object as it travels through the pipeline. The current object is represented by the $_ symbol.</maml:para> <maml:para>As each event arrives in the pipeline, Select-String searches the value of its Message property for the "failed" string, and then displays any lines that include a match.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem c:\windows\system32\*.txt -recurse | select-string -pattern "Microsoft" -casesensitive </dev:code> <dev:remarks> <maml:para>This command examines all files in the subdirectories of C:\Windows\System32 with the .txt file name extension and searches for the string "Microsoft". The CaseSensitive parameter indicates that the "M" in "Microsoft" must be capitalized and that the rest of the characters must be lowercase for Select-String to find a match.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>select-string -path process.txt -pattern idle, svchost -notmatch </dev:code> <dev:remarks> <maml:para>This command finds lines of text in the Process.txt file that do not include the words "idle" or "svchost".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$f = select-string -path audit.log -pattern "logon failed" -context 2, 3 PS C:\>$f.count PS C:\>($f)[0].context | format-list </dev:code> <dev:remarks> <maml:para>The first command searches the Audit.Log file for the phrase "logon failed." It uses the Context parameter to capture 2 lines before the match and 3 lines after the match.</maml:para> <maml:para>The second command uses the Count property of object arrays to display the number of matches found, in this case, 2.</maml:para> <maml:para>The third command displays the lines stored in the Context property of the first MatchInfo object. It uses array notation to indicate the first match (match 0 in a zero-based array), and it uses the T:Microsoft.PowerShell.Commands.Format-List cmdlet to display the value of the Context property as a list.</maml:para> <maml:para>The output consists of two MatchInfo objects, one for each match detected. The context lines are stored in the Context property of the MatchInfo object.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 9 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> $a = get-childitem $pshome\en-us\about*.help.txt | select-string -pattern transcript PS C:\>$b = get-childitem $pshome\en-us\about*.help.txt | select-string -pattern transcript -allmatches PS C:\>$a C:\Windows\system32\WindowsPowerShell\v1.0\en-us\about_Pssnapins.help.txt:39: Start-Transcript and Stop-Transcript. PS C:\>$b C:\Windows\system32\WindowsPowerShell\v1.0\en-us\about_Pssnapins.help.txt:39: Start-Transcript and Stop-Transcript. PS C:\>> $a.matches Groups : {Transcript} Success : True Captures : {Transcript} Index : 13 Length : 10 Value : Transcript PS C:\>$b.matches Groups : {Transcript} Success : True Captures : {Transcript} Index : 13 Length : 10 Value : Transcript Groups : {Transcript} Success : True Captures : {Transcript} Index : 33 Length : 10 Value : Transcript </dev:code> <dev:remarks> <maml:para>This example demonstrates the effect of the AllMatches parameter of Select-String. AllMatches finds all pattern matches in a line, instead of just finding the first match in each line.</maml:para> <maml:para>The first command in the example searches the Windows PowerShell conceptual Help files ("about" Help) for instances of the word "transcript". The output of the first command is saved in the $a variable.</maml:para> <maml:para>The second command is identical, except that it uses the AllMatches parameter. The output of the second command is saved in the $b variable.</maml:para> <maml:para>When you display the value of the variables, the default display is identical, as shown in the example output.</maml:para> <maml:para>However, the fifth and sixth commands display the value of the Matches property of each object. The Matches property of the first command contains just one match (that is, one System.Text.RegularExpressions.Match object), whereas the Matches property of the second command contains objects for both of the matches in the line.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294008</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Comparison_Operators</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Regular_Expressions</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Select-Xml</command:name> <maml:description> <maml:para>Finds text in an XML string or document.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Select</command:verb> <command:noun>Xml</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Select-Xml cmdlet lets you use XPath queries to search for text in XML strings and documents. Enter an XPath query, and use the Content, Path, or Xml parameter to specify the XML to be searched.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Select-Xml</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>XPath</maml:name> <maml:description> <maml:para>Specifies an XPath search query. The query language is case-sensitive. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="2" aliases="Node"> <maml:name>Xml</maml:name> <maml:description> <maml:para>Specifies one or more XML nodes.</maml:para> <maml:para>An XML document will be processed as a collection of XML nodes. If you pipe an XML document to Select-Xml, each document node will be searched separately as it comes through the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">XmlNode[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a hash table of the namespaces used in the XML. Use the format @{<namespaceName> = <namespaceValue>}.</maml:para> <maml:para>When the XML uses the default namespace, which begins with "xmlns", use an arbitrary key for the namespace name. You cannot use "xmlns". In the XPath statement, prefix each node name with the namespace name and a colon, such as "//namespaceName:Node".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Hashtable</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-Xml</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>XPath</maml:name> <maml:description> <maml:para>Specifies an XPath search query. The query language is case-sensitive. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a hash table of the namespaces used in the XML. Use the format @{<namespaceName> = <namespaceValue>}.</maml:para> <maml:para>When the XML uses the default namespace, which begins with "xmlns", use an arbitrary key for the namespace name. You cannot use "xmlns". In the XPath statement, prefix each node name with the namespace name and a colon, such as "//namespaceName:Node".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Hashtable</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>Content</maml:name> <maml:description> <maml:para>Specifies a string that contains the XML to search. You can also pipe strings to Select-Xml.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-Xml</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>XPath</maml:name> <maml:description> <maml:para>Specifies an XPath search query. The query language is case-sensitive. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path and file names of the XML files to search. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a hash table of the namespaces used in the XML. Use the format @{<namespaceName> = <namespaceValue>}.</maml:para> <maml:para>When the XML uses the default namespace, which begins with "xmlns", use an arbitrary key for the namespace name. You cannot use "xmlns". In the XPath statement, prefix each node name with the namespace name and a colon, such as "//namespaceName:Node".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Hashtable</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Select-Xml</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>XPath</maml:name> <maml:description> <maml:para>Specifies an XPath search query. The query language is case-sensitive. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a hash table of the namespaces used in the XML. Use the format @{<namespaceName> = <namespaceValue>}.</maml:para> <maml:para>When the XML uses the default namespace, which begins with "xmlns", use an arbitrary key for the namespace name. You cannot use "xmlns". In the XPath statement, prefix each node name with the namespace name and a colon, such as "//namespaceName:Node".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Hashtable</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the paths and file names of the XML files to search. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>Content</maml:name> <maml:description> <maml:para>Specifies a string that contains the XML to search. You can also pipe strings to Select-Xml.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Namespace</maml:name> <maml:description> <maml:para>Specifies a hash table of the namespaces used in the XML. Use the format @{<namespaceName> = <namespaceValue>}.</maml:para> <maml:para>When the XML uses the default namespace, which begins with "xmlns", use an arbitrary key for the namespace name. You cannot use "xmlns". In the XPath statement, prefix each node name with the namespace name and a colon, such as "//namespaceName:Node".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path and file names of the XML files to search. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>XPath</maml:name> <maml:description> <maml:para>Specifies an XPath search query. The query language is case-sensitive. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true(ByValue,ByPropertyName)" position="2" aliases="Node"> <maml:name>Xml</maml:name> <maml:description> <maml:para>Specifies one or more XML nodes.</maml:para> <maml:para>An XML document will be processed as a collection of XML nodes. If you pipe an XML document to Select-Xml, each document node will be searched separately as it comes through the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">XmlNode[]</command:parameterValue> <dev:type> <maml:name>XmlNode[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the paths and file names of the XML files to search. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String or System.Xml.XmlNode</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a path or XML node to Select-Xml.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Microsoft.PowerShell.Commands.SelectXmlInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>XPath is a standard language that is designed to identify parts of an XML document. For more information about the XPath language, see the "Selection Filters" section of the "Event Selection" topic in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143608. And, see "XPath Reference" in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=143609.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> $Path = "$pshome\Types.ps1xml" PS C:\>$XPath = "/Types/Type/Members/AliasProperty" PS C:\>Select-Xml -Path $path -XPath $xpath | Select-Object -ExpandProperty Node Name ReferencedMemberName ---- -------------------- Count Length Name Key Name ServiceName RequiredServices ServicesDependedOn ProcessName Name Handles Handlecount VM VirtualSize WS WorkingSetSize Name ProcessName Handles Handlecount VM VirtualMemorySize WS WorkingSet PM PagedMemorySize NPM NonpagedSystemMemorySize Name __Class Namespace ModuleName </dev:code> <dev:remarks> <maml:para>This example gets the alias properties in the Types.ps1xml. (For information about this file, see about_Types.ps1xml.) </maml:para> <maml:para>The first command saves the path to the Types.ps1xml file in the $Path variable.</maml:para> <maml:para> The second command saves the XML path to the AliasProperty node in the $XPath variable. </maml:para> <maml:para>The third command uses the Select-Xml cmdlet to get the AliasProperty nodes that are identified by the XPath statement from the Types.ps1xml file. The command uses a pipeline operator to send the AliasProperty nodes to the Select-Object cmdlet. The ExpandProperty parameter expands the Node object and returns its Name and ReferencedMemberName properties.</maml:para> <maml:para>The result shows the Name and ReferencedMemberName of each alias property in the Types.ps1xml file. For example, there is a Count property that is an alias of the Length property.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>[xml]$Types = Get-Content $pshome\Types.ps1xml PS C:\>Select-Xml -Xml $Types -XPath "//MethodName" </dev:code> <dev:remarks> <maml:para>This example shows how to use the XML parameter to provide an XML document to the Select-Xml cmdlet.</maml:para> <maml:para>The first command uses the Get-Content cmdlet to get the content of the Types.ps1xml file and save it in the $Types variable. The "[xml]" casts the variable as an XML object.</maml:para> <maml:para>The second command uses the Select-Xml cmdlet to get the MethodName nodes in the Types.ps1xml file. The command uses the Xml parameter to specify the XML content in the $Types variable and the XPath parameter to specify the path to the MethodName node.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command creates a hash table that represents the XML namespace that is used for the help files and saves it in the $Namespace variable. PS C:\>$Namespace = @{command="http://schemas.microsoft.com/maml/dev/command/2004/10"; maml="http://schemas.microsoft.com/maml/2004/10"; dev="http://schemas.microsoft.com/maml/dev/2004/10"} The second command saves the path to the help files in the $Path variable.If there are no help files in this path on your computer, use the Update-Help cmdlet to download the help files. For more information about Updatable Help, see about_Updatable_Help ( http://go.microsoft.com/fwlink/?LinkId=235801). PS C:\>$Path = "$pshome\en-us\*dll-Help.xml" The third command uses the Select-Xml cmdlet to search the XML for cmdlet names by finding Command:Name element anywhere in the files. It saves the results in the $xml variable.Select-Xml returns a SelectXmlInfo object that has a Node property, which is a System.Xml.XmlElement object. The Node property has an InnerXML property, which contains the actual XML that is retrieved. PS C:\>$Xml = Select-Xml -Path $Path -Namespace $Namespace -XPath "//command:name" The fourth command sends the XML in the $Xml variable to the Format-Table cmdlet. The Format-Table command uses a calculated property to get the Node.InnerXML property of each object in the $Xml variable, trim the white space before and after the text, and display it in the table, along with the path to the source file. PS C:\>$Xml | Format-Table @{Label="Name"; Expression= {($_.node.innerxml).trim()}}, Path -AutoSize Name Path ---- ---- Export-Counter C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Get-Counter C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Get-WinEvent C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Import-Counter C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Add-Computer C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Management.dll-Help.xml Add-Content C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Management.dll-Help.xml Checkpoint-Computer C:\Windows\system32\WindowsPowerShell\v1.0\en-us\Microsoft.PowerShell.Commands.Management.dll-Help.xml ... </dev:code> <dev:remarks> <maml:para>This example shows how to use the Select-Xml cmdlet to search the Windows PowerShell XML-based cmdlet help files. In this example, we'll search for the cmdlet name that serves as a title for each help file and the path to the help file.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command saves a here-string that contains XML in the $xml variable. (For more information about here-strings, see about_Quoting_Rules.) PS C:\>$xml = @" <?xml version="1.0" encoding="utf-8"?> <Book> <projects> <project name="Book1" date="2009-01-20"> <editions> <edition language="English">En.Book1.com</edition> <edition language="German">Ge.Book1.Com</edition> <edition language="French">Fr.Book1.com</edition> <edition language="Polish">Pl.Book1.com</edition> </editions> </project> </projects> </Book> "@ The second command uses the Content parameter of Select-Xml to specify the XML in the $xml variable. PS C:\>Select-Xml -Content $xml -XPath "//edition" | foreach {$_.node.InnerXML} En.Book1.com Ge.Book1.Com Fr.Book1.com Pl.Book1.com The third command is equivalent to the second. It uses a pipeline operator (|) to send the XML in the $xml variable to the Select-Xml cmdlet. PS C:\>$xml | Select-Xml -XPath "//edition" | foreach {$_.node.InnerXML} En.Book1.com Ge.Book1.Com Fr.Book1.com Pl.Book1.com </dev:code> <dev:remarks> <maml:para>This example shows two different ways to send XML to the Select-Xml cmdlet.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command creates a hash table for the default namespace the that snippet XML files use and assigns it to the $SnippetNamespace variable. The hash table value is the XMLNS schema URI in the snippet XML. The hash table key name, "snip," is arbitrary. You can use any name that is not reserved, but you cannot use "xmlns." PS C:\>$SnippetNamespace = @{snip="http://schemas.microsoft.com/PowerShell/Snippets"} The second command uses the Select-Xml cmdlet to get the content of the Title element of each snippet. It uses the Path parameter to specify the Snippets directory and the Namespace parameter to specify the namespace in the $SnippetNamespace variable. The value of the XPath parameter is the "snip" namespace key, a colon (:), and the name of the Title element.The command uses a pipeline operator (|) to send each Node property that Select-Xml returns to the ForEach-Object cmdlet, which gets the title in the value of the InnerXml property of the node. PS C:\>Select-Xml �Path $home\Documents\WindowsPowerShell\Snippets �Namespace $SnippetNamespace �XPath "//snip:Title" | foreach {$_.Node.Innerxml} </dev:code> <dev:remarks> <maml:para>This example shows how to use the Select-Xml cmdlet with XML documents that use the default "xmlns" namespace. The example gets the titles of Windows PowerShell ISE user-created snippet files. For information about snippets, see New-IseSnippet.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294009</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ConvertTo-Xml</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Send-MailMessage</command:name> <maml:description> <maml:para>Sends an e-mail message.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Send</command:verb> <command:noun>MailMessage</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Send-MailMessage cmdlet sends an e-mail message from within Windows PowerShell.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Send-MailMessage</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>To</maml:name> <maml:description> <maml:para>Specifies the addresses to which the mail is sent. Enter names (optional) and the e-mail address, such as "Name <someone@example.com>". This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="sub"> <maml:name>Subject</maml:name> <maml:description> <maml:para>Specifies the subject of the e-mail message. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the body (content) of the e-mail message.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="4" aliases="ComputerName"> <maml:name>SmtpServer</maml:name> <maml:description> <maml:para>Specifies the name of the SMTP server that sends the e-mail message.</maml:para> <maml:para>The default value is the value of the $PSEmailServer preference variable. If the preference variable is not set and this parameter is omitted, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="PsPath"> <maml:name>Attachments</maml:name> <maml:description> <maml:para>Specifies the path and file names of files to be attached to the e-mail message. You can use this parameter or pipe the paths and file names to Send-MailMessage.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Bcc</maml:name> <maml:description> <maml:para>Specifies the e-mail addresses that receive a copy of the mail but are not listed as recipients of the message. Enter names (optional) and the e-mail address, such as "Name <someone@example.com>".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="BAH"> <maml:name>BodyAsHtml</maml:name> <maml:description> <maml:para>Indicates that the value of the Body parameter contains HTML.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Cc</maml:name> <maml:description> <maml:para>Specifies the e-mail addresses to which a carbon copy (CC) of the e-mail message is sent. Enter names (optional) and the e-mail address, such as "Name <someone@example.com>".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to perform this action. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one from the Get-Credential cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="DNO"> <maml:name>DeliveryNotificationOption</maml:name> <maml:description> <maml:para>Specifies the delivery notification options for the e-mail message. You can specify multiple values. "None" is the default value. The alias for this parameter is "dno".</maml:para> <maml:para>The delivery notifications are sent in an e-mail message to the address specified in the value of the To parameter.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: No notification.</maml:para> <maml:para>-- OnSuccess: Notify if the delivery is successful.</maml:para> <maml:para>-- OnFailure: Notify if the delivery is unsuccessful.</maml:para> <maml:para>-- Delay: Notify if the delivery is delayed.</maml:para> <maml:para>-- Never: Never notify.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">OnSuccess</command:parameterValue> <command:parameterValue required="false" variableLength="false">OnFailure</command:parameterValue> <command:parameterValue required="false" variableLength="false">Delay</command:parameterValue> <command:parameterValue required="false" variableLength="false">Never</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="BE"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding used for the body and subject. Valid values are ASCII, UTF8, UTF7, UTF32, Unicode, BigEndianUnicode, Default, and OEM. ASCII is the default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Encoding</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Port</maml:name> <maml:description> <maml:para>Specifies an alternate port on the SMTP server. The default value is 25, which is the default SMTP port. This parameter is available in Windows PowerShell 3.0 and newer releases.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Priority</maml:name> <maml:description> <maml:para>Specifies the priority of the e-mail message. The valid values for this are Normal, High, and Low. Normal is the default.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Normal</command:parameterValue> <command:parameterValue required="false" variableLength="false">Low</command:parameterValue> <command:parameterValue required="false" variableLength="false">High</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseSsl</maml:name> <maml:description> <maml:para>Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer to send mail. By default, SSL is not used.</maml:para> </maml:description> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>From</maml:name> <maml:description> <maml:para>Specifies the address from which the mail is sent. Enter a name (optional) and e-mail address, such as "Name <someone@example.com>". This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="PsPath"> <maml:name>Attachments</maml:name> <maml:description> <maml:para>Specifies the path and file names of files to be attached to the e-mail message. You can use this parameter or pipe the paths and file names to Send-MailMessage.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Bcc</maml:name> <maml:description> <maml:para>Specifies the e-mail addresses that receive a copy of the mail but are not listed as recipients of the message. Enter names (optional) and the e-mail address, such as "Name <someone@example.com>".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Body</maml:name> <maml:description> <maml:para>Specifies the body (content) of the e-mail message.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="BAH"> <maml:name>BodyAsHtml</maml:name> <maml:description> <maml:para>Indicates that the value of the Body parameter contains HTML.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Cc</maml:name> <maml:description> <maml:para>Specifies the e-mail addresses to which a carbon copy (CC) of the e-mail message is sent. Enter names (optional) and the e-mail address, such as "Name <someone@example.com>".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>Specifies a user account that has permission to perform this action. The default is the current user.</maml:para> <maml:para>Type a user name, such as "User01" or "Domain01\User01". Or, enter a PSCredential object, such as one from the Get-Credential cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="DNO"> <maml:name>DeliveryNotificationOption</maml:name> <maml:description> <maml:para>Specifies the delivery notification options for the e-mail message. You can specify multiple values. "None" is the default value. The alias for this parameter is "dno".</maml:para> <maml:para>The delivery notifications are sent in an e-mail message to the address specified in the value of the To parameter.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: No notification.</maml:para> <maml:para>-- OnSuccess: Notify if the delivery is successful.</maml:para> <maml:para>-- OnFailure: Notify if the delivery is unsuccessful.</maml:para> <maml:para>-- Delay: Notify if the delivery is delayed.</maml:para> <maml:para>-- Never: Never notify.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DeliveryNotificationOptions</command:parameterValue> <dev:type> <maml:name>DeliveryNotificationOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="BE"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>Specifies the encoding used for the body and subject. Valid values are ASCII, UTF8, UTF7, UTF32, Unicode, BigEndianUnicode, Default, and OEM. ASCII is the default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>From</maml:name> <maml:description> <maml:para>Specifies the address from which the mail is sent. Enter a name (optional) and e-mail address, such as "Name <someone@example.com>". This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Port</maml:name> <maml:description> <maml:para>Specifies an alternate port on the SMTP server. The default value is 25, which is the default SMTP port. This parameter is available in Windows PowerShell 3.0 and newer releases.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Priority</maml:name> <maml:description> <maml:para>Specifies the priority of the e-mail message. The valid values for this are Normal, High, and Low. Normal is the default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">MailPriority</command:parameterValue> <dev:type> <maml:name>MailPriority</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="4" aliases="ComputerName"> <maml:name>SmtpServer</maml:name> <maml:description> <maml:para>Specifies the name of the SMTP server that sends the e-mail message.</maml:para> <maml:para>The default value is the value of the $PSEmailServer preference variable. If the preference variable is not set and this parameter is omitted, the command fails.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="sub"> <maml:name>Subject</maml:name> <maml:description> <maml:para>Specifies the subject of the e-mail message. This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>To</maml:name> <maml:description> <maml:para>Specifies the addresses to which the mail is sent. Enter names (optional) and the e-mail address, such as "Name <someone@example.com>". This parameter is required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>UseSsl</maml:name> <maml:description> <maml:para>Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer to send mail. By default, SSL is not used.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the path and file names of attachments to Send-MailMessage.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>send-mailmessage -to "User01 <user01@example.com>" -from "User02 <user02@example.com>" -subject "Test mail" </dev:code> <dev:remarks> <maml:para>This command sends an e-mail message from User01 to User02.</maml:para> <maml:para>The mail message has a subject, which is required, but it does not have a body, which is optional. Also, because the SmtpServer parameter is not specified, Send-MailMessage uses the value of the $PSEmailServer preference variable for the SMTP server.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>send-mailmessage -from "User01 <user01@example.com>" -to "User02 <user02@example.com>", "User03 <user03@example.com>" -subject "Sending the Attachment" -body "Forgot to send the attachment. Sending now." -Attachments "data.csv" -priority High -dno onSuccess, onFailure -smtpServer smtp.fabrikam.com </dev:code> <dev:remarks> <maml:para>This command sends an e-mail message with an attachment from User01 to two other users.</maml:para> <maml:para>It specifies a priority value of "High" and requests a delivery notification by e-mail when the e-mail messages are delivered or when they fail.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>send-mailmessage -to "User01 <user01@example.com>" -from "ITGroup <itdept@example.com>" -cc "User02 <user02@example.com>" -bcc "ITMgr <itmgr@example.com>" -subject "Don't forget today's meeting!" -credential domain01\admin01 -useSSL </dev:code> <dev:remarks> <maml:para>This command sends an e-mail message from User01 to the ITGroup mailing list with a copy (CC) to User02 and a blind carbon copy (BCC) to the IT manager (ITMgr).</maml:para> <maml:para>The command uses the credentials of a domain administrator and the UseSSL parameter.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294010</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-Alias</command:name> <maml:description> <maml:para>Creates or changes an alias (alternate name) for a cmdlet or other command element in the current Windows PowerShell session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Set</command:verb> <command:noun>Alias</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Set-Alias cmdlet creates or changes an alias (alternate name) for a cmdlet or for a command element, such as a function, a script, a file, or other executable. You can also use Set-Alias to reassign a current alias to a new command, or to change any of the properties of an alias, such as its description. Unless you add the alias to the Windows PowerShell profile, the changes to an alias are lost when you exit the session or close Windows PowerShell.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-Alias</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the new alias. You can use any alphanumeric characters in an alias, but the first character cannot be a number.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the name of the cmdlet or command element that is being aliased.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies a description of the alias. You can type any string. If the description includes spaces, enclose it quotation marks.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to set a read-only alias. Use the Option parameter to create a read-only alias. The Force parameter cannot set a constant alias.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the alias.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed.</maml:para> <maml:para>-- Private: The alias is available only in the current scope.</maml:para> <maml:para>-- AllScope: The alias is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all aliases in the session, type "get-alias | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constant</command:parameterValue> <command:parameterValue required="false" variableLength="false">Private</command:parameterValue> <command:parameterValue required="false" variableLength="false">AllScope</command:parameterValue> <command:parameterValue required="false" variableLength="false">Unspecified</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies a description of the alias. You can type any string. If the description includes spaces, enclose it quotation marks.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to set a read-only alias. Use the Option parameter to create a read-only alias. The Force parameter cannot set a constant alias.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the new alias. You can use any alphanumeric characters in an alias, but the first character cannot be a number.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the alias.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed.</maml:para> <maml:para>-- Private: The alias is available only in the current scope.</maml:para> <maml:para>-- AllScope: The alias is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all aliases in the session, type "get-alias | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScopedItemOptions</command:parameterValue> <dev:type> <maml:name>ScopedItemOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the alias. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the name of the cmdlet or command element that is being aliased.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.AliasInfo</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Set-Alias generates a System.Management.Automation.AliasInfo object representing the alias. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>An alias is an alternate name or nickname for a cmdlet or command element. To run the cmdlet, you can use its full name or any valid alias. For more information, see about_Aliases.</maml:para> <maml:para>To create a new alias, use Set-Alias or New-Alias. To delete an alias, use Remove-Item.</maml:para> <maml:para>A cmdlet can have multiple aliases, but an alias can only be associated with one cmdlet at a time. If you use set-alias to associate the alias with a different cmdlet, it is no longer associated with the original cmdlet.</maml:para> <maml:para>You can create an alias for a cmdlet, but you cannot create an alias for a command with parameters and values. For example, you can create an alias for Set-Location, but you cannot create an alias for "Set-Location C:\Windows\System32". To create an alias for a command, create a function that includes the command, and then create an alias to the function.</maml:para> <maml:para>To save the aliases from a session and use them in a different session, add the set-alias command to your Windows PowerShell profile. Profiles do not exist by default. To create a profile in the path stored in the $profile variable, type "new-item -type file -force $profile". To see the value of the $profile variable, type "$profile".</maml:para> <maml:para>You can also save your aliases by using Export-Alias to copy the aliases from the session to a file, and then use Import-Alias to add them to the alias list for a new session.</maml:para> <maml:para>You can also refer to Set-Alias by its built-in alias, "sal". For more information, see about_Aliases.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-alias -name list -value get-childitem </dev:code> <dev:remarks> <maml:para>This command creates the alias "list" for the Get-ChildItem cmdlet. After you create the alias, you can use "list" in place of "Get-ChildItem" at the command line and in scripts.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-alias list get-location </dev:code> <dev:remarks> <maml:para>This command associates the alias "list" with the Get-Location cmdlet. If "list" is an alias for another cmdlet, this command changes its association so that it now is the alias only for Get-Location.</maml:para> <maml:para>This command uses the same format as the command in the previous example, but it omits the optional parameter names, -Name and -Value. When you omit parameter names, the values of those parameters must appear in the specified order in the command. In this case, the value of -Name ("list") must be the first parameter and the value of -Value ("get-location") must be the second parameter.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-alias scrub remove-item -option readonly -passthru | format-list </dev:code> <dev:remarks> <maml:para>This command associates the alias "scrub" with the Remove-Item cmdlet. It uses the "ReadOnly" option to prevent the alias from being deleted or assigned to another cmdlet.</maml:para> <maml:para>The PassThru parameter directs Windows PowerShell to pass an object that represents the new alias through the pipeline to the Format-List cmdlet. If the PassThru parameter were omitted, there would be no output from this cmdlet to display (in a list or otherwise).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Set-Alias np c:\windows\notepad.exe </dev:code> <dev:remarks> <maml:para>This command associates the alias, "np", with the executable file for Notepad. After the command completes, to open Notepad from the Windows PowerShell command line, just type "np".</maml:para> <maml:para>This example demonstrates that you can create aliases for executable files and elements other than cmdlets.</maml:para> <maml:para>To make the command more generic, you can use the "Windir" environment variable (${env:windir}) to represent the C\Windows directory. The generic version of the command is "set-alias np ${env:windir}\notepad.exe".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>function CD32 {set-location c:\windows\system32} PS C:\>set-alias go cd32 </dev:code> <dev:remarks> <maml:para>These commands show how to assign an alias to a command with parameters, or even to a pipeline of many commands.</maml:para> <maml:para>You can create an alias for a cmdlet, but you cannot create an alias for a command that consists of a cmdlet and its parameters. However, if you place the command in a function or a script, then you can create a useful function or script name and you can create one or more aliases for the function or script.</maml:para> <maml:para>In this example, the user wants to create an alias for the command "set-location c:\windows\system32", where "set-location" is a cmdlet and "C:\Windows\System32" is the value of the Path parameter.</maml:para> <maml:para>To do this, the first command creates a function called "CD32" that contains the Set-Location command.</maml:para> <maml:para>The second command creates the alias "go" for the CD32 function. Then, to run the Set-Location command, the user can type either "CD32" or "go".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294011</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Alias</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-Date</command:name> <maml:description> <maml:para>Changes the system time on the computer to a time that you specify.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Set</command:verb> <command:noun>Date</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Set-Date cmdlet changes the system date and time on the computer to a date and time that you specify. You can specify a new date and/or time by typing a string or by passing a DateTime or TimeSpan object to Set-Date. To specify a new date or time, use the Date parameter. To specify a change interval, use the Adjust parameter.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-Date</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Date</maml:name> <maml:description> <maml:para>Changes the date and time to the specified values. You can type a new date in the short date format and a time in the standard time format for your locale. Or, you can pass a Date-Time object from Get-Date.</maml:para> <maml:para>If you specify a date, but not a time, Set-Date changes the time to midnight on the specified date. If you specify only a time, it does not change the date.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">DateTime</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayHint</maml:name> <maml:description> <maml:para>Determines which elements of the date and time are displayed.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- date: displays only the date</maml:para> <maml:para>-- time: displays only the time</maml:para> <maml:para>-- datetime: displays the date and time</maml:para> <maml:para>This parameter affects only the display. It does not affect the DateTime object that Get-Date retrieves.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Date</command:parameterValue> <command:parameterValue required="false" variableLength="false">Time</command:parameterValue> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-Date</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByPropertyName)" position="1" aliases="none"> <maml:name>Adjust</maml:name> <maml:description> <maml:para>Adds or subtracts the specified value from the current date and time. You can type an adjustment in standard date and time format for your locale or use the Adjust parameter to pass a TimeSpan object from New-TimeSpan to Set-Date.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TimeSpan</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayHint</maml:name> <maml:description> <maml:para>Determines which elements of the date and time are displayed.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- date: displays only the date</maml:para> <maml:para>-- time: displays only the time</maml:para> <maml:para>-- datetime: displays the date and time</maml:para> <maml:para>This parameter affects only the display. It does not affect the DateTime object that Get-Date retrieves.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Date</command:parameterValue> <command:parameterValue required="false" variableLength="false">Time</command:parameterValue> <command:parameterValue required="false" variableLength="false">DateTime</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByPropertyName)" position="1" aliases="none"> <maml:name>Adjust</maml:name> <maml:description> <maml:para>Adds or subtracts the specified value from the current date and time. You can type an adjustment in standard date and time format for your locale or use the Adjust parameter to pass a TimeSpan object from New-TimeSpan to Set-Date.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TimeSpan</command:parameterValue> <dev:type> <maml:name>TimeSpan</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="True (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Date</maml:name> <maml:description> <maml:para>Changes the date and time to the specified values. You can type a new date in the short date format and a time in the standard time format for your locale. Or, you can pass a Date-Time object from Get-Date.</maml:para> <maml:para>If you specify a date, but not a time, Set-Date changes the time to midnight on the specified date. If you specify only a time, it does not change the date.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">DateTime</command:parameterValue> <dev:type> <maml:name>DateTime</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DisplayHint</maml:name> <maml:description> <maml:para>Determines which elements of the date and time are displayed.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- date: displays only the date</maml:para> <maml:para>-- time: displays only the time</maml:para> <maml:para>-- datetime: displays the date and time</maml:para> <maml:para>This parameter affects only the display. It does not affect the DateTime object that Get-Date retrieves.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">DisplayHintType</command:parameterValue> <dev:type> <maml:name>DisplayHintType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.DateTime</maml:name> <maml:uri>http://go.microsoft.com/fwlink/?LinkID=201522</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a date to Set-Date.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.DateTime</maml:name> <maml:uri>http://go.microsoft.com/fwlink/?LinkID=201522</maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Set-Date returns an object that represents the date that it set.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Use this cmdlet cautiously. Changing the date and time on the computer. The change might prevent the computer from receiving system-wide events and updates that are triggered by a date or time. Use the -WhatIf and -Confirm parameters to avoid errors.</maml:para> <maml:para>You can use standard .NET methods with the DateTime and TimeSpan objects used with Set-Date, such as AddDays, AddMonths and FromFileTime. For more information, see "DateTime Methods" and "TimeSpan Methods."</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Set-Date -Date (Get-Date).AddDays(3) </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command adds three days to the current system date. It does not affect the time. The command uses the Date parameter to specify the date. It uses the Get-Date cmdlet to get the current date and time and applies the AddDays .NET method for DateTime objects with a value of 3 (days).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-date -adjust -0:10:0 -displayHint time </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>This command sets the current system time back by 10 minutes. It uses the Adjust parameter to specify an interval of change and the time change (minus ten minutes) in standard time format for the locale. The DisplayHint parameter tells Windows PowerShell to display only the time, but it does not affect the DateTime object that Set-Date returns.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$t = get-date PS C:\>set-date -date $t </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>These commands change the system date and time on the computer to the date and time saved in the variable $t. The first command gets the date and stores it in $t. The second command uses the Date parameter to pass the DateTime object in $t to the Set-Date cmdlet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$90mins = new-timespan -minutes 90 PS C:\>set-date -adjust $90mins </dev:code> <dev:remarks> <maml:para>Description</maml:para> <maml:para>-----------</maml:para> <maml:para>These commands advance the system time on the local computer by 90 minutes. The first command uses the New-Timespan cmdlet to create a TimeSpan object with a 90-minute interval, and then it saves the TimeSpan object in the $90mins variable. The second command uses the Adjust parameter of Set-Date to adjust the date by the value of the TimeSpan object in the $90mins variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294012</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Date</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-TimeSpan</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-PSBreakpoint</command:name> <maml:description> <maml:para>Sets a breakpoint on a line, command, or variable.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Set</command:verb> <command:noun>PSBreakpoint</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Set-PSBreakpoint cmdlet sets a breakpoint in a script or in any command run in the current session. You can use Set-PSBreakpoint to set a breakpoint before executing a script or running a command, or during debugging, when stopped at another breakpoint.</maml:para> <maml:para>Note: Set-PSBreakpoint cannot set a breakpoint on a remote computer. To debug a script on a remote computer, copy the script to the local computer and then debug it locally.</maml:para> <maml:para>Each Set-PSBreakpoint command creates one of the following three types of breakpoints:</maml:para> <maml:para>-- Line breakpoint: Sets breakpoints at particular line and column coordinates.</maml:para> <maml:para>-- Command breakpoint: Sets breakpoints on commands and functions.</maml:para> <maml:para>-- Variable breakpoint: Sets breakpoints on variables.</maml:para> <maml:para>You can set a breakpoint on multiple lines, commands, or variables in a single Set-PSBreakpoint command, but each Set-PSBreakpoint command sets only one type of breakpoint.</maml:para> <maml:para>At a breakpoint, Windows PowerShell temporarily stops executing and gives control to the debugger. The command prompt changes to "DBG>", and a set of debugger commands become available for use. However, you can use the Action parameter to specify an alternate response, such as conditions for the breakpoint or instructions to perform additional tasks such as logging or diagnostics.</maml:para> <maml:para>The Set-PSBreakpoint cmdlet is one of several cmdlets designed for debugging Windows PowerShell scripts. For more information about the Windows PowerShell debugger, see about_Debuggers.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-PSBreakpoint</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Sets a breakpoint in each of the specified script files. Enter the paths and file names of one or more script files. If the files are in the current directory, you can omit the path. Wildcards are permitted.</maml:para> <maml:para>By default, variable breakpoints and command breakpoints are set on any command that runs in the current session. This parameter is required only when setting a line breakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Line</maml:name> <maml:description> <maml:para>Sets a line breakpoint in a script. Enter one or more line numbers, separated by commas. Windows PowerShell stops immediately before executing the statement that begins on each of the specified lines.</maml:para> <maml:para>Lines are counted from the top left margin of the script file beginning with line number 1 (not 0). If you specify a blank line, execution stops before the next non-blank line. If the line is out of range, the breakpoint is never hit.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Column</maml:name> <maml:description> <maml:para>Specifies the column number of the column in the script file on which execution stops. Enter only one column number. The default is column 1.</maml:para> <maml:para>The Column value is used with the value of the Line parameter to specify the breakpoint. If the Line parameter specifies multiple lines, the Column parameter sets a breakpoint at the specified column on each of the specified lines. Windows PowerShell stops executing before the statement or expression that includes the character at the specified line and column position.</maml:para> <maml:para>Columns are counted from the top left margin beginning with column number 1 (not 0). If you specify a column that does not exist in the script, an error is not declared, but the breakpoint is never executed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands that run at each breakpoint instead of breaking. Enter a script block that contains the commands. You can use this parameter to set conditional breakpoints or to perform other tasks, such as testing or logging.</maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-PSBreakpoint</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Sets a breakpoint in each of the specified script files. Enter the paths and file names of one or more script files. If the files are in the current directory, you can omit the path. Wildcards are permitted.</maml:para> <maml:para>By default, variable breakpoints and command breakpoints are set on any command that runs in the current session. This parameter is required only when setting a line breakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands that run at each breakpoint instead of breaking. Enter a script block that contains the commands. You can use this parameter to set conditional breakpoints or to perform other tasks, such as testing or logging.</maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="C"> <maml:name>Command</maml:name> <maml:description> <maml:para>Sets a command breakpoint. Enter cmdlet names, such as "Get-Process" or function names. Wildcards are permitted.</maml:para> <maml:para>Execution stops just before each instance of each command is executed. If the command is a function, execution stops each time the function is called and at each BEGIN, PROCESS, and END section.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-PSBreakpoint</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Sets a breakpoint in each of the specified script files. Enter the paths and file names of one or more script files. If the files are in the current directory, you can omit the path. Wildcards are permitted.</maml:para> <maml:para>By default, variable breakpoints and command breakpoints are set on any command that runs in the current session. This parameter is required only when setting a line breakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands that run at each breakpoint instead of breaking. Enter a script block that contains the commands. You can use this parameter to set conditional breakpoints or to perform other tasks, such as testing or logging.</maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Mode</maml:name> <maml:description> <maml:para>Determines the mode of access that triggers variable breakpoints. The default is Write.</maml:para> <maml:para>This parameter is valid only when the Variable parameter is used in the command. The mode applies to all breakpoints set in the command.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Write: Stops execution immediately before a new value is written to the variable.</maml:para> <maml:para>-- Read: Stops execution when the variable is read, that is, when its value is accessed, either to be assigned, displayed, or used. In read mode, execution does not stop when the value of the variable changes.</maml:para> <maml:para>-- ReadWrite: Stops execution when the variable is read or written.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Read</command:parameterValue> <command:parameterValue required="false" variableLength="false">Write</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadWrite</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="V"> <maml:name>Variable</maml:name> <maml:description> <maml:para>Sets a variable breakpoint. Enter a comma-separated list of variables without dollar signs ($).</maml:para> <maml:para>Use the Mode parameters to determine the mode of access that triggers the breakpoints. The default mode, Write, stops execution just before a new value is written to the variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies commands that run at each breakpoint instead of breaking. Enter a script block that contains the commands. You can use this parameter to set conditional breakpoints or to perform other tasks, such as testing or logging.</maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Column</maml:name> <maml:description> <maml:para>Specifies the column number of the column in the script file on which execution stops. Enter only one column number. The default is column 1.</maml:para> <maml:para>The Column value is used with the value of the Line parameter to specify the breakpoint. If the Line parameter specifies multiple lines, the Column parameter sets a breakpoint at the specified column on each of the specified lines. Windows PowerShell stops executing before the statement or expression that includes the character at the specified line and column position.</maml:para> <maml:para>Columns are counted from the top left margin beginning with column number 1 (not 0). If you specify a column that does not exist in the script, an error is not declared, but the breakpoint is never executed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="C"> <maml:name>Command</maml:name> <maml:description> <maml:para>Sets a command breakpoint. Enter cmdlet names, such as "Get-Process" or function names. Wildcards are permitted.</maml:para> <maml:para>Execution stops just before each instance of each command is executed. If the command is a function, execution stops each time the function is called and at each BEGIN, PROCESS, and END section.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>If this parameter is omitted, or no action is specified, execution stops at the breakpoint, and the debugger starts.</maml:para> <maml:para>When the Action parameter is used, the Action script block runs at each breakpoint. Execution does not stop unless the script block includes the Break keyword. If you use the Continue keyword in the script block, execution resumes until the next breakpoint.</maml:para> <maml:para>For more information, see about_Script_Blocks, about_Break, and about_Continue.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Line</maml:name> <maml:description> <maml:para>Sets a line breakpoint in a script. Enter one or more line numbers, separated by commas. Windows PowerShell stops immediately before executing the statement that begins on each of the specified lines.</maml:para> <maml:para>Lines are counted from the top left margin of the script file beginning with line number 1 (not 0). If you specify a blank line, execution stops before the next non-blank line. If the line is out of range, the breakpoint is never hit.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Int32[]</command:parameterValue> <dev:type> <maml:name>Int32[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Mode</maml:name> <maml:description> <maml:para>Determines the mode of access that triggers variable breakpoints. The default is Write.</maml:para> <maml:para>This parameter is valid only when the Variable parameter is used in the command. The mode applies to all breakpoints set in the command.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Write: Stops execution immediately before a new value is written to the variable.</maml:para> <maml:para>-- Read: Stops execution when the variable is read, that is, when its value is accessed, either to be assigned, displayed, or used. In read mode, execution does not stop when the value of the variable changes.</maml:para> <maml:para>-- ReadWrite: Stops execution when the variable is read or written.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">VariableAccessMode</command:parameterValue> <dev:type> <maml:name>VariableAccessMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Script</maml:name> <maml:description> <maml:para>Sets a breakpoint in each of the specified script files. Enter the paths and file names of one or more script files. If the files are in the current directory, you can omit the path. Wildcards are permitted.</maml:para> <maml:para>By default, variable breakpoints and command breakpoints are set on any command that runs in the current session. This parameter is required only when setting a line breakpoint.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="V"> <maml:name>Variable</maml:name> <maml:description> <maml:para>Sets a variable breakpoint. Enter a comma-separated list of variables without dollar signs ($).</maml:para> <maml:para>Use the Mode parameters to determine the mode of access that triggers the breakpoints. The default mode, Write, stops execution just before a new value is written to the variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to Set-PSBreakpoint.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Breakpoint object (System.Management.Automation.LineBreakpoint, System.Management.Automation.VariableBreakpoint, System.Management.Automation.CommandBreakpoint)</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Set-PSBreakpoint returns an object that represents each breakpoint that it sets.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Set-PSBreakpoint cannot set a breakpoint on a remote computer. To debug a script on a remote computer, copy the script to the local computer and then debug it locally.</maml:para> <maml:para>When you set a breakpoint on more than one line, command, or variable, Set-PSBreakpoint generates a breakpoint object for each entry.</maml:para> <maml:para>When setting a breakpoint on a function or variable at the command prompt, you can set the breakpoint before or after you create the function or variable.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -script sample.ps1 -line 5 Column : 0 Line : 5 Action : Enabled : True HitCount : 0 Id : 0 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 </dev:code> <dev:remarks> <maml:para>This command sets a breakpoint at line 5 in the Sample.ps1 script. As a result, when the script runs, execution stops immediately before line 5 would execute.</maml:para> <maml:para>When you set a new breakpoint by line number, the Set-PSBreakpoint cmdlet generates a line breakpoint object (System.Management.Automation.LineBreakpoint) that includes the breakpoint ID and hit count, as shown in the following sample output.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -command Increment -script sample.ps1 Command : Increment Action : Enabled : True HitCount : 0 Id : 1 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 </dev:code> <dev:remarks> <maml:para>This command creates a command breakpoint on the Increment function in the Sample.ps1 cmdlet. The script stops executing immediately before each call to the specified function.</maml:para> <maml:para>The result is a command breakpoint object. Before the script runs, the value of the HitCount property is 0.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -script sample.ps1 -variable Server -Mode ReadWrite </dev:code> <dev:remarks> <maml:para>This command sets a breakpoint on the Server variable in the Sample.ps1 script. It uses the Mode parameter with a value of ReadWrite to stop execution when the value of the variable is read and just before the value changes.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -script Sample.ps1 -command "write*" </dev:code> <dev:remarks> <maml:para>This command sets a breakpoint on every command in the Sample.ps1 script that begins with "write", such as "write-host".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -script test.ps1 -command DiskTest ` -action { if ($disk -gt 2) { break } } </dev:code> <dev:remarks> <maml:para>This command stops execution at the DiskTest function in the Test.ps1 script only when the value of the $disk variable is greater than 2.</maml:para> <maml:para>It uses the Set-PSBreakpoint cmdlet to set a command breakpoint on the DiskTest function. The value of the action is a script block that tests the value of the $disk variable in the function.</maml:para> <maml:para>The action uses the BREAK keyword to stop execution if the condition is met. The alternative (and the default) is CONTINUE.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -command checklog Id : 0 Command : checkkog Enabled : True HitCount : 0 Action : PS C:\>function CheckLog { >> get-eventlog -log Application | >> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")} >>} >> PS C:\>Checklog DEBUG: Hit breakpoint(s) DEBUG: Function breakpoint on 'prompt:Checklog' PS C:\>>> </dev:code> <dev:remarks> <maml:para>This command sets a breakpoint on the CheckLog function. Because the command does not specify a script, the breakpoint is set on anything that runs in the current session. The debugger breaks when the function is called, not when it is declared.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-psbreakpoint -script sample.ps1 -line 1, 14, 19 -column 2 -action {&(log.ps1)} Column : 2 Line : 1 Action : Enabled : True HitCount : 0 Id : 6 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 Column : 2 Line : 14 Action : Enabled : True HitCount : 0 Id : 7 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 Column : 2 Line : 19 Action : Enabled : True HitCount : 0 Id : 8 Script : C:\ps-test\sample.ps1 ScriptName : C:\ps-test\sample.ps1 </dev:code> <dev:remarks> <maml:para>This command sets three line breakpoints in the Sample.ps1 script. It sets one breakpoint at column 2 on each of the lines specified in the script. The action specified in the Action parameter applies to all breakpoints.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294013</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Disable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-PSCallStack</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-PSBreakpoint</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Debuggers</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-TraceSource</command:name> <maml:description> <maml:para>Configures, starts, and stops a trace of Windows PowerShell components.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Set</command:verb> <command:noun>TraceSource</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Set-TraceSource cmdlet configures, starts, and stops a trace of a Windows PowerShell component. You can use it to specify which components will be traced and where the tracing output is sent.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-TraceSource</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which components are traced. Enter the name of the trace source of each component. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Determines the type of events that are traced.</maml:para> <maml:para>The valid values are: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. All is the default.</maml:para> <maml:para>The following values are combinations of other values:</maml:para> <maml:para>-- ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)</maml:para> <maml:para>-- Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)</maml:para> <maml:para>-- Errors: (Error and Exception).</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "Constructor,Dispose".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSTraceSourceOptions</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Debugger</maml:name> <maml:description> <maml:para>Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Microsoft Visual Studio. This parameter also selects the default trace listener.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Sends the trace output to the specified file. This parameter also selects the file trace listener. If you use this parameter to start the trace, use the RemoveFileListener parameter to stop the trace.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to overwrite a read-only file. Use with the FilePath parameter.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ListenerOption</maml:name> <maml:description> <maml:para>Adds optional data to the prefix of each trace message in the output. The valid values are "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId", and "Callstack". "None" is the default.</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constructor</command:parameterValue> <command:parameterValue required="false" variableLength="false">Dispose</command:parameterValue> <command:parameterValue required="false" variableLength="false">Finalizer</command:parameterValue> <command:parameterValue required="false" variableLength="false">Method</command:parameterValue> <command:parameterValue required="false" variableLength="false">Property</command:parameterValue> <command:parameterValue required="false" variableLength="false">Delegates</command:parameterValue> <command:parameterValue required="false" variableLength="false">Events</command:parameterValue> <command:parameterValue required="false" variableLength="false">Exception</command:parameterValue> <command:parameterValue required="false" variableLength="false">Lock</command:parameterValue> <command:parameterValue required="false" variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" variableLength="false">Errors</command:parameterValue> <command:parameterValue required="false" variableLength="false">Warning</command:parameterValue> <command:parameterValue required="false" variableLength="false">Verbose</command:parameterValue> <command:parameterValue required="false" variableLength="false">WriteLine</command:parameterValue> <command:parameterValue required="false" variableLength="false">Data</command:parameterValue> <command:parameterValue required="false" variableLength="false">Scope</command:parameterValue> <command:parameterValue required="false" variableLength="false">ExecutionFlow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Assert</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the trace session. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PSHost</maml:name> <maml:description> <maml:para>Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-TraceSource</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which components are traced. Enter the name of the trace source of each component. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RemoveListener</maml:name> <maml:description> <maml:para>Stops the trace by removing the trace listener.</maml:para> <maml:para>Use the following values with RemoveListener:</maml:para> <maml:para>--To remove PSHost (console), type "Host".</maml:para> <maml:para>--To remove Debugger, type "Debug".</maml:para> <maml:para>--To remove all trace listeners, type "*".</maml:para> <maml:para>To remove the file trace listener, use the RemoveFileListener parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-TraceSource</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which components are traced. Enter the name of the trace source of each component. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RemoveFileListener</maml:name> <maml:description> <maml:para>Stops the trace by removing the file trace listener associated with the specified file. Enter the path and file name of the trace output file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Debugger</maml:name> <maml:description> <maml:para>Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Microsoft Visual Studio. This parameter also selects the default trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Sends the trace output to the specified file. This parameter also selects the file trace listener. If you use this parameter to start the trace, use the RemoveFileListener parameter to stop the trace.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to overwrite a read-only file. Use with the FilePath parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ListenerOption</maml:name> <maml:description> <maml:para>Adds optional data to the prefix of each trace message in the output. The valid values are "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId", and "Callstack". "None" is the default.</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">TraceOptions</command:parameterValue> <dev:type> <maml:name>TraceOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which components are traced. Enter the name of the trace source of each component. Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="2" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Determines the type of events that are traced.</maml:para> <maml:para>The valid values are: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. All is the default.</maml:para> <maml:para>The following values are combinations of other values:</maml:para> <maml:para>-- ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)</maml:para> <maml:para>-- Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)</maml:para> <maml:para>-- Errors: (Error and Exception).</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "Constructor,Dispose".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSTraceSourceOptions</command:parameterValue> <dev:type> <maml:name>PSTraceSourceOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PSHost</maml:name> <maml:description> <maml:para>Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the trace session. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RemoveFileListener</maml:name> <maml:description> <maml:para>Stops the trace by removing the file trace listener associated with the specified file. Enter the path and file name of the trace output file.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RemoveListener</maml:name> <maml:description> <maml:para>Stops the trace by removing the trace listener.</maml:para> <maml:para>Use the following values with RemoveListener:</maml:para> <maml:para>--To remove PSHost (console), type "Host".</maml:para> <maml:para>--To remove Debugger, type "Debug".</maml:para> <maml:para>--To remove all trace listeners, type "*".</maml:para> <maml:para>To remove the file trace listener, use the RemoveFileListener parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains a name to Set-TraceSource.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.PSTraceSource</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Set-TraceSource generates a System.Management.Automation.PSTraceSource object representing the trace session. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing.</maml:para> <maml:para>The Windows PowerShell tracing cmdlets are designed to help Windows PowerShell developers, but they are available to all users. They let you monitor nearly every aspect of the functionality of Windows PowerShell.</maml:para> <maml:para>A "trace source" is the part of each Windows PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.</maml:para> <maml:para>A "trace listener" receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.</maml:para> <maml:para>To start a trace, use the Name parameter to specify a trace source (the component to be traced) and the FilePath, Debugger, or PSHost parameters to specify a listener (a destination for the output). Use the Options parameter to determine the types of events that are traced and the ListenerOptions parameter to configure the trace output.</maml:para> <maml:para>To change the configuration of a trace, enter a Set-TraceSource command as you would to start a trace. Windows PowerShell recognizes that the trace source is already being traced. It stops the trace, adds the new configuration, and starts or restarts the trace.</maml:para> <maml:para>To stop a trace, use the RemoveListener parameter. To stop a trace that uses the file listener (a trace started by using the -FilePath parameter), use the RemoveFileListener parameter. When you remove the listener, the trace stops.</maml:para> <maml:para>To determine which components can be traced, use Get-TraceSource. The trace sources for each module are loaded automatically when the component is in use, and they appear in the output of Get-TraceSource.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Set-TraceSource -Name Parameterbinding -Option ExecutionFlow -PSHost -ListenerOption "ProcessID,TimeStamp" </dev:code> <dev:remarks> <maml:para>This command starts tracing for the ParameterBinding component of Windows PowerShell. It uses the Name parameter to specify the trace source, the Option parameter to select the ExecutionFlow trace events, and the PSHost parameter to select the Windows PowerShell host listener, which sends the output to the console. The ListenerOption parameter adds the "ProcessID" and "TimeStamp" values to the trace message prefix.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-tracesource -name ParameterBinding -RemoveListener Host </dev:code> <dev:remarks> <maml:para>This command stops the trace of the ParameterBinding component of Windows PowerShell. It uses the Name parameter to identify the component that was being traced and the RemoveListener parameter to identify the trace listener.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294014</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-TraceSource</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-PSDebug</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Trace-Command</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-Variable</command:name> <maml:description> <maml:para>Sets the value of a variable. Creates the variable if one with the requested name does not exist.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Set</command:verb> <command:noun>Variable</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Set-Variable cmdlet assigns a value to a specified variable or changes the current value. If the variable does not exist, the cmdlet creates it.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-Variable</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the variable name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the value of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies the description of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows you to create a variable with the same name as an existing read-only variable, or to change the value of a read-only variable.</maml:para> <maml:para>By default, you can overwrite a variable, unless the variable has an option value of "ReadOnly" or "Constant". For more information, see the Option parameter.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Changes only the specified items. The value of this parameter qualifies the Name parameter. Enter a name or name pattern, such as "c*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the variable.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed. "Constant" is valid only when you are creating a variable. You cannot change the options of an existing variable to "Constant".</maml:para> <maml:para>-- Private: The variable is available only in the current scope.</maml:para> <maml:para>-- AllScope: The variable is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all variables in the session, type "get-variable | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadOnly</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constant</command:parameterValue> <command:parameterValue required="false" variableLength="false">Private</command:parameterValue> <command:parameterValue required="false" variableLength="false">AllScope</command:parameterValue> <command:parameterValue required="false" variableLength="false">Unspecified</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the new variable. By default, this cmdlet does not generate any output.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Determines the scope of the variable. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Visibility</maml:name> <maml:description> <maml:para>Determines whether the variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Public: The variable is visible. ("Public" is the default.)</maml:para> <maml:para>-- Private: The variable is not visible.</maml:para> <maml:para>When a variable is private, it does not appear in lists of variables, such as those returned by Get-Variable, or in displays of the Variable: drive. Commands to read or change the value of a private variable return an error. However, the user can run commands that use a private variable if the commands were written in the session in which the variable was defined.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Public</command:parameterValue> <command:parameterValue required="false" variableLength="false">Private</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Description</maml:name> <maml:description> <maml:para>Specifies the description of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exclude</maml:name> <maml:description> <maml:para>Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows you to create a variable with the same name as an existing read-only variable, or to change the value of a read-only variable.</maml:para> <maml:para>By default, you can overwrite a variable, unless the variable has an option value of "ReadOnly" or "Constant". For more information, see the Option parameter.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Include</maml:name> <maml:description> <maml:para>Changes only the specified items. The value of this parameter qualifies the Name parameter. Enter a name or name pattern, such as "c*". Wildcards are permitted.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the variable name.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Sets the value of the Options property of the variable.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- None: Sets no options. ("None" is the default.)</maml:para> <maml:para>-- ReadOnly: Can be deleted. Cannot be not changed, except by using the Force parameter.</maml:para> <maml:para>-- Constant: Cannot be deleted or changed. "Constant" is valid only when you are creating a variable. You cannot change the options of an existing variable to "Constant".</maml:para> <maml:para>-- Private: The variable is available only in the current scope.</maml:para> <maml:para>-- AllScope: The variable is copied to any new scopes that are created.</maml:para> <maml:para>To see the Options property of all variables in the session, type "get-variable | format-table -property name, options -autosize".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ScopedItemOptions</command:parameterValue> <dev:type> <maml:name>ScopedItemOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the new variable. By default, this cmdlet does not generate any output.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Scope</maml:name> <maml:description> <maml:para>Determines the scope of the variable. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, see about_Scopes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="2" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the value of the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Visibility</maml:name> <maml:description> <maml:para>Determines whether the variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- Public: The variable is visible. ("Public" is the default.)</maml:para> <maml:para>-- Private: The variable is not visible.</maml:para> <maml:para>When a variable is private, it does not appear in lists of variables, such as those returned by Get-Variable, or in displays of the Variable: drive. Commands to read or change the value of a private variable return an error. However, the user can run commands that use a private variable if the commands were written in the session in which the variable was defined.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SessionStateEntryVisibility</command:parameterValue> <dev:type> <maml:name>SessionStateEntryVisibility</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe an object that represents the value of the variable to Set-Variable.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None or System.Management.Automation.PSVariable</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Set-Variable generates a System.Management.Automation.PSVariable object representing the new or changed variable. Otherwise, this cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-variable -name desc -value "A description" PS C:\>get-variable -name desc </dev:code> <dev:remarks> <maml:para>These commands set the value of the "desc" variable to "A description", and then get the value of the variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>set-variable -name processes -value (Get-Process) -option constant -scope global -description "All processes" -passthru | format-list -property * </dev:code> <dev:remarks> <maml:para>This command creates a global, read-only variable that contains all processes on the system, and then it displays all properties of the variable.</maml:para> <maml:para>The command uses the Set-Variable cmdlet to create the variable. It uses the PassThru parameter to create an object representing the new variable, and it uses the pipeline operator (|) to pass the object to the Format-List cmdlet. It uses the Property parameter of Format-List with a value of all (*) to display all properties of the newly created variable.</maml:para> <maml:para>The value, "(Get-Process)", is enclosed in parentheses to ensure that it is executed before being stored in the variable. Otherwise, the variable contains the words "Get-Process".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\># set-variable -name counter -visibility private PS C:\>new-variable -name counter -visibility public -value 26 PS C:\>$counter 26 PS C:\>get-variable c* Name Value ---- ----- Culture en-US ConsoleFileName ConfirmPreference High CommandLineParameters {} Counter 26 PS C:\>set-variable -name counter -visibility private PS C:\>get-variable c* Name Value ---- ----- Culture en-US ConsoleFileName ConfirmPreference High CommandLineParameters {} PS C:\>$counter "Cannot access the variable '$counter' because it is a private variable" PS C:\>.\use-counter.ps1 #Commands completed successfully. </dev:code> <dev:remarks> <maml:para>This command shows how to change the visibility of a variable to "Private". This variable can be read and changed by scripts with the required permissions, but it is not visible to the user.</maml:para> <maml:para>The sample output shows the difference in the behavior of public and private variables.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294015</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Variable</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Show-Command</command:name> <maml:description> <maml:para>Creates Windows PowerShell commands in a graphical command window.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Show</command:verb> <command:noun>Command</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Show-Command cmdlet lets you create a Windows PowerShell command in a command window. You can use the features of the command window to run the command or have it return the command to you.</maml:para> <maml:para>Show-Command is a very useful teaching and learning tool. Show-Command works on all command types, including cmdlets, functions, workflows and CIM commands.</maml:para> <maml:para>Without parameters, Show-Command displays a command window that lists all available commands in all installed modules. To find the commands in a module, select the module from the Modules drop-down list. To select a command, click the command name.</maml:para> <maml:para>To use the command window, select a command, either by using the Name parameter or by clicking the command name in the Commands list. Each parameter set is displayed on a separate tab. Asterisks indicate the mandatory parameters. To enter values for a parameter, type the value in the text box or select the value from the drop-down box. To add a switch parameter, click to select the parameter check box.</maml:para> <maml:para>When you're ready, you can click Copy to copy the command that you've created to the clipboard or click Run to run the command. You can also use the Passthru parameter to return the command to the host program, such as the Windows PowerShell console. To cancel the command selection and return to the view that displays all commands, press Ctrl and click the selected command.</maml:para> <maml:para>In the Windows PowerShell Integrated Scripting Environment (ISE), a variation of the Show-Command window is displayed by default. For information about using this command window, see the Windows PowerShell ISE help topics. </maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Show-Command</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="CommandName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Displays a command window for the specified command. Enter the name of one command, such as the name of a cmdlet, function, workflow, or CIM command. If you omit this parameter, Show-Command displays a command window that lists all of the Windows PowerShell commands in all modules installed on the computer. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorPopup</maml:name> <maml:description> <maml:para>Displays errors in a pop-up window, in addition to displaying them at the command line. By default, when a command that is run in a Show-Command window generates an error, the error is displayed only at the command line.</maml:para> <maml:para>Also, when you run the command (by using the Run button in the Show-Command window), the ErrorPopup parameter returns the command results to the current command, instead of running the command and returning its output to a new command. You can use this feature to save the command results in a variable.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Height</maml:name> <maml:description> <maml:para>Specifies the height of the Show-Command window in pixels. Enter a value between 300 and the number of pixels in the screen resolution. If the value is too large to display the command window on the screen, Show-Command generates an error. The default height is 600 pixels. For a Show-Command command that includes the Name parameter, the default height is 300 pixels. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Double</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoCommonParameter</maml:name> <maml:description> <maml:para>Omits the Common Parameters section of the command display. By default, the Common Parameters appear in an expandable section at the bottom of the command window. </maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Displays the command string in the console, instead of running it.</maml:para> <maml:para>To run the command string, copy and paste it at the command prompt or save it in a variable and use the Invoke-Expression cmdlet to run the string in the variable.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the width of the Show-Command window in pixels. Enter a value between 300 and the number of pixels in the screen resolution. If the value is too large to display the command window on the screen, Show-Command generates an error. The default width is 300 pixels. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Double</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Height</maml:name> <maml:description> <maml:para>Specifies the height of the Show-Command window in pixels. Enter a value between 300 and the number of pixels in the screen resolution. If the value is too large to display the command window on the screen, Show-Command generates an error. The default height is 600 pixels. For a Show-Command command that includes the Name parameter, the default height is 300 pixels. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Double</command:parameterValue> <dev:type> <maml:name>Double</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="CommandName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Displays a command window for the specified command. Enter the name of one command, such as the name of a cmdlet, function, workflow, or CIM command. If you omit this parameter, Show-Command displays a command window that lists all of the Windows PowerShell commands in all modules installed on the computer. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoCommonParameter</maml:name> <maml:description> <maml:para>Omits the Common Parameters section of the command display. By default, the Common Parameters appear in an expandable section at the bottom of the command window. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Width</maml:name> <maml:description> <maml:para>Specifies the width of the Show-Command window in pixels. Enter a value between 300 and the number of pixels in the screen resolution. If the value is too large to display the command window on the screen, Show-Command generates an error. The default width is 300 pixels. </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Double</command:parameterValue> <dev:type> <maml:name>Double</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Displays the command string in the console, instead of running it.</maml:para> <maml:para>To run the command string, copy and paste it at the command prompt or save it in a variable and use the Invoke-Expression cmdlet to run the string in the variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorPopup</maml:name> <maml:description> <maml:para>Displays errors in a pop-up window, in addition to displaying them at the command line. By default, when a command that is run in a Show-Command window generates an error, the error is displayed only at the command line.</maml:para> <maml:para>Also, when you run the command (by using the Run button in the Show-Command window), the ErrorPopup parameter returns the command results to the current command, instead of running the command and returning its output to a new command. You can use this feature to save the command results in a variable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to Show-Command.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String, System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>When you use the PassThru parameter, Show-Command returns a command string. When you use the ErrorPopup parameter, Show-Command returns the command output (any object).Otherwise, Show-Command does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Show-Command does not work in remote sessions.</maml:para> </maml:alert> <maml:alert> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Show-Command </dev:code> <dev:remarks> <maml:para>This command displays the default view of the Show-Command window. The command window displays a list of all commands in all modules that are installed on the computer. </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Show-Command -Name Invoke-Command </dev:code> <dev:remarks> <maml:para>This command opens the Invoke-Command cmdlet display in the Show-Command window. You can use the Invoke-Command display to run Invoke-Command commands. </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Show-Command -Name Connect-PSSession -Height 700 -Width 1000 -ErrorPopup </dev:code> <dev:remarks> <maml:para>This command opens a Show-Command window for the Connect-PSSession cmdlet. It uses the Height and Width parameters to specify the dimension of the command window and the ErrorPopup parameter to display the error command window. </maml:para> <maml:para>When you click Run, the Connect-PSSession command runs, just as would if you typed the Connect-PSSession command at the command line. </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$PSDefaultParameterValues = @{"Show-Command:Height" = 700; "Show-Command:Width" = 1000; "Show-Command:ErrorPopup" = $True} </dev:code> <dev:remarks> <maml:para>This command uses the $PSDefaultParameterValues automatic variable to set new default values for the Height, Width, and ErrorPopup parameters of the Show-Command cmdlet. Now when you run a Show-Command command, the new defaults are applied automatically. </maml:para> <maml:para>To use these default values in every Windows PowerShell session, add the $PSDefaultParameterValues variable to your Windows PowerShell profile. For more information, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729) and about_PSDefaultParameterValues (http://go.microsoft.com/fwlink/?LinkID=228266). </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Show-Command Get-ChildItem | Out-GridView </dev:code> <dev:remarks> <maml:para>This command shows how to use the Show-Command and Out-GridView cmdlets together. </maml:para> <maml:para>The command uses the Show-Command cmdlet to open a command window for the Get-ChildItem cmdlet. When you click the Run button, the Get-ChildItem command runs and generates output. The pipeline operator ( | ) sends the output of the Get-ChildItem command to the Out-GridView cmdlet, which displays the Get-ChildItem output in an interactive window. </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Show-Command -Passthru Get-EventLog -LogName "Windows PowerShell" -Newest 5 </dev:code> <dev:remarks> <maml:para>This command shows the command that you created in the Show-Command window. The command uses the Passthru parameter, which returns the Show-Command results in a string.</maml:para> <maml:para>For example, if you use the Show-Command window to create a Get-EventLog command that gets the five newest events in the Windows PowerShell event log, and then click OK, the command returns the following output.</maml:para> <maml:para>Viewing the command string helps you to learn Windows PowerShell.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the PassThru parameter of the Show-Command cmdlet. It saves the results of the command in the $c variable.The command opens a Show-Command window. In this case, we use the Show-Command window to create a Get-EventLog command that gets the five newest events in the Windows PowerShell event log. When you click OK, Show-Command returns the command string, which is saved in the $c variable. PS C:\>$c = Show-Command -Passthru This command displays the command string in the $c variable. PS C:\>$c Get-EventLog -LogName "Windows PowerShell" -Newest 5 These commands use the Invoke-Expression cmdlet to run the string in the $c variable. The first command uses the full cmdlet name. The second command uses the "iex" alias for the Invoke-Expression cmdlet. These commands are equivalent and you can use them interchangeably.The output shows the five newest events in the Windows PowerShell event log. PS C:\>Invoke-Expression $c PS C:\>iex $c Index Time EntryType Source InstanceID Message ----- ---- --------- ------ ---------- ------- 11520 Dec 16 16:37 Information PowerShell 400 Engine state is changed from None to Available.... 11519 Dec 16 16:37 Information PowerShell 600 Provider "Variable" is Started. ... 11518 Dec 16 16:37 Information PowerShell 600 Provider "Registry" is Started. ... 11517 Dec 16 16:37 Information PowerShell 600 Provider "Function" is Started. ... 11516 Dec 16 16:37 Information PowerShell 600 Provider "FileSystem" is Started. ... </dev:code> <dev:remarks> <maml:para>This command shows how to run the command string that you get when you use the PassThru parameter of the Show-Command cmdlet. This strategy lets you see the command and use it.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 8 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command runs the Show-Command cmdlet with the ErrorPopup parameter. In addition to displaying errors in a window, ErrorPopup returns command output to the current command, instead of creating a new command.When you run this command, the Show-Command window opens. You can use the window features to set parameter values. To run the command, click the Run button in the Show-Command window. PS C:\>$p = Show-Command Get-Process -ErrorPopup The second command displays the value in the $p variable. PS C:\>$p Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 473 33 94096 112532 709 2.06 4492 powershell </dev:code> <dev:remarks> <maml:para>These commands use the ErrorPopup parameter of the Show-Command cmdlet to save the output of a command in a variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294016</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Sort-Object</command:name> <maml:description> <maml:para>Sorts objects by property values.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Sort</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Sort-Object cmdlet sorts objects in ascending or descending order based on the values of properties of the object.</maml:para> <maml:para>You can specify a single property or multiple properties (for a multi-key sort), and you can select a case-sensitive or case-insensitive sort. You can also direct Sort-Object to display only the objects with a unique value for a particular property.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Sort-Object</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties to use when sorting. Objects are sorted based on the values of these properties. Enter the names of the properties. Wildcards are permitted.</maml:para> <maml:para>If you specify multiple properties, the objects are first sorted by the first property. If more than one object has the same value for the first property, those objects are sorted by the second property. This process continues until there are no more specified properties or no groups of objects.</maml:para> <maml:para>If you do not specify properties, the cmdlet sorts based on default properties for the object type.</maml:para> <maml:para>The value of the Property parameter can be a calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- Ascending <Boolean></maml:para> <maml:para>-- Descending <Boolean></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Indicates that the sort should be case sensitive. By default, sorting is not case sensitive.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Culture</maml:name> <maml:description> <maml:para>Specifies the cultural configuration to use when sorting.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Descending</maml:name> <maml:description> <maml:para>Sorts the objects in descending order. The default is ascending order.</maml:para> <maml:para>The Descending parameter applies to all properties. To sort by some properties in</maml:para> <maml:para>ascending order and others in descending order, you must specify their property values by using a hash table. For details, see the examples.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be sorted.</maml:para> <maml:para>When you use the InputObject parameter to submit a collection of items, Sort-Object receives one object that represents the collection. Because one object cannot be sorted, Sort-Object returns the entire collection unchanged.</maml:para> <maml:para>To sort objects, pipe them to Sort-Object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Unique</maml:name> <maml:description> <maml:para>Eliminates duplicates and returns only the unique members of the collection. You can use this parameter instead of using the Get-Unique cmdlet.</maml:para> <maml:para>This parameter is case-insensitive. As a result, strings that differ only in character casing are considered to be the same (not unique).</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CaseSensitive</maml:name> <maml:description> <maml:para>Indicates that the sort should be case sensitive. By default, sorting is not case sensitive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Culture</maml:name> <maml:description> <maml:para>Specifies the cultural configuration to use when sorting.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Descending</maml:name> <maml:description> <maml:para>Sorts the objects in descending order. The default is ascending order.</maml:para> <maml:para>The Descending parameter applies to all properties. To sort by some properties in</maml:para> <maml:para>ascending order and others in descending order, you must specify their property values by using a hash table. For details, see the examples.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be sorted.</maml:para> <maml:para>When you use the InputObject parameter to submit a collection of items, Sort-Object receives one object that represents the collection. Because one object cannot be sorted, Sort-Object returns the entire collection unchanged.</maml:para> <maml:para>To sort objects, pipe them to Sort-Object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Specifies the properties to use when sorting. Objects are sorted based on the values of these properties. Enter the names of the properties. Wildcards are permitted.</maml:para> <maml:para>If you specify multiple properties, the objects are first sorted by the first property. If more than one object has the same value for the first property, those objects are sorted by the second property. This process continues until there are no more specified properties or no groups of objects.</maml:para> <maml:para>If you do not specify properties, the cmdlet sorts based on default properties for the object type.</maml:para> <maml:para>The value of the Property parameter can be a calculated property. To create a calculated, property, use a hash table. Valid keys are:</maml:para> <maml:para>-- Expression <string> or <script block></maml:para> <maml:para>-- Ascending <Boolean></maml:para> <maml:para>-- Descending <Boolean></maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Unique</maml:name> <maml:description> <maml:para>Eliminates duplicates and returns only the unique members of the collection. You can use this parameter instead of using the Get-Unique cmdlet.</maml:para> <maml:para>This parameter is case-insensitive. As a result, strings that differ only in character casing are considered to be the same (not unique).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the objects to be sorted to Sort-Object.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Sort-Object returns the sorted objects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Sort-Object sorts objects based on the properties that you specify or the default sort properties for objects of that type.</maml:para> <maml:para>If an object does not have one of the specified properties, the property value for that object is interpreted by the cmdlet as NULL and is placed at the end of the sort order.</maml:para> <maml:para>When sorting objects, Sort-Object uses the Compare method for each property. If a property does not implement IComparable, the cmdlet converts the property value to a string and uses the Compare method for System.String</maml:para> <maml:para>The Sort-Object cmdlet sorts objects in ascending or descending order based on the values of properties of the object.</maml:para> <maml:para>If you sort on a property whose value is an enumeration, Sort-Object sorts the enumeration values in numeric order; it does not sort the enumeration member names. For example, if you sort services by status, services with a status of "Stopped" appear before services with a status of "Running", because the value of Status is a ServiceControllerStatus enumeration, in which "Stopped" has a value of 1 and "Running" has a value of 4.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | sort-object Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 9/13/2005 4:24 PM 0 0 -a--- 9/6/2005 4:19 PM 12 a.csv -a--- 9/21/2005 3:49 PM 529 a.Ps -a--- 8/22/2005 4:14 PM 22 a.pl -a--- 9/27/2005 10:33 AM 24 a.txt -a--- 9/15/2005 10:31 AM 398 a.vbs -a--- 7/21/2005 12:39 PM 37066 a.xml -a--- 8/28/2005 11:30 PM 5412 a.xslt -a--- 10/25/2005 1:59 PM 125 AdamTravel.txt -a--- 7/21/2005 9:49 AM 59 add2Num.Ps -a--- 8/29/2005 5:42 PM 7111 add-content.xml -a--- 9/21/2005 12:46 PM 8771 aliens.Ps -a--- 8/10/2005 2:10 PM 798 array.xml -a--- 8/4/2004 5:00 AM 110 AUTORUN.INF -a--- 9/6/2005 4:20 PM 245 b.csv ... </dev:code> <dev:remarks> <maml:para>This command sorts the subdirectories and files in the current directory. Because no properties are specified, the files and directories are sorted in ascending alphabetical order by their default sort property, Name.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem | sort-object -property length Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 12/3/2006 5:35 PM 2 pref.txt -a--- 9/6/2006 3:33 PM 15 count.txt -a--- 7/26/2006 10:01 AM 30 filenoext -a--- 8/18/2006 9:02 AM 52 temp.ps1 -a--- 8/18/2006 9:02 AM 52 temp.msh -a--- 9/6/2006 3:33 PM 56 fivewords.txt -a--- 7/26/2006 9:28 AM 80 date.csv -a--- 7/29/2006 7:15 PM 84 test2.txt -a--- 7/29/2006 7:15 PM 84 test.ps1 </dev:code> <dev:remarks> <maml:para>This command displays the files in the current directory in ascending order by file length.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | sort-object -property WS | select-object -last 5 Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 1105 25 44236 18932 197 93.81 2032 iexplore 2526 66 37668 36836 221 393.27 868 svchost 974 19 22844 45928 371 88.39 3952 WINWORD 1371 22 42192 61872 323 75.75 1584 INFOPATH 2145 58 93088 70680 619 396.69 3908 OUTLOOK </dev:code> <dev:remarks> <maml:para>This command displays the five processes on the computer with the greatest memory use based on the size of their working sets.</maml:para> <maml:para>The command uses the Get-Process cmdlet to get a list of processes. It uses a pipeline operator (|) to send the results to the Sort-Object cmdlet, which sorts the objects in working-set order.</maml:para> <maml:para>Another pipeline operator sends the results to the Select-Object, which displays only the last five items in the list.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-history | sort-object -descending Id CommandLine -- ----------- 51 get-history | sort -descending 50 get-history | sort -descending 49 get-history | sort -descending 48 get-history | sort -descending 47 get-history | sort -descending 46 get-history | sort -descending 45 get-history | sort -descending 44 cd $pshome 43 get-childitem | sort-object 42 gci *.txt </dev:code> <dev:remarks> <maml:para>This command sorts HistoryInfo objects using the Id property as the default key.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-service | sort-object -property @{Expression="Status";Descending=$true}, @{Expression="DisplayName";Descending=$false} Status Name DisplayName ------ ---- ----------- Running ALG Application Layer Gateway Service Running Ati HotKey Poller Ati HotKey Poller Running wuauserv Automatic Updates Running BITS Background Intelligent Transfer Ser... Running Client for NFS Client for NFS ... Stopped clr_optimizatio... .NET Runtime Optimization Service v... Stopped Alerter Alerter Stopped AppMgmt Application Management Stopped aspnet_state ASP.NET State Service Stopped ATI Smart ATI Smart Stopped ClipSrv ClipBook </dev:code> <dev:remarks> <maml:para>This command displays the services on the computer in descending Status order and ascending DisplayName order.</maml:para> <maml:para>The command uses the Get-Service cmdlet to get the services on the computer. It uses a pipeline operator (|) to send services to the Sort-Object cmdlet.</maml:para> <maml:para>To sort one property in ascending order and another property in descending order, the command uses a hash table for the value of the Property parameter. The hash table uses an Expression key to specify the property name and an Ascending or Descending key to specify the sort order.</maml:para> <maml:para>The resulting display, which sorts the Status values in descending order, lists properties with a Status value of "Running" before those with a Status value of "Stopped". When sorted in ascending order, "Stopped" appears before "Running", because Status is an enumerated property in which the value of "Stopped" (1) is less than the value of "Running" (4).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 6 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem *.txt | sort-object -property @{Expression={$_.LastWriteTime - $_.CreationTime}; Ascending=$false} | Format-Table LastWriteTime, CreationTime LastWriteTime CreationTime ------------- ------------ 2/21/2006 10:22:20 AM 10/3/2005 4:19:40 PM 2/27/2006 8:14:24 AM 2/23/2006 10:41:08 PM 2/24/2006 1:26:19 PM 2/23/2006 11:23:36 PM 1/5/2006 12:01:35 PM 1/5/2006 11:35:30 AM 2/24/2006 9:25:40 AM 2/24/2006 9:22:24 AM 2/24/2006 9:40:01 AM 2/24/2006 9:39:41 AM 2/21/2006 10:21:30 AM 2/21/2006 10:21:30 AM </dev:code> <dev:remarks> <maml:para>This command sorts text files in descending order by the time span between CreationTime and LastWriteTime.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 7 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-content servers.txt localhost test01 server01 server02 localhost server01 PS C:\>get-content servers.txt | sort-object -unique localhost server01 server02 test01 </dev:code> <dev:remarks> <maml:para>These commands sort the names of servers in a text file. The second command uses the Sort-Object cmdlet with the Unique parameter to return a sorted list without duplicates.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294017</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Group-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Start-Sleep</command:name> <maml:description> <maml:para>Suspends the activity in a script or session for the specified period of time.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Start</command:verb> <command:noun>Sleep</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Start-Sleep cmdlet suspends the activity in a script or session for the specified period of time. You can use it for many tasks, such as waiting for an operation to complete or pausing before repeating an operation.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Start-Sleep</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Seconds</maml:name> <maml:description> <maml:para>Specifies how long the resource sleeps in seconds. You can omit the parameter name ("Seconds"), or you can abbreviate it as "-s".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Start-Sleep</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="none"> <maml:name>Milliseconds</maml:name> <maml:description> <maml:para>Specifies how long the resource sleeps in milliseconds. The parameter can be abbreviated as "-m".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="none"> <maml:name>Milliseconds</maml:name> <maml:description> <maml:para>Specifies how long the resource sleeps in milliseconds. The parameter can be abbreviated as "-m".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>Seconds</maml:name> <maml:description> <maml:para>Specifies how long the resource sleeps in seconds. You can omit the parameter name ("Seconds"), or you can abbreviate it as "-s".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Int32</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the number of seconds to Start-Sleep.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not return any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also refer to Start-Sleep by its built-in alias, "sleep". For more information, see about_Aliases.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Start-Sleep -s 15 </dev:code> <dev:remarks> <maml:para>This command makes all commands in the session sleep for 15 seconds.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Start-Sleep -m 500 </dev:code> <dev:remarks> <maml:para>This command makes all the commands in the session sleep for one-half of a second (500 milliseconds).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294018</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Tee-Object</command:name> <maml:description> <maml:para>Saves command output in a file or variable and also sends it down the pipeline.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Tee</command:verb> <command:noun>Object</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Tee-Object cmdlet redirects output, that is, it sends the output of a command in two directions (like the letter "T"). It stores the output in a file or variable and also sends it down the pipeline. If Tee-Object is the last command in the pipeline, the command output is displayed at the prompt.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Tee-Object</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Saves the object in the specified file. Wildcard characters are permitted, but must resolve to a single file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Appends the output to the specified file. Without this parameter, the new content replaces any existing content in the file without warning.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be saved and displayed. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe an object to Tee-Object.</maml:para> <maml:para>When you use the InputObject parameter with Tee-Object, instead of piping command results to Tee-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Tee-Object to perform operations on a collection of objects for those objects that have specific values in defined properties, you use Tee-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Tee-Object</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be saved and displayed. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe an object to Tee-Object.</maml:para> <maml:para>When you use the InputObject parameter with Tee-Object, instead of piping command results to Tee-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Tee-Object to perform operations on a collection of objects for those objects that have specific values in defined properties, you use Tee-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Saves the object in the specified file. Unlike FilePath, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Tee-Object</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be saved and displayed. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe an object to Tee-Object.</maml:para> <maml:para>When you use the InputObject parameter with Tee-Object, instead of piping command results to Tee-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Tee-Object to perform operations on a collection of objects for those objects that have specific values in defined properties, you use Tee-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Variable</maml:name> <maml:description> <maml:para>Saves the object in the specified variable. Enter a variable name without the preceding dollar sign ($).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Append</maml:name> <maml:description> <maml:para>Appends the output to the specified file. Without this parameter, the new content replaces any existing content in the file without warning.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Saves the object in the specified file. Wildcard characters are permitted, but must resolve to a single file.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the object to be saved and displayed. Enter a variable that contains the objects or type a command or expression that gets the objects. You can also pipe an object to Tee-Object.</maml:para> <maml:para>When you use the InputObject parameter with Tee-Object, instead of piping command results to Tee-Object, the InputObject value�even if the value is a collection that is the result of a command, such as �InputObject (Get-Process)�is treated as a single object. Because InputObject cannot return individual properties from an array or collection of objects, it is recommended that if you use Tee-Object to perform operations on a collection of objects for those objects that have specific values in defined properties, you use Tee-Object in the pipeline, as shown in the examples in this topic.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Variable</maml:name> <maml:description> <maml:para>Saves the object in the specified variable. Enter a variable name without the preceding dollar sign ($).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Saves the object in the specified file. Unlike FilePath, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe objects to Tee-Object.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Tee-Object returns the object that it redirects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>You can also use the Out-File cmdlet or the redirection operator, both of which save the output in a file but do not send it down the pipeline.</maml:para> </maml:alert> <maml:alert> <maml:para>Tee-Object uses Unicode encoding when it writes to files. As a result, the output might not be formatted properly in files with a different encoding. To specify the encoding, use the Out-File cmdlet.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process | tee-object -filepath C:\Test1\testfile2.txt Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 83 4 2300 4520 39 0.30 4032 00THotkey 272 6 1400 3944 34 0.06 3088 alg 81 3 804 3284 21 2.45 148 ApntEx 81 4 2008 5808 38 0.75 3684 Apoint ... </dev:code> <dev:remarks> <maml:para>This command gets a list of the processes running on the computer and sends the result to a file. Because a second path is not specified, the processes are also displayed in the console.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-process notepad | tee-object -variable proc | select-object processname,handles ProcessName Handles ----------- ------- notepad 43 notepad 37 notepad 38 notepad 38 </dev:code> <dev:remarks> <maml:para>This command gets a list of the processes running on the computer and sends the result to a variable named "proc". It then pipes the resulting objects along to Select-Object, which selects the ProcessName and Handles property. Note that the $proc variable includes the default information returned by Get-Process.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-childitem �path D: �file �system �recurse | tee-object �file c:\test\AllSystemFiles.txt �append | out-file c:\test\NewSystemFiles.txt </dev:code> <dev:remarks> <maml:para>This command saves a list of system files in a two log files, a cumulative file and a current file.</maml:para> <maml:para>The command uses the Get-ChildItem cmdlet to do a recursive search for system files on the D: drive. A pipeline operator (|) sends the list to Tee-Object, which appends the list to the AllSystemFiles.txt file and passes the list down the pipeline to the Out-File cmdlet, which saves the list in the NewSystemFiles.txt file.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294019</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Redirection</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Trace-Command</command:name> <maml:description> <maml:para>Configures and starts a trace of the specified expression or command.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Trace</command:verb> <command:noun>Command</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Trace-Command cmdlet configures and starts a trace of the specified expression or command. It works like Set-TraceSource, except that it applies only to the specified command.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Trace-Command</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which Windows PowerShell components are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type "Get-TraceSource".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Expression</maml:name> <maml:description> <maml:para>Specifies the expression that is being processed during the trace. Enclose the expression in braces ({}).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Determines the type of events that are traced.</maml:para> <maml:para>The valid values are None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. "All" is the default.</maml:para> <maml:para>The following values are combinations of other values:</maml:para> <maml:para>-- ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)</maml:para> <maml:para>-- Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)</maml:para> <maml:para>-- Errors: (Error and Exception).</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "Constructor,Dispose".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSTraceSourceOptions</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Debugger</maml:name> <maml:description> <maml:para>Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Visual Studio. This parameter also selects the default trace listener.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Sends the trace output to the specified file. This parameter also selects the file trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to append trace information to a read-only file. Used with the FilePath parameter. Even using the Force parameter, the cmdlet cannot override security restrictions.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Provides input to the expression that is being processed during the trace.</maml:para> <maml:para>You can enter a variable that represents the input that the expression accepts, or pass an object through the pipeline.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ListenerOption</maml:name> <maml:description> <maml:para>Adds optional data to the prefix of each trace message in the output. The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. "None" is the default.</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constructor</command:parameterValue> <command:parameterValue required="false" variableLength="false">Dispose</command:parameterValue> <command:parameterValue required="false" variableLength="false">Finalizer</command:parameterValue> <command:parameterValue required="false" variableLength="false">Method</command:parameterValue> <command:parameterValue required="false" variableLength="false">Property</command:parameterValue> <command:parameterValue required="false" variableLength="false">Delegates</command:parameterValue> <command:parameterValue required="false" variableLength="false">Events</command:parameterValue> <command:parameterValue required="false" variableLength="false">Exception</command:parameterValue> <command:parameterValue required="false" variableLength="false">Lock</command:parameterValue> <command:parameterValue required="false" variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" variableLength="false">Errors</command:parameterValue> <command:parameterValue required="false" variableLength="false">Warning</command:parameterValue> <command:parameterValue required="false" variableLength="false">Verbose</command:parameterValue> <command:parameterValue required="false" variableLength="false">WriteLine</command:parameterValue> <command:parameterValue required="false" variableLength="false">Data</command:parameterValue> <command:parameterValue required="false" variableLength="false">Scope</command:parameterValue> <command:parameterValue required="false" variableLength="false">ExecutionFlow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Assert</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PSHost</maml:name> <maml:description> <maml:para>Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Trace-Command</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which Windows PowerShell components are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type "Get-TraceSource".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies a command that is being processed during the trace.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Determines the type of events that are traced.</maml:para> <maml:para>The valid values are None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. "All" is the default.</maml:para> <maml:para>The following values are combinations of other values:</maml:para> <maml:para>-- ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)</maml:para> <maml:para>-- Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)</maml:para> <maml:para>-- Errors: (Error and Exception).</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "Constructor,Dispose".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSTraceSourceOptions</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Specifies the parameters and parameter values for the command being traced. The alias for ArgumentList is Args. This feature is especially useful for debugging dynamic parameters.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Debugger</maml:name> <maml:description> <maml:para>Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Visual Studio. This parameter also selects the default trace listener.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Sends the trace output to the specified file. This parameter also selects the file trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to append trace information to a read-only file. Used with the FilePath parameter. Even using the Force parameter, the cmdlet cannot override security restrictions.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Provides input to the expression that is being processed during the trace.</maml:para> <maml:para>You can enter a variable that represents the input that the expression accepts, or pass an object through the pipeline.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ListenerOption</maml:name> <maml:description> <maml:para>Adds optional data to the prefix of each trace message in the output. The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. "None" is the default.</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID".</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">None</command:parameterValue> <command:parameterValue required="false" variableLength="false">Constructor</command:parameterValue> <command:parameterValue required="false" variableLength="false">Dispose</command:parameterValue> <command:parameterValue required="false" variableLength="false">Finalizer</command:parameterValue> <command:parameterValue required="false" variableLength="false">Method</command:parameterValue> <command:parameterValue required="false" variableLength="false">Property</command:parameterValue> <command:parameterValue required="false" variableLength="false">Delegates</command:parameterValue> <command:parameterValue required="false" variableLength="false">Events</command:parameterValue> <command:parameterValue required="false" variableLength="false">Exception</command:parameterValue> <command:parameterValue required="false" variableLength="false">Lock</command:parameterValue> <command:parameterValue required="false" variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" variableLength="false">Errors</command:parameterValue> <command:parameterValue required="false" variableLength="false">Warning</command:parameterValue> <command:parameterValue required="false" variableLength="false">Verbose</command:parameterValue> <command:parameterValue required="false" variableLength="false">WriteLine</command:parameterValue> <command:parameterValue required="false" variableLength="false">Data</command:parameterValue> <command:parameterValue required="false" variableLength="false">Scope</command:parameterValue> <command:parameterValue required="false" variableLength="false">ExecutionFlow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Assert</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PSHost</maml:name> <maml:description> <maml:para>Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="Args"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>Specifies the parameters and parameter values for the command being traced. The alias for ArgumentList is Args. This feature is especially useful for debugging dynamic parameters.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies a command that is being processed during the trace.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Debugger</maml:name> <maml:description> <maml:para>Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Visual Studio. This parameter also selects the default trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Expression</maml:name> <maml:description> <maml:para>Specifies the expression that is being processed during the trace. Enclose the expression in braces ({}).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="PSPath"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Sends the trace output to the specified file. This parameter also selects the file trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Allows the cmdlet to append trace information to a read-only file. Used with the FilePath parameter. Even using the Force parameter, the cmdlet cannot override security restrictions.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Provides input to the expression that is being processed during the trace.</maml:para> <maml:para>You can enter a variable that represents the input that the expression accepts, or pass an object through the pipeline.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ListenerOption</maml:name> <maml:description> <maml:para>Adds optional data to the prefix of each trace message in the output. The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. "None" is the default.</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">TraceOptions</command:parameterValue> <dev:type> <maml:name>TraceOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Name</maml:name> <maml:description> <maml:para>Determines which Windows PowerShell components are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type "Get-TraceSource".</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Option</maml:name> <maml:description> <maml:para>Determines the type of events that are traced.</maml:para> <maml:para>The valid values are None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. "All" is the default.</maml:para> <maml:para>The following values are combinations of other values:</maml:para> <maml:para>-- ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)</maml:para> <maml:para>-- Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)</maml:para> <maml:para>-- Errors: (Error and Exception).</maml:para> <maml:para>To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "Constructor,Dispose".</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSTraceSourceOptions</command:parameterValue> <dev:type> <maml:name>PSTraceSourceOptions</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PSHost</maml:name> <maml:description> <maml:para>Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe objects that represent input to the expression to Trace-Command.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Returns the command trace in the debug stream.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing.</maml:para> <maml:para>The Windows PowerShell tracing cmdlets are designed to help Windows PowerShell developers, but they are available to all users. They let you monitor nearly every aspect of the functionality of the shell.</maml:para> <maml:para>To find the Windows PowerShell components that are enabled for tracing, type "Get-Help Get-TraceSource."</maml:para> <maml:para>A "trace source" is the part of each Windows PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.</maml:para> <maml:para>A "trace listener" receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the host or console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.</maml:para> <maml:para>When you use the Command parameter set, Windows PowerShell processes the command just as it would be processed in a pipeline. For example, command discovery is not repeated for each incoming object.</maml:para> <maml:para>The names of the Name, Expression, Option, and Command parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Name, Expression, Option or Name, Command,-Option . If you include the parameter names, the parameters can appear in any order.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>trace-command -name metadata,parameterbinding,cmdlet -expression {get-process notepad} -pshost </dev:code> <dev:remarks> <maml:para>This command starts a trace of metadata processing, parameter binding, and cmdlet creation and destruction of the "get-process notepad" expression. It uses the Name parameter to specify the trace sources, the Expression parameter to specify the command, and the PSHost parameter to send the output to the console. Because it does not specify any tracing options or listener options, the command uses the defaults, "All" for the tracing options, and "None" for the listener options.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$a = "i*" PS C:\>trace-command parameterbinding {get-alias $input} -pshost -inputobject $a </dev:code> <dev:remarks> <maml:para>These commands trace the actions of the ParameterBinding operations of Windows PowerShell while it processes a Get-Alias expression that takes input from the pipeline.</maml:para> <maml:para>In Trace-Command, the InputObject parameter passes an object to the expression that is being processed during the trace.</maml:para> <maml:para>The first command stores the string "i*" in the $a variable. The second command uses the Trace-Command cmdlet with the ParameterBinding trace source. The PSHost parameter sends the output to the console.</maml:para> <maml:para>The expression being processed is "get-alias $input", where the $input variable is associated with the InputObject parameter. The InputObject parameter passes the variable $a to the expression. In effect, the command being processed during the trace is "get-alias -inputobject $a" or "$a | get-alias".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294020</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-TraceSource</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-TraceSource</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Unblock-File</command:name> <maml:description> <maml:para>Unblocks files that were downloaded from the Internet.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Unblock</command:verb> <command:noun>File</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Unblock-File cmdlet lets you open files that were downloaded from the Internet. It unblocks Windows PowerShell script files that were downloaded from the Internet so you can run them, even when the Windows PowerShell execution policy is RemoteSigned. By default, these files are blocked to protect the computer from untrusted files.</maml:para> <maml:para>Before using the Unblock-File cmdlet, review the file and its source and verify that it is safe to open.</maml:para> <maml:para>Internally, the Unblock-File cmdlet removes the Zone.Identifier alternate data stream, which has a value of "3" to indicate that it was downloaded from the Internet.</maml:para> <maml:para>For more information about Windows PowerShell execution policies, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170).</maml:para> <maml:para>This cmdlet is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Unblock-File</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the files to unblock. Wildcard characters are supported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Unblock-File</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the files to unblock. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the files to unblock. Unlike Path, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the files to unblock. Wildcard characters are supported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a file path to Unblock-File.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The Unblock-File cmdlet works only in file system drives.</maml:para> </maml:alert> <maml:alert> <maml:para>Unblock-File performs the same operation as the Unblock button on the Properties dialog box in File Explorer.</maml:para> </maml:alert> <maml:alert> <maml:para>If you use the Unblock-File cmdlet on a file that is not blocked, the command has no effect on the unblocked file and the cmdlet does not generate errors.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Unblock a file</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Unblock-File -Path C:\Users\User01\Documents\Downloads\PowerShellTips.chm </dev:code> <dev:remarks> <maml:para>This command unblocks the PowerShellTips.chm file.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 2: Unblock multiple files</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>dir C:\Downloads\*PowerShell* | Unblock-File </dev:code> <dev:remarks> <maml:para>This command unblocks all of the files in the C:\Downloads directory whose names include "PowerShell". Do not run a command like this one until you have verified that all files are safe.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>Example 3: Find and unblock scripts</maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command uses the Stream parameter of the Get-Item cmdlet get files with the Zone.Identifier stream.Although you could pipe the output directly to the Unblock-File cmdlet (Get-Item * -Stream "Zone.Identifier" -ErrorAction SilentlyContinue | ForEach {Unblock-File $_.FileName}), it is prudent to review the file and confirm that it is safe before unblocking. PS C:\>Get-Item * -Stream "Zone.Identifier" -ErrorAction SilentlyContinue FileName: C:\ps-test\Start-ActivityTracker.ps1 Stream Length ------ ------ Zone.Identifier 26 The second command shows what happens when you run a blocked script in a Windows PowerShell session in which the execution policy is RemoteSigned. The RemoteSigned policy prevents you from running scripts that are downloaded from the Internet unless they are digitally signed. PS C:\>C:\ps-test\Start-ActivityTracker.ps1 c:\ps-test\Start-ActivityTracker.ps1 : File c:\ps-test\Start-ActivityTracker.ps1 cannot be loaded. The file c:\ps-test\Start-ActivityTracker.ps1 is not digitally signed. The script will not execute on the system. For more information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170. At line:1 char:1 + c:\ps-test\Start-ActivityTracker.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : SecurityError: (:) [], PSSecurityException + FullyQualifiedErrorId : UnauthorizedAccess The third command uses the Unblock-File cmdlet to unblock the script so it can run in the session. PS C:\>Get-Item C:\ps-test\Start-ActivityTracker.ps1 | Unblock-File </dev:code> <dev:remarks> <maml:para>This command shows how to find and unblock Windows PowerShell scripts.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294021</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Execution_Policies</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Item</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>FileSystem Provider</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Unregister-Event</command:name> <maml:description> <maml:para>Cancels an event subscription.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Unregister</command:verb> <command:noun>Event</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Unregister-Event cmdlet cancels an event subscription that was created by using the Register-EngineEvent, Register-ObjectEvent, or Register-WmiEvent cmdlet.</maml:para> <maml:para>When an event subscription is canceled, the event subscriber is deleted from the session and the subscribed events are no longer added to the event queue. When you cancel a subscription to an event created by using the New-Event cmdlet, the new event is also deleted from the session.</maml:para> <maml:para>Unregister-Event does not delete events from the event queue. To delete events, use the Remove-Event cmdlet.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Unregister-Event</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Cancels event subscriptions that have the specified source identifier.</maml:para> <maml:para>A SourceIdentifier or SubscriptionId parameter must be included in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Cancels all event subscriptions, including subscriptions that were hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Unregister-Event</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SubscriptionId</maml:name> <maml:description> <maml:para>Cancels event subscriptions that have the specified subscription identifier.</maml:para> <maml:para>A SourceIdentifier or SubscriptionId parameter must be included in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Cancels all event subscriptions, including subscriptions that were hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Cancels all event subscriptions, including subscriptions that were hidden by using the SupportEvent parameter of Register-ObjectEvent, Register-WmiEvent, and Register-EngineEvent.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Cancels event subscriptions that have the specified source identifier.</maml:para> <maml:para>A SourceIdentifier or SubscriptionId parameter must be included in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SubscriptionId</maml:name> <maml:description> <maml:para>Cancels event subscriptions that have the specified subscription identifier.</maml:para> <maml:para>A SourceIdentifier or SubscriptionId parameter must be included in every command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSEventSubscriber</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the output from Get-EventSubscriber to Unregister-Event.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not return any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> <maml:para>Unregister-Event cannot delete events created by using the New-Event cmdlet unless you have subscribed to the event by using the Register-EngineEvent cmdlet. To delete a custom event from the session, you must remove it programmatically or close the session.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>unregister-event -sourceIdentifier ProcessStarted </dev:code> <dev:remarks> <maml:para>This command cancels the event subscription that has a source identifier of "ProcessStarted".</maml:para> <maml:para>To find the source identifier of an event, use the Get-Event cmdlet. To find the source identifier of an event subscription, use the Get-EventSubscriber cmdlet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>unregister-event -subscriptionId 2 </dev:code> <dev:remarks> <maml:para>This command cancels the event subscription that has a subscription identifier of 2.</maml:para> <maml:para>To find the subscription identifier of an event subscription, use the Get-EventSubscriber cmdlet.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-eventsubscriber -force | unregister-event -force </dev:code> <dev:remarks> <maml:para>This command cancels all event subscriptions in the session.</maml:para> <maml:para>The command uses the Get-EventSubscriber cmdlet to get all event subscriber objects in the session, including the subscribers that are hidden by using the SupportEvent parameter of the event registration cmdlets.</maml:para> <maml:para>It uses a pipeline operator (|) to send the subscriber objects to Unregister-Event, which deletes them from the session. To complete the task, the Force parameter is also required on Unregister-Event.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294022</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-EventSubscriber</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Update-FormatData</command:name> <maml:description> <maml:para>Updates the formatting data in the current session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Update</command:verb> <command:noun>FormatData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Update-FormatData cmdlet reloads the formatting data from formatting files into the current session. This cmdlet lets you update the formatting data without restarting Windows PowerShell.</maml:para> <maml:para>Without parameters, Update-FormatData reloads the formatting files that it loaded previously. You can use the parameters of Update-FormatData to add new formatting files to the session.</maml:para> <maml:para>Formatting files are text files in XML format with the format.ps1xml file name extension. The formatting data in the files defines the display of Microsoft .NET Framework objects in the session.</maml:para> <maml:para>When Windows PowerShell starts, it loads the format data from the formatting files in the Windows PowerShell installation directory ($pshome) into the session. You can use Update-FormatData to reload the formatting data into the current session without restarting Windows PowerShell. This is useful when you have added or changed a formatting file, but do not want to interrupt the session.</maml:para> <maml:para>For more information about formatting files in Windows PowerShell, see about_Format.ps1xml.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Update-FormatData</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="PSPath,Path"> <maml:name>AppendPath</maml:name> <maml:description> <maml:para>Adds the specified formatting files to the session. The files are loaded after Windows PowerShell loads the built-in formatting files.</maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PrependPath</maml:name> <maml:description> <maml:para>Adds the specified formatting files to the session. The files are loaded before Windows PowerShell loads the built-in formatting files.</maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the PrependPath parameter, Windows PowerShell searches the data from the files that you are adding before it encounters the formatting data from the built-in files.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is also referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="PSPath,Path"> <maml:name>AppendPath</maml:name> <maml:description> <maml:para>Adds the specified formatting files to the session. The files are loaded after Windows PowerShell loads the built-in formatting files.</maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the AppendPath parameter, Windows PowerShell searches the data from the built-in files before it encounters the formatting data that you are adding.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is not referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PrependPath</maml:name> <maml:description> <maml:para>Adds the specified formatting files to the session. The files are loaded before Windows PowerShell loads the built-in formatting files.</maml:para> <maml:para>When formatting .NET objects, Windows PowerShell uses the first formatting definition that it finds for each .NET type. If you use the PrependPath parameter, Windows PowerShell searches the data from the files that you are adding before it encounters the formatting data from the built-in files.</maml:para> <maml:para>Use this parameter to add a file that formats a .NET object that is also referenced in the built-in formatting files.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains the append path to Update-FormatData.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>The cmdlet does not return any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Update-FormatData also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an Update-FormatData command to update the formatting data for imported commands. You do not need to import the module again.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>update-formatdata </dev:code> <dev:remarks> <maml:para>This command reloads the formatting files that it loaded previously.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>update-formatdata -appendpath trace.format.ps1xml, log.format.ps1xml </dev:code> <dev:remarks> <maml:para>This command reloads the formatting files into the session, including two new files, Trace.format.ps1xml and Log.format.ps1xml.</maml:para> <maml:para>Because the command uses the AppendPath parameter, the formatting data in the new files is loaded after the formatting data from the built-in files.</maml:para> <maml:para>The AppendPath parameter is used because the new files contain formatting data for objects that are not referenced in the built-in files.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>update-formatdata -prependPath c:\test\NewFiles.format.ps1xml # Edit the NewFiles.format.ps1 file. PS C:\>update-formatdata </dev:code> <dev:remarks> <maml:para>This example shows how to reload a formatting file after you have edited it.</maml:para> <maml:para>The first command adds the NewFiles.format.ps1xml file to the session. It uses the PrependPath parameter because the file contains formatting data for objects that are referenced in the built-in files.</maml:para> <maml:para>After adding the NewFiles.format.ps1xml file and testing it in these session, the author edits the file.</maml:para> <maml:para>The second command uses the Update-FormatData cmdlet to reload the formatting files. Because the NewFiles.format.ps1xml file was previously loaded, Update-FormatData automatically reloads it without using parameters.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294023</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Update-List</command:name> <maml:description> <maml:para>Adds items to and removes items from a property value that contains a collection of objects.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Update</command:verb> <command:noun>List</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Update-List cmdlet adds items to and removes items from a property value of an object, and then it returns the updated object. This cmdlet is designed for properties that contain collections of objects.</maml:para> <maml:para>The Add and Remove parameters add individual items to and remove them from the collection. The Replace parameter replaces the entire collection.</maml:para> <maml:para>If you do not specify a property in the command, Update-List returns an object that describes the update instead of updating the object. You can submit the update object to cmdlets that change objects, such as Set-* cmdlets.</maml:para> <maml:para>This cmdlet works only when the property that is being updated supports the IList interface that Update-List uses. Also, any Set-* cmdlets that accept an update must support the IList interface. The core cmdlets that are installed with Windows PowerShell do not support this interface. To determine whether a cmdlet supports Update-List, see the cmdlet Help topic.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Update-List</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Identifies the property that contains the collection that is being updated. If you omit this parameter, Update-List returns an object that represents the change instead of changing the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Add</maml:name> <maml:description> <maml:para>Specifies the property values to be added to the collection. Enter the values in the order that they should appear in the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be updated. You can also pipe the object to be updated to Update-List.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Remove</maml:name> <maml:description> <maml:para>Specifies the property values to be removed from the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Update-List</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Identifies the property that contains the collection that is being updated. If you omit this parameter, Update-List returns an object that represents the change instead of changing the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be updated. You can also pipe the object to be updated to Update-List.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Replace</maml:name> <maml:description> <maml:para>Specifies a new collection. This parameter replaces all items in the original collection with the items specified by this parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Object[]</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Add</maml:name> <maml:description> <maml:para>Specifies the property values to be added to the collection. Enter the values in the order that they should appear in the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to be updated. You can also pipe the object to be updated to Update-List.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Property</maml:name> <maml:description> <maml:para>Identifies the property that contains the collection that is being updated. If you omit this parameter, Update-List returns an object that represents the change instead of changing the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Remove</maml:name> <maml:description> <maml:para>Specifies the property values to be removed from the collection.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Replace</maml:name> <maml:description> <maml:para>Specifies a new collection. This parameter replaces all items in the original collection with the items specified by this parameter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">Object[]</command:parameterValue> <dev:type> <maml:name>Object[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe the objects to be updated to Update-List.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Objects or System.Management.Automation.PSListModifier</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Update-List returns the updated object, or it returns an object that represents the update action.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-mailbox | update-list -Property aliases -Add "A","B" -Remove "X","Y" | set-mailbox </dev:code> <dev:remarks> <maml:para>This command adds A and B and removes X and Y from the Aliases property of a mailbox.</maml:para> <maml:para>The command uses the Get-MailBox cmdlet from Microsoft Exchange Server to get the mailbox. A pipeline operator sends the mailbox object to the Update-List cmdlet.</maml:para> <maml:para>The Update-List command uses the Property parameter to indicate that the Aliases property of the mailbox is being updated, and it uses the Add and Remove parameters to specify the items that are being added and removed from the collection. The Aliases property fulfills the conditions of Update-List, because it stores a collection of Microsoft .NET Framework objects that have Add and Remove methods.</maml:para> <maml:para>The Update-List cmdlet returns the updated mailbox, which is piped to the Set-MailBox cmdlet, which changes the mailbox.</maml:para> <maml:para>For more information about Get-Mailbox, see http://go.microsoft.com/fwlink/?LinkId=111536.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$m = get-mailbox PS C:\>update-list -InputObject $m -Property aliases -Add "A","B" -Remove "X", "Y" | set-mailbox </dev:code> <dev:remarks> <maml:para>This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the previous command, although it has a slightly different format.</maml:para> <maml:para>The command uses the Get-MailBox cmdlet to get the mailbox, and it saves the mailbox in the $m variable. This command uses the InputObject parameter of Update-List to specify the mailbox. The value of InputObject is the mailbox in the $m variable. It uses the Property parameter to specify the Aliases property and the Add and Remove parameters to specify the items being added to and removed from the value of Aliases.</maml:para> <maml:para>The command uses a pipeline operator (|) to send the updated mailbox object to the Set-Mailbox cmdlet, which changes the mailbox.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>get-mailbox | set-mailbox -alias (update-list -Add "A", "B" -Remove "X","Y") </dev:code> <dev:remarks> <maml:para>This command adds A and B to the value of the Aliases property of a mailbox and removes X and Y. This command has the same effect as the two previous commands, but it uses a different procedure to perform the task.</maml:para> <maml:para>Instead of updating the Aliases property of the mailbox before sending it to Set-Mailbox, this command uses Update-List to create an object that represents the change. Then it submits the change to the Alias parameter of Set-Mailbox.</maml:para> <maml:para>The command uses the Get-MailBox cmdlet to get the mailbox. A pipeline operator sends the mailbox object to the Set-Mailbox cmdlet, which changes mailboxes.</maml:para> <maml:para>The command uses the Alias parameter of Set-Mailbox to change the Aliases property of the mailbox object. The value of the Alias parameter is an Update-List command that creates an object that represents the update. The Update-List command is enclosed in parentheses to ensure that it runs before the value of the Alias parameter is evaluated. When the Set-Mailbox command completes, the mailbox is changed.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>update-list -InputObject $a -Property aliases -replace "A", "B" | set-mailbox </dev:code> <dev:remarks> <maml:para>This command uses the Replace operator of Update-List to replace the collection in the Aliases property of the object in $a with a new collection.</maml:para> <maml:para>This command uses the InputObject parameter which, in this case, is equivalent to using a pipeline operator to pass $a to Update-List.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294024</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Select-Object</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Update-TypeData</command:name> <maml:description> <maml:para>Updates the extended type data in the session.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Update</command:verb> <command:noun>TypeData</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Update-TypeData cmdlet updates the extended type data in the session by reloading the Types.ps1xml files into memory and adding new extended type data.</maml:para> <maml:para>By default, Windows PowerShell loads extended type data as it is needed. Without parameters, Update-TypeData reloads all of the Types.ps1xml files that it has loaded in the session, including any type files that you added. You can use the parameters of Update-TypeData to add new type files and add and replace extended type data.</maml:para> <maml:para>The Update-TypeData cmdlet can be used to preload all type data. This feature is particularly useful when you are developing types and want to load those new types for testing purposes.</maml:para> <maml:para>Beginning in Windows PowerShell 3.0, you can use Update-TypeData to add and replace extended type data in the session without using a Types.ps1xml file. Type data that is added dynamically, that is, without a file, is added only to the current session. To add the type data to all sessions, add an Update-TypeData command to your Windows PowerShell profile. For more information, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729).</maml:para> <maml:para>Also, beginning in Windows PowerShell 3.0, you can use the Get-TypeData cmdlet to get the extended types in the current session and the Remove-TypeData cmdlet to delete extended types from the current session.</maml:para> <maml:para>Exceptions that occur in properties, or from adding properties to an Update-TypeData command, do not report errors to StdErr. This is to suppress exceptions that would occur in many common types during formatting and outputting. If you are getting .NET Framework properties, you can work around the suppression of exceptions by using method syntax instead, as shown in the following example:</maml:para> <maml:para>"hello".get_Length()</maml:para> <maml:para>Note that method syntax can only be used with .NET Framework properties. Properties that are added by running the Update-TypeData cmdlet cannot use method syntax.</maml:para> <maml:para>For more information about the *types.ps1xml files in Windows PowerShell, see about_Types.ps1xml (http://technet.microsoft.com/library/hh847881.aspx).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Update-TypeData</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="PSPath,Path"> <maml:name>AppendPath</maml:name> <maml:description> <maml:para>Specifies the path to optional .ps1xml files. The specified files are loaded in the order that they are listed after the built-in files are loaded. You can also pipe an AppendPath value to Update-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PrependPath</maml:name> <maml:description> <maml:para>Specifies the path to the optional .ps1xml files. The specified files are loaded in the order that they are listed before the built-in files are loaded.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Update-TypeData</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DefaultDisplayProperty</maml:name> <maml:description> <maml:para>Specifies the property of the type that is displayed by the Format-Wide cmdlet when no other properties are specified.</maml:para> <maml:para>Type the name of a standard or extended property of the type. The value of this parameter can be the name of a type that is added in the same command.</maml:para> <maml:para>This value is effective only when there are no wide views defined for the type in a Format.ps1xml file.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DefaultDisplayPropertySet</maml:name> <maml:description> <maml:para>Specifies one or more properties of the type. These properties are displayed by the Format-List cmdlet when no other properties are specified.</maml:para> <maml:para>Type the names of standard or extended properties of the type. The value of this parameter can be the names of types that are added in the same command.</maml:para> <maml:para>This value is effective only when there are no list views defined for the type in a Format.ps1xml file.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DefaultKeyPropertySet</maml:name> <maml:description> <maml:para>Specifies one or more properties of the type. These properties are used by the Group-Object and Sort-Object cmdlets when no other properties are specified.</maml:para> <maml:para>Type the names of standard or extended properties of the type. The value of this parameter can be the names of types that are added in the same command.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Uses the specified type data, even if type data has already been specified for that type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InheritPropertySerializationSet</maml:name> <maml:description> <maml:para>Determines whether the set of properties that are serialized is inherited. The default value is $Null</maml:para> <maml:para>Valid values are:</maml:para> <maml:para> -- $True: The property set is inherited. -- $False: The property set is not inherited. -- $Null: Inheritance is not defined.</maml:para> <maml:para>This parameter is valid only when the value of the SerializationMethod parameter is SpecificProperties. When the value of this parameter is $False, the PropertySerializationSet parameter is required.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Boolean</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MemberName</maml:name> <maml:description> <maml:para>Specifies the name of a property or method.</maml:para> <maml:para>Use this parameter with the TypeName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MemberType</maml:name> <maml:description> <maml:para>Specifies the type of the member to add or change.</maml:para> <maml:para>Use this parameter with the TypeName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>The valid values for this parameter are: AliasProperty, CodeMethod, CodeProperty, Noteproperty, ScriptMethod, and ScriptProperty.</maml:para> <maml:para>For information about these values, see "PSMemberTypes Enumeration" in MSDN at <maml:navigationLink><maml:linkText>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.psmembertypes(v=vs.85).aspx</maml:linkText><maml:uri></maml:uri></maml:navigationLink>. </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">AliasProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">CodeProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">Property</command:parameterValue> <command:parameterValue required="false" variableLength="false">NoteProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">ScriptProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">Properties</command:parameterValue> <command:parameterValue required="false" variableLength="false">PropertySet</command:parameterValue> <command:parameterValue required="false" variableLength="false">Method</command:parameterValue> <command:parameterValue required="false" variableLength="false">CodeMethod</command:parameterValue> <command:parameterValue required="false" variableLength="false">ScriptMethod</command:parameterValue> <command:parameterValue required="false" variableLength="false">Methods</command:parameterValue> <command:parameterValue required="false" variableLength="false">ParameterizedProperty</command:parameterValue> <command:parameterValue required="false" variableLength="false">MemberSet</command:parameterValue> <command:parameterValue required="false" variableLength="false">Event</command:parameterValue> <command:parameterValue required="false" variableLength="false">Dynamic</command:parameterValue> <command:parameterValue required="false" variableLength="false">All</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PropertySerializationSet</maml:name> <maml:description> <maml:para>Specifies the names of properties that are serialized. Use this parameter when the value of the SerializationMethod parameter is SpecificProperties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SecondValue</maml:name> <maml:description> <maml:para>Specifies additional values for AliasProperty, ScriptProperty, CodeProperty, or CodeMethod members.</maml:para> <maml:para>Use this parameter with the TypeName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>When the value of the MemberType parameter is AliasProperty, the value of the SecondValue parameter must be a data type. Windows PowerShell converts ("casts") the value of the alias property to the specified type. For example, if you add an alias property that provides an alternate name for a string property, you can also specify a SecondValue of System.Int32 to convert the aliased string value to an integer.</maml:para> <maml:para>When the value of the MemberType parameter is ScriptProperty, you can use the SecondValue parameter to specify an additional script block. The script block in the value of the Value parameter gets the value of a variable. The script block in the value of the SecondValue parameter set the value of the variable.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SerializationDepth</maml:name> <maml:description> <maml:para>Specifies how many levels of type objects are serialized as strings. The default value, 1, serializes the object and its properties. A value of 0 serializes the object, but not its properties. A value of 2 serializes the object, its properties, and any objects in property values.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SerializationMethod</maml:name> <maml:description> <maml:para>Specifies a serialization method for the type. A serialization method determines which properties of the type are serialized and the technique that is used to serialize them.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- AllPublicProperties: Serialize all public properties of the type. You can use the SerializationDepth parameter to determine whether child properties are serialized.</maml:para> <maml:para>-- String: Serialize the type as a string. You can use the StringSerializationSource to specify a property of the type to use as the serialization result. Otherwise, the type is serialized by using the ToString method of the object.</maml:para> <maml:para>-- SpecificProperties Serialize only the specified properties of this type. Use the PropertySerializationSet parameter to specify the properties of the type that are serialized. You can also use the InheritPropertySerializationSet parameter to determine whether the property set is inherited and the SerializationDepth parameter to determine whether child properties are serialized.</maml:para> <maml:para>In Windows PowerShell, serialization methods are stored in PSStandardMembers internal objects.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>StringSerializationSource</maml:name> <maml:description> <maml:para>Specifies the name of a property of the type. The value of specified property is used as the serialization result. This parameter is valid only when the value of the SerializationMethod parameter is String.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TargetTypeForDeserialization</maml:name> <maml:description> <maml:para>Specifies the type to which object of this type are converted when they are deserialized.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Type</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeAdapter</maml:name> <maml:description> <maml:para>Specifies the type of a type adapter, such as Microsoft.PowerShell.Cim.CimInstanceAdapter. A type adapter enables Windows PowerShell to get the members of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Type</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeConverter</maml:name> <maml:description> <maml:para>Specifies a type converter to convert values between different types. If a type converter is defined for a type, an instance of the type converter is used for the conversion.</maml:para> <maml:para>Enter a System.Type value that is derived from the System.ComponentModel.TypeConverter or System.Management.Automation.PSTypeConverter classes.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Type</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the value of the property or method.</maml:para> <maml:para>If you add an AliasProperty, CodeProperty, ScriptProperty, or CodeMethod member, you can use the SecondValue parameter to add additional information..</maml:para> <maml:para>Use this parameter with the MemberName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies the name of the type to extend.</maml:para> <maml:para>For types in the System namespace, enter the short name. Otherwise, the full type name is required. Wildcards are not supported. </maml:para> <maml:para>You can pipe type names to Update-TypeData. When you pipe an object to Update-TypeData, Update-TypeData gets the type name of the object and type data to the object type.</maml:para> <maml:para>Use this parameter with the MemberName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Update-TypeData</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>TypeData</maml:name> <maml:description> <maml:para>Adds the specified type data to the session. Enter a variable that contains a TypeData object or a command that gets a TypeData object, such as a Get-TypeData command. You can also pipe a TypeData object to Update-TypeData.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">TypeData[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Uses the specified type data, even if type data has already been specified for that type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="PSPath,Path"> <maml:name>AppendPath</maml:name> <maml:description> <maml:para>Specifies the path to optional .ps1xml files. The specified files are loaded in the order that they are listed after the built-in files are loaded. You can also pipe an AppendPath value to Update-TypeData.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String]</command:parameterValue> <dev:type> <maml:name>System.String]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PrependPath</maml:name> <maml:description> <maml:para>Specifies the path to the optional .ps1xml files. The specified files are loaded in the order that they are listed before the built-in files are loaded.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DefaultDisplayProperty</maml:name> <maml:description> <maml:para>Specifies the property of the type that is displayed by the Format-Wide cmdlet when no other properties are specified.</maml:para> <maml:para>Type the name of a standard or extended property of the type. The value of this parameter can be the name of a type that is added in the same command.</maml:para> <maml:para>This value is effective only when there are no wide views defined for the type in a Format.ps1xml file.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DefaultDisplayPropertySet</maml:name> <maml:description> <maml:para>Specifies one or more properties of the type. These properties are displayed by the Format-List cmdlet when no other properties are specified.</maml:para> <maml:para>Type the names of standard or extended properties of the type. The value of this parameter can be the names of types that are added in the same command.</maml:para> <maml:para>This value is effective only when there are no list views defined for the type in a Format.ps1xml file.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>DefaultKeyPropertySet</maml:name> <maml:description> <maml:para>Specifies one or more properties of the type. These properties are used by the Group-Object and Sort-Object cmdlets when no other properties are specified.</maml:para> <maml:para>Type the names of standard or extended properties of the type. The value of this parameter can be the names of types that are added in the same command.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Uses the specified type data, even if type data has already been specified for that type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>InheritPropertySerializationSet</maml:name> <maml:description> <maml:para>Determines whether the set of properties that are serialized is inherited. The default value is $Null</maml:para> <maml:para>Valid values are:</maml:para> <maml:para> -- $True: The property set is inherited. -- $False: The property set is not inherited. -- $Null: Inheritance is not defined.</maml:para> <maml:para>This parameter is valid only when the value of the SerializationMethod parameter is SpecificProperties. When the value of this parameter is $False, the PropertySerializationSet parameter is required.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Boolean</command:parameterValue> <dev:type> <maml:name>Boolean</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MemberName</maml:name> <maml:description> <maml:para>Specifies the name of a property or method.</maml:para> <maml:para>Use this parameter with the TypeName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>MemberType</maml:name> <maml:description> <maml:para>Specifies the type of the member to add or change.</maml:para> <maml:para>Use this parameter with the TypeName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>The valid values for this parameter are: AliasProperty, CodeMethod, CodeProperty, Noteproperty, ScriptMethod, and ScriptProperty.</maml:para> <maml:para>For information about these values, see "PSMemberTypes Enumeration" in MSDN at <maml:navigationLink><maml:linkText>http://msdn.microsoft.com/en-us/library/windows/desktop/system.management.automation.psmembertypes(v=vs.85).aspx</maml:linkText><maml:uri></maml:uri></maml:navigationLink>. </maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSMemberTypes</command:parameterValue> <dev:type> <maml:name>PSMemberTypes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PropertySerializationSet</maml:name> <maml:description> <maml:para>Specifies the names of properties that are serialized. Use this parameter when the value of the SerializationMethod parameter is SpecificProperties.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SecondValue</maml:name> <maml:description> <maml:para>Specifies additional values for AliasProperty, ScriptProperty, CodeProperty, or CodeMethod members.</maml:para> <maml:para>Use this parameter with the TypeName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>When the value of the MemberType parameter is AliasProperty, the value of the SecondValue parameter must be a data type. Windows PowerShell converts ("casts") the value of the alias property to the specified type. For example, if you add an alias property that provides an alternate name for a string property, you can also specify a SecondValue of System.Int32 to convert the aliased string value to an integer.</maml:para> <maml:para>When the value of the MemberType parameter is ScriptProperty, you can use the SecondValue parameter to specify an additional script block. The script block in the value of the Value parameter gets the value of a variable. The script block in the value of the SecondValue parameter set the value of the variable.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SerializationDepth</maml:name> <maml:description> <maml:para>Specifies how many levels of type objects are serialized as strings. The default value, 1, serializes the object and its properties. A value of 0 serializes the object, but not its properties. A value of 2 serializes the object, its properties, and any objects in property values.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SerializationMethod</maml:name> <maml:description> <maml:para>Specifies a serialization method for the type. A serialization method determines which properties of the type are serialized and the technique that is used to serialize them.</maml:para> <maml:para>Valid values are:</maml:para> <maml:para>-- AllPublicProperties: Serialize all public properties of the type. You can use the SerializationDepth parameter to determine whether child properties are serialized.</maml:para> <maml:para>-- String: Serialize the type as a string. You can use the StringSerializationSource to specify a property of the type to use as the serialization result. Otherwise, the type is serialized by using the ToString method of the object.</maml:para> <maml:para>-- SpecificProperties Serialize only the specified properties of this type. Use the PropertySerializationSet parameter to specify the properties of the type that are serialized. You can also use the InheritPropertySerializationSet parameter to determine whether the property set is inherited and the SerializationDepth parameter to determine whether child properties are serialized.</maml:para> <maml:para>In Windows PowerShell, serialization methods are stored in PSStandardMembers internal objects.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>StringSerializationSource</maml:name> <maml:description> <maml:para>Specifies the name of a property of the type. The value of specified property is used as the serialization result. This parameter is valid only when the value of the SerializationMethod parameter is String.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TargetTypeForDeserialization</maml:name> <maml:description> <maml:para>Specifies the type to which object of this type are converted when they are deserialized.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Type</command:parameterValue> <dev:type> <maml:name>Type</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeAdapter</maml:name> <maml:description> <maml:para>Specifies the type of a type adapter, such as Microsoft.PowerShell.Cim.CimInstanceAdapter. A type adapter enables Windows PowerShell to get the members of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Type</command:parameterValue> <dev:type> <maml:name>Type</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TypeConverter</maml:name> <maml:description> <maml:para>Specifies a type converter to convert values between different types. If a type converter is defined for a type, an instance of the type converter is used for the conversion.</maml:para> <maml:para>Enter a System.Type value that is derived from the System.ComponentModel.TypeConverter or System.Management.Automation.PSTypeConverter classes.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Type</command:parameterValue> <dev:type> <maml:name>Type</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue, ByPropertyName)" position="1" aliases="none"> <maml:name>TypeData</maml:name> <maml:description> <maml:para>Adds the specified type data to the session. Enter a variable that contains a TypeData object or a command that gets a TypeData object, such as a Get-TypeData command. You can also pipe a TypeData object to Update-TypeData.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">TypeData[]</command:parameterValue> <dev:type> <maml:name>TypeData[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named" aliases="none"> <maml:name>TypeName</maml:name> <maml:description> <maml:para>Specifies the name of the type to extend.</maml:para> <maml:para>For types in the System namespace, enter the short name. Otherwise, the full type name is required. Wildcards are not supported. </maml:para> <maml:para>You can pipe type names to Update-TypeData. When you pipe an object to Update-TypeData, Update-TypeData gets the type name of the object and type data to the object type.</maml:para> <maml:para>Use this parameter with the MemberName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Value</maml:name> <maml:description> <maml:para>Specifies the value of the property or method.</maml:para> <maml:para>If you add an AliasProperty, CodeProperty, ScriptProperty, or CodeMethod member, you can use the SecondValue parameter to add additional information..</maml:para> <maml:para>Use this parameter with the MemberName, MemberType, Value and SecondValue parameters to add or change a property or method of a type.</maml:para> <maml:para>This parameter is introduced in Windows PowerShell 3.0.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>false</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains the values of the AppendPath, TypeName, or TypeData parameters to Update-TypeData.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>This cmdlet does not return any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Update-Typedata </dev:code> <dev:remarks> <maml:para>This command updates the extended type configuration from the *.types.ps1xml files that have already been used in the session.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>The first command updates the extended type configuration from the *.types.ps1xml files, processing the TypesA.types.ps1xml and TypesB.types.ps1xml files first. PS C:\>Update-Typedata -PrependPath TypesA.types.ps1xml, TypesB.types.ps1xml The second command shows how to update the TypesA.types.ps1xml again, such as you might do if you added or changed a type in the file. You can either repeat the previous command for the TypesA.types.ps1xml file, or run an Update-Typedata command without parameters, because TypesA.types.ps1xml is already in the type file list for the current session. PS C:\>Update-Typedata -PrependPath TypesA.types.ps1xml -or- Update-Typedata </dev:code> <dev:remarks> <maml:para>This example show how to update the types in a type file multiple times in the same session.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Update-TypeData -TypeName System.DateTime -MemberType ScriptProperty -MemberName Quarter -Value {if ($this.Month -in @(1,2,3)) {"Q1"} elseif ($this.Month -in @(4,5,6)) {"Q2"} elseif ($this.Month -in @(7,8,9)) {"Q3"} else {"Q4"} } PS C:\>(Get-Date).QuarterQ1 </dev:code> <dev:remarks> <maml:para>This example uses Update-TypeData to add the Quarter script property to System.DateTime objects in the current session, such as those returned by the Get-Date cmdlet.</maml:para> <maml:para>The Update-TypeData command uses the TypeName parameter to specify the System.DateTime type, the MemberName parameter to specify a name for the new property, the MemberType property to specify the ScriptProperty type, and the Value parameter to specify the script that determines the annual quarter.</maml:para> <maml:para>The value of the Value property is a script that calculates the current annual quarter. The script block the $this automatic variable to represent the current instance of the object and the In operator to determine whether the month value appears in each integer array. For more information about the In operator, see about_Comparison_Operators (http://go.microsoft.com/fwlink/?LinkID=113217).</maml:para> <maml:para>The second command gets the new Quarter property of the current date.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Update-TypeData -TypeName System.DateTime -DefaultDisplayPropertySet DateTime, DayOfYear, Quarter PS C:\>Get-Date | Format-List Thursday, March 15, 2012 12:00:00 AM DayOfYear : 75 Quarter : Q1 </dev:code> <dev:remarks> <maml:para>This example shows how to set the properties of a type that display in lists by default, that is, when no properties are specified. Because the type data is not specified in a Types.ps1xml file, it is effective only in the current session.</maml:para> <maml:para>The first command uses the Update-TypeData cmdlet to set the default list properties for the System.DateTime type. The command uses the TypeName parameter to specify the type and the DefaultDisplayPropertySet parameter to specify the default properties for a list. The selected properties include the new Quarter script property that was added in a previous example.</maml:para> <maml:para>The second command uses the Get-Date cmdlet to get a System.DateTime object that represents the current date. The command uses a pipeline operator (|) to send the DateTime object to the Format-List cmdlet. Because the Format-List command does not specify the properties to display in the list, Windows PowerShell uses the default values that were established by the Update-TypeData command.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 5 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-Module | Update-TypeData -MemberType ScriptProperty -MemberName SupportsUpdatableHelp -Value {if ($this.HelpInfoUri) {$True} else {$False}} Get-Module -ListAvailable | Format-Table Name, SupportsUpdatableHelp Name SupportsUpdatableHelp ---- --------------------- Microsoft.PowerShell.Diagnostics True Microsoft.PowerShell.Host True Microsoft.PowerShell.Management True Microsoft.PowerShell.Security True Microsoft.PowerShell.Utility True Microsoft.WSMan.Management True PSDiagnostics False PSScheduledJob True PSWorkflow True ServerManager True TroubleshootingPack False </dev:code> <dev:remarks> <maml:para>This example demonstrates that when you pipe an object to Update-TypeData, Update-TypeData adds extended type data for the object type. </maml:para> <maml:para>This technique is quicker than using the Get-Member cmdlet or the Get-Type method to get the object type. However, if you pipe a collection of objects to Update-TypeData, it updates the type data of the first object type and then returns an error for all other objects in the collection because the member is already defined on the type.</maml:para> <maml:para>The first command uses the Get-Module cmdlet to get the PSScheduledJob module. The command pipes the module object to the Update-TypeData cmdlet, which updates the type data for the System.Management.Automation.PSModuleInfo type and the types derived from it, such as the ModuleInfoGrouping type that Get-Module returns when you use the ListAvailable parameter in the command.</maml:para> <maml:para>The Update-TypeData commands adds the SupportsUpdatableHelp script property to all imported modules. The value of the Value parameter is a script that returns $True if the HelpInfoUri property of the module is populated and $False otherwise.</maml:para> <maml:para>The second command pipes the module objects from Get-Module to the Format-Table cmdlet, which displays the Name and SupportsUpdatableHelp properties of all modules in a list.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294025</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Types.ps1xml</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-TypeData</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-TypeData</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Wait-Debugger</command:name> <maml:description> <maml:para>Stops a script in the debugger before running the next statement in the script.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Wait</command:verb> <command:noun>Debugger</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This content is coming in a future release.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Wait-Debugger</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> 2: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code> PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Wait-Event</command:name> <maml:description> <maml:para>Waits until a particular event is raised before continuing to run.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Wait</command:verb> <command:noun>Event</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Wait-Event cmdlet suspends execution of a script or function until a particular event is raised. Execution resumes when the event is detected. To cancel the wait, press CTRL+C.</maml:para> <maml:para>This feature provides an alternative to polling for an event. It also allows you to determine the response to an event in two different ways: by using the Action parameter of the event subscription and by waiting for an event to return and then respond with an action.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Wait-Event</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Waits only for events with the specified source identifier. By default, Wait-Events waits for any event.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TimeoutSec"> <maml:name>Timeout</maml:name> <maml:description> <maml:para>Determines the maximum time, in seconds, that Wait-Event waits for the event to occur. The default, -1, waits indefinitely. The timing starts when you submit the Wait-Event command.</maml:para> <maml:para>If the specified time is exceeded, the wait ends and the command prompt returns, even if the event has not been raised. No error message is displayed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByPropertyName)" position="1" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Waits only for events with the specified source identifier. By default, Wait-Events waits for any event.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TimeoutSec"> <maml:name>Timeout</maml:name> <maml:description> <maml:para>Determines the maximum time, in seconds, that Wait-Event waits for the event to occur. The default, -1, waits indefinitely. The timing starts when you submit the Wait-Event command.</maml:para> <maml:para>If the specified time is exceeded, the wait ends and the command prompt returns, even if the event has not been raised. No error message is displayed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSEventArgs</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para> </maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>wait-event </dev:code> <dev:remarks> <maml:para>This command waits for the next event that is raised.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>wait-event -sourceIdentifier "ProcessStarted" </dev:code> <dev:remarks> <maml:para>This command waits for the next event that is raised and that has a source identifier of "ProcessStarted".</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$timer.Interval = 2000 PS C:\>$timer.Autoreset = $false PS C:\>$timer.Enabled = $true; Wait-Event Timer.Elapsed # After 2 seconds EventIdentifier : 12 Sender : System.Timers.Timer SourceEventArgs : System.Timers.ElapsedEventArgs SourceArgs : {System.Timers.Timer, System.Timers.ElapsedEventArgs} SourceIdentifier : Timer.Elapsed TimeGenerated : 6/10/2008 3:24:18 PM MessageData : ForwardEvent : False </dev:code> <dev:remarks> <maml:para>This command uses the Wait-Event cmdlet to wait for a timer event on a timer that is set for 2000 milliseconds.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>wait-event -sourceIdentifier "ProcessStarted" -timeout 90 </dev:code> <dev:remarks> <maml:para>This command waits up to 90 seconds for the next event that is raised and that has a source identifier of "ProcessStarted". If the specified time expires, the wait ends.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294026</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-EventSubscriber</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>New-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-EngineEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-ObjectEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Register-WmiEvent</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Unregister-Event</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Wait-Event</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Debug</command:name> <maml:description> <maml:para>Writes a debug message to the console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Debug</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Debug cmdlet writes debug messages to the console from a script or command.</maml:para> <maml:para>By default, debug messages are not displayed in the console, but you can display them by using the Debug parameter or the $DebugPreference variable.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Debug</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the debug message to send to the console.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the debug message to send to the console.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains a debug message to Write-Debug.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Debug writes only to the debug stream. It does not return any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Write-Debug "Cannot open file." </dev:code> <dev:remarks> <maml:para>This command writes a debug message. Because the value of $DebugPreference is "SilentlyContinue", the message is not displayed in the console.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$DebugPreference SilentlyContinue PS C:\>Write-Debug "Cannot open file." PS C:\> PS C:\>Write-Debug "Cannot open file." -debug DEBUG: Cannot open file. </dev:code> <dev:remarks> <maml:para>This example shows how to use the Debug common parameter to override the value of the $DebugPreference variable for a particular command.</maml:para> <maml:para>The first command displays the value of the $DebugPreference variable, which is "SilentlyContinue", the default.</maml:para> <maml:para>The second command writes a debug message but, because of the value of $DebugPreference, the message does not appear.</maml:para> <maml:para>The third command writes a debug message. It uses the Debug common parameter to override the value of $DebugPreference and to display the debug messages resulting from this command.</maml:para> <maml:para>As a result, even though the value of $DebugPreference is "SilentlyContinue", the debug message appears.</maml:para> <maml:para>For more information about the Debug common parameter, see about_CommonParameters.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$DebugPreference SilentlyContinue PS C:\>Write-Debug "Cannot open file." PS C:\> PS C:\>$DebugPreference = "Continue" PS C:\>Write-Debug "Cannot open file." DEBUG: Cannot open file. </dev:code> <dev:remarks> <maml:para>This command shows the effect of changing the value of the $DebugPreference variable on the display of debug messages.</maml:para> <maml:para>The first command displays the value of the $DebugPreference variable, which is "SilentlyContinue", the default.</maml:para> <maml:para>The second command writes a debug message but, because of the value of $DebugPreference, the message does not appear.</maml:para> <maml:para>The third command assigns a value of "Continue" to the $DebugPreference variable.</maml:para> <maml:para>The fourth command writes a debug message, which appears on the console.</maml:para> <maml:para>For more information about $DebugPreference, see about_Preference_Variables.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294027</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Error</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Output</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Progress</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Verbose</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Warning</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Error</command:name> <maml:description> <maml:para>Writes an object to the error stream.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Error</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Error cmdlet declares a non-terminating error. By default, errors are sent in the error stream to the host program to be displayed, along with output.</maml:para> <maml:para>To write a non-terminating error, enter an error message string, an ErrorRecord object, or an Exception object. Use the other parameters of Write-Error to populate the error record.</maml:para> <maml:para>Non-terminating errors write an error to the error stream, but they do not stop command processing. If a non-terminating error is declared on one item in a collection of input items, the command continues to process the other items in the collection.</maml:para> <maml:para>To declare a terminating error, use the Throw keyword. For more information, see about_Throw (http://go.microsoft.com/fwlink/?LinkID=145153). </maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Error</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the message text of the error. If the text includes spaces or special characters, enclose it in quotation marks. You can also pipe a message string to Write-Error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Category</maml:name> <maml:description> <maml:para>Specifies the category of the error. The default value is NotSpecified.</maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">NotSpecified</command:parameterValue> <command:parameterValue required="false" variableLength="false">OpenError</command:parameterValue> <command:parameterValue required="false" variableLength="false">CloseError</command:parameterValue> <command:parameterValue required="false" variableLength="false">DeviceError</command:parameterValue> <command:parameterValue required="false" variableLength="false">DeadlockDetected</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidArgument</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidData</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidOperation</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidResult</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidType</command:parameterValue> <command:parameterValue required="false" variableLength="false">MetadataError</command:parameterValue> <command:parameterValue required="false" variableLength="false">NotImplemented</command:parameterValue> <command:parameterValue required="false" variableLength="false">NotInstalled</command:parameterValue> <command:parameterValue required="false" variableLength="false">ObjectNotFound</command:parameterValue> <command:parameterValue required="false" variableLength="false">OperationStopped</command:parameterValue> <command:parameterValue required="false" variableLength="false">OperationTimeout</command:parameterValue> <command:parameterValue required="false" variableLength="false">SyntaxError</command:parameterValue> <command:parameterValue required="false" variableLength="false">ParserError</command:parameterValue> <command:parameterValue required="false" variableLength="false">PermissionDenied</command:parameterValue> <command:parameterValue required="false" variableLength="false">ResourceBusy</command:parameterValue> <command:parameterValue required="false" variableLength="false">ResourceExists</command:parameterValue> <command:parameterValue required="false" variableLength="false">ResourceUnavailable</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadError</command:parameterValue> <command:parameterValue required="false" variableLength="false">WriteError</command:parameterValue> <command:parameterValue required="false" variableLength="false">FromStdErr</command:parameterValue> <command:parameterValue required="false" variableLength="false">SecurityError</command:parameterValue> <command:parameterValue required="false" variableLength="false">ProtocolError</command:parameterValue> <command:parameterValue required="false" variableLength="false">ConnectionError</command:parameterValue> <command:parameterValue required="false" variableLength="false">AuthenticationError</command:parameterValue> <command:parameterValue required="false" variableLength="false">LimitsExceeded</command:parameterValue> <command:parameterValue required="false" variableLength="false">QuotaExceeded</command:parameterValue> <command:parameterValue required="false" variableLength="false">NotEnabled</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Activity"> <maml:name>CategoryActivity</maml:name> <maml:description> <maml:para>Describes the action that caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Reason"> <maml:name>CategoryReason</maml:name> <maml:description> <maml:para>Explains how or why the activity caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetName"> <maml:name>CategoryTargetName</maml:name> <maml:description> <maml:para>Specifies the name of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetType"> <maml:name>CategoryTargetType</maml:name> <maml:description> <maml:para>Specifies the type of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>Specifies an ID string to identify the error. The string should be unique to the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RecommendedAction</maml:name> <maml:description> <maml:para>Describes the action that the user should take to resolve or prevent the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TargetObject</maml:name> <maml:description> <maml:para>Specifies the object that was being processed when the error occurred. Enter the object (such as a string), a variable that contains the object, or a command that gets the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Write-Error</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Category</maml:name> <maml:description> <maml:para>Specifies the category of the error. The default value is NotSpecified.</maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">NotSpecified</command:parameterValue> <command:parameterValue required="false" variableLength="false">OpenError</command:parameterValue> <command:parameterValue required="false" variableLength="false">CloseError</command:parameterValue> <command:parameterValue required="false" variableLength="false">DeviceError</command:parameterValue> <command:parameterValue required="false" variableLength="false">DeadlockDetected</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidArgument</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidData</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidOperation</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidResult</command:parameterValue> <command:parameterValue required="false" variableLength="false">InvalidType</command:parameterValue> <command:parameterValue required="false" variableLength="false">MetadataError</command:parameterValue> <command:parameterValue required="false" variableLength="false">NotImplemented</command:parameterValue> <command:parameterValue required="false" variableLength="false">NotInstalled</command:parameterValue> <command:parameterValue required="false" variableLength="false">ObjectNotFound</command:parameterValue> <command:parameterValue required="false" variableLength="false">OperationStopped</command:parameterValue> <command:parameterValue required="false" variableLength="false">OperationTimeout</command:parameterValue> <command:parameterValue required="false" variableLength="false">SyntaxError</command:parameterValue> <command:parameterValue required="false" variableLength="false">ParserError</command:parameterValue> <command:parameterValue required="false" variableLength="false">PermissionDenied</command:parameterValue> <command:parameterValue required="false" variableLength="false">ResourceBusy</command:parameterValue> <command:parameterValue required="false" variableLength="false">ResourceExists</command:parameterValue> <command:parameterValue required="false" variableLength="false">ResourceUnavailable</command:parameterValue> <command:parameterValue required="false" variableLength="false">ReadError</command:parameterValue> <command:parameterValue required="false" variableLength="false">WriteError</command:parameterValue> <command:parameterValue required="false" variableLength="false">FromStdErr</command:parameterValue> <command:parameterValue required="false" variableLength="false">SecurityError</command:parameterValue> <command:parameterValue required="false" variableLength="false">ProtocolError</command:parameterValue> <command:parameterValue required="false" variableLength="false">ConnectionError</command:parameterValue> <command:parameterValue required="false" variableLength="false">AuthenticationError</command:parameterValue> <command:parameterValue required="false" variableLength="false">LimitsExceeded</command:parameterValue> <command:parameterValue required="false" variableLength="false">QuotaExceeded</command:parameterValue> <command:parameterValue required="false" variableLength="false">NotEnabled</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Activity"> <maml:name>CategoryActivity</maml:name> <maml:description> <maml:para>Describes the action that caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Reason"> <maml:name>CategoryReason</maml:name> <maml:description> <maml:para>Explains how or why the activity caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetName"> <maml:name>CategoryTargetName</maml:name> <maml:description> <maml:para>Specifies the name of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetType"> <maml:name>CategoryTargetType</maml:name> <maml:description> <maml:para>Specifies the type of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>Specifies an ID string to identify the error. The string should be unique to the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the message text of the error. If the text includes spaces or special characters, enclose it in quotation marks. You can also pipe a message string to Write-Error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RecommendedAction</maml:name> <maml:description> <maml:para>Describes the action that the user should take to resolve or prevent the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TargetObject</maml:name> <maml:description> <maml:para>Specifies the object that was being processed when the error occurred. Enter the object (such as a string), a variable that contains the object, or a command that gets the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exception</maml:name> <maml:description> <maml:para>Specifies an exception object that represents the error. Use the properties of the object to describe the error.</maml:para> <maml:para>To create an exception object, use a hash table or use the New-Object cmdlet. </maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Exception</command:parameterValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Write-Error</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Activity"> <maml:name>CategoryActivity</maml:name> <maml:description> <maml:para>Describes the action that caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Reason"> <maml:name>CategoryReason</maml:name> <maml:description> <maml:para>Explains how or why the activity caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetName"> <maml:name>CategoryTargetName</maml:name> <maml:description> <maml:para>Specifies the name of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetType"> <maml:name>CategoryTargetType</maml:name> <maml:description> <maml:para>Specifies the type of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RecommendedAction</maml:name> <maml:description> <maml:para>Describes the action that the user should take to resolve or prevent the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>Specifies an error record object that represents the error. Use the properties of the object to describe the error.</maml:para> <maml:para>To create an error record object, use the New-Object cmdlet or get an error record object from the array in the $Error automatic variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Category</maml:name> <maml:description> <maml:para>Specifies the category of the error. The default value is NotSpecified.</maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ErrorCategory</command:parameterValue> <dev:type> <maml:name>ErrorCategory</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Activity"> <maml:name>CategoryActivity</maml:name> <maml:description> <maml:para>Describes the action that caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="Reason"> <maml:name>CategoryReason</maml:name> <maml:description> <maml:para>Explains how or why the activity caused the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetName"> <maml:name>CategoryTargetName</maml:name> <maml:description> <maml:para>Specifies the name of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="TargetType"> <maml:name>CategoryTargetType</maml:name> <maml:description> <maml:para>Specifies the type of the object that was being processed when the error occurred.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorId</maml:name> <maml:description> <maml:para>Specifies an ID string to identify the error. The string should be unique to the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>Specifies an error record object that represents the error. Use the properties of the object to describe the error.</maml:para> <maml:para>To create an error record object, use the New-Object cmdlet or get an error record object from the array in the $Error automatic variable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ErrorRecord</command:parameterValue> <dev:type> <maml:name>ErrorRecord</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Exception</maml:name> <maml:description> <maml:para>Specifies an exception object that represents the error. Use the properties of the object to describe the error.</maml:para> <maml:para>To create an exception object, use a hash table or use the New-Object cmdlet. </maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Exception</command:parameterValue> <dev:type> <maml:name>Exception</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> <maml:para>For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the message text of the error. If the text includes spaces or special characters, enclose it in quotation marks. You can also pipe a message string to Write-Error.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>RecommendedAction</maml:name> <maml:description> <maml:para>Describes the action that the user should take to resolve or prevent the error.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>TargetObject</maml:name> <maml:description> <maml:para>Specifies the object that was being processed when the error occurred. Enter the object (such as a string), a variable that contains the object, or a command that gets the object.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains an error message to Write-Error.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Error object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Error writes only to the error stream. It does not return any objects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Get-ChildItem | ForEach-Object { if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey") {Write-Error "Invalid object" -ErrorID B1 -Targetobject $_ } else {$_ } } </dev:code> <dev:remarks> <maml:para>This command declares a non-terminating error when the Get-ChildItem cmdlet returns a Microsoft.Win32.RegistryKey object, such as the objects in the HKLM: or HKCU: drives of the Windows PowerShell Registry provider.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Write-Error "Access denied." </dev:code> <dev:remarks> <maml:para>This command declares a non-terminating error and writes an "Access denied" error. The command uses the Message parameter to specify the message, but omits the optional Message parameter name.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Write-Error -Message "Error: Too many input values." -Category InvalidArgument </dev:code> <dev:remarks> <maml:para>This command declares a non-terminating error and specifies an error category.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$e = [System.Exception]@{$e = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="http://go.microsoft.com/fwlink/?LinkID=113425"}HelpLink="http://go.microsoft.com/fwlink/?LinkID=113425"} PS C:\> Write-Error $e -Message "Files not found. The $Files location does not contain any XML files." </dev:code> <dev:remarks> <maml:para>This command uses an Exception object to declare a non-terminating error.</maml:para> <maml:para>The first command uses a hash table to create the System.Exception object. It saves the exception object in the $e variable. You can use a hash table to create any object of a type that has a null constructor. </maml:para> <maml:para>The second command uses the Write-Error cmdlet to declare a non-terminating error. The value of the Exception parameter is the Exception object in the $e variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294028</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Debug</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Output</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Progress</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Verbose</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Warning</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Host</command:name> <maml:description> <maml:para>Writes customized output to a host.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Host</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Host cmdlet customizes output. You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. The Separator parameter lets you specify a string to use to separate displayed objects. The particular result depends on the program that is hosting Windows PowerShell.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Host</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Object</maml:name> <maml:description> <maml:para>Objects to display in the console.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>BackgroundColor</maml:name> <maml:description> <maml:para>Specifies the background color. There is no default.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Black</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkBlue</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkGreen</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkCyan</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkRed</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkMagenta</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkYellow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Gray</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkGray</command:parameterValue> <command:parameterValue required="false" variableLength="false">Blue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Green</command:parameterValue> <command:parameterValue required="false" variableLength="false">Cyan</command:parameterValue> <command:parameterValue required="false" variableLength="false">Red</command:parameterValue> <command:parameterValue required="false" variableLength="false">Magenta</command:parameterValue> <command:parameterValue required="false" variableLength="false">Yellow</command:parameterValue> <command:parameterValue required="false" variableLength="false">White</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ForegroundColor</maml:name> <maml:description> <maml:para>Specifies the text color. There is no default.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">Black</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkBlue</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkGreen</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkCyan</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkRed</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkMagenta</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkYellow</command:parameterValue> <command:parameterValue required="false" variableLength="false">Gray</command:parameterValue> <command:parameterValue required="false" variableLength="false">DarkGray</command:parameterValue> <command:parameterValue required="false" variableLength="false">Blue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Green</command:parameterValue> <command:parameterValue required="false" variableLength="false">Cyan</command:parameterValue> <command:parameterValue required="false" variableLength="false">Red</command:parameterValue> <command:parameterValue required="false" variableLength="false">Magenta</command:parameterValue> <command:parameterValue required="false" variableLength="false">Yellow</command:parameterValue> <command:parameterValue required="false" variableLength="false">White</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoNewline</maml:name> <maml:description> <maml:para>Specifies that the content displayed in the console does not end with a newline character.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Separator</maml:name> <maml:description> <maml:para>String to the output between objects displayed on the console.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>BackgroundColor</maml:name> <maml:description> <maml:para>Specifies the background color. There is no default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ConsoleColor</command:parameterValue> <dev:type> <maml:name>ConsoleColor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ForegroundColor</maml:name> <maml:description> <maml:para>Specifies the text color. There is no default.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">ConsoleColor</command:parameterValue> <dev:type> <maml:name>ConsoleColor</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoNewline</maml:name> <maml:description> <maml:para>Specifies that the content displayed in the console does not end with a newline character.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>Object</maml:name> <maml:description> <maml:para>Objects to display in the console.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Separator</maml:name> <maml:description> <maml:para>String to the output between objects displayed on the console.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe objects to be written to the host.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Host sends the objects to the host. It does not return any objects. However, the host might display the objects that Write-Host sends to it.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-host "no newline test " -nonewline no newline test PS C:\> </dev:code> <dev:remarks> <maml:para>This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-host (2,4,6,8,10,12) -Separator ", +2= " 2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12 </dev:code> <dev:remarks> <maml:para>This command displays the even numbers from 2 through 12. The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space).</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-host (2,4,6,8,10,12) -Separator ", -> " -foregroundcolor DarkGreen -backgroundcolor white </dev:code> <dev:remarks> <maml:para>This command displays the even numbers from 2 through 12. It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-host "Red on white text." -ForegroundColor red -BackgroundColor white Red on white text. </dev:code> <dev:remarks> <maml:para>This command displays the string "Red on white text." The text is red, as defined by the ForegroundColor parameter. The background is white, as defined by the BackgroundColor parameter.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294029</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Clear-Host</maml:linkText> <maml:uri> </maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Out-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Debug</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Error</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Output</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Progress</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Verbose</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Warning</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Information</command:name> <maml:description> <maml:para> </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Information</command:noun> <dev:version /> </command:details> <maml:description> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Information</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="Msg"> <maml:name>MessageData</maml:name> <maml:description> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Tags</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="Msg"> <maml:name>MessageData</maml:name> <maml:description> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Tags</maml:name> <maml:description> </maml:description> <command:parameterValue required="false" variableLength="true">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name> </maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> 1: </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\> </dev:code> <dev:remarks> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Output</command:name> <maml:description> <maml:para>Sends the specified objects to the next command in the pipeline. If the command is the last command in the pipeline, the objects are displayed in the console.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Output</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Output cmdlet sends the specified object down the pipeline to the next command. If the command is the last command in the pipeline, the object is displayed in the console.</maml:para> <maml:para>Write-Output sends objects down the primary pipeline, also known as the "output stream" or the "success pipeline." To send error objects down the error pipeline, use Write-Error.</maml:para> <maml:para>This cmdlet is typically used in scripts to display strings and other objects on the console. However, because the default behavior is to display the objects at the end of a pipeline, it is generally not necessary to use the cmdlet. For example, "get-process | write-output" is equivalent to "get-process".</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Output</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to send down the pipeline. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String[]</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoEnumerate</maml:name> <maml:description> <maml:para>By default, the Write-Output cmdlet always enumerates its output. The NoEnumerate parameter suppresses the default behavior, and prevents Write-Output from enumerating output. The NoEnumerate parameter has no effect on collections that were created by wrapping commands in parentheses, because the parentheses force enumeration.</maml:para> </maml:description> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference[]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the objects to send down the pipeline. Enter a variable that contains the objects, or type a command or expression that gets the objects.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="true">PSObject[]</command:parameterValue> <dev:type> <maml:name>PSObject[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>NoEnumerate</maml:name> <maml:description> <maml:para>By default, the Write-Output cmdlet always enumerates its output. The NoEnumerate parameter suppresses the default behavior, and prevents Write-Output from enumerating output. The NoEnumerate parameter has no effect on collections that were created by wrapping commands in parentheses, because the parentheses force enumeration.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe objects to Write-Output.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Output returns the objects that are submitted as input.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$p = get-process PS C:\>write-output $p PS C:\>$p </dev:code> <dev:remarks> <maml:para>These commands get objects representing the processes running on the computer and display the objects on the console.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-output "test output" | get-member </dev:code> <dev:remarks> <maml:para>This command pipes the "test output" string to the Get-Member cmdlet, which displays the members of the String class, demonstrating that the string was passed along the pipeline.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-output @(1,2,3) | measure Count � �: 3 ... PS C:\>write-output @(1,2,3) -NoEnumerate | measure Count � �: 1 </dev:code> <dev:remarks> <maml:para>This command adds the NoEnumerate parameter to treat a collection or array as a single object through the pipeline.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294030</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Tee-Object</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Debug</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Error</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Progress</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Verbose</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Warning</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Progress</command:name> <maml:description> <maml:para>Displays a progress bar within a Windows PowerShell command window.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Progress</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Progress cmdlet displays a progress bar in a Windows PowerShell command window that depicts the status of a running command or script. You can select the indicators that the bar reflects and the text that appears above and below the progress bar.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Progress</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Activity</maml:name> <maml:description> <maml:para>Specifies the first line of text in the heading above the status bar. This text describes the activity whose progress is being reported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Status</maml:name> <maml:description> <maml:para>Specifies the second line of text in the heading above the status bar. This text describes current state of the activity.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Specifies an ID that distinguishes each progress bar from the others. Use this parameter when you are creating more than one progress bar in a single command. If the progress bars do not have different IDs, they are superimposed instead of being displayed in a series.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Completed</maml:name> <maml:description> <maml:para>Indicates whether the progress bar is visible. If this parameter is omitted, Write-Progress displays progress information.</maml:para> </maml:description> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CurrentOperation</maml:name> <maml:description> <maml:para>Specifies the line of text below the progress bar. This text describes the operation that is currently taking place.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ParentId</maml:name> <maml:description> <maml:para>Identifies the parent activity of the current activity. Use the value -1 if the current activity has no parent activity.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PercentComplete</maml:name> <maml:description> <maml:para>Specifies the percentage of the activity that is completed. Use the value -1 if the percentage complete is unknown or not applicable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SecondsRemaining</maml:name> <maml:description> <maml:para>Specifies the projected number of seconds remaining until the activity is completed. Use the value -1 if the number of seconds remaining is unknown or not applicable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SourceId</maml:name> <maml:description> <maml:para>Identifies the source of the record.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none"> <maml:name>Activity</maml:name> <maml:description> <maml:para>Specifies the first line of text in the heading above the status bar. This text describes the activity whose progress is being reported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>Completed</maml:name> <maml:description> <maml:para>Indicates whether the progress bar is visible. If this parameter is omitted, Write-Progress displays progress information.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>CurrentOperation</maml:name> <maml:description> <maml:para>Specifies the line of text below the progress bar. This text describes the operation that is currently taking place.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none"> <maml:name>Id</maml:name> <maml:description> <maml:para>Specifies an ID that distinguishes each progress bar from the others. Use this parameter when you are creating more than one progress bar in a single command. If the progress bars do not have different IDs, they are superimposed instead of being displayed in a series.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="iv"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>ParentId</maml:name> <maml:description> <maml:para>Identifies the parent activity of the current activity. Use the value -1 if the current activity has no parent activity.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>PercentComplete</maml:name> <maml:description> <maml:para>Specifies the percentage of the activity that is completed. Use the value -1 if the percentage complete is unknown or not applicable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SecondsRemaining</maml:name> <maml:description> <maml:para>Specifies the projected number of seconds remaining until the activity is completed. Use the value -1 if the number of seconds remaining is unknown or not applicable.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="none"> <maml:name>SourceId</maml:name> <maml:description> <maml:para>Identifies the source of the record.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none"> <maml:name>Status</maml:name> <maml:description> <maml:para>Specifies the second line of text in the heading above the status bar. This text describes current state of the activity.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You cannot pipe input to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Progress does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>If the progress bar does not appear, check the value of the $ProgressPreference variable. If the value is set to SilentlyContinue, the progress bar is not displayed. For more information about Windows PowerShell preferences, see about_Preference_Variables.</maml:para> <maml:para>The parameters of the cmdlet correspond to the properties of the ProgressRecord class (System.Management.Automation.ProgressRecord). For more information, see the ProgressRecord topic in the Windows PowerShell Software Development Kit (SDK).</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>for ($i = 1; $i -le 100; $i++ ) {write-progress -activity "Search in Progress" -status "$i% Complete:" -percentcomplete $i;} </dev:code> <dev:remarks> <maml:para>This command displays the progress of a For loop that counts from 1 to 100. The Write-Progress command includes a status bar heading ("activity"), a status line, and the variable $i (the counter in the For loop), which indicates the relative completeness of the task.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>for($i = 1; $i -lt 101; $i++ ) {write-progress -activity Updating -status 'Progress->' -percentcomplete $i -currentOperation OuterLoop; ` for($j = 1; $j -lt 101; $j++ ) {write-progress -id 1 -activity Updating -status 'Progress' -percentcomplete $j -currentOperation InnerLoop} } Updating Progress -> [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] OutsideLoop Updating Progress [oooooooooooooooooo ] InnerLoop </dev:code> <dev:remarks> <maml:para>This example displays the progress of two nested For loops, each of which is represented by a progress bar.</maml:para> <maml:para>The Write-Progress command for the second progress bar includes the Id parameter that distinguishes it from the first progress bar. Without the Id parameter, the progress bars would be superimposed on each other instead of being displayed one below the other.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$events = get-eventlog -logname system PS C:\>$events | foreach-object -begin {clear-host;$i=0;$out=""} ` -process {if($_.message -like "*bios*") {$out=$out + $_.Message}; $i = $i+1; write-progress -activity "Searching Events" -status "Progress:" -percentcomplete ($i/$events.count*100)} ` -end {$out} </dev:code> <dev:remarks> <maml:para>This command displays the progress of a command to find the string "bios" in the System event log.</maml:para> <maml:para>In the first line of the command, the Get-EventLog cmdlet gets the events in the System log and stores them in the $events variable.</maml:para> <maml:para>In the second line, the events are piped to the ForEach-Object cmdlet. Before processing begins, the Clear-Host cmdlet is used to clear the screen, the $i counter variable is set to zero, and the $out output variable is set to the empty string.</maml:para> <maml:para>In the third line, which is the Process script block of the ForEach-Object cmdlet, the cmdlet searches the message property of each incoming object for "bios". If the string is found, the message is added to $out. Then, the $i counter variable is incremented to record that another event has been examined.</maml:para> <maml:para>The fourth line uses the Write-Progress cmdlet with values for the Activity and Status text fields that create the first and second lines of the progress bar heading, respectively. The PercentComplete parameter value is calculated by dividing the number of events that have been processed ($i) by the total number of events retrieved ($events.count) and then multiplying that result by 100.</maml:para> <maml:para>In the last line, the End parameter of the ForEach-Object cmdlet is used to display the messages that are stored in the $out variable.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294031</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Debug</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Error</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Output</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Verbose</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Warning</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Verbose</command:name> <maml:description> <maml:para>Writes text to the verbose message stream. </maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Verbose</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Verbose cmdlet writes text to the verbose message stream in Windows PowerShell. Typically, the verbose message stream is used to deliver information about command processing that is used for debugging a command.</maml:para> <maml:para>By default, the verbose message stream is not displayed, but you can display it by changing the value of the $VerbosePreference variable or using the Verbose common parameter in any command.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Verbose</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the message to display. This parameter is required. You can also pipe a message string to Write-Verbose.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the message to display. This parameter is required. You can also pipe a message string to Write-Verbose.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains the message to Write-Verbose.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Verbose writes only to the verbose message stream.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>Verbose messages are returned only when the command uses the Verbose common parameter. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).</maml:para> </maml:alert> <maml:alert> <maml:para>In Windows PowerShell background jobs and remote commands, the $VerbosePreference variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the $VerbosePreference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248).</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>Write-Verbose -Message "Searching the Application Event Log." PS C:\>Write-Verbose -Message "Searching the Application Event Log." -verbose </dev:code> <dev:remarks> <maml:para>These commands use the Write-Verbose cmdlet to display a status message. By default, the message is not displayed.</maml:para> <maml:para>The second command uses the Verbose common parameter, which displays any verbose messages, regardless of the value of the $VerbosePreference variable.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$VerbosePreference = "Continue" PS C:\>Write-Verbose "Copying file $filename" </dev:code> <dev:remarks> <maml:para>These commands use the Write-Verbose cmdlet to display a status message. By default, the message is not displayed.</maml:para> <maml:para>The first command assigns a value of "Continue" to the $VerbosePreference preference variable. The default value, "SilentlyContinue", suppresses verbose messages. The second command writes a verbose message.</maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294032</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Error</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Warning</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Preference_Variables</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Write-Warning</command:name> <maml:description> <maml:para>Writes a warning message.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>Warning</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Write-Warning cmdlet writes a warning message to the Windows PowerShell host. The response to the warning depends on the value of the user's $WarningPreference variable and the use of the WarningAction common parameter.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Write-Warning</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the warning message.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" variableLength="false">SilentlyContinue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Stop</command:parameterValue> <command:parameterValue required="false" variableLength="false">Continue</command:parameterValue> <command:parameterValue required="false" variableLength="false">Inquire</command:parameterValue> <command:parameterValue required="false" variableLength="false">Ignore</command:parameterValue> <command:parameterValue required="false" variableLength="false">Suspend</command:parameterValue> </command:parameterValueGroup> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationAction</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ActionPreference</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named" aliases="ia"> <maml:name>InformationVariable</maml:name> <maml:description> <maml:para> </maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="1" aliases="Msg"> <maml:name>Message</maml:name> <maml:description> <maml:para>Specifies the warning message.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>none</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>You can pipe a string that contains the warning to Write-Warning.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri> </maml:uri> <maml:description> <maml:para /> </maml:description> </dev:type> <maml:description> <maml:para>Write-Warning writes only to the warning stream. It does not generate any other output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors /> <command:nonTerminatingErrors /> <maml:alertSet> <maml:title /> <maml:alert> <maml:para>The default value for the $WarningPreference variable is "Continue", which displays the warning and then continues executing the command. To determine valid values for a preference variable such as $WarningPreference, set it to a string of random characters, such as "abc". The resulting error message will list the valid values.</maml:para> </maml:alert> <maml:alert> <maml:para> </maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title> -------------------------- EXAMPLE 1 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-warning "This is only a test warning." </dev:code> <dev:remarks> <maml:para>This command displays the message "WARNING: This is only a test warning."</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 2 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$w = "This is only a test warning." PS C:\>$w | write-warning </dev:code> <dev:remarks> <maml:para>This example shows that you can use a pipeline operator (|) to send a string to Write-Warning. You can save the string in a variable, as shown in this command, or pipe the string directly to Write-Warning.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 3 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>$warningpreference Continue PS C:\>write-warning "This is only a test warning." This is only a test warning. PS C:\>$warningpreference = "SilentlyContinue" PS C:\>write-warning "This is only a test warning." PS C:\> PS C:\>$warningpreference = "Stop" PS C:\>write-warning "This is only a test warning." WARNING: This is only a test message. Write-Warning : Command execution stopped because the shell variable "WarningPreference" is set to Stop. At line:1 char:14 + write-warning <<<< "This is only a test message." </dev:code> <dev:remarks> <maml:para>This example shows the effect of the value of the $WarningPreference variable on a Write-Warning command.</maml:para> <maml:para>The first command displays the default value of the $WarningPreference variable, which is "Continue". As a result, when you write a warning, the warning message is displayed and execution continues.</maml:para> <maml:para>When you change the value of the $WarningPreference variable, the effect of the Write-Warning command changes again. A value of "SilentlyContinue" suppresses the warning. A value of "Stop" displays the warning and then stops execution of the command.</maml:para> <maml:para>For more information about the $WarningPreference variable, see about_Preference_Variables.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title> -------------------------- EXAMPLE 4 -------------------------- </maml:title> <maml:introduction> <maml:para> </maml:para> </maml:introduction> <dev:code>PS C:\>write-warning "This is only a test warning." -warningaction Inquire WARNING: This is only a test warning. Confirm Continue with this operation? [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): </dev:code> <dev:remarks> <maml:para>This example shows the effect of the WarningAction common parameter on a Write-Warning command. You can use the WarningAction common parameter with any cmdlet to determine how Windows PowerShell responds to warnings resulting from that command. The WarningAction common parameter overrides the value of the $WarningPreference only for that particular command.</maml:para> <maml:para>This command uses the Write-Warning cmdlet to display a warning. The WarningAction common parameter with a value of "Inquire" directs the system to prompt the user when the command displays a warning.</maml:para> <maml:para>For more information about the WarningAction common parameter, see about_CommonParameters.</maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para> </maml:para> <maml:para /> <maml:para /> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText /> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>http://go.microsoft.com/fwlink/p/?linkid=294033</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Debug</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Error</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Host</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Output</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Progress</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Write-Verbose</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_CommonParameters</maml:linkText> <maml:uri /> </maml:navigationLink> <maml:navigationLink> <maml:linkText>about_Preference_Variables</maml:linkText> <maml:uri /> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |