about_Types.ps1xml

TOPIC
	about_Types.ps1xml

SHORT DESCRIPTION
	Explains how the Types.ps1xml files let you extend the Microsoft .NET 
	Framework types of the objects that are used in Windows PowerShell. 

LONG DESCRIPTION
	The Types.ps1xml file in the Windows PowerShell installation directory
	($pshome) is an XML-based text file that lets you add properties and 
	methods to the objects that are used in Windows PowerShell. Windows 
	PowerShell has a built-in Types.ps1xml file that adds several elements
	to the .NET Framework types, but you can create additional Types.ps1xml
	files to further extend the types.

	For example, by default, array objects (System.Array) have a Length 
	property that lists the number of objects in the array. However, because
	the name "length" does not clearly describe the property, Windows 
	PowerShell adds an alias property named "Count" that displays the same 
	value. The following XML adds the Count property to the System.Array type.

		<Type>
			<Name>System.Array</Name>
			<Members>
				<AliasProperty>
					<Name>Count</Name>
					<ReferencedMemberName>
						Length
					</ReferencedMemberName>
				</AliasProperty>
			</Members>
		</Type>

	To get the new AliasProperty, use a Get-Member command on any array, as shown
	in the following example.

		Get-Member -inputobject (1,2,3,4)


	The command returns the following results.

		Name		 MemberType	Definition
		----		 ----------	----------
		Count		AliasProperty Count = Length
		Address		Method		System.Object& Address(Int32 )
		Clone		Method		System.Object Clone()
		CopyTo		 Method		System.Void CopyTo(Array array, Int32 index):
		Equals		 Method		System.Boolean Equals(Object obj)
		Get			Method		System.Object Get(Int32 )
		...


	As a result, you can use either the Count property or the Length property 
	of arrays in Windows PowerShell. For example:

		C:\PS> (1, 2, 3, 4).count
		4

		C:\PS> (1, 2, 3, 4).length
		4
 

  Creating New Types.ps1xml Files

	The .ps1xml files that are installed with Windows PowerShell are 
	digitally signed to prevent tampering because the formatting can include
	script blocks. Therefore, to add a property or method to a .NET Framework
	type, create your own Types.ps1xml files, and then add them to your 
	Windows PowerShell console.

	To create a new file, start by copying an existing Types.ps1xml file. The
	new file can have any name, but it must have a .ps1xml file name 
	extension. You can place the new file in any directory that is accessible
	to Windows PowerShell, but it is useful to place the files in the Windows
	PowerShell installation directory ($pshome) or in a subdirectory of the 
	installation directory.

	When you have saved the new file, use the Update-TypeData cmdlet to add 
	the new file to your Windows PowerShell console. If you want your types
	to take precedence over the types that are defined in the built-in file,
	use the PrependData parameter of the Update-TypeData cmdlet. 
	Update-TypeData affects only the current console. To make the change to
	all future consoles, export the console, or add the Update-TypeData 
	command to your Windows PowerShell profile.


  Types.ps1xml and Add-Member

	The Types.ps1xml files add properties and methods to all the instances 
	of the objects of the specified .NET Framework type in the affected 
	Windows PowerShell console. However, if you need to add properties or 
	methods only to one instance of an object, use the Add-Member cmdlet.

	For more information,see Add-Member.


  Example: Adding an Age Member to FileInfo Objects

	This example shows how to add an Age property to file objects 
	(System.IO.FileInfo). The age of a file is the difference between
	its creation time and the current time in days.

	It is easiest to use the original Types.ps1xml file as a template
	for the new file. The following command copies the original file to
	a file called MyTypes.ps1xml in the $pshome directory.

		copy-item Types.ps1xml MyTypes.ps1xml


	Next, open the Types.ps1xml file in any XML or text editor, such
	as Notepad. Because the Age property is calculated by using a script
	block, find a <ScriptProperty> tag to use as a model for the new Age 
	property. 

	Copy the XML between the <Type> and </Type> tags of the code to create
	the script property. Then, delete the remainder of the file, except for 
	the opening <?xml> and <Types> tags and the closing </Types> tag. You 
	must also delete the digital signature to prevent errors.

	Begin with the model script property, such as the following script 
	property, which was copied from the original Types.ps1xml file.

		<?xml version="1.0" encoding="utf-8" ?>
		<Types>
			<Type>
				 <Name>System.Guid</Name>
					<Members>
						<ScriptProperty>
							<Name>Guid</Name>
							<GetScriptBlock>$this.ToString()</GetScriptBlock>
						</ScriptProperty>
					</Members>
			</Type>
		</Types>


	Then, change the name of the .NET Framework type, the name of the 
	property, and the value of the script block to create an Age property 
	for file objects.


		<?xml version="1.0" encoding="utf-8" ?>
		<Types>
			<Type>
				 <Name>System.IO.FileInfo</Name>
					<Members>
						<ScriptProperty>
							<Name>Age</Name>
							<GetScriptBlock>
							 ((get-date) - ($this.creationtime)).days
							</GetScriptBlock>
						</ScriptProperty>
					</Members>
			</Type>
		</Types>


	After you save the file and close it, use an Update-TypeData command,
	such as the following command, to add the new Types.ps1xml file to the
	current console. The command uses the PrependData parameter to place the
	new file in a higher precedence order than the original file. (For more
	information about Update-TypeData, see Update-TypeData.)

		update-typedata -prependpath $pshome\MyTypes.ps1xml

	To test the change, use a Get-ChildItem command to get the 
	PowerShell.exe file in the $pshome directory, and then pipe the file to
	the Format-List cmdlet to list all of the properties of the file. As a 
	result of the change, the Age property appears in the list.

		get-childitem $pshome\powershell.exe | format-list -property *  


		PSPath			: Microsoft.PowerShell.Core\FileSystem::C:\WINDOWS...
		PSParentPath	: Microsoft.PowerShell.Core\FileSystem::C:\WINDOWS...
		PSChildName	 : powershell.exe
		PSDrive		 : C
		PSProvider		: Microsoft.PowerShell.Core\FileSystem
		PSIsContainer	 : False
		Age			 : 16
		VersionInfo	 : File:			 C:\WINDOWS\system32\WindowsPow...
					InternalName:	 POWERSHELL
					OriginalFilename: PowerShell.EXE
		...


	You can also display the Age property of the file by using the following
	command.

		(get-childitem $pshome\powershell.exe).age
		16
 

  The XML in Types.ps1xml Files

	The <Types> tag encloses all of the types that are defined in the file.
	There should be only one pair of <Types> tags.

	Each .NET Framework type mentioned in the file should be represented by 
	a pair of <Type> tags. 

	The type tags must contain the following tags:

		<Name>: A pair of <Name> tags that enclose the name of the affected 
				.NET Framework type.

		<Members>: A pair of <Members> tags that enclose the tags for the 
					 new properties and methods that are defined for the
					 .NET Framework type.

	Any of the following member tags can be inside the <Members> tags.

	<AliasProperty>: Defines a new name for an existing property.

		 The <AliasProperty> tag must have a pair of <Name> tags that specify
		 the name of the new property and a pair of <ReferencedMemberName> tags
		 that specify the existing property.	 
		
		 For example, the Count alias property is an alias for the Length	 
		 property of array objects.

			 <Type>
				 <Name>System.Array</Name>
				 <Members>
					 <AliasProperty>
						 <Name>Count</Name>
						 <ReferencedMemberName>Length</ReferencedMemberName>
					 </AliasProperty>
				 </Members>
			 </Type>


	<CodeMethod>:  References a static method of a .NET Framework class.

		 The <CodeMethod> tag must have a pair of <Name> tags that specify
		 the name of the new method and a pair of <GetCodeReference> tags
		 that specify the code in which the method is defined.	 
		
		 For example, the Mode property of directories (System.IO.DirectoryInfo
		 objects) is a code property defined in the Windows PowerShell 
		 FileSystem provider.
	
			 <Type>
				 <Name>System.IO.DirectoryInfo</Name>
				 <Members>
					 <CodeProperty>
						<Name>Mode</Name>
						<GetCodeReference>
						 <TypeName>Microsoft.PowerShell.Commands.FileSystemProvider</TypeName>
						 <MethodName>Mode</MethodName>
						</GetCodeReference>
					 </CodeProperty>
				 </Members>
			 </Type>

 
	<CodeProperty>: References a static method of a .NET Framework class.

		 The <CodeProperty> tag must have a pair of <Name> tags that specify
		 the name of the new property and a pair of <GetCodeReference> tags
		 that specify the code in which the property is defined.	 
		
		 For example, the Mode property of directories (System.IO.DirectoryInfo
		 objects) is a code property defined in the Windows PowerShell 
		 FileSystem provider.
	
			 <Type>
				 <Name>System.IO.DirectoryInfo</Name>
				 <Members>
					 <CodeProperty>
						<Name>Mode</Name>
						<GetCodeReference>
						 <TypeName>Microsoft.PowerShell.Commands.FileSystemProvider</TypeName>
						 <MethodName>Mode</MethodName>
						</GetCodeReference>
					 </CodeProperty>
				 </Members>
			 </Type>


	<MemberSet>: Defines a collection of members (properties and methods). 

		 The <MemberSet> tags appear within the primary <Members> tags. The 
		 tags must enclose a pair of <Name> tags surrounding the name of the
		 member set and a pair of secondary <Members> tags that surround the 
		 members (properties and methods) in the set. Any of the tags that 
		 create a property (such as <NoteProperty> or <ScriptProperty>) or a
		 method (such as <Method> or <ScriptMethod>) can be members of the set.

		 In Types.ps1xml files, the <MemberSet> tag is used to define the 
		 default views of the .NET Framework objects in Windows PowerShell. In
		 this case, the name of the member set (the value within the <Name> 
		 tags) is always "PsStandardMembers", and the names of the properties
		 (the value of the <Name> tag) are one of the following:

			- DefaultDisplayProperty: A single property of an object.

			- DefaultDisplayPropertySet: One or more properties of an object.

			- DefaultKeyPropertySet: One or more key properties of an object. 
			A key property identifies instances of property values, such as
			the ID number of items in a session history.

		 For example, the following XML defines the default display of services
		 (System.ServiceProcess.ServiceController objects) that are returned by
		 the Get-Service cmdlet. It defines a member set named 
		 "PsStandardMembers" that consists of a default property set with the 
		 Status, Name, and DisplayName properties.

			 <Type>
				<Name>System.ServiceProcess.ServiceController</Name>
				<Members>
				 <MemberSet>
					 <Name>PSStandardMembers</Name>
					 <Members>
						 <PropertySet>
							 <Name>DefaultDisplayPropertySet</Name>
							 <ReferencedProperties>
								<Name>Status</Name>
								<Name>Name</Name>
								<Name>DisplayName</Name>
							 </ReferencedProperties>
						 </PropertySet>
					 </Members>
				 </MemberSet>
				</Members>
			 </Type>

   
	<Method>: References a native method of the underlying object. 

	<Methods>: A collection of the methods of the object.

	<NoteProperty>: Defines a property with a static value.

		 The <NoteProperty> tag must have a pair of <Name> tags that specify
		 the name of the new property and a pair of <Value> tags that specify
		 the value of the property.	 
		
		 For example, the following XML creates a Status property for 
		 directories (System.IO.DirectoryInfo objects). The value of the 
		 Status property is always "Success".

			 <Type>
				 <Name>System.IO.DirectoryInfo</Name>
				 <Members>
					 <NoteProperty>
						<Name>Status</Name>
						<Value>Success</Value>
					 </NoteProperty>
				 </Members>
			 </Type>


	<ParameterizedProperty>: Properties that take arguments and return a 
							 value.

	<Properties>: A collection of the properties of the object.

	<Property>: A property of the base object.

	<PropertySet>: Defines a collection of properties of the object.

		 The <PropertySet> tag must have a pair of <Name> tags that specify
		 the name of the property set and a pair of <ReferencedProperty> tags
		 that specify the properties. The names of the properties are enclosed
		 in <Name> tag pairs.	 

		 In Types.ps1xml, <PropertySet> tags are used to define sets of 
		 properties for the default display of an object. You can identify the
		 default displays by the value "PsStandardMembers" in the <Name> tag 
		 of a <MemberSet> tag.
		
		 For example, the following XML creates a Status property for 
		 directories (System.IO.DirectoryInfo objects). The value of the Status
		 property is always "Success".

			 <Type>
				 <Name>System.ServiceProcess.ServiceController</Name>
				 <Members>
					 <MemberSet>
						 <Name>PSStandardMembers</Name>
						 <Members>
							 <PropertySet>
								 <Name>DefaultDisplayPropertySet</Name>
								 <ReferencedProperties>
									 <Name>Status</Name
									 <Name>Name</Name>
									 <Name>DisplayName</Name>
								 </ReferencedProperties>
							 </PropertySet>
						 <Members>
					 <MemberSet>
				 <Members>
			 <Type>


	 <ScriptMethod>: Defines a method whose value is the output of a script.

		 The <ScriptMethod> tag must have a pair of <Name> tags that specify
		 the name of the new method and a pair of <Script> tags that enclose
		 the script block that returns the method result.	 
		
		 For example, the ConvertToDateTime and ConvertFromDateTime methods of 
		 management objects (System.System.Management.ManagementObject) are
		 script methods that use the ToDateTime and ToDmtfDateTime static 
		 methods of the System.Management.ManagementDateTimeConverter class. 

			 <Type>
				 <Name>System.Management.ManagementObject</Name>
				 <Members>
					 <ScriptMethod>
						 <Name>ConvertToDateTime</Name>
						 <Script>
							 [System.Management.ManagementDateTimeConverter]::ToDateTime($args[0])
						 </Script>
					 </ScriptMethod>
					 <ScriptMethod>
						 <Name>ConvertFromDateTime</Name>
						 <Script>
							 [System.Management.ManagementDateTimeConverter]::ToDmtfDateTime($args[0])
						 </Script>
					 </ScriptMethod>
				 </Members>
			 </Type>


	<ScriptProperty>: Defines a property whose value is the output of a 
						script.

		 The <ScriptProperty> tag must have a pair of <Name> tags that specify
		 the name of the new property and a pair of <GetScriptBlock> tags
		 that enclose the script block that returns the property value.	 
		
		 For example, the VersionInfo property of files (System.IO.FileInfo
		 objects) is a script property that results from using the FullName 
		 property of the GetVersionInfo static method of 
		 System.Diagnostics.FileVersionInfo objects.

			 <Type>
				<Name>System.IO.FileInfo</Name>
				<Members>
					<ScriptProperty>
					 <Name>VersionInfo</Name>
					 <GetScriptBlock>
						 [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName)
					 </GetScriptBlock>
					</ScriptProperty>   
				</Members>
			 </Type>


	For more information, see the Windows PowerShell Software Development 
	Kit (SDK) in the MSDN (Microsoft Developer Network )library 
	at http://go.microsoft.com/fwlink/?LinkId=144538.


  Update-TypeData

	To load your Types.ps1xml files into a Windows PowerShell console, use
	the Update-TypeData cmdlet. If you want the types in your file to take
	precedence over types in the built-in Types.ps1xml file, use the 
	PrependData parameter of Update-TypeData. Update-TypeData affects only 
	the current console. To make the change to all future consoles, export
	the console, or add the Update-TypeData command to your Windows 
	PowerShell profile.


  Signing a Types.ps1xml File

	To protect users of your Types.ps1xml file, you can sign the file using
	a digital signature. For more information, see about_Signing.
	

SEE ALSO
	about_Signing
	Copy-Item
	Get-Member
	Update-TypeData