about_PowerShell_Config

Descrição breve

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

Nem todas as chaves se aplicam a todas as plataformas. A PowerShellPolicies chave contém subchaves que espelham as configurações gerenciadas pela Política de Grupo do Windows. 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 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.

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.

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 em todas as 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 não Windows.

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

Configurações específicas do Windows

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

• DisableImplicitWinCompat
• WindowsPowerShellCompatibilityModuleDenyList
• WindowsPowerShellCompatibilityNoClobberModuleList
• ExecutionPolicy
• PowerShellPolicies

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.

ExecutionPolicy

Importante

Essa configuração só se aplica a 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 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.

Políticas do PowerShell

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

O PowerShellPolicies é um objeto JSON que contém pares de 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 PowerShellPolicies objeto. Essa configuração pode conter as seguintes subchaves:

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

A ScriptExecution configuração é usada para definir a Política de Execução do PowerShell. Isso tem precedência sobre a ExecutionPolicy configuração 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 Definições de configuração comuns.

No Windows, o PowerShell procura as configurações no registro. Todas as configurações encontradas no registro têm precedência. Em seguida, o 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.

Confira mais informações em about_Group_Policy_Settings.

Configurações para plataformas não Windows

As configurações a seguir se aplicam apenas à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.

Definições de configuração comuns

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

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

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.

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.

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"
    ]
  }
}

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\\6\\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.

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á o processamento de comandos, blocos de script, funções e scripts, sejam invocados interativamente ou por meio da automação.
• EnableScriptBlockInvocationLogging - Habilita o registro de eventos de início e parada do bloco de script.

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 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"
    }
}