New-HgsTraceTarget
Creates a HGS Diagnostics target object.
Syntax
Remote (Default)
New-HgsTraceTarget
-HostName <String>
[-Credential <PSCredential>]
[-PSSessionConfigurationName <String>]
[-Role <BaseHgsRoles[]>]
[<CommonParameters>]
NoAccess
New-HgsTraceTarget
-HostName <String>
-Role <BaseHgsRoles[]>
[-NoAccess]
[<CommonParameters>]
Local
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.
Parameter properties
| Type: | PSCredential |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Remote
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Remote
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
NoAccess
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Local
Indicates that the created target is the current local host.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Local
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-NoAccess
Indicates that no access is available to the target. Therefore, connections will never be opened to this target.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
NoAccess
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Remote
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | BaseHgsRoles[] |
| Default value: | None |
| Accepted values: | None, HostGuardianService, GuardedHost |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Remote
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
Local
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
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.