Compartilhar via

about_PowerShell_Config

Descrição curta

Arquivos de configuração do PowerShell, substituindo a configuração do Registro.

Descrição longa

O arquivo powershell.config.json contém as configurações do PowerShell. O PowerShell carrega essa configuração na inicialização. As configurações também podem ser modificadas em runtime. Anteriormente, essas configurações eram armazenadas no Registro do Windows para PowerShell, mas agora estão contidas em um arquivo para habilitar a configuração no macOS e no Linux.

Resumo das configurações

O arquivo powershell.config.json pode conter as seguintes chaves:

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • ExperimentalFeatures
  • LogChannels
  • LogIdentity
  • LogKeywords
  • LogLevel
  • Microsoft.PowerShell:ExecutionPolicy
  • PSModulePath
  • PowerShellPolicies
    • ExecutionPolicy
    • ConsoleSessionConfiguration
    • ModuleLogging
    • ProtectedEventLogging
    • ScriptBlockLogging
    • ScriptExecution
    • Transcription
    • UpdatableHelp

Nem todas as chaves se aplicam a todas as plataformas. A chave PowerShellPolicies contém subchaves que espelham as configurações gerenciadas pela Política de Grupo de Janelas. Essas subchaves também se aplicam a todas as plataformas quando definidas no nível raiz do arquivo JSON.

Aviso

Chaves não reconhecidas ou valores inválidos no arquivo de configuração são ignorados. Se o arquivo powershell.config.json contiver JSON inválido, o PowerShell não poderá iniciar uma sessão interativa. Se isso ocorrer, você deverá corrigir o arquivo de configuração.

Escopo de configuração

As configurações podem ser definidas para todos os usuários ou no nível de usuário individual.

Configuração de AllUsers (compartilhado)

Um arquivo powershell.config.json no diretório $PSHOME define a configuração de todas as sessões do PowerShell em execução a partir dessa instalação do PowerShell.

Nota

O $PSHOME local é definido como o mesmo diretório que o assembly de System.Management.Automation.dll em execução. Isso também se aplica a instâncias hospedadas do SDK do PowerShell.

Configurações do CurrentUser (por usuário)

Você também pode configurar o PowerShell por usuário colocando o arquivo no diretório de configuração do escopo do usuário. O diretório de configuração do usuário pode ser encontrado entre plataformas com o comando Split-Path $PROFILE.CurrentUserCurrentHost.

Precedência de escopo

No Windows, as configurações gerenciadas pela Política de Grupo do Windows têm precedência sobre as configurações no arquivo de configuração. A Política de Grupo não existe em plataformas que não são do Windows.

Após a Política de Grupo, as configurações definidas no nível de AllUsers têm precedência sobre as configurações definidas para o nível de CurrentUser.

Configurações específicas do Windows

As configurações a seguir se aplicam somente às plataformas Windows.

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • ExecutionPolicy
  • PowerShellPolicies

DisableImplicitWinCompat

Quando definido como true, essa configuração desabilita o recurso de compatibilidade do Windows PowerShell. A compatibilidade do Windows PowerShell permite que o PowerShell 7 carregue módulos do Windows PowerShell 5.1 no modo de compatibilidade.

Para obter mais informações, consulte about_Windows_PowerShell_Compatibility.

WindowsPowerShellCompatibilityModuleDenyList

Essa configuração é uma matriz de nomes de módulo que você deseja excluir da participação no recurso de compatibilidade do Windows PowerShell.

Para obter mais informações, consulte about_Windows_PowerShell_Compatibility.

WindowsPowerShellCompatibilityNoClobberModuleList

Essa configuração é uma matriz de nomes de módulo que não devem ser ignorados carregando a versão do Windows PowerShell 5.1 do módulo.

Para obter mais informações, consulte about_Windows_PowerShell_Compatibility.

ExecutionPolicy

Importante

Essa configuração só se aplica em plataformas Windows.

Configura a política de execução para sessões do PowerShell, determinando quais scripts podem ser executados. Por padrão, o PowerShell usa a política de execução existente.

Para configurações de de Todos os Usuários, isso define a política de execução de LocalMachine. Para configurações de do CurrentUser, isso define a política de execução do CurrentUser.

O exemplo a seguir define a política de execução do PowerShell como RemoteSigned.

{
  "Microsoft.PowerShell:ExecutionPolicy": "RemoteSigned"
}

Para obter mais informações, consulte about_Execution_Policies.

PowerShellPolicies

