All posts by Adam

New-WSManInstance

February 26, 2014 Adam

SYNOPSIS
Creates a new instance of a management resource.

SYNTAX
New-WSManInstance [-ApplicationName <string>] [-ComputerName <string>] [-Credential <PSCredential>] [-Port <int>] [-UseSSL] [-SelectorSet] <hashtable> -ResourceURI <Uri> [-AuthenticationMechanism <AuthenticationMechanism>] [-SessionOption <hashtable>] [-ValueSet <hashtable>] [<CommonParameters>]

New-WSManInstance [-ConnectionURI <Uri>] [-SelectorSet] <hashtable> -ResourceURI <Uri> [-AuthenticationMechanism <AuthenticationMechanism>] [-SessionOption <hashtable>] [-ValueSet <hashtable>] [<CommonParameters>]

DESCRIPTION
The New-WSManInstance cmdlet creates a new instance of a management resource. It uses a resource URI and a value set or input file to create the new instance of the management resource.

This cmdlet uses the WinRM connection/transport layer to create the management resource instance.

PARAMETERS
-ApplicationName <string>
Specifies the application name in the connection. The default value of the ApplicationName parameter is “WSMAN”. The complete identifier for the remote endpoint is in the following format:

For example:

http://server01:8080/WSMAN

Internet Information Services (IIS), which hosts the session, forwards requests with this endpoint to the specified application. This default setting of “WSMAN” is appropriate for most uses. This parameter is designed to be used when numerous computers establish remote connections to one computer that is running Windows PowerShell. In this case, IIS hosts Web Services for Management (WS-Management) for efficiency.

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

-AuthenticationMechanism <AuthenticationMechanism>
Specifies the authentication mechanism to be used at the server. Possible values are:

        – Basic: Basic is a scheme in which the user name and password are sent in clear text to the server or proxy.
        – Default : Use the authentication method implemented by the WS-Management protocol. This is the default.
        – Digest: Digest is a challenge-response scheme that uses a server-specified data string for the challenge.
        – Kerberos: The client computer and the server mutually authenticate by using Kerberos Certificates.
        – Negotiate: Negotiate is a challenge-response scheme that negotiates with the server or proxy to determine the scheme to use for authentication. For example, this parameter value allows negotiation to determine whether the Kerberos protocol or NTLM is used.
        – CredSSP: Use Credential Security Service Provider (CredSSP) authentication, which allows the user to delegate credentials. This option is designed for commands that run on one remote computer but collect data from or run additional commands on other remote computers.

Caution: CredSSP delegates the user’s credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session.

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

-ComputerName <string>
Specifies the computer against which you want to run the management operation. The value can be a fully qualified domain name, a NetBIOS name, or an IP address. Use the local computer name, use localhost, or use a dot (.) to specify the local computer. The local computer is the default. When the remote computer is in a different domain from the user, you must use a fully qualified domain name must be used. You can pipe a value for this parameter to the cmdlet.

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

-ConnectionURI <Uri>
Specifies the connection endpoint. The format of this string is:

The following string is a properly formatted value for this parameter:

http://Server01:8080/WSMAN

The URI must be fully qualified.

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

-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”, “Domain01\User01”, or “User@Domain.com”. Or, enter a PSCredential object, such as one returned by the Get-Credential cmdlet. When you type a user name, you will be prompted for a password.

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

-File <File>
Specifies the path of a file that is used to create a management resource. You specify the management resource by using the ResourceURI parameter and the SelectorSet parameter . For example, the following command uses the File parameter:

Invoke-WSManAction -action stopservice -ResourceURI wmicimv2/Win32_Service -SelectorSet @{Name=”spooler”} -File c:\input.xml -Authentication default

This command calls the StopService method [descriptor] on the Spooler service by using input from a file. The file, Input.xml, contains the following content:

<p:StopService_INPUT xmlns:p=”http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_Service”/>

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

-OptionSet <hashtable>
Passes a set of switches to a service to modify or refine the nature of the request. These are similar to switches used in command-line shells because they are service specific. Any number of options can be specified.

The following example demonstrates the syntax that passes the values 1, 2, and 3 for the a, b, and c parameters:

-OptionSet @{a=1;b=2;c=3}

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

-Port <int>
Specifies the port to use when the client connects to the WinRM service. When the transport is HTTP, the default port is 80. When the transport is HTTPS, the default port is 443. When you use HTTPS as the transport, the value of the ComputerName parameter must match the server’s Certificate common name (CN). However, if the SkipCNCheck parameter is specified as part of the SessionOption parameter, then the Certificate common name of the server does not have to match the host name of the server. The SkipCNCheck parameter should be used only for trusted computers.

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

-ResourceURI <Uri>
Contains the Uniform Resource Identifier (URI) of the resource class or instance. The URI is used to identify a specific type of resource, such as disks or processes, on a computer.

A URI consists of a prefix and a path to a resource. For example:

http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk
http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor

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

-SelectorSet <hashtable>
Specifies a set of value pairs that are used to select particular management resource instances. The SelectorSet parameter is used when more than one instance of the resource exists. The value of the SelectorSet parameter must be a hash table.

The following example shows how to enter a value for this parameter:

-SelectorSet @{Name=”WinRM”;ID=”yyy”}

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

-SessionOption <hashtable>
Defines a set of extended options for the WS-Management session. Enter a SessionOption object that you create by using the New-WSManSessionOption cmdlet. For more information about the options that are available, see New-WSManSessionOption.

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

-UseSSL [<SwitchParameter>]
Specifies that the Secure Sockets Layer (SSL) protocol should be used to establish a connection to the remote computer. By default, SSL is not used.

WS-Management encrypts all the Windows PowerShell content that is transmitted over the network. The UseSSL parameter lets you specify the additional protection of HTTPS instead of HTTP. If SSL is not available on the port that is used for the connection and you specify this parameter, the command fails.

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

-ValueSet <hashtable>
Specifies a hash table that helps modify a management resource. You specify the management resource by using the ResourceURI parameter and the SelectorSet parameter. The value of the ValueSet parameter must be a hash table.

        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
This cmdlet does not accept any input.

OUTPUTS
None
This cmdlet does not generate any output.

NOTES

The Set-WmiInstance cmdlet, a Windows Management Instrumentation (WMI) cmdlet, is similar. Set-WmiInstance uses the DCOM connection/transport layer to create or update WMI instances.

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

C:\PS>New-WSManInstance winrm/config/Listener -SelectorSet @{Transport=HTTPS} -ValueSet @{Hostname=”HOST”;CertificateThumbprint=”XXXXXXXXXX”}

    Description
    ———–
    This command creates an instance of a WS-Management HTTPS listener on all IP addresses.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkId=141448
    Connect-WSMan
    Disable-WSManCredSSP
    Disconnect-WSMan
    Enable-WSManCredSSP
    Get-WSManCredSSP
    Get-WSManInstance
    Invoke-WSManAction
    New-WSManSessionOption
    Remove-WSManInstance
    Set-WSManInstance
    Set-WSManQuickConfig
    Test-WSMan

cmdlet, New, WebServiceProxy

New-WebServiceProxy

February 26, 2014 Adam

NAME
New-WebServiceProxy

SYNOPSIS
Creates a Web service proxy object that lets you use and manage the Web service in Windows PowerShell.

SYNTAX
New-WebServiceProxy [-Uri] <Uri> [[-Class] <string>] [[-Namespace] <string>] [<CommonParameters>]

