Tag Archives: UICulture

New-PSSessionOption

February 26, 2014 Adam

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.

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

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

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

-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

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
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, Import, LocalizedData

Import-LocalizedData

February 26, 2014 Adam

NAME
Import-LocalizedData

SYNOPSIS
Imports language-specific data into scripts and Functions based on the UI culture that is selected for the operating system.

SYNTAX
Import-LocalizedData [-BindingVariable] <string> [[-UICulture] <string>] [-BaseDirectory <string>] [-FileName <string>] [-SupportedCommand <string[]>] [<CommonParameters>]

DESCRIPTION
The Import-LocalizedData cmdlet dynamically retrieves strings from a subdirectory whose name matches the UI language set for the current user of the operating system. It is designed to enable scripts to display user messages in the UI language selected by the current user.

Import-LocalizedData imports data from .psd1 files in language-specific subdirectories of the script directory and saves them in a local Variable that is specified in the command. The cmdlet selects the subdirectory and file based on the value of the $PSUICulture automatic Variable. When you use the local Variable in the script to display a user message, the message appears in the user’s UI language.

You can use the parameters of Import-LocalizedData to specify an alternate UI culture, path, and file name, to add supported commands, and to suppress the error message that appears if the .psd1 files are not found.

The Import-LocalizedData cmdlet supports script internationalization in Windows PowerShell 2.0. This initiative aims to better serve users worldwide by making it easy for scripts to display user messages in the UI language of the current user. For more information about this and about the format of the .psd1 files, see about_script_internationalization.

PARAMETERS
-BaseDirectory <string>
Specifies the base directory where the .psd1 files are located. The default is the directory where the script is located. Import-LocalizedData searches for the .psd1 file for the script in a language-specific subdirectory of the base directory.

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

-BindingVariable <string>
Specifies a Variable into which the text strings are imported. Enter a Variable name without a dollar sign ($).

When using Import-LocalizedData to replace default text strings specified in the DATA section of a script, assign the DATA section to a Variable and enter the name of the DATA section Variable in the value of the BindingVariable parameter. Then, when Import-LocalizedData saves the imported content in the BindingVariable, the imported data will replace the default text strings. If you are not specifying default text strings, you can select any Variable name.

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

-FileName <string>
Specifies the name of the .psd1 file to be imported. Enter a file name without the .psd1 file name extension.

The default is the name of the script. For example, if the script is FindFiles.ps1, Import-LocalizedData searches for FindFiles.psd1. You can use this parameter to direct Import-LocalizedData to search for a different .psd1 file.

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

-SupportedCommand <string[]>
Specifies cmdlets and Functions that generate only data.

Use this parameter to include cmdlets and Functions that you have written or tested. For more information, see about_script_internationalization.

-UICulture <string>
Specifies an alternate UI culture. The default is the value of the $PsUICulture automatic Variable. Enter a UI culture in “<language>-<region>” format, such as en-US, de-DE, or ar-SA.

The value of the UICulture parameter determines the language-specific subdirectory (within the base directory) from which Import-LocalizedData gets the .psd1 file for the script.

The cmdlet searches for a subdirectory with the same name as the value of the UICulture parameter or the $PsUICulture automatic Variable, such as “de-DE” or “ar-SA”. If it cannot find the directory, or the directory does not contain a .psd1 file for the script, it searches for a subdirectory with the name of the language code, such as “de” or “ar”. If it cannot find the subdirectory or .psd1 file, the command fails and the data is displayed in the default language specified in the script.

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Collections.Hashtable
Import-LocalizedData saves the hash table in the Variable that is specified by the value of the BindingVariable parameter.

NOTES

Before using Import-LocalizedData, localize your user messages. Format the messages for each locale (UI culture) in a hash table of key/value pairs, and save the hash table in a file with the same name as the script and a .psd1 file name extension. Create a directory under the script directory for each supported UI culture, and then save the .psd1 file for each UI culture in the directory with the UI culture name.

For example, localize your user messages for the de-DE locale and format them in a hash table. Save the hash table in a <ScriptName>.psd1 file. Then create a de-DE subdirectory under the script directory, and save the de-DE <ScriptName>.psd1 file in the de-DE subdirectory. Repeat this method for each locale that you support.

Import-LocalizedData performs a structured search for the localized user messages for a script.

Import-LocalizedData begins the search in the directory where the script file is located (or the value of the BaseDirectory parameter). It then searches within the base directory for a subdirectory with the same name as the value of the $PsUICulture Variable (or the value of the UICulture parameter), such as “de-DE” or “ar-SA”. Then, it searches in that subdirectory for a .psd1 file with the same name as the script (or the value of the FileName parameter).

If Import-LocalizedData cannot find a subdirectory with the name of the UI culture, or the subdirectory does not contain a .psd1 file for the script, it searches for a .psd1 file for the script in a subdirectory with the name of the language code, such as “de” or “ar”. If it cannot find the subdirectory or .psd1 file, the command fails, the data is displayed in the default language in the script, and an error message is displayed explaining that the data could not be imported. To suppress the message and fail gracefully, use the ErrorAction common parameter with a value of SilentlyContinue.

