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 -LocalThis 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 HostGuardianServiceThis 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 GuardedHostThis 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 HostGuardianServiceThis 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.