New-WebServiceProxy [-Uri] <Uri> [[-Class] <string>] [[-Namespace] <string>] [-Credential <PSCredential>] [<CommonParameters>]

New-WebServiceProxy [-Uri] <Uri> [[-Class] <string>] [[-Namespace] <string>] [-UseDefaultCredential] [<CommonParameters>]

DESCRIPTION
The New-WebServiceProxy cmdlet lets you use a Web service in Windows PowerShell. The cmdlet connects to a Web service and creates a Web service proxy object in Windows PowerShell. You can use the proxy object to manage the Web service.

A Web service is an XML-based program that exchanges data over a network, particularly over the Internet. The Microsoft .NET Framework provides Web service proxy objects that represent the Web service as a .NET Framework object.

PARAMETERS
-Class <string>
Specifies a name for the proxy class that the cmdlet creates for the Web service. The value of this parameter is used with the Namespace parameter to provide a fully qualified name for the class. The default value is generated from the URI.

        Required?                    false
        Position?                    2
        Default value                Generated from the URI
        Accept pipeline input?     false
        Accept wildcard characters? false

-Credential <PSCredential>
Specifies a user account that has permission to perform this action. The default is the current user. This is an alternative to using the UseDefaultCredential parameter.

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.

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

-Namespace <string>
Specifies a namespace for the new class.

The value of this parameter is used with the value of the Class parameter to generate a fully qualified name for the class. The default value is Microsoft.PowerShell.Commands.NewWebserviceProxy.AutogeneratedTypes plus a type that is generated from the URI.

You can set the value of the Namespace parameter so that you can access multiple Web services with the same name.

        Required?                    false
        Position?                    3
        Default value                Microsoft.PowerShell.Commands.NewWebserviceProxy.AutogeneratedTypes
        Accept pipeline input?     false
        Accept wildcard characters? false

-Uri <Uri>
Specifies the URI of the Web service. Enter a URI or the path and file name of a file that contains a service description.

The URI must refer to an .asmx page or to a page that returns a service description. To return a service description of a Web service that was created by using ASP.NET, append “?WSDL” to the URL of the Web service (for example, http://www.contoso.com/MyWebService.asmx?WSDL).

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

-UseDefaultCredential [<SwitchParameter>]
Sets the UseDefaultCredential parameter in the resulting proxy object to True. This is an alternative to using the Credential parameter.

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

INPUTS
None
This cmdlet does not take input from the pipeline.

OUTPUTS
A Web service proxy object
The namespace and class of the object are determined by the parameters of the command. The default is generated from the input Uniform Resource Identifier (URI).

NOTES

New-WebServiceProxy uses the System.Net.WebClient class to load the specified Web service.

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

C:\PS>$zip = New-WebServiceProxy -Uri http://www.webservicex.net/uszip.asmx?WSDL

    Description
    ———–
    This command uses the New-WebServiceProxy command to create a .NET Framework proxy of the US Zip Web service in Windows PowerShell.

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

C:\PS>$URI = “http://www.webservicex.net/uszip.asmx?WSDL”

C:\PS> $zip = New-WebServiceProxy -Uri $URI -Namespace WebServiceProxy -Class ZipClass

    Description
    ———–
    This command uses the New-WebServiceProxy cmdlet to create a .NET Framework proxy of the US Zip Web service.

The first command stores the URI of the Web service in the $URI Variable.

The second command creates the Web service proxy. The command uses the URI parameter to specify the URI and the Namespace and Class parameters to specify the namespace and class of the object.

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

C:\PS>$zip | Get-Member -type method

TypeName: WebServiceProxy.USZip

    Name                     MemberType Definition
    —-                     ———- ———-
    Abort                     Method     System.Void Abort(
    BeginGetInfoByAreaCode    Method     System.IAsyncResul
    BeginGetInfoByCity        Method     System.IAsyncResul
    BeginGetInfoByState     Method     System.IAsyncResul
    BeginGetInfoByZIP         Method     System.IAsyncResul
    CreateObjRef             Method     System.Runtime.Rem
    Discover                 Method     System.Void Discov
    Dispose                 Method     System.Void Dispos
    EndGetInfoByAreaCode     Method     System.Xml.XmlNode
    EndGetInfoByCity         Method     System.Xml.XmlNode
    EndGetInfoByState         Method     System.Xml.XmlNode
    EndGetInfoByZIP         Method     System.Xml.XmlNode
    Equals                    Method     System.Boolean Equ
    GetHashCode             Method     System.Int32 GetHa
    GetInfoByAreaCode         Method     System.Xml.XmlNode
    GetInfoByCity             Method     System.Xml.XmlNode
    GetInfoByState            Method     System.Xml.XmlNode
    GetInfoByZIP             Method     System.Xml.XmlNode
    GetLifetimeService        Method     System.Object GetL
    GetType                 Method     System.Type GetTyp
    InitializeLifetimeService Method     System.Object Init
    ToString                 Method     System.String ToSt

    Description
    ———–
    This command uses the Get-Member cmdlet to display the methods of the Web service proxy object in the $zip Variable. We will use these methods in the following example.

Notice that the TypeName of the proxy object, WebServiceProxy, reflects the namespace and class names that were specified in the previous example.

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

C:\PS>$zip.getinfobyzip(20500).table

    CITY     : Washington
    STATE     : DC
    ZIP     : 20500
    AREA_CODE : 202
    TIME_ZONE : E

    Description
    ———–
    This command uses the Web service proxy stored in the Zip Variable. The command uses the GetInfoByZip method of the proxy and its Table property.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135238
New-Service

cmdlet, New, Variable

New-Variable

February 26, 2014 Adam

NAME
New-Variable

SYNOPSIS
Creates a new Variable.

SYNTAX
New-Variable [-Name] <string> [[-Value] <Object>] [-Description <string>] [-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}] [-PassThru] [-Scope <string>] [-Visibility {Public | Private}] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The New-Variable cmdlet creates a new Variable in Windows PowerShell. You can assign a value to the Variable while creating it or assign or change the value after it is created.

You can use the parameters of New-Variable to set the properties of the Variable (such as those that create read-only or constant Variables), set the scope of a Variable, and determine whether Variables are public or private.

Typically, you create a new Variable by typing the Variable name and its value, such as “$var = 3”, but you can use the New-Variable cmdlet to use its parameters.

PARAMETERS
-Description <string>
Specifies a description of the Variable.

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

-Force [<SwitchParameter>]
Allows you to create a new Variable with the same name as an existing read-only Variable.

By default, you can overwrite a Variable unless the Variable has an option value of ReadOnly or Constant. For more information, see the Option parameter.

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

-Name <string>
Specifies a name for the new Variable.

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

-Option <ScopedItemOptions>
Sets the value of the Options property of the new Variable.

Valid values are:

— None: Sets no options. (“None” is the default.)

— ReadOnly: The value of the Variable cannot be changed except by using the Force parameter. You can use Remove-Variable to delete the Variable.

— Constant: The Variable cannot be deleted, and its properties cannot be changed. “Constant” is available only when you are creating an Alias. You cannot change the option of an existing Variable to “Constant”.

— Private: The Variable is available only within the scope specified by the Scope parameter. It is inherited by child scopes. (This value is not related to the “Private” value of the Visibility parameter.)

— AllScope: The Variable is copied to any new scopes that are created.

To see the Options property of the Variables, type “Get-Variable| Format-Table -property name, options -autosize”.

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

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

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

-Scope <string>
Determines the scope of the new Variable. Valid values are “Global”, “Local”, or “Script”, or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). “Local” is the default. For more information, see about_scopes.

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

