about_PowerShell_Config

Descrição curta

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

Descrição longa

O powershell.config.json arquivo contém definições de configuração para o PowerShell. O PowerShell carrega essa configuração na inicialização. As configurações também podem ser modificadas em tempo de execução. Nem todas as chaves se aplicam a todas as plataformas.

Aviso

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

Resumo das configurações

O powershell.config.json arquivo 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

Escopo de configuração

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

Precedência de escopo

Com exceção de alguns casos especiais, as configurações definidas no nível do CurrentUser têm precedência sobre as configurações definidas para o nível de AllUsers .

Em sistemas de Windows:

  • As configurações gerenciadas por Windows Política de Grupo têm precedência sobre as configurações nos arquivos de configuração.
  • Configurações de nível de escopo de suporte da Política de Execução.

Em todas as plataformas:

  • O valor $env:PSModulePath resultante é uma mesclagem dos valores da PSModulePath chave de ambos os escopos.

Configuração de AllUsers (compartilhada)

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

Observação

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

Configurações 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 seguinte comando:

Split-Path $PROFILE.CurrentUserCurrentHost

Configurações específicas do Windows

As configurações a seguir se aplicam apenas a plataformas Windows.

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • Microsoft.PowerShell:ExecutionPolicy
  • PowerShellPolicies
    • ScriptExecution

DisableImplicitWinCompat

Quando definida 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 deve ser substituída carregando a versão Windows PowerShell 5.1 do módulo.

Para obter mais informações, consulte about_Windows_PowerShell_Compatibility.

Microsoft. PowerShell:ExecutionPolicy

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 AllUsers , isso define a política de execução LocalMachine . Para configurações CurrentUser , isso define a política de execução CurrentUser .

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

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

Para mais informações, veja about_Execution_Policies.

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

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

Use as seguintes chaves 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 suportadas.

  • ExperimentalFeatures
  • PSModulePath
  • PowerShellPolicies

Recursos experimentais

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

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

Exemplo:

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

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

Caminho PSModule

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

Aviso

Configurar um caminho de módulo AllUsers ou CurrentUser aqui 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 exemplos abaixo.

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

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

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

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

Este exemplo mostra a incorporação de uma variável de ambiente em uma PSModulePath configuração. Observe que, usando a variável de HOME ambiente 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"
}

Observação

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

Políticas do PowerShell

É PowerShellPolicies um objeto JSON que contém pares chave-valor para as várias configurações. Com exceção da ScriptExecution configuração, todas as configurações podem ser usadas em plataformas Windows, Linux e macOS.

PowerShellPolicies contém as seguintes subchaves:

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

Em Windows, essas configurações podem ser gerenciadas por Windows Política de Grupo. As configurações de Política de Grupo têm precedência. Se um valor não for definido pela Política de Grupo, o PowerShell aplicará os valores no arquivo JSON na ordem de precedência de escopo .

A Política de Grupo é a maneira recomendada de gerenciar essas configurações em sistemas Windows. Confira mais informações em about_Group_Policy_Settings.

Configuração da Sessão do Console

Essa configuração especifica a configuração de sessão a ser usada para todas as sessões do PowerShell. 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 recursos de função de usuário específicos.

Essa chave contém duas subchaves:

  • EnableConsoleSessionConfiguration - Para ativar 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á sessão definida.

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

Para obter mais informações, consulte about_Session_Configurations.

Registro de Módulo

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

  • EnableModuleLogging - Para ativar o registro do módulo, defina o valor como true. Quando habilitado, 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.

Exemplo:

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

Registro de eventos protegido

Essa configuração permite configurar 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 oferecem suporte a ela usarão o certificado fornecido para criptografar dados de log antes de gravá-los no log. Os dados são criptografados usando o padrão CMS (Cryptographic Message Syntax). 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"
    ]
  }
}

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
}

ScriptExecution

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

Exemplo:

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

Observação

Essa é uma configuração somente Windows.

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 desativar 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 Transcrição inicial.

Ajuda atualizável

Essa configuração de política permite que você defina o valor padrão do parâmetro SourcePath no Update-Help cmdlet. 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