O Windows tem várias configurações que podem ser gerenciadas pela Política de Grupo. Normalmente, essas configurações são armazenadas no Registro do Windows. Essas configurações também podem ser definidas no arquivo powershell.config.json.

O PowerShellPolicies é um objeto JSON que contém pares chave-valor para as várias configurações de política. Essas configurações de política também podem ser listadas no nível raiz do arquivo JSON, fora do objeto PowerShellPolicies. Essa configuração pode conter as seguintes subchaves:

  • ConsoleSessionConfiguration
  • ModuleLogging
  • ProtectedEventLogging
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

A configuração de ScriptExecution é usada para definir a Política de Execução do PowerShell. Isso tem precedência sobre a configuração de ExecutionPolicy descrita acima.

Exemplo:

{
    "PowerShellPolicies": {
        "ScriptExecution": {
            "ExecutionPolicy": "RemoteSigned"
        }
    }
}

Para obter descrições das outras configurações de política, consulte as descrições na seção Configurações comuns seção.

No Windows, o PowerShell procura as configurações no Registro. Todas as configurações encontradas no registro têm precedência. O Próximo PowerShell lê a configuração JSON. Todas as configurações encontradas em PowerShellPoliciese não definidas no registro têm precedência sobre as configurações encontradas no nível raiz da configuração JSON.

Para obter mais informações, consulte about_Group_Policy_Settings.

Configurações para plataformas que não são do Windows

As configurações a seguir se aplicam somente às plataformas Linux e macOS.

As chaves a seguir são usadas para configurar o log do PowerShell para Linux e macOS.

  • LogChannels
  • LogIdentity
  • LogKeywords
  • LogLevel

Para obter uma descrição completa do log do PowerShell para sistemas não Windows, consulte about_Logging_Non-Windows.

Configurações comuns

As configurações a seguir estão disponíveis em todas as plataformas com suporte.

  • ConsoleSessionConfiguration
  • ExperimentalFeatures
  • ModuleLogging
  • ProtectedEventLogging
  • PSModulePath
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

ConsoleSessionConfiguration

Essa configuração especifica a configuração de sessão a ser usada para todas as sessões do PowerShell. Esse pode ser qualquer ponto de extremidade registrado no computador local, incluindo os pontos de extremidade de comunicação remota padrão do PowerShell ou um ponto de extremidade personalizado com funcionalidades de função de usuário específicas.

Essa chave contém duas subchaves:

  • EnableConsoleSessionConfiguration – para habilitar as configurações de sessão, defina o valor como true. Por padrão, esse valor é false.

  • ConsoleSessionConfigurationName – especifica o nome do ponto de extremidade de configuração no qual o PowerShell é executado. Por padrão, não há nenhuma sessão definida.

{
  "ConsoleSessionConfiguration": {
    "EnableConsoleSessionConfiguration": false,
    "ConsoleSessionConfigurationName" : []
  }
}

Para obter mais informações, consulte about_Session_Configurations.

ExperimentalFeatures

Os nomes dos recursos experimentais a serem habilitados no PowerShell. O valor padrão é uma matriz vazia.

O exemplo a seguir habilita o PSCommandNotFoundSuggestion e PSSubsystemPluginModel recursos experimentais quando o PowerShell é iniciado.

Exemplo:

{
  "ExperimentalFeatures": [
    "PSCommandNotFoundSuggestion",
    "PSSubsystemPluginModel"
  ]
}

Para obter mais informações sobre recursos experimentais, consulte Usando recursos experimentais.

Log de Módulos

Essa configuração controla o comportamento do registro em log para módulos do PowerShell. A configuração contém duas subchaves:

  • EnableModuleLogging – para habilitar o registro em log do módulo, defina o valor como true. Quando habilitados, os eventos de execução de pipeline para membros dos módulos especificados são registrados nos arquivos de log do PowerShell.
  • ModuleNames – especifica o nome dos módulos que devem ser registrados em log.

Exemplo:

{
  "ModuleLogging": {
    "EnableModuleLogging": true,
    "ModuleNames" : [
        "PSReadLine",
        "PowerShellGet"
    ]
  }
}

ProtectedEventLogging

Essa configuração permite que você configure o Log de Eventos Protegidos. A configuração contém duas subchaves:

  • EnableProtectedEventLogging - Se você habilitar essa configuração de política, os componentes que dão suporte a ela usarão o certificado fornecido para criptografar dados de log antes de escrevê-los no log. Os dados são criptografados usando o padrão CMS (Sintaxe de Mensagem Criptográfica). Você pode usar Unprotect-CmsMessage para descriptografar essas mensagens criptografadas se tiver acesso à chave privada do certificado.
  • EncryptionCertificate - Fornece uma lista de nomes de certificados a serem usados para criptografia.