-Value <Object>
Specifies the initial value of the Variable.

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

-Visibility <SessionStateEntryVisibility>
Determines whether the Variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users.

Valid values are:

— Public: The Variable is visible. (“Public” is the default.)
— Private: The Variable is not visible.

When a Variable is private, it does not appear in lists of Variables, such as those returned by Get-Variable, or in displays of the Variable: drive. Commands to read or change the value of a private Variable return an error. However, the user can run commands that use a private Variable if the commands were written in the session in which the Variable was defined.

        Required?                    false
        Position?                    named
        Default value                Public
        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

INPUTS
System.Object
You can pipe a value to New-Variable.

OUTPUTS
None or System.Management.Automation.PSVariable
When you use the PassThru parameter, New-Variable generates a System.Management.Automation.PSVariable object representing the new Variable. Otherwise, this cmdlet does not generate any output.

NOTES

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

C:\PS>New-Variable days

    Description
    ———–
    This command creates a new Variable named “days”. It has no value immediately following the command.

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

C:\PS>New-Variable zipcode -Value 98033

    Description
    ———–
    This command creates a Variable named “zipcode” and assigns it the value “98033”.

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

C:\PS>New-Variable -Name max -Value 256 -Option readonly

New-Variable -Name max -Value 1024

New-Variable -Name max -Value 1024 -Force

C:\PS> New-Variable -Name max -Value 256 -Option readonly

    C:\PS> New-Variable -Name max -Value 1024
    New-Variable : A Variable with name ‘max’ already exists.
    At line:1 char:13
    + New-Variable <<<< -Name max -Value 1024

C:\PS> New-Variable -Name max -Value 1024 -Force

    Description
    ———–
    This example shows how to use the ReadOnly option of New-Variable to protect a Variable from being overwritten.

The first command creates a new Variable named Max and sets its value to “256”. It uses the Option parameter with a value of ReadOnly.

The second command tries to create a second Variable with the same name. This command returns an error, because the read-only option is set on the Variable.

The third command uses the Force parameter to override the read-only protection on the Variable. In this case, the command to create a new Variable with the same name succeeds.

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

C:\PS>New-Variable -Name counter -Visibility private

#Effect of private Variable in a module.

C:\PS> Get-Variable c*

    Name                         Value
    —-                         —–
    Culture                        en-US
    ConsoleFileName
    ConfirmPreference             High
    CommandLineParameters         {}

C:\PS> $counter
“Cannot access the Variable ‘$counter’ because it is a private Variable”

    C:\PS> Get-Counter
    Name         Value
    —-         —–
    Counter1     3.1415
    …

    Description
    ———–
    This command demonstrates the behavior of a private Variable in a module. The module contains the Get-Counter cmdlet, which has a private Variable named “Counter”. The command uses the Visibility parameter with a value of “Private” to create the Variable.

The sample output shows the behavior of a private Variable. The user who has loaded the module cannot view or change the value of the Counter Variable, but the Counter Variable can be read and changed by the commands in the module.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113361
    Get-Variable
    Set-Variable
    Remove-Variable
    Clear-Variable

cmdlet, New, TimeSpan

New-TimeSpan

February 26, 2014 Adam

NAME
New-TimeSpan

SYNOPSIS
Creates a TimeSpan object.

SYNTAX
New-TimeSpan [[-Start] <DateTime>] [[-End] <DateTime>] [<CommonParameters>]

New-TimeSpan [-Days <int>] [-Hours <int>] [-Minutes <int>] [-Seconds <int>] [<CommonParameters>]

DESCRIPTION
The New-TimeSpan cmdlet creates a TimeSpan object that represents a time. interval You can use a TimeSpan object to add or subtract time from DateTime objects.

Without parameters, a “New-TimeSpan” command returns a timespan object that represents a time interval of zero.

PARAMETERS
-Days <int>
Indicates the days in the time span. The default is 0.

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

-End <DateTime>
Indicates the end of a time span. The default is the current date and time.

        Required?                    false
        Position?                    2
        Default value                Current date and time
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

-Hours <int>
Indicates the hours in the time span. The default is zero.

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

-Minutes <int>
Indicates the minutes in the time span. The default is 0.

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

-Seconds <int>
Indicates the length of the time span in seconds. The default is 0.

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

-Start <DateTime>
Indicates the start of a time span. Enter a string that represents the date and time, such as “3/15/09” or a DateTime object, such as one from a Get-Date command.

The default is the current date and time.

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

INPUTS
System.DateTime
You can pipe a DateTime object that represents that start time to New-TimeSpan.

OUTPUTS
System.Timespan
New-TimeSpan returns an object that represents the time span.

NOTES

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

C:\PS>$timespan = New-TimeSpan -hour 1 -minute 25

    Description
    ———–
    This command creates a TimeSpan object with a duration of 1 hour and 25 minutes and stores it in a Variable named $timespan. It displays a representation of the TimeSpan object.

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

C:\PS>New-TimeSpan -End (Get-Date -year 2010 -month 1 -day 1)

    Description
    ———–
    This example creates a new TimeSpan object that represents the interval between the time that the command is run and January 1, 2010.

This command does not require the Start parameter, because the default value of the Start parameter is the current date and time.

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

C:\PS>$90days = New-TimeSpan -days 90

C:\PS> (Get-Date) + $90days

    Description
    ———–
    These commands return the date that is 90 days after the current date.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113360
    Set-Date
    Get-Date

cmdlet, New, Service

New-Service

February 26, 2014 Adam

NAME
New-Service

SYNOPSIS
Creates a new Windows service.

SYNTAX
New-Service [-Name] <string> [-BinaryPathName] <string> [-Credential <PSCredential>] [-DependsOn <string[]>] [-Description <string>] [-DisplayName <string>] [-StartupType {Automatic | Manual | Disabled}] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The New-Service cmdlet creates a new entry for a Windows service in the Registry and in the service database. A new service requires an executable file that executes during the service.

The parameters of this cmdlet let you set the display name, description, startup type, and dependencies of the service.

PARAMETERS
-BinaryPathName <string>
Specifies the path to the executable file for the service. This parameter is required.

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

-Credential <PSCredential>
Specifies a user account that has permission to perform this action. Type a user name, such as “User01” or “Domain01\User01”. Or, enter a PSCredential object, such as one from the Get-Credential cmdlet. If you type a user name, you will be prompted for a password.

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

-DependsOn <string[]>
Specifies the names of other services upon which the new service depends. To enter multiple service names, use a comma to separate the names.

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

-Description <string>
Specifies a description of the service.

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

-DisplayName <string>
Specifies a display name for the service.

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

-Name <string>
Specifies the name of the service. This parameter is required.

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

-StartupType <ServiceStartMode>
Sets the startup type of the service. “Automatic” is the default.

Valid values are:

— Manual: The service is started only manually, by a user (using the Service Control Manager) or by an application.

— Automatic: The service is to be started (or was started) by the operating system, at system start-up. If an automatically started service depends on a manually started service, the manually started service is also started automatically at system startup.

— Disabled: The service is disabled and cannot be started by a user or application.

        Required?                    false
        Position?                    named
        Default value                Automatic
        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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.ServiceProcess.ServiceController
New-Service returns an object that represents the new service.

