fix: Fix missing Name in Get-ItemState default formatter (#153)

Author: joshooaj

MilestonePSTools/MilestonePSTools.Format.ps1xml

@@ -72,39 +72,32 @@
       <TableControl>
         <TableHeaders>
           <TableColumnHeader>
-            <Label>Name</Label>
-            <Width>25</Width>
+            <Width>36</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>ItemType</Label>
             <Width>10</Width>
           </TableColumnHeader>
           <TableColumnHeader>
             <Width>18</Width>
           </TableColumnHeader>
           <TableColumnHeader>
-            <Label>Id</Label>
             <Width>36</Width>
           </TableColumnHeader>
         </TableHeaders>
         <TableRowEntries>
           <TableRowEntry>
             <TableColumnItems>
               <TableColumnItem>
-                <ScriptBlock>
-                    ($_ | Get-PlatformItem).Name
-                </ScriptBlock>
+                <PropertyName>Name</PropertyName>
               </TableColumnItem>
               <TableColumnItem>
-                <ScriptBlock>
-                    [VideoOS.Platform.Kind]::DefaultTypeToNameTable[$_.FQID.Kind]
-                </ScriptBlock>
+                <PropertyName>ItemType</PropertyName>
               </TableColumnItem>
               <TableColumnItem>
                 <PropertyName>State</PropertyName>
               </TableColumnItem>
               <TableColumnItem>
-                <ScriptBlock>$_.FQID.ObjectId</ScriptBlock>
+                <PropertyName>Id</PropertyName>
               </TableColumnItem>
             </TableColumnItems>
           </TableRowEntry>

MilestonePSTools/Public/VideoOS/Get-VmsVideoOSItem.ps1

@@ -13,11 +13,11 @@
 # limitations under the License.
 
 function Get-VmsVideoOSItem {
-    [CmdletBinding()]
+    [CmdletBinding(DefaultParameterSetName = 'GetItemByFQID')]
     [OutputType([VideoOS.Platform.Item])]
     [RequiresVmsConnection()]
     param(
-        [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = 'GetItemByFQID')]
+        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName, ParameterSetName = 'GetItemByFQID')]
         [VideoOS.Platform.FQID]
         $Fqid,
 
@@ -29,7 +29,7 @@ function Get-VmsVideoOSItem {
         [guid]
         $Id,
 
-        [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = 'GetItem')]
+        [Parameter(Mandatory, ParameterSetName = 'GetItem')]
         [Parameter(ValueFromPipelineByPropertyName, ParameterSetName = 'GetItems')]
         [ArgumentCompleter([KindArgumentCompleter])]
         [KindNameTransform()]

docs/changelog.md

@@ -7,6 +7,15 @@ hide:
 
 ## [vNext] unreleased
 
+### 🐛 Fixed
+
+- **`Get-ItemState`** output was no longer populating names for `ItemState` records in the terminal output. Now item
+  names are correctly retrieved, and `Name`, `ItemType`, and `Id` values are added to the `ItemState` object as note
+  properties making them easy to access programmatically and not just showing the values in the terminal when displayed
+  with the default formatter. We also will now hide `Event` items in the response, and `Server` item types without names
+  as well. These all tend to be user-defined events, generic events, and built-in system events that aren't useful
+  output.
+
 ## [25.2.21] 2026-01-14
 
 ### 🔄 Changed

docs/commands/en-US/Get-ItemState.md

