diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md index f88896937c50..f05531a2ccb2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Classes.md @@ -1,7 +1,7 @@ --- description: Describes how you can use classes to create your own custom types. Locale: en-US -ms.date: 01/19/2024 +ms.date: 01/22/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Classes @@ -64,18 +64,17 @@ To instantiate an instance of a class, use one of the following syntaxes: ``` ```Syntax -[$ =] []@{[]} +[$ =] [] ``` > [!NOTE] > When using the `[]::new()` syntax, brackets around the class name > are mandatory. The brackets signal a type definition for PowerShell. > -> The hashtable syntax only works for classes that have a default constructor -> that doesn't expect any parameters. It creates an instance of the class with -> the default constructor and then assigns the key-value pairs to the instance -> properties. If any key in the hashtable isn't a valid property name, -> PowerShell raises an error. +> The `` syntax only works for classes that have a +> default constructor that doesn't expect any parameters. It creates an +> instance of the class with the default constructor and then uses runtime type +> conversion to assign the values provided. ## Examples @@ -99,7 +98,67 @@ Brand Fabrikam, Inc. ``` -### Example 2 - Class with instance members +### Example 2 - Using instantiation syntax + +This example defines a **Book** class with several properties, but no +constructor. + +```powershell +class Book { + # Class properties + [string] $Title + [string] $Author + [string] $Synopsis + [string] $Publisher + [datetime] $PublishDate + [int] $PageCount + [string[]] $Tags +} +``` + +The following example shows how the default constructor can assign the values +from a compatible value using type coercion. In this example, a hashtable is +used to provide the property values. + +```powershell +$Book1 = [Book] @{ + Title = '1984' + Author = 'George Orwell' + Synopsis = '' + Publisher = 'Secker & Warburg' + PublishDate = '1949-06-08' + PageCount = 328 + Tags = @('Dystopian', 'Political Fiction', 'Social Science Fiction') +} +$Book1 +``` + +```Output +Title : 1984 +Author : George Orwell +Synopsis : +Publisher : Secker & Warburg +PublishDate : 6/8/1949 12:00:00 AM +PageCount : 328 +Tags : {Dystopian, Political Fiction, Social Science Fiction} +``` + +The key-value pairs of the hashtable are assigned to the instance properties. +If any key in the hashtable isn't a valid property name, instantiation fails. + +In this example, an array is used to provide the values for the generic list. + +```powershell +$List = [System.Collections.Generic.List[int]] @(42, 43) +$List +``` + +```Output +42 +43 +``` + +### Example 3 - Class with instance members This example defines a **Book** class with several properties, constructors, and methods. Every defined member is an _instance_ member, not a static member. @@ -190,12 +249,12 @@ It takes 10 hours and 20 minutes to read The Hobbit by J.R.R. Tolkien (1937), which was published 86 years ago. ``` -### Example 3 - Class with static members +### Example 4 - Class with static members -The **BookList** class in this example builds on the **Book** class in example -2. While the **BookList** class can't be marked static itself, the -implementation only defines the **Books** static property and a set of static -methods for managing that property. +The **BookList** class in this example builds on the **Book** class in the +previous example. While the **BookList** class can't be marked static itself, +the implementation only defines the **Books** static property and a set of +static methods for managing that property. ```powershell class BookList { @@ -369,7 +428,7 @@ Properties are variables declared in the class scope. A property can be of any built-in type or an instance of another class. Classes can have zero or more properties. Classes don't have a maximum property count. -For more information, see [about_Classes_Properties][01]. +For more information, see [about_Classes_Properties][10]. ## Class methods @@ -379,7 +438,7 @@ method doesn't return any output, it must have the **Void** output type. If a method doesn't explicitly define an output type, the method's output type is **Void**. -For more information, see [about_Classes_Methods][02]. +For more information, see [about_Classes_Methods][05]. ## Class constructors @@ -388,7 +447,7 @@ moment of creating the instance of the class. Constructors have the same name as the class. Constructors might have parameters, to initialize the data members of the new object. -For more information, see [about_Classes_Constructors][03]. +For more information, see [about_Classes_Constructors][01]. ## Hidden keyword @@ -417,11 +476,11 @@ Hidden class members are: > When you hide any constructor, the `new()` option is removed from > IntelliSense and completion results. -For more information about the keyword, see [about_Hidden][04]. For more -information about hidden properties, see [about_Classes_Properties][05]. For +For more information about the keyword, see [about_Hidden][12]. For more +information about hidden properties, see [about_Classes_Properties][09]. For more information about hidden methods, see [about_Classes_Methods][06]. For more information about hidden constructors, see -[about_Classes_Constructors][07]. +[about_Classes_Constructors][02]. ## Static keyword @@ -435,9 +494,9 @@ available always. All static properties live for the entire session span. The `static` keyword only applies to class members, not a class itself. For more information about static properties, see -[about_Classes_Properties][08]. For more information about static methods, see -[about_Classes_Methods][09]. For more information about static constructors, -see [about_Classes_Constructors][10]. +[about_Classes_Properties][10]. For more information about static methods, see +[about_Classes_Methods][07]. For more information about static constructors, +see [about_Classes_Constructors][03]. ## Inheritance in PowerShell classes @@ -453,8 +512,7 @@ inherits from an interface must implement that contract. When it does, the class can be used like any other class implementing that interface. For more information about deriving classes that inherit from a base class or -implement interfaces, see -[about_Classes_Inheritance][11]. +implement interfaces, see [about_Classes_Inheritance][04]. ## Export classes with type accelerators @@ -540,7 +598,7 @@ consistently import classes defined in nested modules or classes defined in scripts that are dot-sourced into the root module. Define classes that you want to be available to users outside of the module directly in the root module. -For more information about the `using` statement, see [about_Using][12]. +For more information about the `using` statement, see [about_Using][15]. ## Load newly changed code during development @@ -567,7 +625,7 @@ parameters can't be used with class members. The **PSReference** class was designed to support COM objects. COM objects have cases where you need to pass a value in by reference. -For more information, see [PSReference Class][13]. +For more information, see [PSReference Class][16]. ## Limitations @@ -681,30 +739,30 @@ workaround for those limitations, if any. ## See also -- [about_Classes_Constructors][03] -- [about_Classes_Inheritance][11] -- [about_Classes_Methods][02] -- [about_Classes_Properties][01] -- [about_Enum][14] -- [about_Hidden][04] -- [about_Language_Keywords][15] -- [about_Methods][16] -- [about_Using][12] +- [about_Classes_Constructors][01] +- [about_Classes_Inheritance][04] +- [about_Classes_Methods][05] +- [about_Classes_Properties][08] +- [about_Enum][11] +- [about_Hidden][12] +- [about_Language_Keywords][13] +- [about_Methods][14] +- [about_Using][15] -[01]: about_Classes_Properties.md -[02]: about_Classes_Methods.md -[03]: about_Classes_Constructors.md -[04]: about_Hidden.md -[05]: about_Classes_Properties.md#hidden-properties +[01]: about_Classes_Constructors.md +[02]: about_Classes_Constructors.md#hidden-constructors +[03]: about_Classes_Constructors.md#static-constructors +[04]: about_Classes_Inheritance.md +[05]: about_Classes_Methods.md [06]: about_Classes_Methods.md#hidden-methods -[07]: about_Classes_Constructors.md#hidden-constructors -[08]: about_Classes_Properties.md#static-properties -[09]: about_Classes_Methods.md#static-methods -[10]: about_Classes_Constructors.md#static-constructors -[11]: about_Classes_Inheritance.md -[12]: about_Using.md -[13]: /dotnet/api/system.management.automation.psreference -[14]: about_Enum.md -[15]: about_language_keywords.md -[16]: about_methods.md +[07]: about_Classes_Methods.md#static-methods +[08]: about_Classes_Properties.md +[09]: about_Classes_Properties.md#hidden-properties +[10]: about_Classes_Properties.md#static-properties +[11]: about_Enum.md +[12]: about_Hidden.md +[13]: about_language_keywords.md +[14]: about_methods.md +[15]: about_Using.md +[16]: xref:System.Management.Automation.PSReference diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Classes.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Classes.md index 28e2fd792341..95ca108efd9f 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Classes.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Classes.md @@ -1,7 +1,7 @@ --- description: Describes how you can use classes to create your own custom types. Locale: en-US -ms.date: 01/23/2024 +ms.date: 01/22/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Classes @@ -64,18 +64,17 @@ To instantiate an instance of a class, use one of the following syntaxes: ``` ```Syntax -[$ =] []@{[]} +[$ =] [] ``` > [!NOTE] > When using the `[]::new()` syntax, brackets around the class name > are mandatory. The brackets signal a type definition for PowerShell. > -> The hashtable syntax only works for classes that have a default constructor -> that doesn't expect any parameters. It creates an instance of the class with -> the default constructor and then assigns the key-value pairs to the instance -> properties. If any key in the hashtable isn't a valid property name, -> PowerShell raises an error. +> The `` syntax only works for classes that have a +> default constructor that doesn't expect any parameters. It creates an +> instance of the class with the default constructor and then uses runtime type +> conversion to assign the values provided. ## Examples @@ -99,7 +98,67 @@ Brand Fabrikam, Inc. ``` -### Example 2 - Class with instance members +### Example 2 - Using instantiation syntax + +This example defines a **Book** class with several properties, but no +constructor. + +```powershell +class Book { + # Class properties + [string] $Title + [string] $Author + [string] $Synopsis + [string] $Publisher + [datetime] $PublishDate + [int] $PageCount + [string[]] $Tags +} +``` + +The following example shows how the default constructor can assign the values +from a compatible value using type coercion. In this example, a hashtable is +used to provide the property values. + +```powershell +$Book1 = [Book] @{ + Title = '1984' + Author = 'George Orwell' + Synopsis = '' + Publisher = 'Secker & Warburg' + PublishDate = '1949-06-08' + PageCount = 328 + Tags = @('Dystopian', 'Political Fiction', 'Social Science Fiction') +} +$Book1 +``` + +```Output +Title : 1984 +Author : George Orwell +Synopsis : +Publisher : Secker & Warburg +PublishDate : 6/8/1949 12:00:00 AM +PageCount : 328 +Tags : {Dystopian, Political Fiction, Social Science Fiction} +``` + +The key-value pairs of the hashtable are assigned to the instance properties. +If any key in the hashtable isn't a valid property name, instantiation fails. + +In this example, an array is used to provide the values for the generic list. + +```powershell +$List = [System.Collections.Generic.List[int]] @(42, 43) +$List +``` + +```Output +42 +43 +``` + +### Example 3 - Class with instance members This example defines a **Book** class with several properties, constructors, and methods. Every defined member is an _instance_ member, not a static member. @@ -190,12 +249,12 @@ It takes 10 hours and 20 minutes to read The Hobbit by J.R.R. Tolkien (1937), which was published 86 years ago. ``` -### Example 3 - Class with static members +### Example 4 - Class with static members -The **BookList** class in this example builds on the **Book** class in example -2. While the **BookList** class can't be marked static itself, the -implementation only defines the **Books** static property and a set of static -methods for managing that property. +The **BookList** class in this example builds on the **Book** class in the +previous example. While the **BookList** class can't be marked static itself, +the implementation only defines the **Books** static property and a set of +static methods for managing that property. ```powershell class BookList { @@ -360,7 +419,7 @@ Line | | Book 'The Hobbit by J.R.R. Tolkien (1937)' already in list ``` -### Example 4 - Class definition with and without Runspace affinity +### Example 5 - Class definition with and without Runspace affinity The `ShowRunspaceId()` method of `[UnsafeClass]` reports different thread Ids but the same runspace ID. Eventually, the session state is corrupted causing @@ -426,7 +485,7 @@ Properties are variables declared in the class scope. A property can be of any built-in type or an instance of another class. Classes can have zero or more properties. Classes don't have a maximum property count. -For more information, see [about_Classes_Properties][01]. +For more information, see [about_Classes_Properties][09]. ## Class methods @@ -436,7 +495,7 @@ method doesn't return any output, it must have the **Void** output type. If a method doesn't explicitly define an output type, the method's output type is **Void**. -For more information, see [about_Classes_Methods][02]. +For more information, see [about_Classes_Methods][06]. ## Class constructors @@ -445,7 +504,7 @@ moment of creating the instance of the class. Constructors have the same name as the class. Constructors might have parameters, to initialize the data members of the new object. -For more information, see [about_Classes_Constructors][03]. +For more information, see [about_Classes_Constructors][02]. ## Hidden keyword @@ -474,11 +533,11 @@ Hidden class members are: > When you hide any constructor, the `new()` option is removed from > IntelliSense and completion results. -For more information about the keyword, see [about_Hidden][04]. For more -information about hidden properties, see [about_Classes_Properties][05]. For -more information about hidden methods, see [about_Classes_Methods][06]. For +For more information about the keyword, see [about_Hidden][13]. For more +information about hidden properties, see [about_Classes_Properties][10]. For +more information about hidden methods, see [about_Classes_Methods][07]. For more information about hidden constructors, see -[about_Classes_Constructors][07]. +[about_Classes_Constructors][03]. ## Static keyword @@ -492,9 +551,9 @@ available always. All static properties live for the entire session span. The `static` keyword only applies to class members, not a class itself. For more information about static properties, see -[about_Classes_Properties][08]. For more information about static methods, see -[about_Classes_Methods][09]. For more information about static constructors, -see [about_Classes_Constructors][10]. +[about_Classes_Properties][11]. For more information about static methods, see +[about_Classes_Methods][08]. For more information about static constructors, +see [about_Classes_Constructors][04]. ## Inheritance in PowerShell classes @@ -510,8 +569,7 @@ inherits from an interface must implement that contract. When it does, the class can be used like any other class implementing that interface. For more information about deriving classes that inherit from a base class or -implement interfaces, see -[about_Classes_Inheritance][11]. +implement interfaces, see [about_Classes_Inheritance][05]. ## NoRunspaceAffinity attribute @@ -533,8 +591,7 @@ thread and the thread's current session state. The attribute was added in PowerShell 7.4. For an illustration of the difference in behavior for classes with and without -the `NoRunspaceAffinity` attribute, see -[Example 4](#example-4---class-definition-with-and-without-runspace-affinity). +the `NoRunspaceAffinity` attribute, see [Example 5][01]. ## Export classes with type accelerators @@ -620,7 +677,7 @@ consistently import classes defined in nested modules or classes defined in scripts that are dot-sourced into the root module. Define classes that you want to be available to users outside of the module directly in the root module. -For more information about the `using` statement, see [about_Using][12]. +For more information about the `using` statement, see [about_Using][16]. ## Load newly changed code during development @@ -647,7 +704,7 @@ parameters can't be used with class members. The **PSReference** class was designed to support COM objects. COM objects have cases where you need to pass a value in by reference. -For more information, see [PSReference Class][13]. +For more information, see [PSReference Class][17]. ## Limitations @@ -767,30 +824,31 @@ workaround for those limitations, if any. ## See also -- [about_Classes_Constructors][03] -- [about_Classes_Inheritance][11] -- [about_Classes_Methods][02] -- [about_Classes_Properties][01] -- [about_Enum][14] -- [about_Hidden][04] -- [about_Language_Keywords][15] -- [about_Methods][16] -- [about_Using][12] +- [about_Classes_Constructors][02] +- [about_Classes_Inheritance][05] +- [about_Classes_Methods][06] +- [about_Classes_Properties][09] +- [about_Enum][12] +- [about_Hidden][13] +- [about_Language_Keywords][14] +- [about_Methods][15] +- [about_Using][16] -[01]: about_Classes_Properties.md -[02]: about_Classes_Methods.md -[03]: about_Classes_Constructors.md -[04]: about_Hidden.md -[05]: about_Classes_Properties.md#hidden-properties -[06]: about_Classes_Methods.md#hidden-methods -[07]: about_Classes_Constructors.md#hidden-constructors -[08]: about_Classes_Properties.md#static-properties -[09]: about_Classes_Methods.md#static-methods -[10]: about_Classes_Constructors.md#static-constructors -[11]: about_Classes_Inheritance.md -[12]: about_Using.md -[13]: /dotnet/api/system.management.automation.psreference -[14]: about_Enum.md -[15]: about_language_keywords.md -[16]: about_methods.md +[01]: #example-5---class-definition-with-and-without-runspace-affinity +[02]: about_Classes_Constructors.md +[03]: about_Classes_Constructors.md#hidden-constructors +[04]: about_Classes_Constructors.md#static-constructors +[05]: about_Classes_Inheritance.md +[06]: about_Classes_Methods.md +[07]: about_Classes_Methods.md#hidden-methods +[08]: about_Classes_Methods.md#static-methods +[09]: about_Classes_Properties.md +[10]: about_Classes_Properties.md#hidden-properties +[11]: about_Classes_Properties.md#static-properties +[12]: about_Enum.md +[13]: about_Hidden.md +[14]: about_language_keywords.md +[15]: about_methods.md +[16]: about_Using.md +[17]: xref:System.Management.Automation.PSReference diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Classes.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Classes.md index 5eed77c25f46..268104a63bb5 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Classes.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Classes.md @@ -1,7 +1,7 @@ --- description: Describes how you can use classes to create your own custom types. Locale: en-US -ms.date: 01/23/2024 +ms.date: 01/22/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Classes @@ -64,18 +64,17 @@ To instantiate an instance of a class, use one of the following syntaxes: ``` ```Syntax -[$ =] []@{[]} +[$ =] [] ``` > [!NOTE] > When using the `[]::new()` syntax, brackets around the class name > are mandatory. The brackets signal a type definition for PowerShell. > -> The hashtable syntax only works for classes that have a default constructor -> that doesn't expect any parameters. It creates an instance of the class with -> the default constructor and then assigns the key-value pairs to the instance -> properties. If any key in the hashtable isn't a valid property name, -> PowerShell raises an error. +> The `` syntax only works for classes that have a +> default constructor that doesn't expect any parameters. It creates an +> instance of the class with the default constructor and then uses runtime type +> conversion to assign the values provided. ## Examples @@ -99,7 +98,67 @@ Brand Fabrikam, Inc. ``` -### Example 2 - Class with instance members +### Example 2 - Using instantiation syntax + +This example defines a **Book** class with several properties, but no +constructor. + +```powershell +class Book { + # Class properties + [string] $Title + [string] $Author + [string] $Synopsis + [string] $Publisher + [datetime] $PublishDate + [int] $PageCount + [string[]] $Tags +} +``` + +The following example shows how the default constructor can assign the values +from a compatible value using type coercion. In this example, a hashtable is +used to provide the property values. + +```powershell +$Book1 = [Book] @{ + Title = '1984' + Author = 'George Orwell' + Synopsis = '' + Publisher = 'Secker & Warburg' + PublishDate = '1949-06-08' + PageCount = 328 + Tags = @('Dystopian', 'Political Fiction', 'Social Science Fiction') +} +$Book1 +``` + +```Output +Title : 1984 +Author : George Orwell +Synopsis : +Publisher : Secker & Warburg +PublishDate : 6/8/1949 12:00:00 AM +PageCount : 328 +Tags : {Dystopian, Political Fiction, Social Science Fiction} +``` + +The key-value pairs of the hashtable are assigned to the instance properties. +If any key in the hashtable isn't a valid property name, instantiation fails. + +In this example, an array is used to provide the values for the generic list. + +```powershell +$List = [System.Collections.Generic.List[int]] @(42, 43) +$List +``` + +```Output +42 +43 +``` + +### Example 3 - Class with instance members This example defines a **Book** class with several properties, constructors, and methods. Every defined member is an _instance_ member, not a static member. @@ -190,12 +249,12 @@ It takes 10 hours and 20 minutes to read The Hobbit by J.R.R. Tolkien (1937), which was published 86 years ago. ``` -### Example 3 - Class with static members +### Example 4 - Class with static members -The **BookList** class in this example builds on the **Book** class in example -2. While the **BookList** class can't be marked static itself, the -implementation only defines the **Books** static property and a set of static -methods for managing that property. +The **BookList** class in this example builds on the **Book** class in the +previous example. While the **BookList** class can't be marked static itself, +the implementation only defines the **Books** static property and a set of +static methods for managing that property. ```powershell class BookList { @@ -360,7 +419,7 @@ Line | | Book 'The Hobbit by J.R.R. Tolkien (1937)' already in list ``` -### Example 4 - Class definition with and without Runspace affinity +### Example 5 - Class definition with and without Runspace affinity The `ShowRunspaceId()` method of `[UnsafeClass]` reports different thread Ids but the same runspace ID. Eventually, the session state is corrupted causing @@ -426,7 +485,7 @@ Properties are variables declared in the class scope. A property can be of any built-in type or an instance of another class. Classes can have zero or more properties. Classes don't have a maximum property count. -For more information, see [about_Classes_Properties][01]. +For more information, see [about_Classes_Properties][09]. ## Class methods @@ -436,7 +495,7 @@ method doesn't return any output, it must have the **Void** output type. If a method doesn't explicitly define an output type, the method's output type is **Void**. -For more information, see [about_Classes_Methods][02]. +For more information, see [about_Classes_Methods][06]. ## Class constructors @@ -445,7 +504,7 @@ moment of creating the instance of the class. Constructors have the same name as the class. Constructors might have parameters, to initialize the data members of the new object. -For more information, see [about_Classes_Constructors][03]. +For more information, see [about_Classes_Constructors][02]. ## Hidden keyword @@ -474,11 +533,11 @@ Hidden class members are: > When you hide any constructor, the `new()` option is removed from > IntelliSense and completion results. -For more information about the keyword, see [about_Hidden][04]. For more -information about hidden properties, see [about_Classes_Properties][05]. For -more information about hidden methods, see [about_Classes_Methods][06]. For +For more information about the keyword, see [about_Hidden][13]. For more +information about hidden properties, see [about_Classes_Properties][10]. For +more information about hidden methods, see [about_Classes_Methods][07]. For more information about hidden constructors, see -[about_Classes_Constructors][07]. +[about_Classes_Constructors][03]. ## Static keyword @@ -492,9 +551,9 @@ available always. All static properties live for the entire session span. The `static` keyword only applies to class members, not a class itself. For more information about static properties, see -[about_Classes_Properties][08]. For more information about static methods, see -[about_Classes_Methods][09]. For more information about static constructors, -see [about_Classes_Constructors][10]. +[about_Classes_Properties][11]. For more information about static methods, see +[about_Classes_Methods][08]. For more information about static constructors, +see [about_Classes_Constructors][04]. ## Inheritance in PowerShell classes @@ -510,8 +569,7 @@ inherits from an interface must implement that contract. When it does, the class can be used like any other class implementing that interface. For more information about deriving classes that inherit from a base class or -implement interfaces, see -[about_Classes_Inheritance][11]. +implement interfaces, see [about_Classes_Inheritance][05]. ## NoRunspaceAffinity attribute @@ -533,8 +591,7 @@ thread and the thread's current session state. The attribute was added in PowerShell 7.4. For an illustration of the difference in behavior for classes with and without -the `NoRunspaceAffinity` attribute, see -[Example 4](#example-4---class-definition-with-and-without-runspace-affinity). +the `NoRunspaceAffinity` attribute, see [Example 5][01]. ## Export classes with type accelerators @@ -620,7 +677,7 @@ consistently import classes defined in nested modules or classes defined in scripts that are dot-sourced into the root module. Define classes that you want to be available to users outside of the module directly in the root module. -For more information about the `using` statement, see [about_Using][12]. +For more information about the `using` statement, see [about_Using][16]. ## Load newly changed code during development @@ -647,7 +704,7 @@ parameters can't be used with class members. The **PSReference** class was designed to support COM objects. COM objects have cases where you need to pass a value in by reference. -For more information, see [PSReference Class][13]. +For more information, see [PSReference Class][17]. ## Limitations @@ -767,30 +824,31 @@ workaround for those limitations, if any. ## See also -- [about_Classes_Constructors][03] -- [about_Classes_Inheritance][11] -- [about_Classes_Methods][02] -- [about_Classes_Properties][01] -- [about_Enum][14] -- [about_Hidden][04] -- [about_Language_Keywords][15] -- [about_Methods][16] -- [about_Using][12] +- [about_Classes_Constructors][02] +- [about_Classes_Inheritance][05] +- [about_Classes_Methods][06] +- [about_Classes_Properties][09] +- [about_Enum][12] +- [about_Hidden][13] +- [about_Language_Keywords][14] +- [about_Methods][15] +- [about_Using][16] -[01]: about_Classes_Properties.md -[02]: about_Classes_Methods.md -[03]: about_Classes_Constructors.md -[04]: about_Hidden.md -[05]: about_Classes_Properties.md#hidden-properties -[06]: about_Classes_Methods.md#hidden-methods -[07]: about_Classes_Constructors.md#hidden-constructors -[08]: about_Classes_Properties.md#static-properties -[09]: about_Classes_Methods.md#static-methods -[10]: about_Classes_Constructors.md#static-constructors -[11]: about_Classes_Inheritance.md -[12]: about_Using.md -[13]: /dotnet/api/system.management.automation.psreference -[14]: about_Enum.md -[15]: about_language_keywords.md -[16]: about_methods.md +[01]: #example-5---class-definition-with-and-without-runspace-affinity +[02]: about_Classes_Constructors.md +[03]: about_Classes_Constructors.md#hidden-constructors +[04]: about_Classes_Constructors.md#static-constructors +[05]: about_Classes_Inheritance.md +[06]: about_Classes_Methods.md +[07]: about_Classes_Methods.md#hidden-methods +[08]: about_Classes_Methods.md#static-methods +[09]: about_Classes_Properties.md +[10]: about_Classes_Properties.md#hidden-properties +[11]: about_Classes_Properties.md#static-properties +[12]: about_Enum.md +[13]: about_Hidden.md +[14]: about_language_keywords.md +[15]: about_methods.md +[16]: about_Using.md +[17]: xref:System.Management.Automation.PSReference diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Classes.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Classes.md index 713e4c76d07c..77f92f29e3be 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Classes.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Classes.md @@ -1,7 +1,7 @@ --- description: Describes how you can use classes to create your own custom types. Locale: en-US -ms.date: 01/23/2024 +ms.date: 01/22/2026 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Classes @@ -64,18 +64,17 @@ To instantiate an instance of a class, use one of the following syntaxes: ``` ```Syntax -[$ =] []@{[]} +[$ =] [] ``` > [!NOTE] > When using the `[]::new()` syntax, brackets around the class name > are mandatory. The brackets signal a type definition for PowerShell. > -> The hashtable syntax only works for classes that have a default constructor -> that doesn't expect any parameters. It creates an instance of the class with -> the default constructor and then assigns the key-value pairs to the instance -> properties. If any key in the hashtable isn't a valid property name, -> PowerShell raises an error. +> The `` syntax only works for classes that have a +> default constructor that doesn't expect any parameters. It creates an +> instance of the class with the default constructor and then uses runtime type +> conversion to assign the values provided. ## Examples @@ -99,7 +98,67 @@ Brand Fabrikam, Inc. ``` -### Example 2 - Class with instance members +### Example 2 - Using instantiation syntax + +This example defines a **Book** class with several properties, but no +constructor. + +```powershell +class Book { + # Class properties + [string] $Title + [string] $Author + [string] $Synopsis + [string] $Publisher + [datetime] $PublishDate + [int] $PageCount + [string[]] $Tags +} +``` + +The following example shows how the default constructor can assign the values +from a compatible value using type coercion. In this example, a hashtable is +used to provide the property values. + +```powershell +$Book1 = [Book] @{ + Title = '1984' + Author = 'George Orwell' + Synopsis = '' + Publisher = 'Secker & Warburg' + PublishDate = '1949-06-08' + PageCount = 328 + Tags = @('Dystopian', 'Political Fiction', 'Social Science Fiction') +} +$Book1 +``` + +```Output +Title : 1984 +Author : George Orwell +Synopsis : +Publisher : Secker & Warburg +PublishDate : 6/8/1949 12:00:00 AM +PageCount : 328 +Tags : {Dystopian, Political Fiction, Social Science Fiction} +``` + +The key-value pairs of the hashtable are assigned to the instance properties. +If any key in the hashtable isn't a valid property name, instantiation fails. + +In this example, an array is used to provide the values for the generic list. + +```powershell +$List = [System.Collections.Generic.List[int]] @(42, 43) +$List +``` + +```Output +42 +43 +``` + +### Example 3 - Class with instance members This example defines a **Book** class with several properties, constructors, and methods. Every defined member is an _instance_ member, not a static member. @@ -190,12 +249,12 @@ It takes 10 hours and 20 minutes to read The Hobbit by J.R.R. Tolkien (1937), which was published 86 years ago. ``` -### Example 3 - Class with static members +### Example 4 - Class with static members -The **BookList** class in this example builds on the **Book** class in example -2. While the **BookList** class can't be marked static itself, the -implementation only defines the **Books** static property and a set of static -methods for managing that property. +The **BookList** class in this example builds on the **Book** class in the +previous example. While the **BookList** class can't be marked static itself, +the implementation only defines the **Books** static property and a set of +static methods for managing that property. ```powershell class BookList { @@ -360,7 +419,7 @@ Line | | Book 'The Hobbit by J.R.R. Tolkien (1937)' already in list ``` -### Example 4 - Class definition with and without Runspace affinity +### Example 5 - Class definition with and without Runspace affinity The `ShowRunspaceId()` method of `[UnsafeClass]` reports different thread Ids but the same runspace ID. Eventually, the session state is corrupted causing @@ -426,7 +485,7 @@ Properties are variables declared in the class scope. A property can be of any built-in type or an instance of another class. Classes can have zero or more properties. Classes don't have a maximum property count. -For more information, see [about_Classes_Properties][01]. +For more information, see [about_Classes_Properties][09]. ## Class methods @@ -436,7 +495,7 @@ method doesn't return any output, it must have the **Void** output type. If a method doesn't explicitly define an output type, the method's output type is **Void**. -For more information, see [about_Classes_Methods][02]. +For more information, see [about_Classes_Methods][06]. ## Class constructors @@ -445,7 +504,7 @@ moment of creating the instance of the class. Constructors have the same name as the class. Constructors might have parameters, to initialize the data members of the new object. -For more information, see [about_Classes_Constructors][03]. +For more information, see [about_Classes_Constructors][02]. ## Hidden keyword @@ -474,11 +533,11 @@ Hidden class members are: > When you hide any constructor, the `new()` option is removed from > IntelliSense and completion results. -For more information about the keyword, see [about_Hidden][04]. For more -information about hidden properties, see [about_Classes_Properties][05]. For -more information about hidden methods, see [about_Classes_Methods][06]. For +For more information about the keyword, see [about_Hidden][13]. For more +information about hidden properties, see [about_Classes_Properties][10]. For +more information about hidden methods, see [about_Classes_Methods][07]. For more information about hidden constructors, see -[about_Classes_Constructors][07]. +[about_Classes_Constructors][03]. ## Static keyword @@ -492,9 +551,9 @@ available always. All static properties live for the entire session span. The `static` keyword only applies to class members, not a class itself. For more information about static properties, see -[about_Classes_Properties][08]. For more information about static methods, see -[about_Classes_Methods][09]. For more information about static constructors, -see [about_Classes_Constructors][10]. +[about_Classes_Properties][11]. For more information about static methods, see +[about_Classes_Methods][08]. For more information about static constructors, +see [about_Classes_Constructors][04]. ## Inheritance in PowerShell classes @@ -510,8 +569,7 @@ inherits from an interface must implement that contract. When it does, the class can be used like any other class implementing that interface. For more information about deriving classes that inherit from a base class or -implement interfaces, see -[about_Classes_Inheritance][11]. +implement interfaces, see [about_Classes_Inheritance][05]. ## NoRunspaceAffinity attribute @@ -533,8 +591,7 @@ thread and the thread's current session state. The attribute was added in PowerShell 7.4. For an illustration of the difference in behavior for classes with and without -the `NoRunspaceAffinity` attribute, see -[Example 4](#example-4---class-definition-with-and-without-runspace-affinity). +the `NoRunspaceAffinity` attribute, see [Example 5][01]. ## Export classes with type accelerators @@ -620,7 +677,7 @@ consistently import classes defined in nested modules or classes defined in scripts that are dot-sourced into the root module. Define classes that you want to be available to users outside of the module directly in the root module. -For more information about the `using` statement, see [about_Using][12]. +For more information about the `using` statement, see [about_Using][16]. ## Load newly changed code during development @@ -647,7 +704,7 @@ parameters can't be used with class members. The **PSReference** class was designed to support COM objects. COM objects have cases where you need to pass a value in by reference. -For more information, see [PSReference Class][13]. +For more information, see [PSReference Class][17]. ## Limitations @@ -767,30 +824,31 @@ workaround for those limitations, if any. ## See also -- [about_Classes_Constructors][03] -- [about_Classes_Inheritance][11] -- [about_Classes_Methods][02] -- [about_Classes_Properties][01] -- [about_Enum][14] -- [about_Hidden][04] -- [about_Language_Keywords][15] -- [about_Methods][16] -- [about_Using][12] +- [about_Classes_Constructors][02] +- [about_Classes_Inheritance][05] +- [about_Classes_Methods][06] +- [about_Classes_Properties][09] +- [about_Enum][12] +- [about_Hidden][13] +- [about_Language_Keywords][14] +- [about_Methods][15] +- [about_Using][16] -[01]: about_Classes_Properties.md -[02]: about_Classes_Methods.md -[03]: about_Classes_Constructors.md -[04]: about_Hidden.md -[05]: about_Classes_Properties.md#hidden-properties -[06]: about_Classes_Methods.md#hidden-methods -[07]: about_Classes_Constructors.md#hidden-constructors -[08]: about_Classes_Properties.md#static-properties -[09]: about_Classes_Methods.md#static-methods -[10]: about_Classes_Constructors.md#static-constructors -[11]: about_Classes_Inheritance.md -[12]: about_Using.md -[13]: /dotnet/api/system.management.automation.psreference -[14]: about_Enum.md -[15]: about_language_keywords.md -[16]: about_methods.md +[01]: #example-5---class-definition-with-and-without-runspace-affinity +[02]: about_Classes_Constructors.md +[03]: about_Classes_Constructors.md#hidden-constructors +[04]: about_Classes_Constructors.md#static-constructors +[05]: about_Classes_Inheritance.md +[06]: about_Classes_Methods.md +[07]: about_Classes_Methods.md#hidden-methods +[08]: about_Classes_Methods.md#static-methods +[09]: about_Classes_Properties.md +[10]: about_Classes_Properties.md#hidden-properties +[11]: about_Classes_Properties.md#static-properties +[12]: about_Enum.md +[13]: about_Hidden.md +[14]: about_language_keywords.md +[15]: about_methods.md +[16]: about_Using.md +[17]: xref:System.Management.Automation.PSReference diff --git a/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md b/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md index 7fbf6e2804ef..ae986acb3789 100644 --- a/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md +++ b/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md @@ -1,6 +1,6 @@ --- description: Scripting for Performance in PowerShell -ms.date: 08/18/2025 +ms.date: 01/21/2026 title: PowerShell scripting performance considerations --- @@ -267,6 +267,42 @@ In this example, PowerShell creates an `[ArrayList]` to hold the results written inside the array expression. Just before assigning to `$results`, PowerShell converts the `[ArrayList]` to an `[Object[]]`. +### Type-safe collections + +PowerShell is a loosely typed language, which makes coding easier but can have performance +implications. Consider using type-safe (or type-specific) collections. Type-safe collections consume +less memory and are faster. Compare the following examples: + +```powershell +$Stopwatch = [System.Diagnostics.Stopwatch]::StartNew() +$ListInt = [System.Collections.Generic.List[int]]::new() +for ($i = 0; $i -lt 1mb; $i++) { + $ListInt.Add($i) +} +$Stopwatch.Stop() +Write-Host "Time to add 1mb integers to List[int]: $($Stopwatch.Elapsed.TotalSeconds) seconds." +``` + +```Output +Time to add 1mb integers to List[int]: 9.8841501 seconds. +``` + +Creating a list of `[int]` is faster than creating a list of `[Object]`. + +```powershell +$Stopwatch = [System.Diagnostics.Stopwatch]::StartNew() +$ListObject = [System.Collections.Generic.List[Object]]::new() +for ($i = 0; $i -lt 1mb; $i++) { + $ListObject.Add($i) +} +$Stopwatch.Stop() +Write-Host "Time to add 1mb integers to List[Object]: $($Stopwatch.Elapsed.TotalSeconds) seconds." +``` + +```Output +Time to add 1mb integers to List[Object]: 10.5677782 seconds. +``` + ## String addition Strings are immutable. Each addition to the string actually creates a new string big enough to hold diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 8e4e55975935..171a7f631a65 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -239,6 +239,8 @@ items: href: whats-new/module-compatibility.md - name: Windows PowerShell items: + - name: Windows PowerShell update message + href: windows-powershell/update-notification-message.yml - name: ISE items: - name: Introducing the Windows PowerShell ISE diff --git a/reference/docs-conceptual/windows-powershell/media/update-notification-message/windows-powershell-update-notice.png b/reference/docs-conceptual/windows-powershell/media/update-notification-message/windows-powershell-update-notice.png new file mode 100644 index 000000000000..a1700b7966e4 Binary files /dev/null and b/reference/docs-conceptual/windows-powershell/media/update-notification-message/windows-powershell-update-notice.png differ diff --git a/reference/docs-conceptual/windows-powershell/update-notification-message.yml b/reference/docs-conceptual/windows-powershell/update-notification-message.yml new file mode 100644 index 000000000000..ad53ea4fa7b6 --- /dev/null +++ b/reference/docs-conceptual/windows-powershell/update-notification-message.yml @@ -0,0 +1,64 @@ +### YamlMime:FAQ +metadata: + description: >- + This article explains the intent of the update notification message in Windows PowerShell. + ms.date: 01/22/2026 + ms.topic: faq + title: Windows PowerShell update message + +title: Windows PowerShell update message +summary: | + When you start Windows PowerShell you see a message that tells you to install the latest version + of PowerShell along with a URL. + + ![Update notification message](./media/update-notification-message/windows-powershell-update-notice.png) + + This article explains the intent of this message and provides answers to frequently asked + questions. + +sections: + - name: Frequently asked questions + questions: + - question: Why am I seeing this message? + answer: | + Windows PowerShell displays this message at startup to make you aware that there is a + newer version of PowerShell available. + + - question: I opened the URL but it didn't install an update. + answer: | + The `aka.ms` link takes you to this page. If you want to install the latest version of + PowerShell, follow the instructions in + [Install PowerShell on Windows](../install/install-powershell-on-windows.md). + + - question: But I installed PowerShell 7, why am I still seeing this message? + answer: | + You always get the message when you run Windows PowerShell 5.1. PowerShell 7 doesn't + replace Windows PowerShell 5.1. PowerShell 7 installs side-by-side. You can run either + version. + + - question: Can I disable the message? + answer: No. There is no way to disable the message. + + - question: How does Windows PowerShell 5.1 get updated? + answer: | + Windows PowerShell 5.1 is a built-in component of Windows. It's important to understand + that Windows PowerShell is no longer being developed. Microsoft only publishes security + updates for Windows PowerShell 5.1. All updates are managed through standard Windows + update channels. + + - question: My install of Windows is up-to-date. Why am I still getting this message? + answer: | + This message appears every time you start Windows PowerShell 5.1. It doesn't mean that + Windows PowerShell 5.1 is not up-to-date. It means that you are not running PowerShell 7. + + - question: Why would I want to install PowerShell 7? + answer: | + Windows PowerShell 5.1 is no longer being developed. PowerShell 7 is actively developed + and supported. PowerShell 7 is faster, more secure, and is available for Windows, Linux + and macOS. For more information, see + [Differences between Windows PowerShell 5.1 and PowerShell 7](../whats-new/differences-from-windows-powershell.md). + + - question: Do I need to install PowerShell 7? + answer: | + No, you don't need to install PowerShell 7 unless you have a specific requirement for the + features it provides.