NOTES

To run this cmdlet on Windows Vista and later versions of Windows, start Windows PowerShell with the “Run as administrator” option.

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

C:\PS>New-Service -Name TestService -BinaryPathName “C:\WINDOWS\System32\svchost.exe -k netsvcs”

    Description
    ———–
    This command creates a new service named “TestService”.

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

C:\PS>New-Service -Name TestService -path “C:\WINDOWS\System32\svchost.exe -k netsvcs” -DependsOn NetLogon -DisplayName “Test Service” -StartupType Manual -Description “This is a test service.”

    Description
    ———–
    This command creates a new service named “TestService”. It uses the parameters of the New-Service cmdlet to specify a description, startup type, and display name for the new service.

To specify the BinaryPathName parameter, the command uses the Path parameter Alias. You can also use “-bpn”.

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

C:\PS>Get-WmiObject win32_service -filter “name=’testservice'”

    ExitCode : 0
    Name     : testservice
    ProcessId : 0
    StartMode : Auto
    State     : Stopped
    Status    : OK

    Description
    ———–
    This command uses the Get-WmiObject cmdlet to get the Win32_Service object for the new service. This object includes the start mode and the service description.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113359
    Get-Service
    Start-Service
    Stop-Service
    Restart-Service
    Resume-Service
    Set-Service
    Suspend-Service

cmdlet, New, PSSessionOption

New-PSSessionOption

February 26, 2014 Adam

NAME
New-PSSessionOption

SYNOPSIS
Creates an object that contains advanced options for a PSSession.

SYNTAX
New-PSSessionOption [-ApplicationArguments <PSPrimitiveDictionary>] [-CancelTimeout <int>] [-Culture <CultureInfo>] [-IdleTimeout <int>] [-MaximumReceivedDataSizePerCommand <int>] [-MaximumReceivedObjectSize <int>] [-MaximumRedirection <int>] [-NoCompression] [-NoEncryption] [-NoMachineProfile] [-OpenTimeout <int>] [-OperationTimeout <int>] [-ProxyAccessType {None | IEConfig | WinHttpConfig | AutoDetect | NoProxyServer}] [-ProxyAuthentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-ProxyCredential <PSCredential>] [-SkipCACheck] [-SkipCNCheck] [-SkipRevocationCheck] [-UICulture <CultureInfo>] [-UseUTF16] [<CommonParameters>]

DESCRIPTION
The New-PSSessionOption cmdlet creates an object that contains advanced options for a PSSession. You can use the object as the value of the SessionOption parameter of cmdlets that create a PSSession, such as New-PSSession, Enter-PSSession, and Invoke-Command.

Without parameters, New-PSSessionOption generates an object that contains the default values for all of the options. Because all of the properties can be edited, you can use the resulting object as a template, and create standard option objects for your enterprise.

PARAMETERS
-ApplicationArguments <PSPrimitiveDictionary>
Specifies a hash table that is sent directly to the session configuration without interpretation. This hash table is available to the session configuration as a property of the PSSenderInfo class.

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

-CancelTimeout <int>
Determines how long Windows PowerShell waits for a cancel operation (CTRL + C) to complete before terminating it. Enter a value in milliseconds.

The default value is 60000 (one minute). A value of 0 (zero) means no timeout; the command continues indefinitely.

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

-Culture <CultureInfo>
Specifies the culture to use for the PSSession. Enter a culture name in <languagecode2>-<country/regioncode2> format, such as “ja-jP”, a Variable that contains a CultureInfo object, or a command that gets a CultureInfo object, such as “Get-Culture“.

The default value is $null, and the culture that is set in the operating system when the PSSession is created is used in the PSSession.

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

-IdleTimeout <int>
Determines how long the PSSession stays open if the remote computer does not receive any communication from the local computer, including the heartbeat signal. When the interval expires, the PSSession closes.

Enter a value in milliseconds. The default value is 240000 (4 minutes). The minimum value is 60000 (1 minute).

If both the local and remote computers specify an idle timeout value, the PSSession uses the shorter timeout value. The local computer can set an idle timeout value by using this parameter or by setting an idle timeout in the $PSSessionOption preference Variable. The remote computer can specify an idle timeout value in the WS-Management configuration (WSMAN:\localhost\shell\idletimeout).

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

-MaximumReceivedDataSizePerCommand <int>
Specifies the maximum number of bytes that the local computer can receive from the remote computer in a single command. Enter a value in bytes. By default, there is no data size limit.

This option is designed to protect the resources on the client computer.

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

-MaximumReceivedObjectSize <int>
Specifies the maximum size of an object that the local computer can receive from the remote computer. Enter a value in bytes. By default, there is no data size limit.

This option is designed to protect the resources on the client computer.

-MaximumRedirection <int>
Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection.

This option is used in the PSSession only when the AllowRedirection parameter is used in the command that creates the PSSession.

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

-NoCompression [<SwitchParameter>]
Turns off packet compression in the PSSession. Compression uses more processor cycles, but it makes transmission faster.

-NoEncryption [<SwitchParameter>]
Turns off data encryption.

-NoMachineProfile [<SwitchParameter>]
Prevents loading the user’s Windows user profile. As a result, the PSSession might be created faster, but user-specific Registry settings, items such as Environment Variables, and Certificates are not available in the PSSession.

-OpenTimeout <int>
Determines how long the client computer waits for the session connection to be established. When the interval expires, the command to establish the connection fails. Enter a value in milliseconds.

The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the command continues indefinitely.

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

-OperationTimeout <int>
Determines the maximum time that any operation in the PSSession can run. When the interval expires, the operation fails. Enter a value in milliseconds.

The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the operation continues indefinitely.

-ProxyAccessType <ProxyAccessType>
Determines which mechanism is used to resolve the host name. Valid values are IEConfig, WinHttpConfig, AutoDetect, NoProxyServer and None. The default value is None.

For information about the values of this parameter, see the description of the System.Management.Automation.Remoting.ProxyAccessType enumeration in the MSDN (Microsoft Developer Network) Library at http://go.microsoft.com/fwlink/?LinkId=144756.

-ProxyAuthentication <AuthenticationMechanism>
Specifies the authentication method that is used for proxy resolution. Valid values are Basic, Digest, and Negotiate. The default value is Negotiate.

For information about the values of this parameter, see the description of the System.Management.Automation.Runspaces.AuthenticationMechanism enumeration in the MSDN library at http://go.microsoft.com/fwlink/?LinkID=144382.

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

-ProxyCredential <PSCredential>
Specifies the credentials to use for proxy authentication. Enter a Variable that contains a PSCredential object or a command that gets a PSCredential object, such as Get-Credential. If this option is not set, no credentials are specified.

-SkipCACheck [<SwitchParameter>]
Specifies that when connecting over HTTPS, the client does not validate that the server Certificate is signed by a trusted Certificate authority (CA).

Use this option only when the remote computer is trusted by using another mechanism, such as when the remote computer is part of a network that is physically secure and isolated, or the remote computer is listed as a trusted host in a WinRM configuration.

-SkipCNCheck [<SwitchParameter>]
Specifies that the Certificate common name (CN) of the server does not need to match the hostname of the server. This option is used only in remote operations that use the HTTPS protocol.

Use this option only for trusted computers.

-SkipRevocationCheck [<SwitchParameter>]
Does not validate the revocation status of the server Certificate.

-UICulture <CultureInfo>
Specifies the UI culture to use for the PSSession.