If Import-LocalizedData finds the subdirectory and the .psd1 file, it imports the hash table of user messages into the value of the BindingVariable parameter in the command. Then, when you display a message from the hash table in the Variable, the localized message is displayed.

For more information, see about_script_internationalization.

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

C:\PS>Import-LocalizedData -BindingVariable messages

    Description
    ———–
    This command imports text strings into the $messages Variable. It uses all of the default values for the cmdlet parameters.

If the command is included in the Archives.ps1 script in the C:\test directory, and the value of the $PsUICulture automatic Variable is zh-CN, Import-LocalizedData imports the Archives.psd1 file in the C:\test\zh-CN directory.

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

C:\PS>Import-LocalizedData -BindingVariable msgTbl -UICulture ar-SA -FileName Simple -BaseDirectory C:\Data\Localized

    Description
    ———–
    This command imports text strings into the $msgTbl Variable of a script.

It uses the UICulture parameter to direct the cmdlet to import data from the Simple.psd1 file in the ar-SA subdirectory of C:\Data\Localized.

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

C:\PS># In C:\Test\en-US\test.psd1:

    ConvertFrom-StringData @’
     # English strings
    Msg1 = “The Name parameter is missing from the command.”
    Msg2 = “This command requires the credentials of a member of the Administrators group on the computer.”
    Msg3 = “Use $_ to represent the object that is being processed.”
    ‘@

# In C:\Test\Test.ps1

Import-LocalizedData -BindingVariable messages
Write-Host $messages.msg2

# In Windows PowerShell

C:\PS> .\test.ps1
This command requires the credentials of a member of the Administrators group on the computer.

    Description
    ———–
    This example shows how to use localized data in a simple script.

The first part of the example shows the contents of the Test.psd1 file. It contains a ConvertFrom-StringData command that converts a series of named text strings into a hash table. The test.psd1 file is located in the en-US subdirectory of the C:\Test directory that contains the script.

The second part of the example shows the contents of the Test.ps1 script. It contains an Import-LocalizedData command that imports the data from the matching .psd1 file into the $Messages Variable and a Write-Host command that writes one of the messages in the $Messages Variable to the host program.

The last part of the example runs the script. The output shows that it displays the correct user message in the UI language set for the current user of the operating system.

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

C:\PS># In TestScript.ps1

    $UserMessages = DATA {
        ConvertFrom-StringData @’
        # English strings
            Msg1 = “Enter a name.”
            Msg2 = “Enter your employee ID.”
            Msg3 = “Enter your building number.”
    ‘@ }

Import-LocalizedData -BindingVariable UserMessages

$UserMessages.Msg1
…

    Description
    ———–
    This example shows how to use Import-LocalizedData to replace default text strings defined in the DATA section of a script.

In this example, the DATA section of the TestScript.ps1 script contains a ConvertFrom-StringData command that converts the contents of the DATA section to a hash table and stores in the value of the $UserMessages Variable.

The script also includes an Import-LocalizedData command, which imports a hash table of translated text strings from the TestScript.psd1 file in the subdirectory specified by the value of the $PsUICulture Variable. If the command finds the .psd1 file, it saves the translated strings from the file in the value of the same $UserMessages Variable, overwriting the hash table saved by the DATA section logic.

The third command displays the first message in the $UserMessages Variable.

If the Import-LocalizedData command finds a .psd1 file for the $PsUICulture language, the value of the $UserMessages Variable contains the translated text strings. If the command fails for any reason, the command displays the default text strings defined in the DATA section of the script.

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

    C:\PS># In Day1.ps1
    Import-LocalizedData -BindingVariable Day
    Day.MessageDate

    # In Day2.ps1
    Import-LocalizedData -BindingVariable Day -ErrorAction:silentlycontinue
    Day.MessageDate

C:\PS> .\Day1.ps1

    Import-LocalizedData : Cannot find PowerShell data file ‘Day1.psd1’ in directory ‘C:\ps-test\fr-BE\’ or any parent culture directories.
    At C:\ps-test\Day1.ps1:17 char:21
    + Import-LocalizedData <<<< Day
    Today is Tuesday

C:\PS> .\Day2.ps1

Today is Tuesday

    Description
    ———–
    This example shows how to suppress the error messages that appear when Import-LocalizedData cannot find the directories that match the user’s UI culture or cannot find a .psd1 file for the script in those directories.

You can use the ErrorAction common parameter with a value of “SilentlyContinue” to suppress the error message. This is especially useful when you have provided user messages in a default or “fallback” language, and no error message is needed.

This example compares two scripts, Day1.ps1 and Day2.ps1, that include an Import-LocalizedData command. The scripts are identical, except that Day2 uses the ErrorAction common parameter with a value of SilentlyContinue.

The sample output shows the results of running both scripts when the UI culture is set to fr-BE and there are no matching files or directories for that UI culture. Day1.ps1 displays an error message and English output. Day2.ps1 just displays the English output.

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