Tag Archives: Debug

Write-Host

February 26, 2014 Adam

SYNOPSIS
Writes customized output to a host.

SYNTAX
Write-Host [[-Object] <Object>] [-BackgroundColor {Black | DarkBlue | DarkGreen | DarkCyan | DarkRed | DarkMagenta | DarkYellow | Gray | DarkGray | Blue | Green | Cyan | Red | Magenta | Yellow | White}] [-ForegroundColor {Black | DarkBlue | DarkGreen | DarkCyan | DarkRed | DarkMagenta | DarkYellow | Gray | DarkGray | Blue | Green | Cyan | Red | Magenta | Yellow | White}] [-NoNewline] [-Separator <Object>] [<CommonParameters>]

DESCRIPTION
The Write-Host cmdlet customizes output. You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. The Separator parameter lets you specify a string to use to separate displayed objects. The particular result depends on the program that is hosting Windows PowerShell.

PARAMETERS
-BackgroundColor <ConsoleColor>
Specifies the background color. There is no default.

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

-ForegroundColor <ConsoleColor>
Specifies the text color. There is no default.

-NoNewline [<SwitchParameter>]
Specifies that the content displayed in the console does not end with a newline character.

-Object <Object>
Objects to display in the console.

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

-Separator <Object>
String to the output between objects displayed on the console.

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

INPUTS
System.Object
You can pipe objects to be written to the host.

OUTPUTS
None
Write-Host sends the objects to the host. It does not return any objects. However, the host might display the objects that Write-Host sends to it.

NOTES

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

C:\PS>Write-Host “no newline test ” -NoNewline

no newline test C:\PS>

    Description
    ———–
    This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt.

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

C:\PS>Write-Host (2,4,6,8,10,12) -Separator “, +2= ”

2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12

    Description
    ———–
    This command displays the even numbers from 2 through 12. The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space).

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

C:\PS>Write-Host (2,4,6,8,10,12) -Separator “, -> ” -ForegroundColor DarkGreen -BackgroundColor white

    Description
    ———–
    This command displays the even numbers from 2 through 12. It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background.

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

C:\PS>Write-Host “Red on white text.” -ForegroundColor red -BackgroundColor white

Red on white text.

    Description
    ———–
    This command displays the string “Red on white text.” The text is red, as defined by the ForegroundColor parameter. The background is white, as defined by the BackgroundColor parameter.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113426
    Write-Verbose
    Write-Error
    Write-Progress
    Write-Debug
    Write-Output
    Write-Warning
    Out-Host

cmdlet, Output, Write

Write-Output

February 26, 2014 Adam

NAME
Write-Output

SYNOPSIS
Sends the specified objects to the next command in the pipeline. If the command is the last command in the pipeline, the objects are displayed in the console.

SYNTAX
Write-Output [-InputObject] <PSObject[]> [<CommonParameters>]

DESCRIPTION
The Write-Output cmdlet sends the specified object down the pipeline to the next command. If the command is the last command in the pipeline, the object is displayed in the console.

Write-Output sends objects down the primary pipeline, also known as the “output stream” or the “success pipeline.” To send error objects down the error pipeline, use Write-Error.

This cmdlet is typically used in scripts to display strings and other objects on the console. However, because the default behavior is to display the objects at the end of a pipeline, it is generally not necessary to use the cmdlet. For example, “Get-Process | Write-Output” is equivalent to “Get-Process“.

PARAMETERS
-InputObject <PSObject[]>
Specifies the objects to send down the pipeline. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

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

INPUTS
System.Management.Automation.PSObject
You can pipe objects to Write-Output.

OUTPUTS
System.Management.Automation.PSObject
Write-Output returns the objects that are submitted as input.

NOTES

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

C:\PS>$p = Get-Process

c:\PS> Write-Output $p

c:\PS> $p

    Description
    ———–
    These commands get objects representing the processes running on the computer and display the objects on the console.

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

