New-HgsTraceTarget

Creates a HGS Diagnostics target object.

Syntax

New-HgsTraceTarget
   -HostName <String>
   [-Credential <PSCredential>]
   [-PSSessionConfigurationName <String>]
   [-Role <BaseHgsRoles[]>]
   [<CommonParameters>]
New-HgsTraceTarget
   -HostName <String>
   [-NoAccess]
   -Role <BaseHgsRoles[]>
   [<CommonParameters>]
New-HgsTraceTarget
   [-Local]
   [-Role <BaseHgsRoles[]>]
   [<CommonParameters>]

Description

The New-HgsTraceTarget cmdlet creates a Host Guardian Service (HGS) Diagnostics target object. The Get-HgsTrace cmdlet can use this information to determine how to connect to a particular host as well as what aspects of the host to trace and diagnose.

Examples

Example 1: Create a default target object

PS C:\> New-HgsTraceTarget -Local

This command creates a target object named localhost. Since this command does not specify a role, the cmdlet will use the credentials of the current session and then infers the role though the list of installed features on the target.

Example 2: Create a target with different credentials and a specified role

PS C:\> New-HgsTraceTarget -HostName "hgs-01.contoso.com" -Credential (Get-Credential) -Role HostGuardianService

This command creates a target object with hostname named hgs-01.contoso.com that uses the provided credentials and makes the target a HGS node.

Example 3: Create a target to which no access is available with a specified role

PS C:\> New-HgsTraceTarget -HostName "hyperv-02.contoso.com" -NoAccess -Role GuardedHost

This command creates a target object with hostname named hyperv-02.contoso.com that has no credentials but is regarded as a guarded host. No attempt will be made to connect to a NoAccess target.

Example 4: Create a target that reuses the current session's credentials and a specified role

PS C:\> New-HgsTraceTarget -HostName "hgs-01.contoso.com" -role HostGuardianService

This command creates a target object with hostname named hgs-01.contoso.com that reuses the credentials of the current session and makes the target a HGS node.

Example 5: Create a target that reuses the current session's credentials and infer the role

PS C:\> New-HgsTraceTarget -HostName "hyperv-02.contoso.com"

This command creates a target object with hostname hyperv-02.contoso.com that reuses the credentials of the current session and then infers the role though the list of installed features on the target.

Parameters

-Credential

Specifies a PSCredential object under which the management group connection runs. To obtain a PSCredential object, use the Get-Credential cmdlet. For more information, type Get-Help Get-Credential.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HostName

Specifies the hostname of the target. This parameter is used to resolve an IP address when a remote Windows PowerShell® session is opened.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Local

Indicates that the created target is the current local host.

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NoAccess

Indicates that no access is available to the target. Therefore, connections will never be opened to this target.

Type:SwitchParameter
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-PSSessionConfigurationName

Specifies the remote Windows PowerShell session configuration to utilize when a remote runspace is opened. If you omit this parameter, the default runspace is utilized by the Get-HgsTrace cmdlet, or the HGS configuration for targets that have the HostGuardianService role.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Role

Specifies the role a particular target plays in a guarded fabric. This can be a HGS node (HostGuardianService) or a Guarded Host (GuardedHost). If you do not specify a role, it will be inferred by the open connection and the inspection of the installed Windows features.

Type:BaseHgsRoles[]
Accepted values:None, HostGuardianService, GuardedHost, None, HostGuardianService, GuardedHost
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Outputs

Microsoft.Windows.HostGuardianService.Diagnostics.Payload.InputTarget

This cmdlet returns a target object that is a collection of metadata that contains connection information of a host operating in a guarded fabric as well as its role in the fabric.