Citrix Virtual Apps and Desktops SDK

Get-HypInventoryItem

March 11, 2024

Contributed by:

Gets the resource items and child items from specified inventory locations using the resource type and a set of filtering and pagination parameters.

Syntax

Get-HypInventoryItem
   -ResourceType <String>
   [-ContinuationToken <String>]
   [-MaxRecords <Int32>]
   [-Skip <Int32>]
   [-ContainsName <String>]
   [-ForwardDirection <Boolean>]
   [-Tags <String>]
   [-Id <String>]
   [-AdditionalDataFilter <String>]
   [-Template <String>]
   [-Warn <Boolean>]
   [-Force <Boolean>]
   [-LiteralPath] <String>
   [<CitrixCommonParameters>]
   [<CommonParameters>]
<!--NeedCopy-->

Description

The `Get-HypInventoryItem` cmdlet gets the resource items and child items from specified inventory locations using the resource type and a set of filtering and pagination parameters.

`Get-HypInventoryItem` requires a Hosting Unit path and the ResourceType parameter. The ResourceType specifies the resource extension, such as `template`, `vm`, etc.

Optional parameters control how many items to return, where to start the list of items and how to filter items so that only a subset are returned.

Examples

EXAMPLE 1

Gets the first template resource from the ctx-test Hosting Unit

PS C:\Users\admin> Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType vm
          

