about_Using

Artigo
02/07/2024

Breve descrição

Permite especificar namespaces para usar na sessão.

Descrição longa

A using instrução permite especificar namespaces para usar 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 using instruções 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 using instrução não deve conter variáveis.

A using instrução não é a mesma que o modificador de using: escopo 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 seguinte obtém o hash criptográfico para a cadeia “Hello World”.

Observe como o using namespace System.Text e using namespace System.IO simplificar as referências a [UnicodeEncoding] in System.Text e [Stream] [MemoryStream] in 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 módulo, uma especificação de módulo completo ou um caminho para um arquivo de <module-name> 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> é um nome ou especificação de módulo, o PowerShell procura o módulo especificado no 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 é 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 obrigatória do módulo. Isso não pode ser usado com as outras chaves de versão.

Import-Module e a #requires instrução importa 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 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 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 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:

Convés
Cartão

Import-Module e a #requires instrução importa apenas 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 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 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

Partilhar via