Set-XdrEndpointDeviceTag
SYNOPSIS
Sets, adds, or removes user-defined tags on endpoint devices in Microsoft Defender XDR.
SYNTAX
Replace (Default)
Set-XdrEndpointDeviceTag -DeviceId <String[]> -Tags <String[]> [-ProgressAction <ActionPreference>] [-WhatIf]
[-Confirm] [<CommonParameters>]
AddRemove
Set-XdrEndpointDeviceTag -DeviceId <String[]> [-Add <String[]>] [-Remove <String[]>]
[-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION
Manages user-defined tags on one or more endpoint devices by calling the editMachineTags API. Only modifies UserDefinedTags; BuiltInTags and DynamicRulesTags are managed through separate mechanisms. Supports two modes:
- Replace (Tags): Replaces all existing user-defined tags with the provided tags.
- AddRemove (Add/Remove): Retrieves current user-defined tags, adds and/or removes the specified tags, and sets the resulting list. Both -Add and -Remove can be used together in a single call.
When using -Add or -Remove, the cmdlet fetches each device's current user-defined tags via Get-XdrEndpointDeviceTag, modifies the list, then calls editMachineTags with the updated set.
EXAMPLES
EXAMPLE 1
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Tags "Production", "VDI"
Replaces all user-defined tags on the device with Production and VDI.
EXAMPLE 2
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Add "VDI"
Adds the VDI tag to the device's existing user-defined tags without removing any.
EXAMPLE 3
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Remove "TestTag"
Removes the TestTag from the device, keeping all other user-defined tags.
EXAMPLE 4
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Add "Production" -Remove "TestTag"
Adds the Production tag and removes the TestTag in a single operation.
EXAMPLE 5
Set-XdrEndpointDeviceTag -DeviceId "abc123", "def456" -Add "Production"
Adds the Production tag to multiple devices.
PARAMETERS
-DeviceId
One or more device IDs (SenseMachineIds) identifying the target devices.
Type: String[]
Parameter Sets: (All)
Aliases: MachineId, SenseMachineId
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
-Tags
Array of tag strings to set on the devices. Replaces all existing user-defined tags.
Type: String[]
Parameter Sets: Replace
Aliases: MachineTags
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Add
Array of tag strings to add to each device's existing user-defined tags. Duplicates are ignored. Can be combined with -Remove in a single call.
Type: String[]
Parameter Sets: AddRemove
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Remove
Array of tag strings to remove from each device's existing user-defined tags. Can be combined with -Add in a single call.
Type: String[]
Parameter Sets: AddRemove
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the command runs. The command is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts for confirmation before making changes.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
The ProgressAction parameter is a common parameter, not a cmdlet parameter. For more information, see about_CommonParameters.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.