About PSSnapins

SHORT DESCRIPTION

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.

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.

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.

FINDING SNAP-INS

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

To get the snap-in for each Windows PowerShell provider, type:

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

INSTALLING 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.

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

ADDING THE SNAP-IN TO THE CURRENT SESSION

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:

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 session unless you save them.

SAVING THE SNAP-INS

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 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 profile, paste or type the command, and then save the profile. For more information, see about_Profiles.

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:

For more information, see Export-Console.

OPENING WINDOWS POWERSHELL WITH 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 file that includes the snap-in. For example, the following command starts Windows PowerShell with the NewConsole.psc1 console file:

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

REMOVING 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 current session, type:

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

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.

Написание оснастки Windows PowerShell Writing a Windows PowerShell Snap-in

В этом примере показано, как создать оснастку Windows PowerShell, которая может использоваться для регистрации всех командлетов и поставщиков Windows PowerShell в сборке. This example shows how to write a Windows PowerShell snap-in that can be used to register all the cmdlets and Windows PowerShell providers in an assembly.

При использовании этого типа оснастки не следует выбирать командлеты и поставщики, которые нужно зарегистрировать. With this type of snap-in, you do not select which cmdlets and providers you want to register. Чтобы создать оснастку, которая позволяет выбрать регистрируемые объекты, см. раздел написание пользовательской оснастки Windows PowerShell. To write a snap-in that allows you to select what is registered, see Writing a Custom Windows PowerShell Snap-in.

Написание оснастки Windows PowerShell Writing a Windows PowerShell Snap-in

Добавьте атрибут Рунинсталлераттрибуте. Add the RunInstallerAttribute attribute.

Создайте открытый класс, производный от класса System. Management. Automation. PSSnapin . Create a public class that derives from the System.Management.Automation.PSSnapIn class.

В этом примере имя класса — «GetProcPSSnapIn01». In this example, the class name is «GetProcPSSnapIn01».

Добавьте открытое свойство для имени оснастки (обязательно). Add a public property for the name of the snap-in (required). При именовании оснасток не используйте следующие символы: # , . , , ,, ( ) , < , >, [ , ] , & , — / \ $ ; : » ‘ > | ? @ ` . * When naming snap-ins, do not use any of the following characters: # , . , , , ( , ) , < , >, [ , ] , & , — , / , \ , $ , ; , : , » , ‘ , , > , | , ? , @ , ` , *

В этом примере имя оснастки — «GetProcPSSnapIn01». In this example, the name of the snap-in is «GetProcPSSnapIn01».

Добавьте открытое свойство для поставщика оснастки (обязательно). Add a public property for the vendor of the snap-in (required).

В этом примере поставщиком является «Microsoft». In this example, the vendor is «Microsoft».

Добавьте открытое свойство для ресурса поставщика оснастки (необязательно). Add a public property for the vendor resource of the snap-in (optional).

В этом примере ресурсом поставщика является «GetProcPSSnapIn01, Microsoft». In this example, the vendor resource is «GetProcPSSnapIn01,Microsoft».

Добавьте открытое свойство для описания оснастки (обязательно). Add a public property for the description of the snap-in (required).

В этом примере описание: «это оснастка Windows PowerShell, которая регистрирует командлет Get-proc». In this example, the description is «This is a Windows PowerShell snap-in that registers the get-proc cmdlet».

Добавьте открытое свойство для ресурса описания оснастки (необязательно). Add a public property for the description resource of the snap-in (optional).

В этом примере ресурсом поставщика является «GetProcPSSnapIn01, это оснастка Windows PowerShell, которая регистрирует командлет Get-proc». In this example, the vendor resource is «GetProcPSSnapIn01,This is a Windows PowerShell snap-in that registers the get-proc cmdlet».

Пример Example

В этом примере показано, как создать оснастку Windows PowerShell, которая может использоваться для регистрации командлета Get-Proc в оболочке Windows PowerShell. This example shows how to write a Windows PowerShell snap-in that can be used to register the Get-Proc cmdlet in the Windows PowerShell shell. Имейте в виду, что в этом примере полная сборка будет содержать только класс оснастки GetProcPSSnapIn01 и Get-Proc класс командлета. Be aware that in this example, the complete assembly would contain only the GetProcPSSnapIn01 snap-in class and the Get-Proc cmdlet class.

Add-PSSnapin