Enter a culture name in <languagecode2>-<country/regioncode2> format, such as “ja-jP”, a Variable that contains a CultureInfo object, or a command that gets a CultureInfo object, such as Get-Culture.

The default value is $null, and the UI culture that is set in the operating system when the PSSession is created is used in the PSSession.

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

-UseUTF16 [<SwitchParameter>]
Encode the request in UTF16 format rather than UTF8 format.

        Required?                    false
        Position?                    named
        Default value                False (UTF8 encoding)
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.Automation.Remoting.PSSessionOption

NOTES

If the SessionOption parameter is not used in a command to create a PSSession, the session options are determined by the property values of the $PSSessionOption preference Variable, if it is set. For more information about the $PSSessionOption Variable, see about_preference_variables.

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

C:\PS>New-PSSessionOption

    MaximumConnectionRedirectionCount : 5
    NoCompression                     : False
    NoMachineProfile                 : False
    ProxyAccessType                 : IEConfig
    ProxyAuthentication             : Negotiate
    ProxyCredential                 :
    SkipCACheck                     : False
    SkipCNCheck                     : False
    SkipRevocationCheck             : False
    OperationTimeout                 : 00:03:00
    NoEncryption                     : False
    UseUTF16                         : False
    Culture                         :
    UICulture                         :
    MaximumReceivedDataSizePerCommand :
    MaximumReceivedObjectSize         :
    ApplicationArguments             :
    OpenTimeout                     : 00:03:00
    CancelTimeout                     : 00:01:00
    IdleTimeout                     : 00:04:00

    Description
    ———–
    This command creates a session option object with all of the default values.

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

C:\PS>$pso = New-PSSessionoption -Culture “fr-fr” -MaximumReceivedObjectSize 10MB

C:\PS> New-PSSession -computerName Server01 -SessionOption $pso

    Description
    ———–
    This example shows how to use a session option object to configure a session.

The first command creates a new session option object and saves it in the value of the $pso Variable.

The second command uses the New-PSSession cmdlet to create a PSSession on the Server01 remote computer. The command uses the session option object in the value of the $pso Variable as the value of the SessionOption parameter of the command.

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

C:\PS>Enter-PSSession -computername Server01 -sessionOption (New-PSSessionoption -NoEncryption -NoCompression)

    Description
    ———–
    This command uses the Enter-PSSession cmdlet to start an interactive session with the Server01 computer. The value of the SessionOption parameter is a New-PSSessionOption command with the NoEncryption and NoCompression switch parameters.

The New-PSSessionOption command is enclosed in parentheses to make sure that it runs before the Enter-PSSession command.

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

C:\PS>$a = New-PSSessionoption

    C:\PS> $a.UICulture = (UIGet-Culture)
    C:\PS> $a.OpenTimeout = (New-TimeSpan -minutes 4)
    C:\PS> $a.MaximumConnectionRedirectionCount = 1

C:\PS> $a

    MaximumConnectionRedirectionCount : 1
    NoCompression                     : False
    NoMachineProfile                 : False
    ProxyAccessType                 : IEConfig
    ProxyAuthentication             : Negotiate
    ProxyCredential                 :
    SkipCACheck                     : False
    SkipCNCheck                     : False
    SkipRevocationCheck             : False
    OperationTimeout                 : 00:03:00
    NoEncryption                     : False
    UseUTF16                         : False
    Culture                         :
    UICulture                         : en-US
    MaximumReceivedDataSizePerCommand :
    MaximumReceivedObjectSize         :
    ApplicationArguments             :
    OpenTimeout                     : 00:04:00
    CancelTimeout                     : 00:01:00
    IdleTimeout                     : 00:04:00

    Description
    ———–
    This example demonstrates that you can edit the session option object. All properties have read/write values.

Use this method to create a standard session object for your enterprise, and then create customized versions of it for particular uses.

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

C:\PS>$PSSessionOption = New-PSSessionOption -OpenTimeout 120000

    Description
    ———–
    This command creates a $PSSessionOption preference Variable.

When the $PSSessionOption preference Variable exists in the session, it establishes default values for options in the PSSessions that are created by using the New-PSSession, Enter-PSSession, and Invoke-Command cmdlets.

To make the $PSSessionOption Variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile.

For more information about the $PSSessionOption Variable, see about_preference_variables. For more information about profiles, see about_profiles.

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

C:\PS>$skipCN = New-PSSessionoption -SkipCNCheck

C:\PS> New-PSSession -computername 171.09.21.207 -UseSSL -credential domain01\user01 -sessionOption $skipCN

    Description
    ———–
    This example shows how to use a SessionOption object to fulfill the requirements for a remote session configuration.

The first command uses the New-PSSessionOption cmdlet to create a session option object with the SkipCNCheck property. The command saves the resulting session object in the $skipCN Variable.

The second command uses the New-PSSession cmdlet to create a new PSSession on a remote computer. The $skipCN check Variable is used in the value of the SessionOption parameter.

Because the computer is identified by its IP address, the value of the ComputerName parameter does not match any of the common names in the Certificate used for Secure Sockets Layer (SSL). As a result, the SkipCNCheck option is required.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=144305
    Enter-PSSession
    New-PSSession
    Invoke-Command

cmdlet, New, PSSession

New-PSSession

February 26, 2014 Adam

NAME
New-PSSession

SYNOPSIS
Creates a persistent connection to a local or remote computer.

SYNTAX
New-PSSession [[-ComputerName] <string[]>] [-ApplicationName <string>] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-Port <int>] [-SessionOption <PSSessionOption>] [-UseSSL] [-ThrottleLimit <int>] [<CommonParameters>]

New-PSSession [[-Session] <PSSession[]>] [-Name <string[]>] [-ThrottleLimit <int>] [<CommonParameters>]