@@ -14,18 +14,16 @@ Gets the ItemState of all known items in the site
 ## SYNTAX
 
 ```
-Get-ItemState [-CamerasOnly] [<CommonParameters>]
+Get-ItemState [-CamerasOnly] [[-Timeout] <TimeSpan>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
 
-Sends a MessageCommunication.ProvideCurrentStateRequest message and returns the response.
+The `Get-ItemState` cmdlet sends a "MessageCommunication.ProvideCurrentStateRequest" message and returns the response
+from the XProtect Event Server.
 
-The ProvideCurrentStateResponse contains a flat collection of ItemState objects representing the state of all known items in the site.
-Each ItemState contains an FQID, and State property.
-The FQID.Kind and FQID.ObjectId can be used to determine what type of object the state represents, and the ID of that object.
-
-Most of the time, you will probably only be interested in Camera objects, so you can filter the output with the -CamerasOnly switch.
+The `VideoOS.Platform.Messaging.ItemState` objects returned by this command have an `FQID` and `State` property, and
+using the `FQID` this command enriches the output by adding the item `Name`, `ItemType`, and `Id` as note properties.
 
 REQUIREMENTS  
 
@@ -61,12 +59,27 @@ Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 1
+Position: Named
 Default value: False
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Timeout
+Specifies a timeout period in the form of a TimeSpan. The default value is 60 seconds.
+
+```yaml
+Type: TimeSpan
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 1
+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](http://go.microsoft.com/fwlink/?LinkID=113216).
 

docs/commands/en-US/Get-PlatformItem.md

@@ -13,9 +13,9 @@ Gets a VideoOS.Platform.Item object representing a configuration item
 
 ## SYNTAX
 
-### ByFQID
+### ByFQID (Default)
 ```
-Get-PlatformItem [[-Fqid] <FQID>] [<CommonParameters>]
+Get-PlatformItem [-Fqid] <FQID> [<CommonParameters>]
 ```
 
 ### BySearch
@@ -26,7 +26,7 @@ Get-PlatformItem [[-SearchText] <String>] [[-MaxResultCount] <Int32>] [[-Timeout
 
 ### ByKind
 ```
-Get-PlatformItem [[-Kind] <Guid>] [<CommonParameters>]
+Get-PlatformItem [-Kind] <Guid> [<CommonParameters>]
 ```
 
 ### ListAvailable
@@ -88,7 +88,7 @@ Type: FQID
 Parameter Sets: ByFQID
 Aliases:
 
-Required: False
+Required: True
 Position: 1
 Default value: None
 Accept pipeline input: True (ByPropertyName, ByValue)
@@ -157,10 +157,10 @@ Type: Guid
 Parameter Sets: ByKind
 Aliases:
 
-Required: False
+Required: True
 Position: 1
 Default value: 00000000-0000-0000-0000-000000000000
-Accept pipeline input: True (ByValue)
+Accept pipeline input: False
 Accept wildcard characters: False
 ```
 

docs/commands/en-US/Get-VmsVideoOSItem.md

@@ -12,7 +12,7 @@ Gets `[VideoOS.Platform.Item]` objects of the specified Kind.
 
 ## SYNTAX
 
-### GetItemByFQID
+### GetItemByFQID (Default)
 ```
 Get-VmsVideoOSItem -Fqid <FQID> [<CommonParameters>]
 ```
@@ -118,7 +118,7 @@ Aliases:
 Required: True
 Position: Named
 Default value: None
-Accept pipeline input: True (ByPropertyName)
+Accept pipeline input: True (ByPropertyName, ByValue)
 Accept wildcard characters: False
 ```
 
@@ -165,7 +165,7 @@ Aliases:
 Required: True
 Position: Named
 Default value: None
-Accept pipeline input: True (ByPropertyName)
+Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
@@ -177,7 +177,7 @@ Aliases:
 Required: False
 Position: Named
 Default value: None
-Accept pipeline input: True (ByPropertyName)
+Accept pipeline input: False
 Accept wildcard characters: False
 ```
 

src/MilestonePSTools/DeviceCommands/GetItemState.cs

@@ -16,6 +16,7 @@
 using System.Collections.Concurrent;
 using System.Collections.ObjectModel;
 using System.Management.Automation;
+using System.Threading;
 using VideoOS.Platform;
 using VideoOS.Platform.Messaging;
 
@@ -51,9 +52,12 @@ public class GetItemState : ConfigApiCmdlet
         /// <summary>
         /// <para type="description">Filter the ItemState results to Camera items</para>
         /// </summary>
-        [Parameter(Position = 1)]
+        [Parameter()]
         public SwitchParameter CamerasOnly { get; set; }
 
+        [Parameter(Position = 1)]
+        public TimeSpan Timeout { get; set; } = TimeSpan.FromSeconds(60);
+
         /// <summary>
         /// 
         /// </summary>
@@ -62,6 +66,7 @@ protected override void ProcessRecord()
             _itemStates = new BlockingCollection<ItemState>();
             MessageCommunication mc = null;
             object obj = null;
+            CancellationTokenSource cts = null;
             try
             {
                 MessageCommunicationManager.Start(Connection.CurrentSite.FQID.ServerId);
@@ -70,12 +75,40 @@ protected override void ProcessRecord()
                 obj = mc.RegisterCommunicationFilter(ProvideCurrentStateResponse,
                     new CommunicationIdFilter(MessageCommunication.ProvideCurrentStateResponse));
                 mc.TransmitMessage(new Message(MessageCommunication.ProvideCurrentStateRequest), null, null, null);
-
-                foreach (var itemState in _itemStates.GetConsumingEnumerable())
+                cts = new CancellationTokenSource(Timeout);
+                foreach (var itemState in _itemStates.GetConsumingEnumerable(cts.Token))
                 {
-                    WriteObject(itemState);
+                    // Ignore Event item states
+                    var kind = Kind.DefaultTypeToNameTable.ContainsKey(itemState.FQID.Kind)
+                        ? Kind.DefaultTypeToNameTable[itemState.FQID.Kind].ToString()
+                        : "External";
+                    if (kind == "Event") continue;
+                    
+                    var item = Configuration.Instance.GetItem(itemState.FQID);
+
+                    // Ignore ItemState records where no corresponding item can be found
+                    // These are typically Generic Events or built-in system events
+                    if (item == null && kind == "Server") continue;
+
+                    // Enrich the ItemState with helpful properties
+                    var psObj = PSObject.AsPSObject(itemState);
+                    psObj.Properties.Add(new PSNoteProperty("Name", item?.Name ?? "Not available"));
+                    psObj.Properties.Add(new PSNoteProperty("ItemType", kind));
+                    psObj.Properties.Add(new PSNoteProperty("Id", itemState.FQID.ObjectId));
+                    
+                    WriteObject(psObj);
                 }
             }
+            catch (PipelineStoppedException)
+            {
+                throw;
+            }
+            catch (OperationCanceledException cancelledException)
+            {
+                WriteError(
+                    new ErrorRecord(
+                        cancelledException, $"The operation timed out after the Timeout delay of {Timeout}", ErrorCategory.OperationTimeout, null));
+            }
             catch (Exception e)
             {
                 WriteError(
@@ -84,6 +117,7 @@ protected override void ProcessRecord()
             }
             finally
             {
+                cts?.Dispose();
                 mc?.UnRegisterCommunicationFilter(obj);
                 mc?.Dispose();
                 MessageCommunicationManager.Stop(Connection.CurrentSite.FQID.ServerId);

src/MilestonePSTools/DeviceCommands/GetPlatformItem.cs

@@ -44,15 +44,15 @@ namespace MilestonePSTools.DeviceCommands
     ///     <para/><para/><para/>
     /// </example>
     /// </summary>
-    [Cmdlet(VerbsCommon.Get, "PlatformItem")]
+    [Cmdlet(VerbsCommon.Get, "PlatformItem", DefaultParameterSetName = "ByFQID")]
     [OutputType(typeof(Item))]
     [RequiresVmsConnection()]
     public class GetPlatformItem : ConfigApiCmdlet
     {
         /// <summary>
         /// <para type="description">VideoOS.Platform.FQID of a Milestone configuration Item</para>
         /// </summary>
-        [Parameter(Position = 1, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true, ParameterSetName = "ByFQID")]
+        [Parameter(Mandatory = true, Position = 1, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true, ParameterSetName = "ByFQID")]
         public FQID Fqid { get; set; }
 
         /// <summary>
@@ -64,7 +64,7 @@ public class GetPlatformItem : ConfigApiCmdlet
         /// <summary>
         /// <para type="description">Specifies the GUID constant for the Kind of object you want to return</para>
         /// </summary>
-        [Parameter(Position = 1, ValueFromPipeline = true, ParameterSetName = "ByKind")]
+        [Parameter(Mandatory = true, Position = 1, ParameterSetName = "ByKind")]
         [ArgumentCompleter(typeof(KindArgumentCompleter))]
         [KindNameTransform()]
         public Guid Kind { get; set; }
@@ -125,7 +125,7 @@ protected override void ProcessRecord()
                 {
                     WriteError(
                         new ErrorRecord(
-                            new MIPException($"GetItemsBySearch failed: {result.ToString()}"),
+                            new MIPException($"GetItemsBySearch failed: {result}"),
                             "GetItemsBySearch Failed",
                             ErrorCategory.InvalidResult,
                             null));

src/MilestonePSTools/Utility/KindNameTransformAttribute.cs

@@ -17,7 +17,9 @@
 using System.Linq;
 using System.Management.Automation;
 using System.Reflection;
+using System.Text.RegularExpressions;
 using VideoOS.Platform;
+using VideoOS.Platform.Messaging;
 
 namespace MilestonePSTools.Utility
 {
@@ -33,6 +35,11 @@ public KindNameTransformAttribute()
 
         public override object Transform(EngineIntrinsics engineIntrinsics, object inputData)
         {
+            if (inputData is PSObject psobject)
+            {
+                inputData = psobject.ImmediateBaseObject;
+            }
+
             if (inputData is Guid guid)
             {
                 if (!Kind.DefaultTypeToNameTable.ContainsKey(guid))
@@ -42,6 +49,16 @@ public override object Transform(EngineIntrinsics engineIntrinsics, object input
                 return guid;
             }
 
+            if (inputData is FQID fqid)
+            {
+                return fqid.Kind;
+            }
+
+            if (inputData is ItemState itemState)
+            {
+                return itemState.FQID.Kind;
+            }
+
             if (inputData is string kindName)
             {
                 return ConvertToGuid(kindName);
@@ -61,6 +78,15 @@ public override object Transform(EngineIntrinsics engineIntrinsics, object input
 
         private Guid ConvertToGuid(string kindName)
         {
+            // Input is a guid in string format
+            if (Guid.TryParse(kindName, out var parsedGuid)) return parsedGuid;
+
+            // Input is FQID.ToString()
+            var match = Regex.Match(kindName, @"Type:(?<id>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$");
+            if (match.Success)
+            {
+                return Guid.Parse(match.Groups["id"].Value);
+            }
             var field = _fields.SingleOrDefault(f => f.FieldType == typeof(Guid) && f.Name.Equals(kindName, StringComparison.OrdinalIgnoreCase));
             if (field == null)
             {