about_Using

Artigo
05/09/2024

Descrição breve

Permite que você especifique namespaces a serem usados na sessão.

Descrição longa

A using instrução permite que você especifique namespaces a serem usados na sessão. A adição de namespaces simplifica o uso de classes e membros do .NET e permite que você importe classes de módulos de script e assemblies.

As using instruções devem vir antes de qualquer outra instrução em um script ou módulo. Nenhuma instrução não comentada pode precedê-la, incluindo parâmetros.

A using instrução não deve conter nenhuma variável.

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

Sintaxe de namespace

Para resolve tipos de um namespace do .NET:

using namespace <.NET-namespace>

Especificar um namespace facilita a referência de tipos por seus nomes curtos.

Exemplo – Adicionar namespaces para resolução de nome de tipo

O script a seguir obtém o hash criptográfico da cadeia de caracteres "Olá, Mundo".

Observe como e using namespace System.Textusing namespace System.IO simplificam as referências a [UnicodeEncoding] em 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 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 completa do módulo ou um caminho para um arquivo de módulo.

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

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

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

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 mínima aceitável 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. Isso não pode ser usado com as outras chaves de versão.

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

A using module instrução importa classes e enumerações do módulo raiz (ModuleToProcess) de um módulo de script ou módulo binário. Ele não importa consistentemente classes ou enumerações definidas em módulos aninhados ou em scripts que são de origem de ponto para o módulo raiz. Defina classes e enumerações que você deseja que estejam disponíveis para usuários fora do módulo diretamente no módulo raiz.

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

Para garantir que você esteja executando a versão mais recente, inicie uma nova sessão. Classes e enumerações definidas no PowerShell e importadas com uma using instrução não podem ser descarregadas.

Exemplo – Carregar classes de um módulo de script

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

Conjunto
Card

Import-Module e a instrução #requires só importam as funções, os aliases e as 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 do assembly

A sintaxe a seguir carrega tipos .NET de um assembly em um script no início da execução. Você deve usar um caminho totalmente qualificado para o arquivo de assembly.

using assembly <.NET-assembly-path>

A using assembly instrução é semelhante ao uso 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, consulte Add-Type.

Exemplo – Tipos de carga de um assembly

Este exemplo carrega um assembly para que suas classes possam ser usadas ao processar dados. O script a seguir converte dados em um 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

Compartilhar via