Exemplo:

{
  "ProtectedEventLogging": {
    "EnableProtectedEventLogging": false,
    "EncryptionCertificate": [
      "Joe"
    ]
  }
}

PSModulePath

Substitui as configurações de PSModulePath para esta sessão do PowerShell. Se a configuração for para o usuário atual, definirá o caminho do módulo CurrentUser. Se a configuração for para todos os usuários, definirá o os AllUsers caminho do módulo.

Aviso

Configurar um de Todos os Usuários ou o caminho do módulo CurrentUser não altera o local de instalação com escopo para cmdlets do PowerShellGet, como Install-Module. Esses cmdlets sempre usam os caminhos de módulo padrão.

Se nenhum valor for definido, o PowerShell usará o valor padrão para a respectiva configuração de caminho do módulo. Para obter mais informações sobre esses padrões, consulte about_PSModulePath.

Essa configuração permite que variáveis de ambiente sejam usadas inserindo-as entre % caracteres, como "%HOME%\Documents\PowerShell\Modules", da mesma forma que o Shell de Comando do Windows permite. Essa sintaxe também se aplica ao Linux e ao macOS. Veja abaixo exemplos.

Este exemplo mostra uma configuração de PSModulePath para um ambiente do Windows:

{
  "PSModulePath": "C:\\Program Files\\PowerShell\\6\\Modules"
}

Este exemplo mostra uma configuração de PSModulePath para um ambiente macOS ou Linux:

{
  "PSModulePath": "/opt/powershell/6/Modules"
}

Este exemplo mostra a inserção de uma variável de ambiente em uma configuração de PSModulePath. Observe que, usando a variável de ambiente HOME e o separador de diretório /, essa sintaxe funciona no Windows, macOS e Linux.

{
  "PSModulePath": "%HOME%/Documents/PowerShell/Modules"
}

Este exemplo usa uma variável de ambiente que só funciona no macOS e no Linux:

{
  "PSModulePath": "%XDG_CONFIG_HOME%/powershell/Modules"
}

Nota

As variáveis do PowerShell não podem ser inseridas em configurações de PSModulePath. PSModulePath configurações no Linux e no macOS diferenciam maiúsculas de minúsculas. Uma configuração de PSModulePath deve usar separadores de diretório válidos para a plataforma. No macOS e no Linux, isso significa /. No Windows, / e \ funcionam.

ScriptBlockLogging

Essa configuração controla o registro em log de todas as entradas de script do PowerShell. Essa configuração contém duas subchaves:

  • EnableScriptBlockLogging - Se você habilitar essa configuração de política, o PowerShell registrará em log o processamento de comandos, scriptblocks, funções e scripts, sejam invocados interativamente ou por meio da automação.
  • EnableScriptBlockInvocationLogging – habilita o registro em log de eventos de início e parada do scriptblock.

Exemplo:

"ScriptBlockLogging": {
  "EnableScriptBlockInvocationLogging": true,
  "EnableScriptBlockLogging": false
}

Transcrição

Essa configuração de política permite capturar a entrada e a saída de comandos do PowerShell em transcrições baseadas em texto. Se você habilitar essa configuração de política, o PowerShell habilitará a transcrição para todas as sessões do PowerShell.

Essa configuração controla como a transcrição funciona no PowerShell. Essa configuração contém três subchaves:

  • EnableTranscripting - Quando essa configuração está habilitada, o PowerShell cria arquivos de log de transcrição no local configurado.
  • EnableInvocationHeader - Por padrão, o PowerShell inclui um cabeçalho na parte superior do arquivo de log de transcrição. Você pode desabilitar o cabeçalho usando essa configuração.
  • OutputDirectory - Essa configuração permite coletar arquivos de log de transcrição em um local central em vez do local padrão.

Exemplo:

{
    "Transcription": {
        "EnableTranscripting": true,
        "EnableInvocationHeader": true,
        "OutputDirectory": "C:\\tmp"
      }
}

Para obter mais informações, consulte de início da transcrição.

UpdatableHelp

Essa configuração de política permite que você defina o valor padrão do parâmetro SourcePath no cmdlet Update-Help. Esse valor padrão pode ser substituído especificando um valor diferente usando o parâmetro SourcePath.

Exemplo:

{
    "UpdatableHelp": {
      "DefaultSourcePath": "F:\\temp"
    }
}
  • Last updated on