Adds one or more Windows PowerShell snap-ins to the current session.

Syntax

Description

The Add-PSSnapin cmdlet adds registered Windows PowerShell snap-ins to the current session. After the snap-ins are added, you can use the cmdlets and providers that the snap-ins support in the current session.

To add the snap-in to all future Windows PowerShell sessions, add an Add-PSSnapin command to your Windows PowerShell profile. For more information, see about_Profiles.

Beginning in Windows PowerShell 3.0, the core commands that are included in Windows PowerShell are packaged in modules. The exception is Microsoft.PowerShell.Core, which is a snap-in (PSSnapin). By default, only the Microsoft.PowerShell.Core snap-in is added to the session. Modules are imported automatically on first use and you can use the Import-Module cmdlet to import them.

Examples

Example 1: Add snap-ins

This command adds the Microsoft Exchange and Active Directory snap-ins to the current session.

Example 2: Add all the registered snap-ins

This command adds all of the registered Windows PowerShell snap-ins to the session. It uses the Get-PSSnapin cmdlet with the Registered parameter to get objects representing each of the registered snap-ins. The pipeline operator (|) passes the result to Add-PSSnapin , which adds them to the session. The PassThru parameter returns objects that represent each of the added snap-ins.

Example 3: Register a snap-in and add it

The first command gets snap-ins that have been added to the current session that include the snap-ins that are installed with Windows PowerShell. In this example, ManagementFeatures is not returned. This indicates that it has not been added to the session.

The second command gets snap-ins that have been registered on your system, which includes those that have already been added to the session. It does not include the snap-ins that are installed with Windows PowerShell. In this case, the command does not return any snap-ins. This indicates that the ManagementFeatures snapin has not been registered on the system.

The third command creates an alias, installutil, for the path of the InstallUtil tool in .NET Framework.

The fourth command uses the InstallUtil tool to register the snap-in. The command specifies the path of ManagementCmdlets.dll, the filename or module name of the snap-in.

The fifth command is the same as the second command. This time, you use it to verify that the ManagementCmdlets snap-in is registered.

The sixth command uses the Add-PSSnapin cmdlet to add the ManagementFeatures snap-in to the session. It specifies the name of the snap-in, ManagementFeatures, not the file name.

To verify that the snap-in is added to the session, the seventh command uses the Module parameter of the Get-Command cmdlet. It displays the items that were added to the session by a snap-in or module.

You can also use the PSSnapin property of the object that the Get-Command cmdlet returns to find the snap-in or module in which a cmdlet originated. The eighth command uses dot notation to find the value of the PSSnapin property of the Set-Alias cmdlet.

This example demonstrates the process of registering a snap-in on your system and then adding it to your session. It uses ManagementFeatures, a fictitious snap-in implemented in a file that is named ManagementCmdlets.dll.

Parameters

Specifies the name of the snap-in. This is the Name, not the AssemblyName or ModuleName. Wildcards are permitted.

To find the names of the registered snap-ins on your system, type Get-PSSnapin -Registered .

Type:	String [ ]
Position:	0
Default value:	None
Accept pipeline input:	True
Accept wildcard characters:	True

Indicates that this cmdlet returns an object that represents each added snap-in. By default, this cmdlet does not generate any output.

Type:	SwitchParameter
Position:	Named
Default value:	None
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

None

You cannot pipe objects to this cmdlet.

Outputs

None or System.Management.Automation.PSSnapInInfo

This cmdlet returns a PSSnapInInfo object that represents the snap-in if you specify the PassThru parameter. Otherwise, this cmdlet does not generate any output.

Notes

Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins (PSSnapins). The exception is Microsoft.PowerShell.Core, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins.

For information about the CreateDefault2 method that creates newer-style sessions with core modules, see CreateDefault2 Method.

Add-PSSnapin adds the snap-in only to the current session. To add the snap-in to all Windows PowerShell sessions, add it to your Windows PowerShell profile. For more information, see about_Profiles.

You can add any snap-in that has been registered using the Microsoft .NET Framework install utility. For more information, see How to Register Cmdlets, Providers, and Host Applications.

To get a list of snap-ins that are registered on your computer, type Get-PSSnapin -Registered .

Before adding a snap-in, Add-PSSnapin checks the version of the snap-in to verify that it is compatible with the current version of Windows PowerShell. If the snap-in fails the version check, Windows PowerShell reports an error.