about_PowerShell_Config

  • Artigo

Breve descrição

Arquivos de configuração para 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 Linux.

Resumo das configurações

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

Âmbito da configuração

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

Configuração de AllUsers (compartilhada)

Um powershell.config.json arquivo no diretório define a $PSHOME configuração para 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 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 do âmbito de aplicação

No Windows, as definições geridas pela Política de Grupo do Windows têm precedência sobre as definições no ficheiro de configuração. A Política de Grupo não existe em plataformas que não sejam 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 só se aplicam 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 devem ser agrupados carregando a versão do módulo do Windows PowerShell 5.1.

Para obter mais informações, consulte about_Windows_PowerShell_Compatibility.

Política de Execução

Importante

Esta 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 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 obter mais informações, consulte about_Execution_Policies.

PowerShellPolíticas

O Windows tem várias configurações que podem ser gerenciadas pela Diretiva 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 chave-valor para as várias configurações de política. Essas configurações de diretiva 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 definições de política, consulte as descrições na secçã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 PowerShellPolicies, e 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, veja about_Group_Policy_Settings.

Configurações para plataformas que não sejam 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 que não sejam Windows, consulte about_Logging_Non-Windows.

Definições de configuração comuns

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

  • 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. Isso pode ser qualquer ponto de extremidade registrado na máquina local, incluindo os pontos de extremidade de comunicação remota padrão do PowerShell ou um ponto de extremidade personalizado com recursos específicos de função de usuário.

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

Características 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 é iniciado.

Exemplo:

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

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

ModuleLogging

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

  • EnableModuleLogging - Para habilitar as configurações de sessão, 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"
    ]
  }
}

ProtectedEventLogging

Esta definição permite-lhe configurar o Registo de Eventos Protegido. A configuração contém duas subchaves:

  • EnableProtectedEventLogging - Se você habilitar essa configuração de política, os componentes que a suportam usarão o certificado fornecido para criptografar os 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"
    ]
  }
}

PSModulePath

Substitui as PSModulePath configurações para esta sessão do 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, defina 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 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 respetiva 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 incorporando-as entre % caracteres, como "%HOME%\Documents\PowerShell\Modules", da mesma forma que o Shell de Comando do Windows permite. Esta sintaxe também se aplica ao Linux e macOS. Veja abaixo os exemplos.

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 HOME variável de 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 em macOS e Linux:

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

Nota

As variáveis do PowerShell não podem ser incorporadas em PSModulePath configurações. PSModulePath as configurações no Linux e 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 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 invocados interativamente ou por meio de automação.
  • EnableScriptBlockInvocationLogging - Permite o registro de eventos de início e parada de bloco de script.

Exemplo:

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

Transcrição

Esta 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 - Esta configuração permite que você colete 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 Start-Transcript.

Ajuda atualizável

Esta configuração de política permite definir 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"
    }
}