Guia de início rápido do host do Windows PowerShell

Para hospedar o Windows PowerShell em seu aplicativo, use a classe System.Management.Automation.PowerShell. Essa classe fornece métodos que criam um pipeline de comandos e, em seguida, executam esses comandos em um espaço de execução. A maneira mais simples de criar um aplicativo host é usar o espaço de execução padrão. O espaço de execução padrão contém todos os comandos principais do Windows PowerShell. Se desejar que seu aplicativo exponha apenas um subconjunto dos comandos do Windows PowerShell, crie um espaço de execução personalizado.

Observação

Para executar os exemplos a seguir, você precisa ter o Microsoft.PowerShell.SDK pacote NuGet instalado.

Usando o espaço de execução padrão

Para começar, usaremos o espaço de execução padrão e usaremos os métodos da classe System.Management.Automation.PowerShell do para adicionar comandos, parâmetros, instruções e scripts a um pipeline.

AddCommand

Use o System.Management.Automation.PowerShell.AddCommand método para adicionar comandos ao pipeline. Por exemplo, suponha que você queira obter a lista de processos em execução na máquina. A maneira de executar esse comando é a seguinte.

1. Crie um objeto System.Management.Automation.PowerShell.

   PowerShell ps = PowerShell.Create();
   

2. Adicione o comando que você deseja executar.

   ps.AddCommand("Get-Process");
   

3. Invoque o comando.

   ps.Invoke();
   

Se você chamar o método AddCommand mais de uma vez antes de chamar o System.Management.Automation.PowerShell.Invoke método, o resultado do primeiro comando será canalizado para o segundo e assim por diante. Se você não quiser canalizar o resultado de um comando anterior para um comando, adicione-o chamando o System.Management.Automation.PowerShell.AddStatement vez disso.

AddParameter

O exemplo anterior executa um único comando sem parâmetros. Você pode adicionar parâmetros ao comando usando o System.Management.Automation.PSCommand.AddParameter método. Por exemplo, o código a seguir obtém uma lista de todos os processos nomeados powershell em execução na máquina.

PowerShell.Create().AddCommand("Get-Process")
                   .AddParameter("Name", "powershell")
                   .Invoke();

Você pode adicionar parâmetros adicionais chamando o método AddParameter repetidamente.

PowerShell.Create().AddCommand("Get-ChildItem")
                   .AddParameter("Path", @"C:\Windows")
                   .AddParameter("Filter", "*.exe")
                   .Invoke();

Você também pode adicionar um dicionário de nomes e valores de parâmetros chamando o System.Management.Automation.PowerShell.AddParameters método.

var parameters = new Dictionary<string, string>
{
    { "Path", @"C:\Windows" },
    { "Filter", "*.exe" }
};

PowerShell.Create().AddCommand("Get-Process")
                   .AddParameters(parameters)
                   .Invoke()

AddStatement

Você pode simular o processamento em lote usando o System.Management.Automation.PowerShell.AddStatement método, que adiciona uma instrução adicional ao final do pipeline. O código a seguir obtém uma lista de processos em execução com o nome powershelle, em seguida, obtém a lista de serviços em execução.

PowerShell ps = PowerShell.Create();
ps.AddCommand("Get-Process").AddParameter("Name", "powershell");
ps.AddStatement().AddCommand("Get-Service");
ps.Invoke();

AddScript

Você pode executar um script existente chamando o System.Management.Automation.PowerShell.AddScript método. O exemplo a seguir adiciona um script ao pipeline e o executa. Este exemplo pressupõe que já exista um script chamado MyScript.ps1 em uma pasta chamada D:\PSScripts.

PowerShell ps = PowerShell.Create();
ps.AddScript(@"D:\PSScripts\MyScript.ps1").Invoke();

Há também uma versão do método AddScript que usa um parâmetro booleano chamado useLocalScope. Se esse parâmetro for definido como true, o script será executado no escopo local. O código a seguir executará o script no escopo local.