New-PSSession [-ConnectionURI] <Uri[]> [-AllowRedirection] [-Authentication {Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [<CommonParameters>]

DESCRIPTION
The New-PSSession cmdlet creates a Windows PowerShell session (PSSession) on a local or remote computer. When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer.

Use a PSSession to run multiple commands that share data, such as a Function or the value of a Variable. To run commands in a PSSession, use the Invoke-Command cmdlet. To use the PSSession to interact directly with a remote computer, use the Enter-PSSession cmdlet. For more information, see about_pssessions.

You can run commands on a remote computer without creating a PSSession by using the ComputerName parameters of Enter-PSSession or Invoke-Command. When you use the ComputerName parameter, Windows PowerShell creates a temporary connection that is used for the interactive session or for a single command and is then closed.

PARAMETERS
-AllowRedirection [<SwitchParameter>]
Allows redirection of this connection to an alternate Uniform Resource Identifier (URI).

When you use the ConnectionURI parameter, the remote destination can return an instruction to redirect to a different URI. By default, Windows PowerShell does not redirect connections, but you can use the AllowRedirection parameter to allow it to redirect the connection.

You can also limit the number of times that the connection is redirected by setting the MaximumConnectionRedirectionCount property of the $PSSessionOption preference Variable, or the MaximumConnectionRedirectionCount property of the value of the SessionOption parameter.
The default value is 5. For more information, see the description of the SessionOption parameter, and see New-PSSessionOption.

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

-ApplicationName <string>
Specifies the application name segment of the connection URI. Use this parameter to specify the application name when you are not using the ConnectionURI parameter in the command.

The default value is the value of the $PSSessionApplicationName preference Variable on the local computer. If this preference Variable is not defined, the default value is “WSMAN”. This value is appropriate for most uses. For more information, see about_preference_variables.

The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the URLPrefix property of a listener on the remote computer.

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

-Authentication <AuthenticationMechanism>
Specifies the mechanism that is used to authenticate the user’s credentials. Valid values are “Default”, “Basic”, “Credssp”, “Digest”, “Kerberos”, “Negotiate”, and “NegotiateWithImplicitCredential”. The default value is “Default”.

CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of Windows.

For more information about the values of this parameter, see the description of the System.Management.Automation.Runspaces.AuthenticationMechanism enumeration in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkID=144382.

Caution: Credential Security Service Provider (CredSSP) authentication, in which the user’s credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session.

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

-CertificateThumbprint <string>
Specifies the digital public key Certificate (X509) of a user account that has permission to perform this action. Enter the Certificate thumbprint of the Certificate.

Certificates are used in client Certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.

To get a Certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.

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

-ComputerName <string[]>
Creates a persistent connection (PSSession) to the specified computer. If you enter multiple computer names, New-PSSession creates multiple PSSessions, one for each computer. The default is the local computer.

Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more remote computers. To specify the local computer, type the computer name, “localhost”, or a dot (.). When the computer is in a different domain than the user, the fully qualified domain name is required. You can also pipe a computer name (in quotes) to New-PSSession.

To use an IP address in the value of the ComputerName parameter, the command must include the Credential parameter. Also, the computer must be configured for HTTPS transport or the IP address of the remote computer must be included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to the TrustedHosts list, see “How to Add a Computer to the Trusted Host List” in about_remote_TroubleShooting.

Note: In Windows Vista and later versions of Windows, to include the local computer in the value of the ComputerName parameter, you must start Windows PowerShell with the “Run as administrator” option.

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

-ConfigurationName <string>
Specifies the session configuration that is used for the new PSSession.

Enter a configuration name or the fully qualified resource Uniform Resource Identifier (URI) for a session configuration. If you specify only the configuration name, the following schema URI is prepended: http://schemas.microsoft.com/powershell.

The session configuration for a session is located on the remote computer. If the specified session configuration does not exist on the remote computer, the command fails.

The default value is the value of the $PSSessionConfigurationName preference Variable on the local computer. If this preference Variable is not set, the default is Microsoft.PowerShell. For more information, see about_preference_variables.

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

-ConnectionURI <Uri[]>
Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint. The URI must be fully qualified.

The format of this string is as follows:
<Transport>://<ComputerName>:<Port>/<ApplicationName>

The default value is as follows:
http://localhost:80/WSMAN

Valid values for the Transport segment of the URI are HTTP and HTTPS. If you do not specify a ConnectionURI, you can use the UseSSL, ComputerName, Port, and ApplicationName parameters to specify the URI values.

If the destination computer redirects the connection to a different URI, Windows PowerShell prevents the redirection unless you use the AllowRedirection parameter in the command.

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

-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”, “Domain01\User01”, or “User@Domain.com”, or enter a PSCredential object, such as one returned by the Get-Credential cmdlet.

When you type a user name, you will be prompted for a password.

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

-Name <string[]>
Specifies a friendly name for the PSSession.

You can use the name to refer to the PSSession when using other cmdlets, such as Get-PSSession and Enter-PSSession. The name is not required to be unique to the computer or the current session.

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

-Port <int>
Specifies the network port on the remote computer that is used for this command. The default is port 80 (the HTTP port).

Before using an alternate port, you must configure the WinRM listener on the remote computer to listen at that port. Use the following commands to configure the listener:

1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="<port-number>"}

Do not use the Port parameter unless you must. The port setting in the command applies to all computers and sessions in which the command runs. An alternate port setting might prevent the command from running on all computers.

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

-Session <PSSession[]>
Uses the specified PSSession as a model for the new PSSession. This parameter creates new PSSessions with the same properties as the specified PSSessions.

Enter a Variable that contains the PSSessions or a command that creates or gets the PSSessions, such as a New-PSSession or Get-PSSession command.

The resulting PSSessions have the same computer name, application name, connection URI, port, configuration name, throttle limit, and Secure Sockets Layer (SSL) value as the originals, but they have a different display name, ID, and instance ID (GUID).

-SessionOption <PSSessionOption>
Sets advanced options for the session. Enter a SessionOption object that you create by using the New-PSSessionOption cmdlet.

The default values for the options are determined by the value of the $PSSessionOption preference Variable, if it is set. Otherwise, the session uses the system defaults.

For a description of the session options, including the default values, see New-PSSessionOption. For information about the $PSSessionOption preference Variable, see about_preference_variables.

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

-ThrottleLimit <int>
Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0 (zero), the default value, 32, is used.

The throttle limit applies only to the current command, not to the session or to the computer.

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

-UseSSL [<SwitchParameter>]
Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used.

WS-Management encrypts all Windows PowerShell content transmitted over the network. UseSSL is an additional protection that sends the data across an HTTPS connection instead of an HTTP connection.

If you use this parameter, but SSL is not available on the port used for the command, the command fails.

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

INPUTS
System.String, System.URI, System.Management.Automation.Runspaces.PSSession
You can pipe a ComputerName (string), ConnectionURI (URI), or Session (PSSession) object to New-PSSession.

OUTPUTS
System.Management.Automation.Runspaces.PSSession

NOTES

This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see about_remote_requirements.

In Windows Vista and later versions of Windows, to create a PSSession on the local computer, you must start Windows PowerShell with the “Run as administrator” option.

When you are finished with the PSSession, use the Remove-PSSession cmdlet to delete the PSSession and release its resources.

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

C:\PS>$s = New-PSSession

    Description
    ———–
    This command creates a new PSSession on the local computer and saves the PSSession in the $s Variable.

You can now use this PSSession to run commands on the local computer.

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

C:\PS>$Server01 = New-PSSession -ComputerName Server01

    Description
    ———–
    This command creates a new PSSession on the Server01 computer and saves it in the $Server01 Variable.

When creating multiple PSSessions, assign them to Variables with useful names. This will help you manage the PSSessions in subsequent commands.

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

C:\PS>$s1, $s2, $s3 = new-session -ComputerName server1,server2,server3

    Description
    ———–
    This command creates three new PSSessions, one on each of the computers specified by the ComputerName parameter.

The command uses the assignment operator (=) to assign the new PSSessions to an array of Variables: $s1, $s2, $s3. It assigns the Server01 PSSession to $s1, the Server02 PSSession to $s2, and the Server03 PSSession to $s3.

When you assign multiple objects to an array of Variables, Windows PowerShell assigns each object to a Variable in the array respectively. If there are more objects than Variables, all remaining objects are assigned to the last Variable. If there are more Variables than objects, the remaining Variables are empty (null).

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

C:\PS>New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12

    Description
    ———–
    This command creates a new PSSession on the Server01 computer that connects to server port 8081 and uses the SSL protocol. The new PSSession uses an alternate session configuration called “E12”.

Before setting the port, you must configure the WinRM listener on the remote computer to listen on port 8081. For more information, see the description of the Port parameter.

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

C:\PS>New-PSSession -session $s -Credential domain01\user01

    Description
    ———–
    This command creates a new PSSession with the same properties as an existing PSSession. You can use this command format when the resources of an existing PSSession are exhausted and a new PSSession is needed to offload some of the demand.

The command uses the Session parameter of New-PSSession to specify the PSSession saved in the $s Variable. It uses the credentials of the Domain1\Admin01 user to complete the command.

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

C:\PS>$global:s = New-PSSession -ComputerName server1.domain44.corpnet.fabrikam.com -Credential domain01\admin01

    Description
    ———–
    This example shows how to create a PSSession with a global scope on a computer in a different domain.

By default, PSSessions created at the command line are created with local scope and PSSessions created in a script have script scope.

To create a PSSession with global scope, create a new PSSession and then store the PSSession in a Variable that is cast to a global scope. In this case, the $s Variable is cast to a global scope.

The command uses the ComputerName parameter to specify the remote computer. Because the computer is in a different domain than the user account, the full name of the computer is specified along with the credentials of the user.

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

C:\PS>$rs = Get-Content c:\test\servers.txt | New-PSSession -ThrottleLimit 50

    Description
    ———–
    This command creates a PSSession on each of the 200 computers listed in the Servers.txt file and it stores the resulting PSSession in the $rs Variable. The PSSessions have a throttle limit of 50.

You can use this command format when the names of computers are stored in a database, spreadsheet, text file, or other text-convertible format.

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

C:\PS>$s = New-PSSession -URI http://Server01:91/NewSession -Credential domain01\user01

    Description
    ———–
    This command creates a PSSession on the Server01 computer and stores it in the $s Variable. It uses the URI parameter to specify the transport protocol, the remote computer, the port, and an alternate session configuration. It also uses the Credential parameter to specify a user account with permission to create a session on the remote computer.

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

C:\PS>$s = New-PSSession -ComputerName (Import-Csv servers.csv) -Credential domain01\admin01 -ThrottleLimit 16

C:\PS> Invoke-Command -session $s -scriptblock {Get-Process powershell} -AsJob

    Description
    ———–
    These commands create a set of PSSessions and then run a background job in each of the PSSessions.

The first command creates a new PSSession on each of the computers listed in the Servers.csv file. It uses the New-PSSession cmdlet to create the PSSession. The value of the ComputerName parameter is a command that uses the Import-Csv cmdlet to import the Servers.csv file and read its contents.

The command uses the Credential parameter to create the PSSessions with the permission of a domain administrator, and it uses the ThrottleLimit parameter to limit the command to 16 concurrent connections. The command saves the PSSessions in the $s Variable.

The second command uses the AsJob parameter of Invoke-Command to start a background job that runs a “Get-Process PowerShell” command in each of the PSSessions in $s.

For more information about background jobs, see about_jobs and about_remote_Jobs.

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

C:\PS>New-PSSession -ConnectionURI https://management.exchangelabs.com/Management

    Description
    ———–
    This command creates a new PSSession that connects to a computer that is specified by a URI instead of a computer name.

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

C:\PS>$so = New-WSManSessionOption -SkipCACheck

PS C:\> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential server01\admin01

    Description
    ———–
    This example shows how to create and use a SessionOption parameter.

The first command uses the New-WSManSessionOption cmdlet to create a session option. It saves the resulting SessionOption object in the $so parameter.

The second command uses the option in a new session. The command uses the New-PSSession cmdlet to create a new session. The value of the SessionOption parameter is the SessionOption object in the $so Variable.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135237
    about_pssessions
    about_remote
    Get-PSSession
    Remove-PSSession
    Enter-PSSession
    Exit-PSSession
    Invoke-Command

cmdlet, New, PSDrive

New-PSDrive

February 26, 2014 Adam

NAME
New-PSDrive

SYNOPSIS
Creates a Windows PowerShell drive in the current session.

SYNTAX
New-PSDrive [-Name] <string> [-PSProvider] <string> [-Root] <string> [-Credential <PSCredential>] [-Description <string>] [-Scope <string>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The New-PSDrive cmdlet creates a Windows PowerShell drive that is “mapped” to or associated with a location in a data store, such as a network drive, a directory on the local computer, or a Registry key.

You can use the Windows PowerShell drives that you create to access data in the associated data store, just like you would do with any mapped drive. You can change locations into the drive (using “Set-Location“, “cd”, or “chdir”) and access the contents of the drive (using “Get-Item“, “Get-ChildItem“, or “dir”).

However, the Windows PowerShell drives are known only to Windows PowerShell. You cannot access them by using Windows Explorer, Windows Management Instrumentation (WMI), Component Object Model (COM), or the Microsoft .NET Framework, or by using tools such as Net Use.

Windows PowerShell drives exist only in the current Windows PowerShell session. To make the drive persistent, you can export the session to which you have added the drive, or you can save a New-PSDrive command in your Windows PowerShell profile.

To delete a drive that was created by New-PSDrive, use the Remove-PSDrive cmdlet.

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

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

-Description <string>
Specifies a brief text description of the drive. Type any string.

To see the descriptions of all of the Windows PowerShell drives on your system, type “Get-PSDrive | format name, description”. To see the description of a particular Windows PowerShell drives, type “(Get-PSDrive <DriveName>).description”.

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

-Name <string>
Specifies a name for the new drive. You can use any valid string for the name. You are not limited to drive letters. Windows PowerShell drives names are case-sensitive.

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

-PSProvider <string>
Specifies the Windows PowerShell provider that supports drives of this type.

For example, if the Windows PowerShell drives is associated with a network share or file system directory, the Windows PowerShell provider is “FileSystem”. If the Windows PowerShell drive is associated with a Registry key, the provider is “Registry”.

To see a list of the providers in your Windows PowerShell session, type “Get-PSProvider“.

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

-Root <string>
Specifies the data store location that the Windows PowerShell drive is mapped to.

For example, specify a network share (such as \\Server01\Public), a local directory (such as C:\Program Files), or a Registry key (such as HKLM:\Software\Microsoft).

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

-Scope <string>
Specifies a scope for the drive. 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?     true (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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.Automation.PSDriveInfo

NOTES

The New-PSDrive 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>New-PSDrive -Name P -PSProvider FileSystem -Root \\Server01\Public

    Name     Provider     Root
    —-     ——–     —-
    P         FileSystem    \\Server01\Public

    Description
    ———–
    This command creates a Windows PowerShell drive that Functions like a mapped network drive in Windows. The command creates a Windows PowerShell drive named P: that is mapped to the \\Server01\Public network share.

It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell FileSystem provider, and the Root parameter to specify the network share.

When the command completes, the contents of the \\Server01\Public share appear in the P: drive. To see them, type: “dir p:”.

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

C:\PS>New-PSDrive -Name MyDocs -PSProvider FileSystem -Root “C:\Documents and Settings\User01\My Documents” -Description “Maps to my My Documents folder.”

    Name     Provider     Root
    —-     ——–     —-
    MyDocs     FileSystem    C:\Documents and Settings\User01\My Documents

    Description
    ———–
    This command creates a Windows PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the
    “C:\Documents and Settings\User01\My Documents” directory on the local computer.

It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell FileSystem provider, the Root parameter to specify the path to the My Documents folder, and the Description parameter to create a description of the drive.

When the command completes, the contents of the My Documents folder appear in the MyDocs: drive. To see them, type: “dir mydocs:”.

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

C:\PS>New-PSDrive -Name MyCompany -PSProvider Registry -Root HKLM:\Software\MyCompany

    Name     Provider     Root
    —-     ——–     —-
    MyCompany Registry     HKEY_LOCAL_MACHINE\Software\MyCo…

    Description
    ———–
    This command creates a Windows PowerShell drive that provides quick access to a frequently checked Registry key. It creates a drive named MyCompany that is mapped to the HKLM\Software\MyCompany Registry key.

It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell Registry provider, and the Root parameter to specify the Registry key.

When the command completes, the contents of the MyCompany key appear in the MyCompany: drive. To see them, type: “dir MyCompany:”.

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

C:\PS>New-PSDrive -Name PsDrive -PSProvider FileSystem -Root \\Server01\Public

C:\PS> $drive = New-Object -com wscript.network
C:\PS> $drive.MapNetworkDrive(“X:”, “\\Server01\Public”)

C PS:\> Get-PSDrive public, x

    Name     Provider     Root
    —-     ——–     —-
    PsDrive    FileSystem    \\Server01\public
    X         FileSystem    X:\

C:\PS>Get-PSDrive psdrive, x | Get-Member

     TypeName: System.Management.Automation.PSDriveInfo
    Name                MemberType Definition
    —-                ———- ———-
    CompareTo         Method     System.Int32 CompareTo(PSDriveInfo drive),
    Equals             Method     System.Boolean Equals(Object obj),
    GetHashCode         Method     System.Int32 GetHashCode()
    …

    C:\PS> net use
    Status     Local     Remote                    Network
    —————————————————————————
                 X:        \\server01\public         Microsoft Windows Network

    C:\PS> Get-WmiObject win32_logicaldisk | ft deviceid
    deviceid
    ——–
    C:
    D:
    X:

    C:\PS> Get-WmiObject win32_networkconnection
    LocalName                     RemoteName                    ConnectionState             Status
    ———                     ———-                    —————             ——
    X:                            \\products\public             Disconnected                 Unavailable

    Description
    ———–
    This example shows the difference between a Windows drive that is mapped to a network share and a Windows PowerShell drive that is mapped to the same network share.

The first command uses the New-PSDrive cmdlet to create a Windows PowerShell drive called PSDrive: that is mapped to the \\Server01\Public network share.

The second set of commands uses the New-Object cmdlet to create a Wscript.Network COM object and then use its MapNetworkDrive method to map the \\Server01\Public network share to the X: drive on the local computer.

Now, you can examine the two drives. Using a Get-PSDrive drive command, the drives appear to be the same, although the network share name appears only in the root of the PSDrive: drive.

Sending the drive objects to Get-Member shows that they have the same object type, System.Management.Automation.PSDriveInfo.

However, a “net use” command, a Get-WmiObject command to the Win32_LogicalDisk class, and a Get-WmiObject command to the Win32_NetworkConnection class find only the X: drive that was created by using the Wscript.Network object. That is because Windows PowerShell drives are known only to Windows PowerShell.

If you close the Windows PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists.

Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it needs to be persistant, and whether the drive needs to be visible to other Windows features.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113357
    about_providers
    Get-PSDrive
    Remove-PSDrive

cmdlet, New, Object

New-Object

February 26, 2014 Adam

NAME
New-Object

SYNOPSIS
Creates an instance of a Microsoft .NET Framework or COM object.

SYNTAX
New-Object -ComObject <string> [-Strict] [-Property <hashtable>] [<CommonParameters>]

New-Object [-TypeName] <string> [[-ArgumentList] <Object[]>] [-Property <hashtable>] [<CommonParameters>]

DESCRIPTION
The New-Object cmdlet creates an instance of a .NET Framework or COM object.

You can specify either the type of a .NET Framework class or a ProgID of a COM object. By default, you type the fully qualified name of a .NET Framework class and the cmdlet returns a reference to an instance of that class. To create an instance of a COM object, use the ComObject parameter and specify the ProgID of the object as its value.

PARAMETERS
-ArgumentList <Object[]>
Specifies a list of arguments to pass to the constructor of the .NET Framework class. Separate elements in the list by using commas (,). The Alias for ArgumentList is Args.

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

-ComObject <string>
Specifies the programmatic identifier (ProgID) of the COM object.

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

-Property <hashtable>
Sets property values and invokes methods of the new object.

Enter a hash table in which the keys are the names of properties or methods and the values are property values or method arguments. New-Object creates the object and sets each property value and invokes each method in the order that they appear in the hash table.

If the new object is derived from the PSObject class, and you specify a property that does not exist on the object, New-Object adds the specified property to the object as a NoteProperty. If the object is not a PSObject, the command generates a non-terminating error.

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

-Strict [<SwitchParameter>]
Specifies that an error should be raised if the COM object that you attempt to create uses an interop assembly. This enables you to distinguish actual COM objects from .NET Framework objects with COM-callable wrappers.

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

-TypeName <string>
Specifies the fully qualified name of the .NET Framework class. You cannot specify both the TypeName parameter and the ComObject parameter.

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
Object
New-Object returns the object that is created.

NOTES

New-Object provides the most commonly-used Functionality of the VBScript CreateObject Function. A statement like Set objShell = CreateObject(“Shell.Application”) in VBScript can be translated to $objShell = New-Object -comobject “Shell.Application” in Windows PowerShell.

New-Object expands upon the Functionality available in the Windows Script Host Environment by making it easy to work with .NET Framework objects from the command line and within scripts.

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

C:\PS>New-Object -TypeName System.Version -ArgumentList “1.2.3.4”

    Major Minor Build Revision
    —– —– —– ——–
    1     2     3     4

    Description
    ———–
    This command creates a System.Version object using the string “1.2.3.4” as the constructor.

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

C:\PS>$ie = New-Object -comobject InternetExplorer.Application -Property @{navigate2=”www.microsoft.com”; visible = $true}

    Description
    ———–
    This command creates an instance of the COM object that represents the Internet Explorer application. It uses the Property parameter to call the Navigate2 method and to set the Visible property of the object to $true to make the application visible.

This command is the equivalent of the following:

    $ie = New-Object -comobject InternetExplorer.Application
    $ie.navigate2(“www.microsoft.com”)
    $ie.visible = $true

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

C:\PS>$a=New-Object -comobject Word.Application -strict -Property @{visible=$true}

    New-Object : The object written to the pipeline is an instance of the type
    “Microsoft.Office.Interop.Word.ApplicationClass” from the component’s prima
    ry interop assembly. If this type exposes different members than the IDispa
    tch members, scripts written to work with this object might not work if the
     primary interop assembly is not installed.
    At line:1 char:14
    + $a=New-Object <<<< -COM Word.Application -Strict; $a.visible=$true

    Description
    ———–
    This command demonstrates that specifying the Strict parameter causes the New-Object cmdlet to generate a non-terminating error when the COM object that is created uses an interop assembly.

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

C:\PS>$objshell = New-Object -comobject “Shell.Application”

C:\PS> $objshell | Get-Member

C:\PS> $objshell.ToggleDesktop()

    Description
    ———–
    The command uses the ComObject parameter to create a COM object with the “Shell.Application” ProgID. It stores the resulting object in the $objShell Variable.

The second command pipes the $objShell Variable to the Get-Member cmdlet, which displays the properties and methods of the COM object.

The third command calls the ToggleDesktop method of the object to minimize the open windows on your desktop.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113355
    Compare-Object
    Select-Object
    Sort-Object
    ForEach-Object
    Group-Object
    Measure-Object
    Tee-Object
    Where-Object

cmdlet, ModuleManifest, New

New-ModuleManifest

February 26, 2014 Adam

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

-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

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