Tag Archives: Path

cmdlet, ModuleManifest, New

New-ModuleManifest

NAME
    New-ModuleManifest

SYNOPSIS
    Creates a new module manifest.

SYNTAX
    New-ModuleManifest [-Path] <string> -Author <string> -CompanyName <string> -Copyright <string> -Description <string> -FileList <string[]> -FormatsToProcess <string[]> -ModuleToProcess <string> -NestedModules <string[]> -RequiredAssemblies <string[]> -TypesToProcess <string[]> [-AliasesToExport <string[]>] [-ClrVersion <Version>] [-CmdletsToExport <string[]>] [-DotNetFrameworkVersion <Version>] [-FunctionsToExport <string[]>] [-Guid <Guid>] [-ModuleList <Object[]>] [-ModuleVersion <Version>] [-PassThru] [-PowerShellHostName <string>] [-PowerShellHostVersion <Version>] [-PowerShellVersion <Version>] [-PrivateData <Object>] [-ProcessorArchitecture {None | MSIL | X86 | IA64 | Amd64}] [-RequiredModules <Object[]>] [-ScriptsToProcess <string[]>] [-VariablesToExport <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The New-ModuleManifest cmdlet creates a new module manifest (.psd1) file, populates its values, and saves the manifest file in the specified path.

    Module authors can use this cmdlet to create a manifest for their module. A module manifest is a .psd1 file that contains a hash table. The keys and values in the hash table describe the contents and attributes of the module, define the prerequisites, and determine how the components are processed. Manifests are not required for a module.

    New-ModuleManifest creates a manifest that includes all of the commonly used manifest keys, so you can use the default output as a manifest template. To add or change values, or to add module keys that this cmdlet does not add, open the resulting file in a text editor.

    Each parameter of this cmdlet (except for Path and PassThru) creates a module manifest key and its value. In a module manifest, only the ModuleVersion key is required. However, several other parameters of this cmdlet are mandatory. As a result, you can type a “New-ModuleManifest” command without parameters and the cmdlet will prompt you for values for other commonly used keys. To leave the value empty, press ENTER.

    For a complete description of the format, effects, and requirements of a module manifest, see “How to Write a Module Manifest” in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143613.

PARAMETERS
    -AliasesToExport <string[]>
        Specifies the Aliases that the module exports. Wildcards are permitted.

        You can use this parameter to restrict the Aliases that are exported by the module. It can remove Aliases from the list of exported Aliases, but it cannot add Aliases to the list.

        If you omit this parameter, New-ModuleManifest creates an AliasesToExport key with a value of * (all), meaning that all Aliases that are exported by the module are exported by the manifest.

        Required?                    false
        Position?                    named
        Default value                * (all)
        Accept pipeline input?     false
        Accept wildcard characters? true

    -Author <string>
        Specifies the module author.

        This parameter is required by the cmdlet, but the Author key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates an Author key with the name of the current user.

        Required?                    true
        Position?                    named
        Default value                Name of the current user
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ClrVersion <Version>
        Specifies the version of the Common Language Runtime (CLR) of the Microsoft .NET Framework that the module requires.

        If you omit this parameter, New-ModuleManifest creates a CLRVersion key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -CmdletsToExport <string[]>
        Specifies the cmdlets that the module exports. Wildcards are permitted.

        You can use this parameter to restrict the cmdlets that are exported by the module. It can remove cmdlets from the list of exported cmdlets, but it cannot add cmdlets to the list.

        If you omit this parameter, New-ModuleManifest creates a CmdletsToExport key with a value of * (all), meaning that all cmdlets that are exported by the module are exported by the manifest.

        Required?                    false
        Position?                    named
        Default value                * (all)
        Accept pipeline input?     false
        Accept wildcard characters? true

    -CompanyName <string>
        Identifies the company or vendor who created the module.

        This parameter is required by the cmdlet, but the CompanyName key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a CompanyName key with a value of “Unknown”.

        Required?                    true
        Position?                    named
        Default value                “Unknown”
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Copyright <string>
        Specifies a copyright statement for the module.

        This parameter is required by the cmdlet, but the Copyright key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a Copyright key with a value of “(c) <year> <username>. All rights reserved.” where <year> is the current year and <username> is the value of the Author key (if one is specified) or the name of the current user.

        Required?                    true
        Position?                    named
        Default value                (c) <year> <username>. All rights reserved.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Description <string>
        Describes the contents of the module.

        This parameter is required by the cmdlet, but the Description key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a Description key with an empty string value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -DotNetFrameworkVersion <Version>
        Specifies the version of the Microsoft .NET Framework that the module requires.

        If you omit this parameter, New-ModuleManifest creates a DotNetFrameWorkVersion key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -FileList <string[]>
        Specifies all items that are included in the module.

        This key is designed to act as a module inventory. These files are not automatically exported with the module.

        This parameter is required by the cmdlet, but the FileList key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a FileList key with an empty array value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -FormatsToProcess <string[]>
        Specifies the formatting files (.ps1xml) that run when the module is imported.

        When you import a module, Windows PowerShell runs the Update-FormatData cmdlet with the specified files. Because formatting files are not scoped, they affect all session states in the session.

        This parameter is required by the cmdlet, but the FormatsToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a FormatsToProcess key with an empty array value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -FunctionsToExport <string[]>
        Specifies the Functions that the module exports. Wildcards are permitted.

        You can use this parameter to restrict the Functions that are exported by the module. It can remove Functions from the list of exported Aliases, but it cannot add Functions to the list.

        If you omit this parameter, New-ModuleManifest creates an FunctionsToExport key with a value of * (all), meaning that all Functions that are exported by the module are exported by the manifest.

        Required?                    false
        Position?                    named
        Default value                * (all)
        Accept pipeline input?     false
        Accept wildcard characters? true

    -Guid <Guid>
        Specifies a unique identifier for the module. The GUID can be used to distinguish among modules with the same name.

        If you omit this parameter, New-ModuleManifest creates a GUID key in the manifest and generates a GUID for the value.

        To create a new GUID in Windows PowerShell, type “[guid]::NewGuid()”.

        Required?                    false
        Position?                    named
        Default value                A GUID generated for the module
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ModuleList <Object[]>
        Lists all modules that are packaged with this module.

        Enter each module name as a string or enter a hash table with ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key.

        This key is designed to act as a module inventory. These modules are not automatically processed.

        If you omit this parameter, New-ModuleManifest creates a ModuleList key in the manifest with an empty array value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ModuleToProcess <string>
        Specifies the primary or “root” file of the module. When the module is imported, the members that are exported from the root module file are imported into the caller’s session state. Enter the file name of one script module (.psm1) or binary module (.dll).

        If a module has a manifest file and no root file has been designated in the ModuleToProcess key, the manifest becomes the primary file for the module, and the module becomes a “manifest module” (ModuleType = Manifest).

        To export members from .psm1 or .dll files in a module that has a manifest, the names of those files must be specified in the values of the ModuleToProcess or NestedModules keys in the manifest. Otherwise, their members are not exported.

        This parameter is required by the cmdlet, but the ModuleToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a ModuleToProcess key with an empty string value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ModuleVersion <Version>
        Specifies the version of the module.

        This parameter is not required by the cmdlet, but a ModuleVersion key is required in the manifest. If you omit this parameter, New-ModuleManifest creates a ModuleVersion key with a value of “1.0”.

        Required?                    false
        Position?                    named
        Default value                1.0
        Accept pipeline input?     false
        Accept wildcard characters? false

    -NestedModules <string[]>
        Specifies script modules (.psm1) and binary modules (.dll) that are imported into the module’s session state. The files in the NestedModules key run in the order in which they are listed in the value.

        Typically, nested modules contain commands that the root module needs for its internal processing. By default, the commands in nested modules are exported from the module’s session state into the caller’s session state, but the root module can restrict the commands that it exports (for example, by using an Export-Module command).

        Nested modules in the module session state are available to the root module, but they are not returned by a Get-Module command in the caller’s session state.

        Scripts (.ps1) that are listed in the NestedModules key are run in the module’s session state, not in the caller’s session state. To run a script in the caller’s session state, list the script file name in the value of the ScriptsToProcess key in the manifest.

        This parameter is required by the cmdlet, but the NestedModules key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a NestedModules key with an empty array value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -PassThru [<SwitchParameter>]
        Writes the resulting module manifest to the console, in addition to creating a .psd1 file. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Path <string>
        Specifies the path and file name of the new module manifest. Enter a path and file name with a .psd1 file name extension, such as “$pshome\Modules\MyModule\MyModule.psd1”. This parameter is required.

        If you specify the path to an existing file, New-ModuleManifest replaces the file without warning unless the file has the read-only attribute.

        The manifest should be located in the module’s directory, and the manifest file name should be the same as the module directory name, but with a .psd1 file name extension.

        Note: You cannot use Variables, such as $pshome or $home, in response to a prompt for a Path parameter value. To use a Variable, include the Path parameter in the command.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -PowerShellHostName <string>
        Specifies the name of the Windows PowerShell host program that the module requires. Enter the name of the host program, such as “Windows PowerShell ISE Host” or “ConsoleHost”. Wildcards are not permitted.

        To find the name of a host program, in the program, type “$host.name”.

        If you omit this parameter, New-ModuleManifest creates a PowerShellHostName key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -PowerShellHostVersion <Version>
        Specifies the minimum version of the Windows PowerShell host program that works with the module. Enter a version number, such as 1.1.

        If you omit this parameter, New-ModuleManifest creates a PowerShellHostName key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -PowerShellVersion <Version>
        Specifies the minimum version of Windows PowerShell that will work with this module. Enter 1.0 or 2.0. Requirements for versions greater than 2.0 are not enforced.

        If you omit this parameter, New-ModuleManifest creates a PowerShellVersion key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -PrivateData <Object>
        Specifies data that is passed to the module when it is imported.

        If you omit this parameter, New-ModuleManifest creates a PrivateData key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ProcessorArchitecture <ProcessorArchitecture>
        Specifies the processor architecture that the module requires. Valid values are x86, AMD64, IA64, and None (unknown or unspecified).

        If you omit this parameter, New-ModuleManifest creates a ProcessorArchitecture key with an empty string value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -RequiredAssemblies <string[]>
        Specifies the assembly (.dll) files that the module requires. Windows PowerShell loads the specified assemblies before updating types or formats, importing nested modules, or importing the module file that is specified in the value of the ModuleToProcess key.

        Use this parameter to list all the assemblies that the module requires, including assemblies that must be loaded to update any formatting or type files that are listed in the FormatsToProcess or TypesToProcess keys, even if those assemblies are also listed as binary modules in the NestedModules key.

        This parameter is required by the cmdlet, but the RequiredAssemblies key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a RequiredAssemblies key with an empty array value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -RequiredModules <Object[]>
        Specifies modules that must be in the global session state. If the required modules are not in the global session state, attempts to import this module will fail.

        Enter each module name as a string or enter a hash table with the ModuleName and GUID keys. The hash table can also have an optional ModuleVersion key. For more information, see the examples.

        Windows PowerShell does not import required modules automatically. It verifies only that the required modules are present. However, modules can include scripts (.ps1) that import the required modules into the global session state.

        If you omit this parameter, New-ModuleManifest creates a RequiredModules key with an empty array value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ScriptsToProcess <string[]>
        Specifies script (.ps1) files that run in the caller’s session state when the module is imported. You can use these scripts to prepare an Environment, just as you might use a login script.

        To specify scripts that run in the module’s session state, use the NestedModules key.

        If you omit this parameter, New-ModuleManifest creates a ScriptsToProcess key with an empty array value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -TypesToProcess <string[]>
        Specifies the type files (.ps1xml) that run when the module is imported.

        When you import the module, Windows PowerShell runs the Update-TypeData cmdlet with the specified files. Because type files are not scoped, they affect all session states in the session.

        This parameter is required by the cmdlet, but the TypesToProcess key is not required in the manifest. If you omit this parameter and do not enter a value when prompted, New-ModuleManifest creates a TypesToProcess key with an empty array value.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -VariablesToExport <string[]>
        Specifies the Variables that the module exports. Wildcards are permitted.

        You can use this parameter to restrict the Variables that are exported by the module. It can remove Variables from the list of exported Variables, but it cannot add Variables to the list.

        If you omit this parameter, New-ModuleManifest creates a VariablesToExport key with a value of * (all), meaning that all Variables that are exported by the module are exported by the manifest.

        Required?                    false
        Position?                    named
        Default value                * (all)
        Accept pipeline input?     false
        Accept wildcard characters? true

    -Confirm [<SwitchParameter>]
        Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -WhatIf [<SwitchParameter>]
        Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    None
        You cannot pipe input to this cmdlet.

OUTPUTS
    None or System.String
        By default, New-ModuleManifest does not generate any output. However, if you use the PassThru parameter, it generates a System.String object representing the module manifest..

NOTES

        Module manifests are usually optional. However, a module manifest is required to export an assembly that is installed in the global assembly cache.

        To add or change files in the $pshome\Modules directory (%Windir%\System32\WindowsPowerShell\v1.0\Modules), start Windows PowerShell with the “Run as administrator” option.

        A “session” is an instance of the Windows PowerShell execution Environment. A session can have one or more session state. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the global session state.

        The “caller’s session state” is the session state into which a module is imported. Typically, it refers to the global session state, but when a module imports nested modules, the “caller” is the module and the “caller’s session state” is the module’s session state.

    ————————– EXAMPLE 1 ————————–

    C:\PS>New-ModuleManifest

    Path: C:\Users\User01\Documents\WindowsPowerShell\Modules\Test-Module\Test-Module.psd1
    NestedModules[0]: BackgroundModule.psm1
    Author: Jinghao Liu
    CompanyName: Fabrikam, Inc.
    Copyright: Copyright © 2009 Liu Jinghao. All rights reserved.
    ModuleToProcess: TestModule.psm1
    Description: Cmdlets to find common errors in scripts.
    TypesToProcess[0]: TestTypes.ps1xml
    FormatsToProcess[0]: TestFormat.ps1xml
    RequiredAssemblies[0]: Test.dll
    FileList[0]: Test-Module.psd1
    FileList[1]: Test-Module.psm1
    FileList[2]: BackgroundModule.psm1
    FileList[3]: TestTypes.ps1xml
    FileList[4]: TestFormat.ps1xml
    FileList[5]: Test.dll
    FileList[6]: TestIcon.ico

    Description
    ———–
    This command creates a new module manifest. The cmdlet prompts you for the parameters that it requires, including the Path parameter, and creates a manifest file in the specified location.

    The output of this command shows sample responses to the prompts. To use default values, press ENTER.

    The actual prompt, and its handling of quoted and non-quoted phrases, depends on the host program in which Windows PowerShell is running.

    ————————– EXAMPLE 2 ————————–

    C:\PS>New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC

    Description
    ———–
    This command creates a new module manifest. The command includes parameters that the cmdlet does not require (or prompt for). You can include other manifest key values at the prompt.

    ————————– EXAMPLE 3 ————————–

    C:\PS>New-ModuleManifest -RequiredModules FileTransfer,@{ModuleName=”BackgroundModule”;GUID=”486569a2-2784-48bf-af15-70ba837a64d0″;ModuleVersion=”3.5″}

    Description
    ———–
    This example shows how to use the string and hash table formats of the RequiredModules parameter value. Strings and hash tables can be used in the same command.

    This command commands creates a module manifest for a module that requires the FileTransfer module and a (fictitious) module named “BackgroundModule”.

    The command uses a string format to specify the name of the FileTransfer module and the hash table format to specify the name, a GUID, and a version of the BackgroundModule.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=141555
    Import-Module
    Get-Module
    New-Module
    Remove-Module
    Export-ModuleMember
    Test-ModuleManifest
    about_modules

Alias, cmdlet, Import

Import-Alias

NAME
    Import-Alias

SYNOPSIS
    Imports an Alias list from a file.

SYNTAX
    Import-Alias [-Path] <string> [-Force] [-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Import-Alias cmdlet imports an Alias list from a file.

PARAMETERS
    -Force [<SwitchParameter>]
        Allows the cmdlet to import an Alias that is already defined and is read only. You can use the following command to display information about the currently-defined Aliases:

        Get-Alias | Select-Object name,Options
        The value of the Options property will include “ReadOnly” if the corresponding Alias is read only.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -PassThru [<SwitchParameter>]
        Returns an object representing the Alias. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Path <string>
        Specifies the path to a file that includes exported Alias information. Wildcards are allowed but they must resolve to a single name.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    -Scope <string>
        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.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Confirm [<SwitchParameter>]
        Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -WhatIf [<SwitchParameter>]
        Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a path to Import-Alias.

OUTPUTS
    None or System.Management.Automation.AliasInfo
        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.

NOTES

    ————————– EXAMPLE 1 ————————–

    C:\PS>Import-Alias test.txt

    Description
    ———–
    This command imports Alias information from a file named test.txt.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113339
    Export-Alias
    Get-Alias
    New-Alias
    Set-Alias

Clixml, cmdlet, Import

Import-Clixml

NAME
    Import-Clixml

SYNOPSIS
    Imports a CLIXML file and creates corresponding objects within Windows PowerShell.

SYNTAX
    Import-Clixml [-Path] <string[]> [<CommonParameters>]

DESCRIPTION
    The Import-Clixml cmdlet imports a CLIXML file with data that represents Microsoft .NET Framework objects and creates the objects in Windows PowerShell.

PARAMETERS
    -Path <string[]>
        Specifies the location of the XML files to be converted into Windows PowerShell objects.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a path to Import-Clixml.

OUTPUTS
    PSObject
        Import-Clixml returns objects that have been deserialized from the stored XML files.

NOTES

        When specifying multiple values for a parameter, use commas to separate the values. For example, “<parameter-name> <value1>, <value2>”.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Get-Process | Export-Clixml pi.xml

    C:\PS> $processes = Import-Clixml pi.xml

    Description
    ———–
    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.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113340

cmdlet, Counter, Import

Import-Counter

NAME
    Import-Counter

SYNOPSIS
    Imports performance counter log files (.blg, .csv, .tsv) and creates the objects that represent each counter sample in the log.

SYNTAX
    Import-Counter [-Path] <string[]> [-Counter <string[]>] [-EndTime <DateTime>] [-MaxSamples <Int64>] [-StartTime <DateTime>] [<CommonParameters>]

    Import-Counter [-Path] <string[]> -ListSet <string[]> [<CommonParameters>]

    Import-Counter [-Path] <string[]> -Summary <switch> [<CommonParameters>]

DESCRIPTION
    The Import-Counter cmdlet imports performance counter data from performance counter log files and creates objects for each counter sample in the file. The PerformanceCounterSampleSet objects that it creates are identical to the objects that Get-Counter returns when it collects performance counter data.

    You can import data from comma-separated value (.csv), tab-separated value ( .tsv), and binary performance log (.blg) performance log files. If you are using .blg files, you can import multiple files (up to 32 different files) in each command. And, you can use the parameters of Import-Counter to filter the data that you import.

    Along with Get-Counter and Export-Counter, this feature lets you collect, export, import, combine, filter, manipulate, and re-export performance counter data within Windows PowerShell.

PARAMETERS
    -Counter <string[]>
        Imports data only for the specified performance counters. By default, Import-Counter imports all data from all counters in the input files. Enter one or more counter paths. Wildcards are permitted in the Instance part of the path.

        Each counter path has the following format. Notice that the ComputerName value is required in the path, even on the local computer.
             “\\<ComputerName>\<CounterSet>(<Instance>)\<CounterName>”

        For example:
                “\\Server01\Processor(2)\% User Time”
                “\Processor(*)\% Processor Time

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? true

    -EndTime <DateTime>
        Imports only counter data with a timestamp less than or equal to the specified date and time. Enter a DateTime object, such as one created by the Get-Date cmdlet. By default, Import-Counter imports all counter data in the files specified by the Path parameter.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -ListSet <string[]>
        Gets the performance counter sets that are represented in the exported files. Commands with this parameter do not import any data.

        Enter one or more counter set names. Wildcards are permitted. To get all counter sets in the file, type “Import-Counter -listset *”.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? true

    -MaxSamples <Int64>
        Specifies the maximum number of samples of each counter to import. By default, Get-Counter imports all of the data in the files specified by the Path parameter.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Path <string[]>
        Specifies the file paths of the files to be imported. This parameter is required.

        Enter the path and file name of a, .csv,, .tsv, or .blg file that you exported by using the Export-Counter cmdlet. You can specify only one .csv or .tsv file, but you can specify multiple .blg files (up to 32) in each command. You can also pipe file path strings (in quotation marks) to Import-Counter.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? true

    -StartTime <DateTime>
        Imports only counter data with a timestamp greater than or equal to the specified date and time. Enter a DateTime object, such as one created by the Get-Date cmdlet. By default, Import-Counter imports all counter data in the files specified by the Path parameter.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Summary <switch>
        Gets a summary of the imported data, instead of getting individual counter data samples.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe performance counter log paths to Import-Counter.

OUTPUTS
    Microsoft.PowerShell.Commands.GetCounter.PerformanceCounterSampleSet, Microsoft.PowerShell.Commands.GetCounter.CounterSet, Microsoft.PowerShell.Commands.GetCounter.CounterFileInfo
        By default, Import-Counter returns a Microsoft.PowerShell.Commands.GetCounter.PerformanceCounterSampleSet. If you use the ListSet parameter, Import-Command returns a Microsoft.PowerShell.Commands.GetCounter.CounterSet object. If you use the Summary parameter, Import-Command returns a Microsoft.PowerShell.Commands.GetCounter.CounterFileInfo object.

NOTES

        The Import-Counter cmdlet does not have a ComputerName parameter. However, if the computer is configured for Windows PowerShell remoting, you can use the Invoke-Command cmdlet to run an Import-Counter command on a remote computer.

    ————————– EXAMPLE 1 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This command imports all of the counter data from the ProcessorData.csv file into the $data Variable.

    C:\PS> $data = Import-Counter -Path ProcessorData.csv

    ————————– EXAMPLE 2 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This command imports only the Processor(_total)\Interrupts\sec counter data from the ProcessorData.blg file into the $i Variable.

    C:\PS> $i = Import-Counter -Path ProcessorData.blg -Counter “\\SERVER01\Processor(_Total)\Interrupts/sec”

    ————————– EXAMPLE 3 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This example shows how to select data from a performance counter log file (.blg) and then export the selected data to a .csv file.

    The first four commands get the counter paths from the file and save them in a Variable. The last two commands import selected data and then export only the selected data.

    The first command uses Import-Counter to import all of the performance counter data from the ProcessorData.blg files. The command saves the data in the $data Variable.

    C:\PS> $data = Import-Counter .\processordata.blg

    The second command displays the counter paths in the $data Variable. The display is shown in the command output.

    C:\PS> $data[0].countersamples | Format-Table path

    Path
    —-
    \\SERVER01\Processor(_Total)\DPC Rate
    \\SERVER01\Processor(1)\DPC Rate
    \\SERVER01\Processor(0)\DPC Rate
    \\SERVER01\Processor(_Total)\% Idle Time
    \\SERVER01\Processor(1)\% Idle Time
    \\SERVER01\Processor(0)\% Idle Time
    \\SERVER01\Processor(_Total)\% C3 Time
    \\SERVER01\Processor(1)\% C3 Time
    …

    The third command gets the counter paths that end in “Interrupts/sec” and saves the paths in the $IntCtrs Variable.

    C:\PS> $IntCtrs = $data[0].countersamples | where {$_.path -like “*interrupts/sec”} | foreach {$_.path}

    The fourth command displays the selected counter paths.

    C:\PS> $IntCtrs

    \\SERVER01\Processor(_Total)\Interrupts/sec
    \\SERVER01\Processor(1)\Interrupts/sec
    \\SERVER01\Processor(0)\Interrupts/sec

    The fifth command uses the Import-Counter cmdlet to import the data. It uses the Counter parameter with the $IntCtrs Variable to import only data for the counter paths in $IntCtrs.

    C:\PS> $i = Import-Counter -Path .\processordata.blg -Counter $intCtrs

    The sixth command uses the Export-Counter cmdlet to export the data.

    C:\PS> $i | Export-Counter -Path .\interrupts.csv -format CSV

    ————————– EXAMPLE 4 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This example shows how to display all the counter paths in a group of imported counter sets.

    The first command uses the ListSet parameter to get all of the counter sets that are represented in a counter data file.

    C:\PS> Import-Counter -Path processordata.csv -listset *

    CounterSetName     : Processor
    MachineName        : \\SERVER01
    CounterSetType     : MultiInstance
    Description        :
    Paths             : {\\SERVER01\Processor(*)\DPC Rate, \\SERVER01\Processor(*)\% Idle Time, \\SERVER01
                         \Processor(*)\% C3 Time, \\SERVER01\Processor(*)\% Interrupt Time…}
    PathsWithInstances : {\\SERVER01\Processor(_Total)\DPC Rate, \\SERVER01\Processor(1)\DPC Rate, \\SERVER01
                         \Processor(0)\DPC Rate, \\SERVER01\Processor(_Total)\% Idle Time…}
    Counter            : {\\SERVER01\Processor(*)\DPC Rate, \\SERVER01\Processor(*)\% Idle Time, \\SERVER01
                         \Processor(*)\% C3 Time, \\SERVER01\Processor(*)\% Interrupt Time…}

    The second command gets all of the counter paths from the list set.

    C:\PS> Import-Counter -Path processordata.csv -listset * | foreach {$_.paths}

    \\SERVER01\Processor(*)\DPC Rate
    \\SERVER01\Processor(*)\% Idle Time
    \\SERVER01\Processor(*)\% C3 Time
    \\SERVER01\Processor(*)\% Interrupt Time
    \\SERVER01\Processor(*)\% C2 Time
    \\SERVER01\Processor(*)\% User Time
    \\SERVER01\Processor(*)\% C1 Time
    \\SERVER01\Processor(*)\% Processor Time
    \\SERVER01\Processor(*)\C1 Transitions/sec
    \\SERVER01\Processor(*)\% DPC Time
    \\SERVER01\Processor(*)\C2 Transitions/sec
    \\SERVER01\Processor(*)\% Privileged Time
    \\SERVER01\Processor(*)\C3 Transitions/sec
    \\SERVER01\Processor(*)\DPCs Queued/sec
    \\SERVER01\Processor(*)\Interrupts/sec

    ————————– EXAMPLE 5 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This example imports only the counter data that has a time stamp between the starting an ending ranges specified in the command.

    The first command lists the time stamps of all of the data in the ProcessorData.blg file.

     C:\PS> Import-Counter -Path .\disk.blg | Format-Table timestamp

    The second and third commands save particular time stamps in the $start and $end Variables. The strings are cast to DateTime objects.

     C:\PS> $start = [datetime]”7/9/2008 3:47:00 PM”
     C:\PS> $end = [datetime]”7/9/2008 3:47:59 PM”

    The fourth command uses Import-Counter to get only counter data that has a time stamp between the start and end times (inclusive). The command uses the StartTime and EndTime parameters to specify the range.

     C:\PS> $t-data = Import-Counter -Path disk.blg -StartTime $start -EndTime $end

    ————————– EXAMPLE 6 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This example shows how to import the five oldest and five newest samples from a performance counter log file.

    The first command uses the Import-Counter cmdlet to import data from the Disk.blg file. The command uses the MaxSamples parameter to limit the import to five counter samples. This command gets the first (oldest) five samples in the file.

    C:\PS> Import-Counter -Path disk.blg -MaxSamples 5

    The second command uses array notation and the Windows PowerShell range operator (..) to get the last five counter samples from the file. These are the five newest samples.

    C:\PS> (Import-Counter -Path disk.blg)[-1 .. -5]

    ————————– EXAMPLE 7 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This command uses the Summary parameter to get a summary of the counter data from the Memory.blg file.

    C:\PS> Import-Counter D:\Samples\memory.blg -summary

    OldestRecord            NewestRecord            SampleCount
    ————            ————            ———–
    7/10/2008 2:59:18 PM    7/10/2008 3:00:27 PM    1000

    ————————– EXAMPLE 8 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This example updates a performance counter log file.

    The first command uses the ListSet parameter of Import-Counter to get the counters in OldData.blg, an existing counter log file. The command uses a pipeline operator (|) to send the data to a ForEach-Object command that gets only the values of the PathsWithInstances property of each object.

    C:\PS> $counters = Import-Counter olddata.blg -ListSet * | foreach {$_.PathsWithInstances}

    The second command uses those same counters in a new Get-Counter command to get a current sample, and export it to the NewData.blg file.

    C:\PS> Get-Counter -Counter $counters -MaxSamples 20 | Export-Counter c:\Logs\newdata.blg

    ————————– EXAMPLE 9 ————————–

    C:\PS># Import-Counter

    Description
    ———–
    This command imports performance log data from two logs and saves the data in the $counters Variable. The command uses a pipeline operator to send performance log paths to Import-Counter.

    C:\PS> $counters = “d:\test\pdata.blg”, “d:\samples\netlog.blg” | Import-Counter

    Notice that each path is enclosed in quotation marks and that the paths are separated from each other by a comma.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=138338
    Get-Counter
    Export-Counter

cmdlet, Csv, Import

Import-Csv

NAME
    Import-Csv

SYNOPSIS
    Converts object properties in a comma-separated value (CSV) file into CSV versions of the original objects.

SYNTAX
    Import-Csv [[-Delimiter] <char>] [-Path] <string[]> [-Header <string[]>] [<CommonParameters>]

    Import-Csv -UseCulture [-Path] <string[]> [-Header <string[]>] [<CommonParameters>]

DESCRIPTION
    The Import-Csv cmdlet creates objects from CSV Variable-length files that are generated by the Export-Csv cmdlet.

    You can use the parameters of the Import-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 Import-Csv to use the list separator for the current culture as the item delimiter.

    The objects that Import-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.

    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 save the CSV strings in a file.

PARAMETERS
    -Delimiter <char>
        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.

        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.

        Required?                    false
        Position?                    2
        Default value                ,
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Header <string[]>
        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.

        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.

        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.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Path <string[]>
        Specifies the path to the CSV file to import. You can also pipe a path to Import-Csv.

        Required?                    true
        Position?                    1
        Default value                None
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    -UseCulture [<SwitchParameter>]
        Use the list separator for the current culture as the item delimiter. The default is a comma (,).

        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.

        Required?                    true
        Position?                    named
        Default value                Comma
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a path to Import-Csv.

OUTPUTS
    Object.
        Import-Csv returns the objects described by the content in the CSV file.

NOTES

        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.

        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.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Get-Process | Export-Csv processes.csv

    C:\PS> $p = Import-Csv processes.csv

    C:\PS> $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
    …

    C:\PS> $p | Out-GridView

    Description
    ———–
    This example shows how to export and then import a CSV file of Microsoft .NET Framework 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.

    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.

    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.

    ————————– EXAMPLE 2 ————————–

    C:\PS>Get-Process | Export-Csv processes.csv -Delimiter :

    C:\PS> $p = Import-Csv processes.csv -Delimiter :

    Description
    ———–
    This example shows how to use the Delimiter parameter of Import-Csv. In this example, the processes are exported to a file that uses a colon (:) as a delimiter.

    When importing, the Import-Csv file uses the Delimiter parameter to indicate the delimiter that is used in the file.

    ————————– EXAMPLE 3 ————————–

    C:\PS>$p = Import-Csv processes.csv -UseCulture

    C:\PS> (Get-Culture).textinfo.listseparator

    ,

    Description
    ———–
    This example shows how to use the UseCulture parameter of Import-Csv.

    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.

    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.

    ————————– EXAMPLE 4 ————————–

    C:\PS>Start-Job -scriptblock { Get-Process } | Export-Csv jobs.csv

    C:\PS> $header = “MoreData”,”StatusMessage”,”Location”,”Command”,”State”,”Finished”,”InstanceId”,”SessionId”,”Name”,”ChildJobs”,”Output”,”Error”,”Progress”,”Verbose”,”Debug”,”Warning”,”StateChanged”

    # Delete header from file
    C:\PS> $a = (Get-Content jobs.csv)
    C:\PS> $a = $a[0], $a[2..($a.count – 1)]
    C:\PS> $a > jobs.csv

    C:\PS> $j = Import-Csv jobs.csv -Header $header

    C:\PS> $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 :

    Description
    ———–
    This example shows how to use the Header parameter of Import-Csv to change the names of properties in the resulting imported object.

    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.

    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”.

    The next three commands delete the original header (the second line) from the Jobs.csv file.

    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.

    The seventh command displays the object in the $j Variable. The resulting object has “MoreData” and “State” properties, as shown in the command output.

    ————————– EXAMPLE 5 ————————–

    C:\PS>”.\processes.csv” | Import-Csv

    Description
    ———–
    This command imports the objects from the Processes.csv file.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113341
    Export-Csv
    ConvertTo-Csv
    ConvertFrom-Csv

cmdlet, Invoke, Item

Invoke-Item

NAME
    Invoke-Item

SYNOPSIS
    Performs the default action on the specified item.

SYNTAX
    Invoke-Item [-LiteralPath] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Invoke-Item [-Path] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Invoke-Item cmdlet performs the default action on the specified item. For example, it runs an executable file or opens a document file in the application associated with the document file type. The default action depends on the type of item and is determined by the Windows PowerShell provider that provides access to the data.

PARAMETERS
    -Credential <PSCredential>
        Specifies a user account that has permission to perform this action. The default is the current user.

        Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        This parameter is not supported by any providers installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Exclude <string[]>
        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.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Include <string[]>
        Performs the default action only on the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as “*.txt”. Wildcards are permitted.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -LiteralPath <string[]>
        Specifies a path to the item. 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.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Path <string[]>
        Specifies the path to the selected item.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    -Confirm [<SwitchParameter>]
        Prompts you for confirmation before executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -WhatIf [<SwitchParameter>]
        Describes what would happen if you executed the command without actually executing the command.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -UseTransaction [<SwitchParameter>]
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a path to Invoke-Item.

OUTPUTS
    None
        The command does not generate any output. However, output might be generated by the item that it invokes.

NOTES

        The Invoke-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PsSProvider”. For more information, see about_providers.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Invoke-Item C:\Test\aliasApr04.doc

    Description
    ———–
    This command opens the file AliasApr04.doc in Microsoft Office Word. In this case, opening in Word is the default action for .doc files.

    ————————– EXAMPLE 2 ————————–

    C:\PS>Invoke-Item “C:\Documents and Settings\Lister\My Documents\*.xls”

    Description
    ———–
    This command opens all of the Microsoft Office Excel spreadsheets in the C:\Documents and Settings\Lister\My Documents folder. Each spreadsheet is opened in a new instance of Excel. In this case, opening in Excel is the default action for .xls files.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113345
    about_providers
    Clear-Item
    Get-Item
    Move-Item
    Set-Item
    New-Item
    Remove-Item
    Rename-Item
    Copy-Item

cmdlet, Get, Item

Get-Item

NAME
    Get-Item

SYNOPSIS
    Gets the item at the specified location.

SYNTAX
    Get-Item [-LiteralPath] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-UseTransaction] [<CommonParameters>]

    Get-Item [-Path] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Get-Item cmdlet gets the item at the specified location. It does not get the contents of the item at the location unless you use a wildcard character (*) to request all the contents of the item.

    The Get-Item cmdlet is used by Windows PowerShell providers to enable you to navigate through different types of data stores.

PARAMETERS
    -Credential <PSCredential>
        Specifies a user account that has permission to perform this action. The default is the current user.

        Type a user-name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        This parameter is not supported by any providers installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Exclude <string[]>
        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.

        The Exclude parameter is effective only when the command includes the contents of an item, such as C:\Windows\*, where the wildcard character specifies the contents of the C:\Windows directory.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Force [<SwitchParameter>]
        Allows the cmdlet to get items that cannot otherwise be accessed, such as hidden items. Implementation varies from provider to provider. For more information, see about_providers. Even using the Force parameter, the cmdlet cannot override security restrictions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Include <string[]>
        Retrieves 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.

        The Include parameter is effective only when the command includes the contents of an item, such as C:\Windows\*, where the wildcard character specifies the contents of the C:\Windows directory.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -LiteralPath <string[]>
        Specifies a path to the item. Unlike Path, 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.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Path <string[]>
        Specifies the path to an item. Get-Item gets the item at the specified location. Wildcards are permitted. This parameter is required, but the parameter name (“Path”) is optional.

        Use a dot (.) to specify the current location. Use the wildcard character (*) to specify all the items in the current location.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    -UseTransaction [<SwitchParameter>]
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a path to Get-Item.

OUTPUTS
    Object
        Get-Item returns the objects that it gets. The type is determined by the type of objects in the path.

NOTES

        You can also refer to Get-Item by its built-in Alias, “gi”. For more information, see about_aliases.

        Get-Item does not have a Recurse parameter, because it gets only an item, not its contents. To get the contents of an item recursively, use Get-ChildItem.

        To navigate through the Registry, use Get-Item to get Registry keys and Get-ItemProperty to get Registry values and data. The Registry values are considered to be properties of the Registry key.

        The Get-Item cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Get-Item .

    Directory: C:\

    Mode                LastWriteTime     Length Name
    —-                ————-     —— —-
    d—-         7/26/2006 10:01 AM            ps-test

    Description
    ———–
    This command gets the current directory. The dot (.) represents the item at the current location (not its contents).

    ————————– EXAMPLE 2 ————————–

    C:\PS>Get-Item *

    Directory: C:\ps-test

    Mode                LastWriteTime     Length Name
    —-                ————-     —— —-
    d—-         7/26/2006 9:29 AM            Logs
    d—-         7/26/2006 9:26 AM            Recs
    -a—         7/26/2006 9:28 AM         80 date.csv
    -a—         7/26/2006 10:01 AM         30 filenoext
    -a—         7/26/2006 9:30 AM     11472 process.doc
    -a—         7/14/2006 10:47 AM         30 test.txt

    Description
    ———–
    This command gets all the items in the current directory. The wildcard character (*) represents all the contents of the current item.

    ————————– EXAMPLE 3 ————————–

    C:\PS>Get-Item C:\

    Description
    ———–
    This command gets the current directory of the C: drive. The object that is retrieved represents only the directory, not its contents.

    ————————– EXAMPLE 4 ————————–

    C:\PS>Get-Item C:\*

    Description
    ———–
    This command gets the items in the C: drive. The wildcard character (*) represents all the items in the container, not just the container.

    In Windows PowerShell, use a single asterisk (*) to get contents, instead of the traditional “*.*”. The format is interpreted literally, so “*.*” would not retrieve directories or file names without a dot.

    ————————– EXAMPLE 5 ————————–

    C:\PS>(Get-Item C:\Windows).LastAccessTime

    Description
    ———–
    This command gets the LastAccessTime property of the C:\Windows directory. LastAccessTime is just one property of file system directories. To see all of the properties of a directory, type “(Get-Item <directory-name>) | Get-Member“.

    ————————– EXAMPLE 6 ————————–

    C:\PS>Get-Item hklm:\software\microsoft\powershell\1\shellids\microsoft.powershell\*

    Description
    ———–
    This command shows the contents of the Microsoft.PowerShell Registry key. You can use Get-Item with the Windows PowerShell Registry provider to get Registry keys and subkeys, but you must use Get-ItemProperty to get the Registry values and data.

    ————————– EXAMPLE 7 ————————–

    C:\PS>Get-Item c:\Windows\* -Include *.* -Exclude w*

    Description
    ———–
    This command gets items in the Windows directory with names that include a dot (.), but do not begin with w*. This command works only when the path includes a wildcard character (*) to specify the contents of the item.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113319
    about_providers
    Clear-Item
    Copy-Item
    Invoke-Item
    Move-Item
    Set-Item
    New-Item
    Remove-Item
    Rename-Item

cmdlet, Get, ItemProperty

Get-ItemProperty

NAME
    Get-ItemProperty

SYNOPSIS
    Gets the properties of a specified item.

SYNTAX
    Get-ItemProperty [-LiteralPath] <string[]> [[-Name] <string[]>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-UseTransaction] [<CommonParameters>]

    Get-ItemProperty [-Path] <string[]> [[-Name] <string[]>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Get-ItemProperty cmdlet gets the properties of the specified items. For example, you can use Get-ItemProperty to get the value of the LastAccessTime property of a file object. You can also use Get-ItemProperty to view Registry entries and their values.

PARAMETERS
    -Credential <PSCredential>
        Specifies a user account that has permission to perform this action. The default is the current user.

        Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        This parameter is not supported by any providers installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Exclude <string[]>
        Omits the specified items. Wildcards are permitted.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Include <string[]>
        Includes the specified items.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -LiteralPath <string[]>
        Specifies a path to the item property. 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.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Name <string[]>
        Specifies the name of the property or properties to retrieve.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Path <string[]>
        Specifies the path to the item or items.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        Accept wildcard characters? false

    -UseTransaction [<SwitchParameter>]
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a path to Get-ItemProperty.

OUTPUTS
    Object
        Get-ItemProperty returns an object for each item property that it gets. The object type depends on the object that is retrieved.

NOTES

        The Get-ItemProperty cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Get-Itemproperty C:\Windows

    Description
    ———–
    This command gets information about the C:\Windows directory.

    ————————– EXAMPLE 2 ————————–

    C:\PS>Get-Itemproperty C:\Test\Weather.xls | Format-List

    Description
    ———–
    This command gets the properties of the C:\Test\Weather.xls file. The result is piped to the Format-List cmdlet to display the output as a list.

    ————————– EXAMPLE 3 ————————–

    C:\PS>Get-Itemproperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion

    Description
    ———–
    This command displays the value name and data of each of the Registry entries contained in the CurrentVersion Registry subkey. Note that the command requires that there is a Windows PowerShell drive named HKLM: that is mapped to the HKEY_LOCAL_MACHINE hive of the Registry. A drive with that name and mapping is available in Windows PowerShell by default. Alternatively, the path to this Registry subkey can be specified by using the following alternative path that begins with the provider name followed by two colons:
    Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion.

    ————————– EXAMPLE 4 ————————–

    C:\PS>Get-Itemproperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion `
    -Name “ProgramFilesDir”

    Description
    ———–
    This command gets the value name and data of the ProgramFilesDir Registry entry in the CurrentVersion Registry subkey. The command uses the Path parameter to specify the subkey and the Name parameter to specify the value name of the entry.

    ————————– EXAMPLE 5 ————————–

    C:\PS>Get-Itemproperty -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\PowerShellEngine

    ApplicationBase         : C:\Windows\system32\WindowsPowerShell\v1.0\
    ConsoleHostAssemblyName : Microsoft.PowerShell.ConsoleHost, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad
                             364e35, ProcessorArchitecture=msil
    PowerShellVersion     : 2.0
    RuntimeVersion         : v2.0.50727
    CTPVersion             : 5
    PSCompatibleVersion     : 1.0,2.0

    Description
    ———–
    This command gets the value names and data of the Registry entries in the PowerShellEngine Registry key. The results are shown in the following sample output.

    ————————– EXAMPLE 6 ————————–

    C:\PS>Get-Itemproperty -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell

    Path                                                        ExecutionPolicy
    —-                                                        —————
    C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe RemoteSigned

    C:\PS>Get-Itemproperty -Path HKLM:\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell | Format-List -property *

    PSPath         : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\PowerShell\1\ShellIds\Micro
                     soft.PowerShell
    PSParentPath    : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\Software\Microsoft\PowerShell\1\ShellIds
    PSChildName     : Microsoft.PowerShell
    PSDrive         : HKLM
    PSProvider     : Microsoft.PowerShell.Core\Registry
    Path            : C:\Windows\system32\WindowsPowerShell\v1.0\powershell.exe
    ExecutionPolicy : RemoteSigned

    Description
    ———–
    This example shows how to format the output of a Get-ItemProperty command in a list to make it easy to see the Registry values and data and to make it easy to interpret the results.

    The first command uses the Get-ItemProperty cmdlet to get the Registry entries in the Microsoft.PowerShell subkey. This subkey stores options for the default shell for Windows PowerShell. The results are shown in the following sample output.

    The output shows that there are two Registry entries, Path and ExecutionPolicy. When a Registry key contains fewer than five entries, by default it is displayed in a table, but it is often easier to view in a list.

    The second command uses the same Get-ItemProperty command. However, this time, the command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet. The Format-List command uses the Property parameter with a value of * (all) to display all of the properties of the objects in a list. The results are shown in the following sample output.

    The resulting display shows the Path and ExecutionPolicy Registry entries, along with several less familiar properties of the Registry key object. The other properties, prefixed with “PS”, are properties of Windows PowerShell custom objects, such as the objects that represent the Registry keys.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113320
    about_providers
    Set-ItemProperty
    Clear-ItemProperty
    Copy-ItemProperty
    Move-ItemProperty
    New-ItemProperty
    Remove-ItemProperty
    Rename-ItemProperty

cmdlet, Get, Help

Get-Help

NAME
    Get-Help

SYNOPSIS
    Displays information about Windows PowerShell commands and concepts.

SYNTAX
    Get-Help [-Full] [[-Name] <string>] [-Category <string[]>] [-Component <string[]>] [-Functionality <string[]>] [-Online] [-Path <string>] [-Role <string[]>] [<CommonParameters>]

    Get-Help [-Detailed] [[-Name] <string>] [-Category <string[]>] [-Component <string[]>] [-Functionality <string[]>] [-Online] [-Path <string>] [-Role <string[]>] [<CommonParameters>]

    Get-Help [-Examples] [[-Name] <string>] [-Category <string[]>] [-Component <string[]>] [-Functionality <string[]>] [-Online] [-Path <string>] [-Role <string[]>] [<CommonParameters>]

    Get-Help [-Parameter <string>] [[-Name] <string>] [-Category <string[]>] [-Component <string[]>] [-Functionality <string[]>] [-Online] [-Path <string>] [-Role <string[]>] [<CommonParameters>]

DESCRIPTION
    The Get-Help cmdlet displays information about Windows PowerShell concepts and commands, including cmdlets, providers, Functions and scripts. To get a list of all cmdlet help topic titles, type “Get-Help *”.

    If you type “Get-Help” followed by the exact name of a help topic, or by a word unique to a help topic, Get-Help displays the topic contents. If you enter a word or word pattern that appears in several help topic titles, Get-Help displays a list of the matching titles. If you enter a word that does not appear in any help topic titles, Get-Help displays a list of topics that include that word in their contents.

    In addition to “Get-Help“, you can also type “help” or “man”, which displays one screen of text at a time, or “<cmdlet-Name> -?”, which is identical to Get-Help but works only for cmdlets.

    You can display the entire help file or selected parts of the file, such as the syntax, parameters, or examples. You can also use the Online parameter to display an online version of a help file in your Internet browser. These parameters have no effect on conceptual help topics.

    Conceptual help topics in Windows PowerShell begin with “about_”, such as “about_Comparison_Operators”. To see all “about_” topics, type “Get-Help about_*”. To see a particular topic, type “Get-Help about_<topic-Name>”, such as “Get-Help about_Comparison_Operators“.

PARAMETERS
    -Category <string[]>
        Displays help for items in the specified category. Valid values are Alias, Cmdlet, Provider, and HelpFile. Conceptual topics are in the HelpFile category.

        Category is a property of the MamlCommandHelpInfo object that Get-Help returns. This parameter has no effect on displays of conceptual (“about_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Component <string[]>
        Displays a list of tools with the specified component value, such as “Exchange.” Enter a component name. Wildcards are permitted.

        Component is a property of the MamlCommandHelpInfo object that Get-Help returns. This parameter has no effect on displays of conceptual (“About_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Detailed [<SwitchParameter>]
        Adds parameter descriptions and examples to the basic help display.

        This parameter has no effect on displays of conceptual (“About_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Examples [<SwitchParameter>]
        Displays only the name, synopsis, and examples. To display only the examples, type “(Get-Help <cmdlet-Name>).examples”.

        This parameter has no effect on displays of conceptual (“About_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Full [<SwitchParameter>]
        Displays the entire help file for a cmdlet, including parameter descriptions and attributes, examples, input and output object types, and additional notes.

        This parameter has no effect on displays of conceptual (“About_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Functionality <string[]>
        Displays help for items with the specified Functionality. Enter the Functionality. Wildcards are permitted.

        Functionality is a property of the MamlCommandHelpInfo object that Get-Help returns. This parameter has no effect on displays of conceptual (“About_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Name <string>
        Requests help about the specified tool or conceptual topic. Enter a cmdlet, provider, script, or Function name, such as Get-Member, a conceptual topic name, such as “about_Objects”, or an Alias, such as “ls”. Wildcards are permitted in cmdlet and provider names, but you cannot use wildcards to find the names of Function help and script help topics.

        To get help for a script that is not located in a path that is listed in the Path Environment Variable, type the path and file name of the script .

        If you enter the exact name of a help topic, Get-Help displays the topic contents. If you enter a word or word pattern that appears in several help topic titles, Get-Help displays a list of the matching titles. If you enter a word that does not match any help topic titles, Get-Help displays a list of topics that include that word in their contents.

        The names of conceptual topics, such as about_objects, must be entered in English, even in non-English versions of Windows PowerShell.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Online [<SwitchParameter>]
        Displays the online version of a help topic in the default Internet browser. This parameter is valid only for cmdlet, Function, and script help topics.

        Get-Help uses the Internet address (Uniform Resource Identifier [URI]) that appears in the first item of the Related Links section of a cmdlet, Function, or script help topic. This parameter works only when the help topic includes a URI that begins with “Http” or “Https” and an Internet browser is installed on the system.

        For information about supporting this feature in help topics that you write, see about_Comment_Based_Help, and see “How to Write Cmdlet Help” in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkID=123415.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Parameter <string>
        Displays only the detailed descriptions of the specified parameters. Wildcards are permitted.

        This parameter has no effect on displays of conceptual (“About_”) help.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Path <string>
        Gets help that explains how the cmdlet works in the specified provider path. Enter a Windows PowerShell provider path.

        This parameter gets a customized version of a cmdlet help topic that explains how the cmdlet works in the specified Windows PowerShell provider path. This parameter is effective only for help about a provider cmdlet and only when the provider includes a custom version of the provider cmdlet help topic.

        To see the custom cmdlet help for a provider path, go to the provider path location and enter a Get-Help command or, from any path location, use the Path parameter of Get-Help to specify the provider path. For more information, see about_providers.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Role <string[]>
        Displays help customized for the specified user role. Enter a role. Wildcards are permitted.

        Enter the role that the user plays in an organization. Some cmdlets display different text in their help files based on the value of this parameter. This parameter has no effect on help for the core cmdlets.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    None
        You cannot pipe objects to this cmdlet.

OUTPUTS
    System.String or MamlCommandHelpInfo
        If you request a conceptual topic, Get-Help returns it as a string. If you specify the name of a cmdlet,, Function, or script, it returns a MamlCommandHelpInfo object. Otherwise, Get-Help returns one of the formatted views that are specified in the Help.Format.ps1xml file in the $pshome directory.

NOTES

        Without parameters, “Get-Help” displays information about the Windows PowerShell help system.

        The full view of help (-Full) includes a table of information about the parameters. The table includes the following fields:

        — Required: Indicates whether the parameter is required (true) or optional (false).

        — Position: Indicates whether the parameter is named or positional (numbered). Positional parameters must appear in a specified place in the command.

        — “Named” indicates that the parameter name is required, but that the parameter can appear anywhere in the command.

        — <Number> indicates that the parameter name is optional, but when the name is omitted, the parameter must be in the place specified by the number. For example, “2” indicates that when the parameter name is omitted, the parameter must be the second (2) or only unnamed parameter in the command. When the parameter name is used, the parameter can appear anywhere in the command.

        — Default value: The parameter value that Windows PowerShell uses if you do not include the parameter in the command.

        — Accepts pipeline input: Indicates whether you can (true) or cannot (false) send objects to the parameter through a pipeline. “By Property Name” means that the pipelined object must have a property with the same name as the parameter name.

        — Accepts wildcard characters: Indicates whether the value of a parameter can include wildcard characters, such as * and ?.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Get-Help

    Description
    ———–
    This command displays help about the Windows PowerShell help system.

    ————————– EXAMPLE 2 ————————–

    C:\PS>Get-Help *

    Description
    ———–
    This command displays a list of all help files in the Windows PowerShell help system.

    ————————– EXAMPLE 3 ————————–

    C:\PS>Get-Help Get-Alias

    C:\PS>help Get-Alias

    C:\PS>Get-Alias -?

    Description
    ———–
    These commands display basic information about the Get-Alias cmdlet. The “Get-Help” and “-?” commands display the information on a single page. The “Help” command displays the information one page at a time.

    ————————– EXAMPLE 4 ————————–

    C:\PS>Get-Help about_*

    Description
    ———–
    This command displays a list of the conceptual topics included in Windows PowerShell help. All of these topics begin with the characters “about_”. To display a particular help file, type “Get-Help <topic-Name>, for example, “Get-Help about_Signing“.

    ————————– EXAMPLE 5 ————————–

    C:\PS>Get-Help ls -detailed

    Description
    ———–
    This command displays detailed help for the Get-ChildItem cmdlet by specifying one of its Aliases, “ls.” The Detailed parameter requests the detailed view of the help file, which includes parameter descriptions and examples. To see the complete help file for a cmdlet, use the Full parameter.

    ————————– EXAMPLE 6 ————————–

    C:\PS>Get-Help format-string -Full

    Description
    ———–
    This command displays the full view help for the Format-String cmdlet. The full view of help includes parameter descriptions, examples, and a table of technical details about the parameters.

    ————————– EXAMPLE 7 ————————–

    C:\PS>Get-Help Start-Service -examples

    Description
    ———–
    This command displays examples of using Start-Service in Windows PowerShell commands.

    ————————– EXAMPLE 8 ————————–

    C:\PS>Get-Help Get-ChildItem -parameter f*

    Description
    ———–
    This command displays descriptions of the parameters of the Get-ChildItem cmdlet that begin with “f” (filter and force). For descriptions of all parameters, type “Get-Help Get-ChildItem parameter*”.

    ————————– EXAMPLE 9 ————————–

    C:\PS>(Get-Help Write-Output).syntax

    Description
    ———–
    This command displays only the syntax of the Write-Output cmdlet.

    Syntax is one of many properties of help objects; others are description, details, examples, and parameters. To find all properties and methods of help objects, type “Get-Help <cmdlet-Name> | Get-Member“; for example, “Get-Help Start-Service | get member”.

    ————————– EXAMPLE 10 ————————–

    C:\PS>(Get-Help Trace-Command).alertset

    Description
    ———–
    This command displays the notes about the cmdlet. The notes are stored in the alertSet property of the help object.

    The notes include conceptual information and tips for using the cmdlet. By default, the notes are displayed only when you use the Full parameter of Get-Help, but you can also display them by using the alertSet property.

    ————————– EXAMPLE 11 ————————–

    C:\PS>Get-Help Add-Member -Full | Out-String -stream | Select-String -pattern clixml

    Description
    ———–
    This example shows how to search for a word in particular cmdlet help topic. This command searches for the word “clixml” in the full version of the help topic for the Add-Member cmdlet.

    Because the Get-Help cmdlet generates a MamlCommandHelpInfo object, not a string, you need to use a command that transforms the help topic content into a string, such as Out-String or Out-File.

    ————————– EXAMPLE 12 ————————–

    C:\PS>Get-Help Get-Member -Online

    Description
    ———–
    This command displays the online version of the help topic for the Get-Member cmdlet.

    ————————– EXAMPLE 13 ————————–

    C:\PS>Get-Help remoting

    Description
    ———–
    This command displays a list of topics that include the word “remoting” in their contents.

    When you enter a word that does not appear in any topic title, Get-Help displays a list of topics that include that word.

    ————————– EXAMPLE 14 ————————–

    C:\PS>Get-Help Get-Item -Path SQLSERVER:\DataCollection

    NAME
        Get-Item

    SYNOPSIS
        Gets a collection of Server objects for the local computer and any computers to which you have made a SQL Server PowerShell connection.
    …

    C:\PS> cd SQLSERVER:\DataCollection
    C:\PS> SQLSERVER:\DataCollection> Get-Help Get-Item

    NAME
        Get-Item

    SYNOPSIS
        Gets a collection of Server objects for the local computer and any computers to which you have made a SQL Server PowerShell connection.
    …

    C:\PS> Get-Item

    NAME
        Get-Item

    SYNOPSIS
        Gets the item at the specified location.

    …

    Description
    ———–
    This example shows how to get help for the Get-Item cmdlet that explains how to use the cmdlet in the DataCollection node of the Windows PowerShell SQL Server provider.

    The example shows two ways of getting the custom help for Get-Item.

    The first command uses the Path parameter of Get-Help to specify the provider path. This command can be entered at any path location.

    The second command uses the Set-Location cmdlet (alias = “cd”) to go to the provider path. From that location, even without the Path parameter, the Get-Help command gets the custom help for the provider path.

    The third command shows that a Get-Help command in a file system path, and without the Path parameter, gets the standard help for the Get-Item cmdlet.

    ————————– EXAMPLE 15 ————————–

    C:\PS>Get-Help c:\ps-test\MyScript.ps1

    Description
    ———–
    This command gets help for the MyScript.ps1 script. For information about writing help for your Functions and scripts, see about_Comment_Based_Help.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113316

    about_Comment_Based_Help
    Get-Command
    Get-PSDrive
    Get-Member

cmdlet, Content, Get

Get-Content

NAME
    Get-Content

SYNOPSIS
    Gets the content of the item at the specified location.

SYNTAX
    Get-Content [-LiteralPath] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-ReadCount <Int64>] [-TotalCount <Int64>] [-UseTransaction] [<CommonParameters>]

    Get-Content [-Path] <string[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-ReadCount <Int64>] [-TotalCount <Int64>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Get-Content cmdlet gets the content of the item at the location specified by the path, such as the text in a file. It reads the content one line at a time and returns an object for each line.

PARAMETERS
    -Credential <PSCredential>
        Specifies a user account that has permission to perform this action. The default is the current user.

        Type a user name, such as “User01” or “Domain01\User01”, or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

        This parameter is not supported by any providers that are installed with Windows PowerShell.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Exclude <string[]>
        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.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Force [<SwitchParameter>]
        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.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Include <string[]>
        Retrieves 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.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -LiteralPath <string[]>
        Specifies the path to an item. Unlike Path, 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.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -Path <string[]>
        Specifies the path to an item. Get-Content retrieves the content of the item. Wildcards are permitted. The parameter name (“Path” or “FilePath”) is optional.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -ReadCount <Int64>
        Specifies how many lines of content are sent through the pipeline at a time. The default value is 1. A value of 0 (zero) sends all of the content at one time.

        This parameter does not change the content displayed, but it does affect the time it takes to display the content. As the value of ReadCount increases, the time it takes to return the first line increases, but the total time for the operation decreases. This can make a perceptible difference in very large items.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -TotalCount <Int64>
        Specifies how many lines of content are retrieved. The default is -1 (all lines).

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -UseTransaction [<SwitchParameter>]
        Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_transactions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    None
        You cannot pipe input to Get-Content.

OUTPUTS
    Object
        Get-Content returns objects that represent the content that it gets. The object type depends on the content type.

NOTES

        You can also refer to Get-Content by its built-in Aliases, “cat”, “type” and “gc”. For more information, see about_aliases.

        The Get-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type “Get-PSProvider“. For more information, see about_providers.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Get-Content -Path C:\Chapters\chapter1.txt

    Description
    ———–
    This command displays the content of the Chapter1.txt file on the console. It uses the Path parameter to specify the name of the item. Get-Content actually passes the content down the pipeline, but because there are no other pipeline elements, the content is formatted and displayed on the console.

    ————————– EXAMPLE 2 ————————–

    C:\PS>Get-Content c:\Logs\Log060912.txt -TotalCount 50 | Set-Content sample.txt

    Description
    ———–
    This command gets the first 50 lines of the Log060912.txt file and stores them in the sample.txt file. The command uses the Get-Content cmdlet to get the text in the file. (The name of Path parameter, which is optional, is omitted.) The TotalCount parameter limits the retrieval to the first 50 lines. The pipeline operator (|) sends the result to Set-Content, which places it in the sample.txt file.

    ————————– EXAMPLE 3 ————————–

    C:\PS>(Get-Content cmdlets.txt -TotalCount 5)[-1]

    Description
    ———–
    This command gets the fifth line of the Cmdlets.txt text file. It uses the TotalCount parameter to get the first five lines and then uses array notation to get the last line (indicated by “-1”) of the resulting set.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113310
    about_providers
    Add-Content
    Set-Content
    Clear-Content