about_Using

Artigo
05/09/2024

Breve descrição

Permite-lhe especificar espaços de nomes a utilizar na sessão.

Descrição longa

A using instrução permite-lhe especificar espaços de nomes a utilizar na sessão. A adição de espaços de nomes simplifica a utilização de classes e membros .NET e permite-lhe importar classes de módulos de script e assemblagens.

As using instruções têm de ser apresentadas antes de quaisquer outras instruções num script ou módulo. Nenhuma instrução não consolidada pode precedê-la, incluindo parâmetros.

A using instrução não pode conter variáveis.

A using instrução não é a mesma que o modificador de using: âmbito para variáveis. Para obter mais informações, veja about_Remote_Variables.

Sintaxe do espaço de nomes

Para resolver tipos a partir de um espaço de nomes .NET:

using namespace <.NET-namespace>

Especificar um espaço de nomes facilita a referência de tipos pelos respetivos nomes curtos.

Exemplo – Adicionar espaços de nomes para resolução de nomes de tipo

O script seguinte obtém o hash criptográfico para a cadeia “Hello World”.

Tenha em atenção como as using namespace System.Text e using namespace System.IO simplificam as referências a [UnicodeEncoding] dentro System.Text e [Stream][MemoryStream] em System.IO.

using namespace System.Text
using namespace System.IO

[string]$string = "Hello World"
## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5"
[string]$algorithm = "SHA256"

[byte[]]$stringBytes = [UnicodeEncoding]::Unicode.GetBytes($string)

[Stream]$memoryStream = [MemoryStream]::new($stringBytes)
$getFileHashSplat = @{
    InputStream = $memoryStream
    Algorithm   = $algorithm
}
$hashFromStream = Get-FileHash @getFileHashSplat
$hashFromStream.Hash.ToString()

Sintaxe do módulo

Para carregar classes e enumerações a partir de um módulo do PowerShell:

using module <module-name>

O valor de pode ser um nome de <module-name> módulo, uma especificação de módulo completa ou um caminho para um ficheiro de módulo.

Quando <module-name> é um caminho, o caminho pode ser completamente qualificado ou relativo. Um caminho relativo é resolvido relativamente ao script que tem a using instrução.

Quando <module-name> é uma especificação de nome ou módulo, o PowerShell procura no PSModulePath o módulo especificado.

Uma especificação de módulo é uma tabela hash que tem as seguintes chaves.

ModuleName - Necessário Especifica o nome do módulo.
GUID - Opcional Especifica o GUID do módulo.
Também é necessário especificar pelo menos uma das três chaves abaixo.
- ModuleVersion - Especifica uma versão aceitável mínima do módulo.
- MaximumVersion - Especifica a versão máxima aceitável do módulo.
- RequiredVersion - Especifica uma versão exata e necessária do módulo. Isto não pode ser utilizado com as outras chaves de Versão.

Import-Module e a #requires instrução só importa as funções, aliases e variáveis do módulo, conforme definido pelo módulo. As classes e enumerações não são importadas.

A using module instrução importa classes e enumerações do módulo de raiz (ModuleToProcess) de um módulo de script ou módulo binário. Não importa consistentemente classes ou enumerações definidas em módulos aninhados ou em scripts que são de origem de pontos no módulo raiz. Defina as classes e enumerações que pretende que estejam disponíveis para utilizadores fora do módulo diretamente no módulo de raiz.

Durante o desenvolvimento de um módulo de script, é comum fazer alterações ao código e, em seguida, carregar a nova versão do módulo com Import-Module o parâmetro Force . Isto funciona apenas para alterações às funções no módulo de raiz. Import-Module não recarrega nenhum módulo aninhado. Além disso, não há forma de carregar classes ou enumerações atualizadas.

Para garantir que está a executar a versão mais recente, tem de iniciar uma nova sessão. As classes e enumerações definidas no PowerShell e importadas com uma using instrução não podem ser descarregadas.

Exemplo – Carregar classes a partir de um módulo de script

Neste exemplo, um módulo de script do PowerShell com o nome CardGames define as seguintes classes:

Deck
Cartão

Import-Module e a #requires instrução só importa as funções, aliases e variáveis do módulo, conforme definido pelo módulo. As classes não são importadas. O using module comando importa o módulo e também carrega as definições de classe.

using module CardGames

[Deck]$deck = [Deck]::new()
$deck.Shuffle()
[Card[]]$hand1 = $deck.Deal(5)
[Card[]]$hand2 = $deck.Deal(5)
[Card[]]$hand3 = $deck.Deal(5)

Sintaxe de assemblagem

A seguinte sintaxe carrega os tipos de .NET de uma assemblagem para um script no início da execução. Tem de utilizar um caminho completamente qualificado para o ficheiro de assemblagem.

using assembly <.NET-assembly-path>

A using assembly instrução é semelhante à utilização do Add-Type cmdlet. No entanto, o Add-Type cmdlet adiciona o tipo no momento em que Add-Type é executado, em vez de no início da execução do script. Para obter mais informações, veja Add-Type (Adicionar Tipo).

Exemplo - Tipos de carga de uma assemblagem

Este exemplo carrega uma assemblagem para que as respetivas classes possam ser utilizadas ao processar dados. O script seguinte converte dados num formato YAML.

using assembly './YamlDotNet.dll'
using namespace YamlDotNet

$yamlSerializer = [Serialization.Serializer]::new()

$info = [ordered]@{
  Inventory = @(
    @{ Name = 'Apples' ; Count = 1234 }
    @{ Name = 'Bagels' ; Count = 5678 }
  )
  CheckedAt = [datetime]'2023-01-01T01:01:01'
}

$yamlSerializer.Serialize($info)

Inventory:
- Name: Apples
  Count: 1234
- Name: Bagels
  Count: 5678
CheckedAt: 2023-01-01T01:01:01.0000000

Partilhar via