AdditionalData : {[ServiceOfferingDescription, T3 Micro Instance], [TenancyType, Shared], [NetworkMappings,
                 [[["subnet-074242d7489b7209e","us-east-1a.availabilityzone\\10.0.128.0/17
                 (vpc-0fa6e41d72507f877).network"]]]], [SecurityGroups, ["private.securitygroup"]]...}
FullName       : aws-test-non-persistent-vda-win2022 (i-0d2abbcbc89876ed2).vm
FullPath       :
Id             : i-0d2abbcbc89876ed2
IsContainer    : False
IsMachine      : True
IsSnapshotable : True
IsSymLink      : False
Name           : aws-test-non-persistent-vda-win2022 (i-0d2abbcbc89876ed2)
ObjectPath     : /aws-test-non-persistent-vda-win2022 (i-0d2abbcbc89876ed2).vm
ObjectType     : Vm
ObjectTypeName : vm

PS C:\Users\admin> Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template


Description             : Canonical, Ubuntu, 16.04 LTS, amd64 xenial image build on 2019-06-28
HasPersistentRootVolume : True
IsWindowsTemplate       : True
Owner                   : 679593333241
AdditionalData          : {[BlockDeviceCount, 1], [EnaSupport, True], [HibernationSupported, False], [Warning, Unable
                          to find snapshot or instance for AMI;]...}
FullName                : ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-20190628-d83d0782-cb94-
                          46d7-8993-f4ce15d1a484-ami-0cfee17793b08a293.4 (ami-021d9d94f93a07a43).template
FullPath                :
Id                      : ami-021d9d94f93a07a43
IsContainer             : False
IsMachine               : False
IsSnapshotable          : False
IsSymLink               : False
Name                    : ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-20190628-d83d0782-cb94-
                          46d7-8993-f4ce15d1a484-ami-0cfee17793b08a293.4 (ami-021d9d94f93a07a43)
ObjectPath              : /ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-20190628-d83d0782-cb94
                          -46d7-8993-f4ce15d1a484-ami-0cfee17793b08a293.4 (ami-021d9d94f93a07a43).template
ObjectType              : Template
ObjectTypeName          : template

PS C:\Users\admin> Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType template -ContainName persistent | select Name

Name
----
test-non-persistent-vda-win2022 (ami-0a2d913927e0352f3)

PS C:\Users\admin> Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType vm -MaxRecords 100 | select Name

Name
----
test-non-persistent-vda-win2022 (i-0f33601c7439a81aa)
test-Automation (i-021f404ff81e4b3b3)
test-non-persistent-vda-win2022-2 (i-0821ca8ba8c3d171c)
test-Bastion (i-026182c752bd20329)
test-AD (i-09dcfc3180ac723ea)
test-non-persistent-hibernation-vda-win2022 (i-02747245f4fd643e6)
test-Ubuntu-MP-test (i-0f311930f6509955b)
test-persistent-vda (i-00c55f1107b662c04)
aws-test-non-persistent-vda-win2022 (i-0d2abbcbc89876ed2)

PS C:\Users\admin> Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType vm -MaxRecords 100 -Skip 2 | select Name

Name
----
test-non-persistent-vda-win2022-2 (i-0821ca8ba8c3d171c)
test-Bastion (i-026182c752bd20329)
test-AD (i-09dcfc3180ac723ea)
test-non-persistent-hibernation-vda-win2022 (i-02747245f4fd643e6)
test-Ubuntu-MP-test (i-0f311930f6509955b)
test-persistent-vda (i-00c55f1107b662c04)
aws-test-non-persistent-vda-win2022 (i-0d2abbcbc89876ed2)
<!--NeedCopy-->

EXAMPLE 2

This will return first 100 launch template versions in that hosting unit.

PS C:\Users\admin> Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\ctx-test" -MaxRecords 100
<!--NeedCopy-->

EXAMPLE 3

This will return 100 launch template versions after skipping first 100 in that hosting unit.

PS C:\Users\admin> Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\ctx-test" -MaxRecords 100 -Skip 100
<!--NeedCopy-->

EXAMPLE 4

Examples of Additional Data returned for launch template version and different filters and Parameters.

PS C:\Users\admin> $items = Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\ctx-test" -MaxRecords 200
PS C:\Users\admin> $items[0].AdditionalData
Key                        Value
---                        -----
ServiceOfferingDescription T3 Large Instance
TenancyType                Shared
HibernationSupported       False
NetworkMappings            [[["subnet-074242d7489b7209e","us-east-1a.availabilityzone\\10.0.128.0/17 (vpc-0fa6e41d72507f877).network"]]]
SecurityGroups             ["private.securitygroup"]
PositionAndCount           {"Item1":1,"Item2":1}
Hypervisor                 nitro
TotalItemsCount            29
TotalFilteredItemsCount    29
Tags                       {"user":["test-user"]}

PS C:\Users\admin> $items[5].AdditionalData
Key                        Value
---                        -----
ServiceOfferingDescription T3 Small Instance
TenancyType                Shared
HibernationSupported       False
NetworkMappings            [[["subnet-074242d7489b7209e","us-east-1a.availabilityzone\\10.0.128.0/17 (vpc-0fa6e41d72507f877).network"]],[["subnet-074242d7489b7209e","us-east-1a.availabilityzone\\10.0.128.0/17 (vpc-0fa6e41d72507f877).network"]]]
SecurityGroups             ["private.securitygroup"]
PositionAndCount           {"Item1":2,"Item2":12}
Hypervisor                 nitro

PS C:\Users\admin> $items = Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\ctx-test" -MaxRecords 200 -Template "ami-01548d6ca90670e7e" -Warn $true
PS C:\Users\admin> $items[3].AdditionalData
Key Value
--- -----
ServiceOfferingDescription T2 Medium Instance
TenancyType Shared
HibernationSupported False
PositionAndCount {"Item1":1,"Item2":1}
Hypervisor xen
Warning Block device count mismatch;


PS C:\Users\admin>  Get-HypInventoryItem -ResourceType "launchtemplateversion" -LiteralPath "XDHyp:\HostingUnits\ctx-test" -MaxRecords 5 -Warn $true -AdditionalDataFilter "{'Hypervisor' : 'nitro'}" | Select Name
Name
----
lt-0bb652503d45dcbcd (9)
lt-0e1146edd2bbd3d18 (1)
lt-0e1146edd2bbd3d18 (2)
lt-0e1146edd2bbd3d18 (3)
lt-0e1146edd2bbd3d18 (4)
<!--NeedCopy-->

EXAMPLE 5

Examples of Additional Data return for snapshot data type with different filtering parameters. Note: Tags and Custom Attributes both are used in -Tags parameter. The first element in AdditionalData will list all possbile Tag values.

PS C:\Users\admin> $items = Get-HypInventoryItem -LiteralPath "XDHyp:\HostingUnits\ctx-test" -ResourceType "snapshot" -MaxRecords 10
PS C:\Users\admin> $items[0].AdditionalData

Key                     Value
---                     -----
GuestOsId               windows2022srvNext_64Guest
TotalItemsCount         47
TotalFilteredItemsCount 47
Tags                    {"Tag_1": ["Category_1]", "Custom_Attribute": ["Custom_Attribute_Value_1", "Custom_Attribute_Value_2"]}



PS C:\Users\admin> $items = Get-HypInventoryItem -LiteralPath 'XDHyp:\HostingUnits\ctx-test' -ResourceType "snapshot" -MaxRecords 10 -Tags '{ "Tag_1": "Category_1", "Custom_Attribute": "Custom_Attribute_Value_1" }' -AdditionalDataFilter '{"GuestOsId": "windows2022srvNext_64Guest"}' | Select Name

Name
----
VMSnapshot20

PS C:\Users\admin> $items[0].AdditionalData

Key                     Value
---                     -----
GuestOsId               windows2022srvNext_64Guest
TotalItemsCount         47
TotalFilteredItemsCount 1
Tags                    {"Tag_1": ["Category_1]", "Custom_Attribute": ["Custom_Attribute_Value_1", "Custom_Attribute_Value_2"]}
<!--NeedCopy-->

Parameters

-LiteralPath

This specifies the XDHyp:\ path to the Hosting Unit for the inventory to use. This parameter is required.

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-ResourceType

This parameter specifies the type of the resources to return. This is a required parameter and corresponds to the resource Name extension, such as `template`, `vm`, ‘launchtemplateversion’ (only supported in AWS), or ‘snapshot’ (only supported in VMware).

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-ContinuationToken

This parameter controls where to start including items from the inventory. This is usually the `Id` of an item and the included items begin after the given item is found.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-MaxRecords

The maximum number of items to return for the given call of the cmdlet. The default is to return one item.

Type:	Int32
Position:	Named
Default value:	1
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	False

-Skip

Skips the specified number of records before returning results. Also reduces the count returned by -ReturnTotalRecordCount.

Type:	Int32
Position:	Named
Default value:	0
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	False

-ContainsName

This parameter filters items so that only the ones containing the given string in the `Name` are included.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-ForwardDirection

Specifies whether the items are returned in forward page order (the default) or reverse.

Type:	Boolean
Position:	Named
Default value:	True
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	False

-Tags

This parameter specifies a JSON dictionary where the keys are the tag names and the values are the tag values. The parameter is used to filter items which have the given tags. An item must have all the given tags to match. Special values of `Not tagged` and `All values` are supported. For VMware, refer for additional usage details.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-Id

This parameter returns a single item with the given Identifier.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-AdditionalDataFilter

This specifies a JSON dictionary of parameters to use in filtering resources using the AdditionalData properties. All values given must match for an item to be included.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-Template

This parameter is used for the Machine Profile ResourceTypes only. It specifies a Template identifier or name to use in validation of the Machine Profile with the given Template. The validation will pass if the given Machine Profile resource is compatible with the given Template. Only Machine Profiles which pass this validation are included.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	True

-Warn

This parameter is used for along with any validation filtering parameter (such as TemplateId). It specifies that rather than excluding the items which failed validation, the item is included but with a Warning property added to the AdditionalData. This property carries a string which describes the reason for validation failure.

Type:	Boolean
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	False

-Force

Specifies whether to return the full list of items or whether to exclude the items created as part of Machine Creation Services. The default behavior is to exclude the MCS created items.

Type:	Boolean
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	True (ByValue)
Accept wildcard characters:	False

CitrixCommonParameters

This cmdlet supports the common Citrix parameters: -AdminAddress, -AdminClientIP, -BearerToken, -TraceParent, -TraceState and -VirtualSiteId. For more information, see about_CitrixCommonParameters.

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.

Inputs

None

You can’t pipe objects to this cmdlet.

Outputs

PSObject

A list of inventory items which are found in the given Hosting Unit inventory of the given ResourceType and matching any optional filtering parameters. As a convenience the first item of the list contains AdditionalData fields for `TotalItemsCount`, `TotalFilteredItemsCount` and `Tags`. These fields provide the counts of all the items of the ResourceType in the inventory, the set of items which would match the filters and a set of tags which may be used to filter the items, respectively.

Notes

For filtering in VMware, Tag’s name is treated as the key and its category name as the value. Apart from Tags, VMware also has Custom Attributes which are key-value pair based metadata for the resources. Both of them can be applied to filtering using `-Tags` parameter.

In VMware, snapshots don’t have tags or custom attributes of their own. So, these values are fetched from their parent VMs.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Get-HypInventoryItem

March 11, 2024

Contributed by:

March 11, 2024

Contributed by:

Get-HypInventoryItem

Syntax

Description

Examples

EXAMPLE 1

EXAMPLE 2

EXAMPLE 3

EXAMPLE 4

EXAMPLE 5

Parameters

-LiteralPath

-ResourceType

-ContinuationToken

-MaxRecords

-Skip

-ContainsName

-ForwardDirection

-Tags

-Id

-AdditionalDataFilter

-Template

-Warn

-Force

CitrixCommonParameters

CommonParameters

Inputs

None

Outputs

PSObject

Notes

Related Links

In this article