PowerShell ps = PowerShell.Create();
ps.AddScript(@"D:\PSScripts\MyScript.ps1", true).Invoke();

Criando um espaço de execução personalizado

Embora o espaço de execução padrão usado nos exemplos anteriores carregue todos os comandos principais do Windows PowerShell, você pode criar um espaço de execução personalizado que carregue apenas um subconjunto especificado de todos os comandos. Você pode querer fazer isso para melhorar o desempenho (carregar um número maior de comandos é um acerto de desempenho) ou para restringir a capacidade do usuário de executar operações. Um espaço de execução que expõe apenas um número limitado de comandos é chamado de espaço de execução restrito. Para criar um espaço de execução restrito, use o System.Management.Automation.Runspaces.Runspace e classes de System.Management.Automation.Runspaces.InitialSessionState.

Criando um objeto InitialSessionState

Para criar um espaço de execução personalizado, você deve primeiro criar um objeto System.Management.Automation.Runspaces.InitialSessionState. No exemplo a seguir, usamos o System.Management.Automation.Runspaces.RunspaceFactory para criar um espaço de execução depois de criar um objeto InitialSessionState padrão.

InitialSessionState iss = InitialSessionState.CreateDefault();

Runspace rs = RunspaceFactory.CreateRunspace(iss);
rs.Open();

PowerShell ps = PowerShell.Create();
ps.Runspace = rs;
ps.AddCommand("Get-Command");
ps.Invoke();

rs.Close();

Restringindo o espaço de corrida

No exemplo anterior, criamos um objeto padrão System.Management.Automation.Runspaces.InitialSessionState que carrega todo o núcleo interno do Windows PowerShell. Também poderíamos ter chamado o método System.Management.Automation.Runspaces.InitialSessionState.CreateDefault2 para criar um objeto InitialSessionState que carregaria apenas os comandos no snapin Microsoft.PowerShell.Core. Para criar um espaço de execução mais restrito, você deve criar um objeto InitialSessionState vazio chamando o System.Management.Automation.Runspaces.InitialSessionState.Create método e, em seguida, adicionar comandos ao InitialSessionState.

O uso de um espaço de execução que carrega apenas os comandos especificados fornece um desempenho significativamente melhorado.

Use os métodos da classe System.Management.Automation.Runspaces.SessionStateCmdletEntry para definir cmdlets para o estado inicial da sessão. O exemplo a seguir cria um estado de sessão inicial vazio e, em seguida, define e adiciona os comandos Get-Command e Import-Module ao estado da sessão inicial. Em seguida, criamos um espaço de execução limitado por esse estado de sessão inicial e executamos os comandos nesse espaço de execução.

Crie o estado inicial da sessão.

InitialSessionState iss = InitialSessionState.Create();

Defina e adicione comandos ao estado inicial da sessão.

SessionStateCmdletEntry getCommand = new SessionStateCmdletEntry(
    "Get-Command", typeof(Microsoft.PowerShell.Commands.GetCommandCommand), "");
SessionStateCmdletEntry importModule = new SessionStateCmdletEntry(
    "Import-Module", typeof(Microsoft.PowerShell.Commands.ImportModuleCommand), "");

iss.Commands.Add(getCommand);
iss.Commands.Add(importModule);

Crie e abra o espaço de execução.

Runspace rs = RunspaceFactory.CreateRunspace(iss);
rs.Open();

Execute um comando e mostre o resultado.

PowerShell ps = PowerShell.Create();
ps.Runspace = rs;
ps.AddCommand("Get-Command");

Collection<CommandInfo> result = ps.Invoke<CommandInfo>();

foreach (CommandInfo entry in result)
{
    Console.WriteLine(entry.Name);
}

Feche o espaço de execução.

rs.Close();

Quando executado, a saída desse código terá a seguinte aparência.

Get-Command
Import-Module