Snap-in do PowerShell: alterar as configurações simples nas Seções de Configuração

Artigo
03/12/2024

No passo a passo anterior, você aprendeu a gerenciar contêineres de namespace do IIS, como Sites, Pools de Aplicativos, Aplicativos e Diretórios Virtuais.

Neste passo a passo, gerenciaremos as configurações que não são expostas por meio do namespace do IIS.

Introdução

Há vários cmdlets que permitem alterar as configurações do IIS não configuráveis por meio do namespace do IIS, ou seja, não é possível usar cmdlets internos para modificá-las. Em vez disso, é necessário usar os cmdlets fornecidos pelo IIS. Este passo a passo se baseia em, aplicativos e diretórios virtuais que criamos em passo a passo anteriores.

Get-WebConfiguration e Get-WebConfigurationProperty

O Get-WebConfiguration e o Get-WebConfigurationProperty, permitem que você obtenha seções de configuração do IIS. Eles são muito semelhantes a Get-Item e Get-ItemProperty. Onde tem o Get-Item* funciona apenas em contêineres de namespace (Sites, Aplicativos, AppPools, VDirs), o Get-WebConfiguration* funcionará em qualquer seção de configuração do IIS.

Consultar definições de configuração

Vamos analisar quais configurações para a seção directoryBrowse estão habilitadas no aplicativo DemoApp, que criamos anteriormente. Primeiro, navegamos até a pasta do DemoApp e, em seguida, consultamos as configurações de autenticação nessa pasta. Veja como fazer isso:

PS IIS:\> cd IIS:\Sites\DemoSite\DemoApp
PS IIS:\Sites\DemoSite\DemoApp> dir
Type               Name                             Physical Path
----               ----                             -------------
file               Default.htm                      C:\DemoSite\DemoApp\Default.htm
virtualDirectory   DemoVirtualDir2                  C:\DemoSite\DemoVirtualDir2

No próximo exemplo, estamos usando o parâmetro -filter para especificar a seção de configuração na qual estamos interessados e o parâmetro -name para especificar em qual propriedade queremos examinar. Caso queira visualizar as configurações de uma seção que não é o local atual, use a propriedade -PSPath sobre ela. Aqui está um exemplo de como você consultaria as configurações de navegação de diretório no Site Padrão:

Get-WebConfigurationProperty -filter /system.webServer/directoryBrowse -name enabled -PSPath 'IIS:\Sites\Default Web Site'
ItemXPath                   : /system.webServer/directoryBrowse
IsInheritedFromDefaultValue : False
IsProtected                 : False
Name                        : enabled
TypeName                    : System.Boolean
Schema                      : Microsoft.IIs.PowerShell.Framework.ConfigurationAttributeSchema
Value                       : False
IsExtended                  : False

Usar o Set-WebConfigurationProperty

Alterar a configuração é tão simples quanto:

Lidar com seções bloqueadas

Aqui está um problema. As seções de autenticação geralmente são bloqueadas, ou seja, elas não podem ser gravadas em um arquivo web.config, mas precisam ser gravadas no arquivo central applicationhost.config. O uso do comando acima para habilitar o WindowsAuthentication falharia com uma violação de bloqueio:

PS IIS:\Sites\DemoSite\DemoApp> Set-WebConfigurationProperty -filter /system.webServer/security/authentication/windowsAuthentication -name enabled -value true
Set-WebConfigurationProperty : This configuration section cannot be used at this path. This happens
 when the section is locked at a parent level. Locking is either by default (overrideModeDefault="D
eny"), or set explicitly by a location tag with overrideMode="Deny" or the legacy allowOverride="fa
lse".
At line:1 char:29
+ Set-WebConfigurationProperty  <<<< -filter /system.webServer/security/authentication/windowsAuthentication -name enabled -value true

O que você precisa fazer aqui é usar o parâmetro -PSPath e -location. O comando a seguir habilitará a Autenticação do Windows para o Aplicativo DemoApp. No entanto, a configuração é gravada em applicationhost.config usando uma marca de localização. Clique aqui para encontrar mais informações sobre bloqueio e marcas de localização.

PS IIS:\Sites\DemoSite\DemoApp> Set-WebConfigurationProperty -filter /system.webServer/security/authentication/windowsAuthentication -name enabled -value true -PSPath IIS:\ -location DemoSite/DemoApp

No entanto, não é necessário especificar locais ao consultar a configuração. O comando Get-WebConfigurationProperty regular mostrará que a configuração está habilitada.

PS IIS:\Sites\DemoSite\DemoApp> Get-WebConfigurationProperty -filter /system.webServer/security/authentication/windowsAuthentication -name enabled
True

Get-WebConfiguration versus Get-WebConfigurationProperty

O mesmo se aplica a Get-Item versus Get-ItemProperty no exemplo anterior. O Get-WebConfiguration obtém a seção inteira em vez de apenas uma propriedade. Isso permite armazenar a seção em uma variável, fazer modificações nas propriedades da seção e salvar a seção novamente por meio de Set-WebConfiguration. E você obtém o benefício da conclusão do comando.

Veja um exemplo. Não basta copiar e colar. Explore as propriedades da seção de windowsAuthentication. Digite $winAuth. e pressione a tecla <TAB> para iterar por meio das propriedades e funções disponíveis.

PS IIS:\Sites\DemoSite\DemoApp> $winAuth = Get-WebConfiguration -filter /system.webServer/security/authentication/windowsAuthentication 
PS IIS:\Sites\DemoSite\DemoApp> $winAuth.enabled = $false
PS IIS:\Sites\DemoSite\DemoApp> $winAuth | set-Webconfiguration -filter /system.webServer/security/authentication/windowsAuthentication -PSPath IIS:\ -location "DemoSite/DemoApp"

Add-WebConfiguration

O Add-WebConfiguration é um cmdlet que você deseja usar se precisar adicionar algo a uma coleção de configurações do IIS. Manipuladores, módulos, configurações de documento padrão e alguns outros exemplos em que o IIS usa uma coleção para armazenar vários valores.

Aqui está um exemplo de como adicionar um novo documento padrão à coleção de documentos padrão do DemoApp:

PS IIS:\Sites\DemoSite\DemoApp>Add-WebConfiguration /system.webServer/defaultDocument/files  "IIS:\sites\Default Web Site" -at 0 -value
@{value="new-index.html"}

O exemplo usa o parâmetro adicional -at. Isso permite especificar onde na coleção deseja adicionar o novo valor. 0 está no início; -1 especifica o final.

Resumo

Neste passo a passo, você aprendeu a usar os cmdlets de configuração da Web fornecidos pelo IIS. Você aprendeu a consultar as configurações de configuração, como definir configurações usando marcas de localização, como aproveitar a conclusão da linha de comando e como adicionar entradas a coleções.

No próximo passo a passo, você aprenderá a realizar algumas tarefas de configuração complexas usando recursos avançados do Provedor do IIS, como globbing e XPath.

Share via