New-Hgs Trace Target

Module:
hgsdiagnostics
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.

Required Parameters

-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
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
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
Accept pipeline input: False
Accept wildcard characters: False

Optional 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
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
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[]
Parameter Sets: None, HostGuardianService, GuardedHost, None, HostGuardianService, GuardedHost
Position: Named
Default value: None
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.