C:\PS>Write-Output “test output” | Get-Member

    Description
    ———–
    This command pipes the “test output” string to the Get-Member cmdlet, which displays the members of the String class, demonstrating that the string was passed along the pipeline.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113427
    Write-Debug
    Write-Verbose
    Write-Error
    Write-Progress
    Write-Host
    Write-Warning
    Tee-Object

cmdlet, TypeData, Update

Update-TypeData

February 26, 2014 Adam

NAME
Update-TypeData

SYNOPSIS
Updates the current extended type configuration by reloading the *.types.ps1xml files into memory.

SYNTAX
Update-TypeData [[-AppendPath] <string[]>] [-PrependPath <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Update-TypeData cmdlet updates the current extended type configuration by reloading the *.types.ps1xml files into memory. Extended type information is normally loaded when Windows PowerShell requires the type information it contains. The Update-TypeData cmdlet can be used to preload all type information. It is particularly useful when you are developing types and want to load those new types for testing purposes.

For more information about the *types.ps1xml files in Windows PowerShell, see about_types.ps1xml.

PARAMETERS
-AppendPath <string[]>
Specifies the path to the optional .ps1xml files that will be included in the list of files loaded. These are processed after the built-in files are loaded.

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

-PrependPath <string[]>
Specifies the path to the optional .ps1xml files that will be included in the list of files loaded. However, these files are processed in the order they are specified and before the built-in files are loaded.

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

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

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

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

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

INPUTS
System.String
You can pipe a string that contains the append path to Update-TypeData.

OUTPUTS
None
This cmdlet does not return any output.

NOTES

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

C:\PS>Update-TypeData

    Description
    ———–
    This example updates the extended type configuration from the *.types.ps1xml files.

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

C:\PS>Update-TypeData -PrependPath typesA.types.Ps1xml, typesB.types.Ps1xml

    Description
    ———–
    This example updates the extended type configuration from the *.types.ps1xml files, processing the typesA and typesB files first.

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

cmdlet, Transaction, Use

Use-Transaction

February 26, 2014 Adam

NAME
Use-Transaction

SYNOPSIS
Adds the script block to the active transaction.

SYNTAX
Use-Transaction [-TransactedScript] <scriptblock> [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Use-Transaction cmdlet adds a script block to an active transaction. This enables you to do transacted scripting using transaction-enabled Microsoft .NET Framework objects. The script block can contain only transaction-enabled .NET Framework objects, such as instances of the Microsoft.PowerShell.Commands.Management.TransactedString class.

The UseTransaction parameter, which is optional for most cmdlets, is required when using this cmdlet.

The Use-Transaction cmdlet is one of a set of cmdlets that support the transactions feature in Windows PowerShell. For more information, see about_transactions.

PARAMETERS
-TransactedScript <scriptblock>
Specifies the script block that is run in the transaction. Enter any valid script block enclosed in braces ( { } ). This parameter is required.

        Required?                    true
        Position?                    1
        Default value                None
        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
PSObject
Use-Transaction returns the result of the transaction.

NOTES

The Use-Transaction parameter includes the command in the active transaction. Because the Use-Transaction cmdlet is always used in transactions, this parameter is required to make any Use-Transaction command effective.

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

C:\PS>Start-Transaction

C:\PS> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString

C:\PS> $transactedString.Append(“Hello”)
C:\PS> Use-Transaction -TransactedScript { $transactedString.Append(“, World”) } -UseTransaction

C:\PS> $transactedString.ToString()
Hello

C:\PS> Use-Transaction -TransactedScript { $transactedString.ToString() } -UseTransaction
Hello, World

    C:\PS> Complete-Transaction
    C:\PS> $transactedString.ToString()
    Hello, World

    Description
    ———–
    This example shows how to use the Use-Transaction cmdlet to script against a transaction-enabled .NET Framework object. In this case, the object is a TransactedString object.

The first command uses the Start-Transaction cmdlet to start a transaction.

The second command uses the New-Object command to create a TransactedString object. It stores the object in the $TransactedString Variable.

The third and fourth commands both use the Append method of the TransactedString object to add text to the value of $TransactedString. One command is part of the transaction; the other is not.

The third command uses the Append method of the transacted string to add “Hello” to the value of $TransactedString. Because the command is not part of the transaction, the change is applied immediately.

The fourth command uses the Use-Transaction cmdlet to add text to the string within the transaction. The command uses the Append method to add “, World” to the value of $TransactedString. The command is enclosed in braces ( {} ) to make it a script block. The UseTransaction parameter is required in this command.

The fifth and sixth commands use the ToString method of the TransactedString object to display the value of the TransactedString as a string. Again, one command is part of the transaction; the other is not.

The fifth command uses the ToString method to display the current value of the $TransactedString Variable. Because it is not part of the transaction, it displays only the current state of the string.

The sixth command uses the Use-Transaction cmdlet to run the same command within the transaction. Because the command is part of the transaction, it displays the current value of the string within the transaction, much like a preview of the transaction changes.

The seventh command uses the Complete-Transaction cmdlet to commit the transaction.

The final command uses the ToString method to display the resulting value of the Variable as a string.

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

C:\PS>Start-Transaction

C:\PS> $transactedString = New-Object Microsoft.PowerShell.Commands.Management.TransactedString

C:\PS> $transactedString.Append(“Hello”)
C:\PS> Use-Transaction -TransactedScript { $transactedString.Append(“, World”) } -UseTransaction

C:\PS> Undo-Transaction

C:\PS> $transactedString.ToString()
Hello

    Description
    ———–
    This example shows the effect of rolling back a transaction that includes Use-Transaction commands. Like all commands in a transaction, when the transaction is rolled back, the transacted changes are discarded and the data is unchanged.

The first command uses the Start-Transaction cmdlet to start a transaction.

The second command uses the New-Object command to create a TransactedString object. It stores the object in the $TransactedString Variable.

The third command, which is not part of the transaction, uses the Append method to add “Hello” to the value of $TransactedString.

The fourth command uses the Use-Transaction cmdlet to run another command that uses the Append method within the transaction. The command uses the Append method to add “, World” to the value of $TransactedString.

The fifth command uses the Undo-Transaction cmdlet to roll back the transaction. As a result, all commands performed within the transaction are reversed.

The final command uses the ToString method to display the resulting value of $TransactedString as a string. The results show that only the changes made outside of the transaction were applied to the object.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135271
    about_transactions
    Start-Transaction
    Get-Transaction
    Complete-Transaction
    Undo-Transaction

cmdlet, Stop, Transcript

Stop-Transcript

February 26, 2014 Adam

NAME
Stop-Transcript

SYNOPSIS
Stops a transcript.

SYNTAX
Stop-Transcript [<CommonParameters>]

DESCRIPTION
The Stop-Transcript cmdlet stops a transcript that was started by using the Start-Transcript cmdlet. You can also stop a transcript by ending the session.

PARAMETERS
    <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.String
Stop-Transcript returns a string that contains a status message and the path to the output file.

NOTES

If a transcript has not been started, the command fails.

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

C:\PS>Stop-Transcript

    Description
    ———–
    This command stops any running transcripts.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113415
Start-Transcript

cmdlet, Service, Suspend

Suspend-Service

February 26, 2014 Adam

NAME
Suspend-Service

SYNOPSIS
Suspends (pauses) one or more running services.

SYNTAX
Suspend-Service [-Name] <string[]> [-Exclude <string[]>] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Suspend-Service -DisplayName <string[]> [-Exclude <string[]>] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

Suspend-Service [-InputObject <ServiceController[]>] [-Exclude <string[]>] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Suspend-Service cmdlet sends a suspend message to the Windows Service Controller for each of the specified services. While suspended, the service is still running, but its action is halted until resumed, such as by using Resume-Service. You can specify the services by their service names or display names, or you can use the InputObject parameter to pass a service object representing the services that you want to suspend.

PARAMETERS
-DisplayName <string[]>
Specifies the display names of the services to be suspended. Wildcards are permitted.

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

-Exclude <string[]>
Omits the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as “s*”. Wildcards are permitted.

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

-Include <string[]>
Suspends only the specified services. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as “s*”. Wildcards are permitted.

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

-InputObject <ServiceController[]>
Specifies ServiceController objects representing the services to be suspended. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

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

-Name <string[]>
Specifies the service names of the services to be suspended. Wildcards are permitted.

The parameter name is optional. You can use “Name” or its Alias, “ServiceName”, or you can omit the parameter name.

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

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

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

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

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

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

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

INPUTS
System.ServiceProcess.ServiceController or System.String
You can pipe a service object or a string that contains a service name to Suspend-Service.

OUTPUTS
None or System.ServiceProcess.ServiceController
When you use the PassThru parameter, Suspend-Service generates a System.ServiceProcess.ServiceController object representing the service. Otherwise, this cmdlet does not generate any output.

NOTES

Suspend-Service can control services only when the current user has permission to do so. If a command does not work correctly, you might not have the required permissions.

Also, Suspend-Service can suspend only services that support being suspended and resumed. To determine whether a particular service can be suspended, use the Get-Service cmdlet with the CanPauseAndContinue property. For example, “Get-Service wmi | Format-List name, canpauseandcontinue”. To find all services on the computer that can be suspended, type “Get-Service | Where-Object {$_.canpauseandcontinue -eq “True”}”.

To find the service names and display names of the services on your system, type “Get-Service“. The service names appear in the Name column, and the display names appear in the DisplayName column.

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

C:\PS>Suspend-Service -displayname “Telnet”

    Description
    ———–
    This command suspends the Telnet service (Tlntsvr) service on the local computer.

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

C:\PS>Suspend-Service -Name lanman* -WhatIf

    Description
    ———–
    This command tells what would happen if you suspended the services that have a service name that begins with “lanman”. To suspend the services, rerun the command without the WhatIf parameter.

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

C:\PS>Get-Service schedule | Suspend-Service

    Description
    ———–
    This command uses the Get-Service cmdlet to get an object that represents the Task Scheduler (Schedule) service on the computer. The pipeline operator (|) passes the result to the Suspend-Service cmdlet, which suspends the service.

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

C:\PS>Get-Service | Where-Object {$_.canpauseandcontinue -eq “True”} | Suspend-Service -Confirm

    Description
    ———–
    This command suspends all of the services on the computer that can be suspended. It uses the Get-Service cmdlet to get objects representing the services on the computer. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects only the services that have a value of “True” for the CanPauseAndContinue property. Another pipeline operator passes the results to the Suspend-Service cmdlet. The Confirm parameter prompts you for confirmation before suspending each of the services.

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

cmdlet, Object, Tee

Tee-Object

February 26, 2014 Adam

NAME
Tee-Object

SYNOPSIS
Saves command output in a file or Variable, and displays it in the console.

SYNTAX
Tee-Object [-FilePath] <string> [-InputObject <psobject>] [<CommonParameters>]

Tee-Object -Variable <string> [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Tee-Object cmdlet sends the output of a command in two directions (like the letter “T”). It stores the output in a file or Variable and also sends it down the pipeline. If Tee-Object is the last command in the pipeline, the command output is displayed in the console.

PARAMETERS
-FilePath <string>
Specifies the file where the cmdlet stores the object. Accepts wildcards that resolve to a single file.

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

-InputObject <psobject>
Specifies the object input to the cmdlet. Enter a Variable that contains the objects or type a command or expression that gets the objects.

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

-Variable <string>
Assigns a reference to the input objects to the specified Variable.

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

INPUTS
System.Management.Automation.PSObject
You can pipe objects to be redirected to Tee-Object.

OUTPUTS
System.Management.Automation.PSObject
Tee-Object returns the object that it redirected.

NOTES

You can also use the Out-File cmdlet or the redirection operator, both of which save the output in a file but do not send it down the pipeline.

Tee-Object uses Unicode encoding when it writes to files. As a result, the output might not be formatted properly in files with a different encoding. To specify the encoding, use the Out-File cmdlet.

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

C:\PS>Get-Process | Tee-Object -FilePath C:\Test1\testfile2.txt

    Handles NPM(K)    PM(K)     WS(K) VM(M) CPU(s)    Id ProcessName
    ——- ——    —–     —– —– ——    — ———–
     83     4     2300     4520    39     0.30    4032 00THotkey
     272     6     1400     3944    34     0.06    3088 alg
     81     3     804     3284    21     2.45     148 ApntEx
     81     4     2008     5808    38     0.75    3684 Apoint
    …

    Description
    ———–
    This command gets a list of the processes running on the computer and sends the result to a file. Because a second path is not specified, the result will be displayed in the console.

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

C:\PS>Get-Process notepad | Tee-Object -variable proc | Select-Object processname,handles

    ProcessName                             Handles
    ———–                             ——-
    notepad                                 43
    notepad                                 37
    notepad                                 38
    notepad                                 38

    Description
    ———–
    This command gets a list of the processes running on the computer and sends the result to a Variable named “proc”. It then pipes the resulting objects along to Select-Object, which selects the ProcessName and Handles property. Note that the $proc Variable includes the default information returned by Get-Process.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113417
    about_Redirection
    Select-Object

cmdlet, ComputerSecureChannel, Test

Test-ComputerSecureChannel

February 26, 2014 Adam

NAME
Test-ComputerSecureChannel

SYNOPSIS
Tests and repairs the secure channel between the local computer and its domain.

SYNTAX
Test-ComputerSecureChannel [-Repair] [-Server <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
The Test-ComputerSecureChannel cmdlet verifies that the secure channel between the local computer and its domain is working correctly by checking the status of its trust relationships. If a connection fails, you can use the Repair parameter to try to restore it.

Test-ComputerSecureChannel returns “True” if the secure channel is working correctly and “False” if it is not. This result lets you use the cmdlet in conditional statements in Functions and scripts. To get more detailed test results, use the Verbose parameter.

This cmdlet works much like NetDom.exe. Both NetDom and Test-ComputerSecureChannel use the NetLogon service to perform the actions.

PARAMETERS
-Repair [<SwitchParameter>]
Removes and then rebuilds the secure channel established by the NetLogon service. Use this parameter to try to restore a connection that has failed the test (returned “False”.)

To use this parameter, the current user must be a member of the Administrators group on the local computer.

-Server <string>
Uses the specified domain controller to run the command. If this parameter is omitted, Test-ComputerSecureChannel selects a default domain controller for the operation.

-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.Boolean
The cmdlet returns “True” when the connection is working correctly and “False” when it is not.

NOTES

To run a Test-ComputerSecureChannel command on Windows Vista and later versions of Windows, open Windows PowerShell with the “Run as administrator” option.

Test-ComputerSecureChannel is implemented by using the I_NetLogonControl2 Function, which controls various aspects of the Netlogon service.

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

C:\PS>Test-ComputerSecureChannel

True

    Description
    ———–
    This command tests the secure channel between the local computer and the domain to which it is joined.

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

C:\PS>Test-ComputerSecureChannel -Server DCName.fabrikam.com

True

    Description
    ———–
    This command specifies a preferred domain controller for the test.

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

C:\PS>Test-ComputerSecureChannel -Repair

True

    Description
    ———–
    This command resets the secure channel between the local computer and its domain.

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

C:\PS>Test-ComputerSecureChannel -Verbose

    VERBOSE: Performing operation “Test-ComputerSecureChannel” on Target “SERVER01”.
    True
    VERBOSE: “The secure channel between ‘SERVER01’ and ‘net.fabrikam.com’ is alive and working correctly.”

    Description
    ———–
    This command uses the Verbose common parameter to request detailed messages about the operation. For more information about the Verbose parameter, see about_CommonParameters.

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

C:\PS>Set-Alias tcsc Test-ComputerSecureChannel

    if (!(tcsc))
         {Write-Host “Connection failed. Reconnect and retry.”}
    else { &(.\get-Servers.ps1) }

    Description
    ———–
    This example shows how to use Test-ComputerSecureChannel to test a connection before running a script that requires the connection.

The first command uses the Set-Alias cmdlet to create an Alias for the cmdlet name. This saves space and prevents typing errors.

The If statement checks the value that Test-ComputerSecureChannel returns before running a script.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=137749
    Checkpoint-Computer
    Restart-Computer
    Stop-Computer
    Reset-ComputerMachinePassword

cmdlet, Connection, Test

Test-Connection

February 26, 2014 Adam

NAME
Test-Connection

SYNOPSIS
Sends ICMP echo request packets (“pings”) to one or more computers.

SYNTAX
Test-Connection [-ComputerName] <string[]> [[-Source] <string[]>] [-AsJob] [-Authentication {Default | None | Connect | Call | Packet | PacketIntegrity | PacketPrivacy | Unchanged}] [-BufferSize <int>] [-Count <int>] [-Credential <PSCredential>] [-Delay <int>] [-Impersonation {Default | Anonymous | Identify | Impersonate | Delegate}] [-Quiet] [-ThrottleLimit <int>] [-TimeToLive <int>] [<CommonParameters>]

DESCRIPTION
The Test-Connection cmdlet sends Internet Control Message Protocol (ICMP) echo request packets (“pings”) to one or more remote computers and returns the echo response replies. You can use this cmdlet to determine whether a particular computer can be contacted across an Internet Protocol (IP) network.

You can use the parameters of Test-Connection to specify both the sending and receiving computers, to run the command as a background job, to set a timeout and number of pings, and to configure the connection and authentication.

Unlike the traditional “ping” command, Test-Connection returns a Win32_PingStatus object that you can investigate in Windows PowerShell, but you can use the Quiet parameter to force it to return only a Boolean value.

PARAMETERS
-AsJob [<SwitchParameter>]
Runs the command as a background job.

Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the “Run as administrator” option. For more information, see about_remote_requirements.

When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. The job is created on the local computer and the results from remote computers are automatically returned to the local computer. To get the job results, use the Receive-Job cmdlet.

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

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

-Authentication <AuthenticationLevel>
Specifies the authentication level that is used for the WMI connection. (Test-Connection uses WMI.)

Valid values are:

        Unchanged:     The authentication level is the same as the previous command.
        Default:         Windows Authentication.
        None:            No COM authentication.
        Connect:         Connect-level COM authentication.
        Call:            Call-level COM authentication.
        Packet:         Packet-level COM authentication.
        PacketIntegrity: Packet Integrity-level COM authentication.
        PacketPrivacy: Packet Privacy-level COM authentication.

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

-BufferSize <int>
Specifies the size, in bytes, of the buffer sent with this command. The default value is 32.

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

-ComputerName <string[]>
Specifies the computers to ping. Type the computer names or type IP addresses in IPv4 or IPv6 format. Wildcard characters are not permitted. This parameter is required.

This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.

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

-Count <int>
Specifies the number of echo requests to send. The default value is 4.

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

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

-Delay <int>
Specifies the interval between pings, in seconds.

        Required?                    false
        Position?                    named
        Default value                1 (second)
        Accept pipeline input?     false
        Accept wildcard characters? false

-Impersonation <ImpersonationLevel>
Specifies the impersonation level to use when calling WMI. (Test-Connection uses WMI.) The default value is “Impersonate”.

Valid values are:

        Default:     Default impersonation.
        Anonymous:    Hides the identity of the caller.
        Identify:     Allows objects to query the credentials of the caller.
        Impersonate: Allows objects to use the credentials of the caller.

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

-Quiet [<SwitchParameter>]
Suppresses all errors and returns $True if any pings succeeded and $False if all failed.

-Source <string[]>
Specifies the names of the computers where the ping originates. Enter a comma-separated list of computer names. The default is the local computer.

        Required?                    false
        Position?                    2
        Default value                Local computer
        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, the default value, 32, is used.

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

-TimeToLive <int>
Specifies the maximum time, in seconds, that each echo request packet (“pings”) is active. The default value is 80 (seconds). The Alias of the TimeToLive parameter is TTL.

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.ManagementObject#root\cimv2\Win32_PingStatus, System.Management.Automation.RemotingJob, System.Boolean
When you use the AsJob parameter, the cmdlet returns a job object. When you use the Quiet parameter, it returns a Boolean. Otherwise, this cmdlet returns a Win32_PingStatus object for each ping.

NOTES

This cmdlet uses the Win32_PingStatus class. A “get-wmiojbect win32_pingstatus” command is equivalent to a Test-Connection command.

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

C:\PS>Test-Connection server01

    Source        Destination     IPV4Address     IPV6Address Bytes    Time(ms)
    ——        ———–     ———–     ———– —–    ——–
    ADMIN1        Server01        157.59.137.44                32     0
    ADMIN1        Server01        157.59.137.44                32     0
    ADMIN1        Server01        157.59.137.44                32     0
    ADMIN1        Server01        157.59.137.44                32     1

    Description
    ———–
    This command sends echo request packets (“pings”) from the local computer to the Server01 computer. This command uses the ComputerName parameter to specify the Server01 computer, but omits the optional parameter name.

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

C:\PS>Test-Connection -ComputerName server01, server02, server12 -Credential domain01\user01

    Description
    ———–
    This command sends pings from the local computer to several remote computers. It uses the Credential parameter to specify a user account that has permission to ping all of the remote computers.

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

C:\PS>Test-Connection -Source Server02, Server 12, localhost -ComputerName Server01

    Description
    ———–
    This command sends pings from different source computers to a single remote computer, Server01. Use this command format to test the latency of connections from multiple points.

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

C:\PS>Test-Connection -ComputerName Server01 -Count 3 -Delay 2 -TTL 256 -BufferSize 256 -throttle 32

    Description
    ———–
    This command sends three pings from the local computer to the Server01 computer. It uses the parameters of Test-Connection to customize the command.

Use this command format when the ping response is expected to take longer than usual, either because of an extended number of hops or a high-traffic network condition.

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

C:\PS>$job = Test-Connection -ComputerName (Get-Content servers.txt) -AsJob

C:\PS> if ($job.jobstateinfo.state -ne “Running”) {$results = Receive-Job $job}

    Description
    ———–
    This example shows how to run a Test-Connection command as a Windows PowerShell background job.

The first command uses the Test-Connection cmdlet to ping many computers in an enterprise. The value of ComputerName parameter is a Get-Content command that reads a list of computer names from the Servers.txt file. The command uses the AsJob parameter to run the command as a background job.

The second command checks to see that the job is not still running, and if it is not, it uses a Receive-Job command to get the results and store them in the $results Variable.

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

C:\PS>Test-Connection Server55 -Credential domain55\user01 -Impersonation Identify

    Description
    ———–
    This command uses the Test-Connection cmdlet to ping a remote computer. The command uses the Credential parameter to specify a user account with permission to ping the remote computer and the Impersonation parameter to change the impersonation level to “Identify”.

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

C:\PS>if (Test-Connection -ComputerName Server01 -quiet) {New-PSSession Server01}

    Description
    ———–
    This command creates a PSSession on the Server01 only if at least one of the pings sent to the computer succeeds.

The command uses the Test-Connection cmdlet to ping the Server01 computer. The command uses the Quiet parameter, which returns a Boolean value, instead of a Win32_PingStatus object. The value is $True if any of the four pings succeed and is, otherwise, false.

If the Test-Connection command returns a value of $True, the command uses the New-PSSession cmdlet to create the PSSession.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135266
    Add-Computer
    Restart-Computer
    Stop-Computer

cmdlet, ModuleManifest, Test

Test-ModuleManifest

February 26, 2014 Adam

NAME
Test-ModuleManifest

SYNOPSIS
Verifies that a module manifest file accurately describes the contents of a module.

SYNTAX
Test-ModuleManifest [-Path] <string> [<CommonParameters>]

DESCRIPTION
The Test-ModuleManifest cmdlet verifies that the files that are listed in the module manifest (.psd1) file actually exist in the specified paths.

This cmdlet is designed to help module authors test their manifest files. Module users can also use this cmdlet in scripts and commands to detect errors before running scripts that depend on the module.

The Test-ModuleManifest cmdlet returns an object that represents the module (the same type of object that Get-Module returns). If any files are not in the locations specified in the manifest, the cmdlet also generates an error for each missing file.

PARAMETERS
-Path <string>
Specifies the path to the module manifest file. Enter a path (optional) and the name of the module manifest file with the .psd1 file name extension. The default location is the current directory. This parameter is required. The parameter name (“Path”) is optional. You can also pipe a path to Test-ModuleManifest.

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

INPUTS
System.String
You can pipe the path to a module manifest to Test-ModuleManifest.

OUTPUTS
System.Management.Automation.PSModuleInfo
Test-ModuleManifest returns a PSModuleInfo object that represents the module. It returns this object even if the manifest has errors.

NOTES

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

C:\PS>Test-ModuleManifest -Path $pshome\Modules\TestModule.psd1

    Description
    ———–
    This command tests the TestModule.psd1 module manifest.

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

C:\PS>”$pshome\Modules\TestModule.psd1″ | Test-ModuleManifest

    Test-ModuleManifest : The specified type data file ‘C:\Windows\System32\Wi
    ndowsPowerShell\v1.0\Modules\TestModule\TestTypes.ps1xml’ could not be pro
    cessed because the file was not found. Please correct the path and try aga
    in.
    At line:1 char:34
    + “$pshome\Modules\TestModule.psd1” | Test-ModuleManifest <<<<
        + CategoryInfo         : ResourceUnavailable: (C:\Windows\System32\Win
    dowsPowerShell\v1.0\Modules\TestModule\TestTypes.ps1xml:String) [Test-Modul
    eManifest], FileNotFoundException
        + FullyQualifiedErrorId : Modules_TypeDataFileNotFound,Microsoft.
    PowerShell.Commands.TestModuleManifestCommandName

    Name             : TestModule
    Path             : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Test
    Module\TestModule.psd1
    Description     :
    Guid             : 6f0f1387-cd25-4902-b7b4-22cff6aefa7b
    Version         : 1.0
    ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Test
    Module
    ModuleType        : Manifest
    PrivateData     :
    AccessMode        : ReadWrite
    ExportedAliases : {}
    ExportedCmdlets : {}
    ExportedFunctions : {}
    ExportedVariables : {}
    NestedModules     : {}

    Description
    ———–
    This command uses a pipeline operator (|) to send a path string to Test-ModuleManifest.

The command output shows that the test failed, because the TestTypes.ps1xml file, which was listed in the manifest, was not found.

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

C:\PS>function Bool-ModuleManifest ($path)
{$a = dir $path | Test-ModuleManifest -ErrorAction SilentlyContinue; $?}

    Description
    ———–
    This Function is like Test-ModuleManifest, but it returns a Boolean value; it returns “True” if the manifest passed the test and “False” otherwise.

The Function uses the Get-ChildItem cmdlet (alias = dir) to get the module manifest specified by the $path Variable. It uses a pipeline operator (|) to pass the file object to the Test-ModuleManifest cmdlet.

The Test-ModuleManifest command uses the ErrorAction common parameter with a value of SilentlyContinue to suppress the display of any errors that the command generates. It also saves the PSModuleInfo object that Test-ModuleManifest returns in the $a Variable, so the object is not displayed.

Then, in a separate command (the semi-colon [;] is the command separator), it displays the value of the $? automatic Variable, which returns “True” if the previous command generated no error and “False” otherwise.

You can use this Function in conditional statements, such as those that might precede an Import-Module command or a command that uses the module.

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