Skip to content

Commit

Permalink
Rewrite about_modules (#10720)
Browse files Browse the repository at this point in the history
* Rewrite about_modules

* Fix broken link

* Apply suggestions from code review

Co-authored-by: Mikey Lombardi (He/Him) <[email protected]>

* Feedback edits

---------

Co-authored-by: Mikey Lombardi (He/Him) <[email protected]>
  • Loading branch information
sdwheeler and michaeltlombardi authored Dec 7, 2023
1 parent 3323aee commit 02cba40
Show file tree
Hide file tree
Showing 12 changed files with 1,166 additions and 1,913 deletions.
613 changes: 227 additions & 386 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md

Large diffs are not rendered by default.

174 changes: 62 additions & 112 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_PSSnapins.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes Windows PowerShell snap-ins and shows how to use and manage them.
Locale: en-US
ms.date: 01/03/2018
ms.date: 12/07/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pssnapins?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about PSSnapins
Expand All @@ -14,29 +14,27 @@ Describes Windows PowerShell snap-ins and shows how to use and manage them.

## Long description

A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that
contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell
includes a set of basic snap-ins, but you can extend the power and value of
Windows PowerShell by adding snap-ins that contain providers and cmdlets that
you create or get from others.
A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that can
contain Windows PowerShell providers and cmdlets. Windows PowerShell includes a
set of basic snap-ins, but you can extend the power and value of Windows
PowerShell by adding snap-ins that contain providers and cmdlets that you
create or get from others.

When you add a snap-in, the cmdlets and providers that it contains are
immediately available for use in the current session, but the change affects
only the current session.

To add the snap-in to all future sessions, save it in your Windows PowerShell
profile. You can also use the Export-Console cmdlet to save the snap-in names
to a console file and then use it in future sessions. You can even save
multiple console files, each with a different set of snap-ins.
profile. You can also use the `Export-Console` cmdlet to save the snap-in names
to a console file and then use that saved configuration in future sessions.

NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows
PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or unavailable
in subsequent versions. To package Windows PowerShell cmdlets and providers,
use modules. For information about creating modules and converting snap-ins to
modules, see
[Writing a Windows PowerShell Module](/powershell/scripting/developer/module/writing-a-windows-powershell-module).
Beginning in Windows PowerShell 3.0, the cmdlets that ship with PowerShell are
packaged in modules. The exception is **Microsoft.PowerShell.Core**, which is
the only remaining snap-in. The **Microsoft.PowerShell.Core** snap-in is loaded
in every session by default. The remaining modules are loaded automatically on
first-use. For more information, see [about_Modules][02].

### FINDING SNAP-INS
## Find a snap-in

To get a list of the Windows PowerShell snap-ins on your computer, type:

Expand All @@ -50,40 +48,29 @@ To get the snap-in for each Windows PowerShell provider, type:
Get-PSProvider | Format-List name, pssnapin
```

To get all the registered snap-ins on your system or to verify that a snap-in
is registered, type:

```powershell
Get-PSSnapin -registered
```

To get a list of the cmdlets in a Windows PowerShell snap-in, type:

```powershell
Get-Command -Module <snap-in_name>
```

### INSTALLING A SNAP-IN
## Install a snap-in

The built-in snap-ins are registered in the system and added to the default
session when you start Windows PowerShell. However, you have to register
snap-ins that you create or obtain from others and then add the snap-ins to
your session.

### REGISTERING A SNAP-IN

A Windows PowerShell snap-in is a program written in a .NET Framework language
that is compiled into a .dll file. To use the providers and cmdlets in a
snap-in, you must first register the snap-in (add it to the registry).

Most snap-ins include an installation program (an .exe or .msi file) that
registers the .dll file for you. However, if you receive a snap-in as a .dll
file, you can register it on your system. For more information, see
[How to Register Cmdlets, Providers, and Host Applications](/previous-versions//ms714644(v=vs.85)).

To get all the registered snap-ins on your system or to verify that a snap-in
is registered, type:

```powershell
Get-PSSnapin -registered
```

### ADDING THE SNAP-IN TO THE CURRENT SESSION
## Add a snap-in to the current session

To add a registered snap-in to the current session, use the Add-PsSnapin
To add a registered snap-in to the current session, use the `Add-PsSnapin`
cmdlet. For example, to add the Microsoft SQL Server snap-in to the session,
type:

Expand All @@ -92,52 +79,53 @@ Add-PSSnapin sql
```

After the command is completed, the providers and cmdlets in the snap-in are
available in the session. However, they are available only in the current
available in the session. However, they're available only in the current
session unless you save them.

### SAVING THE SNAP-INS
## Save a snap-ins

To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin
To use a snap-in in future Windows PowerShell sessions, add the `Add-PsSnapin`
command to your Windows PowerShell profile. Or, export the snap-in names to a
console file.

If you add the Add-PSSnapin command to your profile, it is available in all
If you add the `Add-PSSnapin` command to your profile, it's available in all
future Windows PowerShell sessions. If you export the names of the snap-ins in
your session, you can use the export file only when you need the snap-ins.

To add the Add-PsSnapin command to your Windows PowerShell profile, open your
To add the `Add-PsSnapin` command to your Windows PowerShell profile, open your
profile, paste or type the command, and then save the profile. For more
information, see [about_Profiles](about_Profiles.md).
information, see [about_Profiles][03].

To save the snap-ins from a session in console file (.psc1), use the
Export-Console cmdlet. For example, to save the snap-ins in the current
session configuration to the NewConsole.psc1 file in the current directory,
To save the snap-ins from a session in console file (`.psc1`), use the
`Export-Console` cmdlet. For example, to save the snap-ins in the current
session configuration to the `NewConsole.psc1` file in the current directory,
type:

```powershell
Export-Console NewConsole
```

For more information, see Export-Console.
For more information, see [Export-Console][05].

### OPENING WINDOWS POWERSHELL WITH A CONSOLE FILE
## Open Windows PowerShell using a console file

To use a console file that includes the snap-in, start Windows PowerShell
(PowerShell.exe) from the command prompt in Cmd.exe or in another Windows
PowerShell session. Use the PsConsoleFile parameter to specify the console
(`powershell.exe`) from the command prompt in `cmd.exe` or in another Windows
PowerShell session. Use the **PsConsoleFile** parameter to specify the console
file that includes the snap-in. For example, the following command starts
Windows PowerShell with the NewConsole.psc1 console file:
Windows PowerShell with the `NewConsole.psc1` console file:

```powershell
PowerShell.exe -psconsolefile NewConsole.psc1
```

The providers and cmdlets in the snapin are now available for use in the session.
The providers and cmdlets in the snap-in are now available for use in the
session.

### REMOVING A SNAP-IN
## Remove a snap-in

To remove a Windows PowerShell snap-in from the current session, use the
Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the
`Remove-PsSnapin` cmdlet. For example, to remove the SQL Server snap-in from the
current session, type:

```powershell
Expand All @@ -147,67 +135,29 @@ Remove-PSSnapin sql
This cmdlet removes the snap-in from the session. The snap-in is still loaded,
but the providers and cmdlets that it supports are no longer available.

### BUILT-IN COMMANDS

In Windows PowerShell 2.0 and in older-style host programs in Windows
PowerShell 3.0 and later, the built-in commands that are installed with
Windows PowerShell are packaged in snap-ins that are added automatically to
every Windows PowerShell session.

Beginning in Windows PowerShell 3.0, in newer-style host programs -- those
that start sessions by using the InitialSessionState.CreateDefault2 method --
the built-in commands are packaged in modules. The exception is
Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in
is included in every session by default. The built-in modules are loaded
automatically on first-use.

NOTE: Remote sessions, including sessions that are started by using the
New-PSSession cmdlet, are older-style sessions in which the built-in commands
are packaged in snap-ins.

The following snap-ins (or modules) are installed with Windows PowerShell.

- Microsoft.PowerShell.Core - Contains providers and cmdlets used to manage
the basic features of Windows PowerShell. It includes the FileSystem,
Registry, Alias, Environment, Function, and Variable providers and basic
cmdlets like Get-Help, Get-Command, and Get-History.

- Microsoft.PowerShell.Host - Contains cmdlets used by the Windows PowerShell
host, such as Start-Transcript and Stop-Transcript.

- Microsoft.PowerShell.Management - Contains cmdlets such as Get-Service and
Get-ChildItem that are used to manage Windows-based features.

- Microsoft.PowerShell.Security - Contains the Certificate provider and
cmdlets used to manage Windows PowerShell security, such as Get-Acl,
Get-AuthenticodeSignature, and ConvertTo-SecureString.

- Microsoft.PowerShell.Utility - Contains cmdlets used to manipulate objects
and data, such as Get-Member, Write-Host, and Format-List.

- Microsoft.WSMan.Management - Contains the WSMan provider and cmdlets that
manage the Windows Remote Management service, such as Connect-WSMan and
Enable-WSManCredSSP.

## LOGGING SNAP-IN EVENTS
## Log snap-in events

Beginning in Windows PowerShell 3.0, you can record execution events for the
cmdlets in Windows PowerShell modules and snap-ins by setting the
LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more
information, see [about_EventLogs](about_EventLogs.md).
**LogPipelineExecutionDetails** property of modules and snap-ins to `$true`.
For more information, see [about_EventLogs][01].

## See also

- [about_Modules](about_Modules.md)
- [about_Profiles](about_Profiles.md)
- [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command)
- [Export-Console](xref:Microsoft.PowerShell.Core.Export-Console)
- [Add-PsSnapin](xref:Microsoft.PowerShell.Core.Add-PSSnapin)
- [Get-PsSnapin](xref:Microsoft.PowerShell.Core.Get-PSSnapin)
- [Remove-PsSnapin](xref:Microsoft.PowerShell.Core.Remove-PSSnapin)

## KEYWORDS

about_Snapins
about_Snap_ins
about_Snap-ins
- [about_Modules][02]
- [about_Profiles][03]
- [Get-Command][06]
- [Export-Console][05]
- [Add-PsSnapin][04]
- [Get-PsSnapin][07]
- [Remove-PsSnapin][08]

<!-- link references -->
[01]: about_EventLogs.md
[02]: about_Modules.md
[03]: about_Profiles.md
[04]: xref:Microsoft.PowerShell.Core.Add-PSSnapin
[05]: xref:Microsoft.PowerShell.Core.Export-Console
[06]: xref:Microsoft.PowerShell.Core.Get-Command
[07]: xref:Microsoft.PowerShell.Core.Get-PSSnapin
[08]: xref:Microsoft.PowerShell.Core.Remove-PSSnapin
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Variables that customize the behavior of PowerShell.
Locale: en-US
ms.date: 01/30/2023
ms.date: 12/07/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about Preference Variables
Expand Down Expand Up @@ -1085,27 +1085,22 @@ preference variable is used by cmdlets that send email, such as the

## $PSModuleAutoloadingPreference

Enables and disables automatic importing of modules in the session. **All** is
the default. To import a module, get or use any command in the module. For
example, use `Get-Command`. The `$PSModuleAutoloadingPreference` variable does
not exist by default. The default behavior when the variable isn't defined is
the same as `$PSModuleAutoloadingPreference = 'All'`.
Enables and disables automatic importing of modules in the session. The
`$PSModuleAutoloadingPreference` variable doesn't exist by default. The default
behavior when the variable isn't defined is the same as
`$PSModuleAutoloadingPreference = 'All'`.

Regardless of the variable's value, you can use [Import-Module][44] to import a
module.
To automatically import a module, get or use a command contained in the module.

The `$PSModuleAutoloadingPreference` variable takes one of the
[`PSModuleAutoLoadingPreference`][58] enumeration values: **None**,
**ModuleQualified**, or **All**.
[`PSModuleAutoLoadingPreference`][58] enumeration values:

Valid values are:

- **All**: Modules are imported automatically on first-use.
- **ModuleQualified**: Modules are imported automatically only when a user uses
- `All`: Modules are imported automatically on first-use.
- `ModuleQualified`: Modules are imported automatically only when a user uses
the module-qualified name of a command in the module. For example, if the
user types `MyModule\MyCommand`, PowerShell imports the **MyModule** module.
- **None**: Automatic importing of modules is disabled in the session. To
import a module, use the `Import-Module` cmdlet.
- `None`: Disables the automatic importing of modules. To import a module, use
the `Import-Module` cmdlet.

For more information about automatic importing of modules, see
[about_Modules][34].
Expand Down Expand Up @@ -1745,7 +1740,6 @@ At line:1 char:1
[41]: about_Variable_Provider.md
[42]: about_Variables.md
[43]: xref:Microsoft.PowerShell.Core.Enter-PSSession
[44]: xref:Microsoft.PowerShell.Core.Import-Module
[45]: xref:Microsoft.PowerShell.Core.Invoke-Command
[46]: xref:Microsoft.PowerShell.Core.New-PSSession
[47]: xref:Microsoft.PowerShell.Core.New-PSSessionOption
Expand Down
Loading

0 comments on commit 02cba40

Please sign in to comment.