about_Using

Breve descrição

Permite especificar namespaces para usar na sessão.

Descrição longa

A instrução using permite especificar namespaces a serem usados na sessão. Adicionar namespaces simplifica o uso de classes e membros .NET e permite importar classes de módulos de script e assemblies.

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

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

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

Sintaxe do namespace

Para resolver tipos de um namespace .NET:

using namespace <.NET-namespace>

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

Exemplo - Adicionar namespaces para resolução typename

O script a seguir obtém o hash criptográfico para a cadeia de caracteres "Hello World".

Observe como o using namespace System.Text e using namespace System.IO simplificam as referências a [UnicodeEncoding] em System.Text e [Stream] e [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 <module-name> pode ser um nome de módulo, uma especificação de módulo completo 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 instrução using.

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

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

• ModuleName - Obrigatório Especifica o nome do módulo.
• GUID - Opcional Especifica o GUID do módulo.
• Também é Obrigató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 importam apenas as funções, aliases e variáveis do módulo, conforme definido pelo módulo. Classes e enumerações não são importadas.

A instrução using module 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 dot-sourced 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, em seguida, carregar a nova versão do módulo usando Import-Module com o parâmetro Force. Isso funciona apenas para alterações de 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 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 instrução using 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:

• Deck
• Cartão

Import-Module e a instrução #Requires importam apenas as funções, aliases e variáveis do módulo, conforme definido pelo módulo. As classes não são importadas. O comando using module 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 montagem

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 instrução using assembly é semelhante ao uso do cmdlet Add-Type. No entanto, o cmdlet Add-Type 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