about_Using

Descrição curta

Permite que você indique quais namespaces são usados na sessão.

Descrição longa

A using instrução permite que você especifique quais namespaces são 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 e assemblies de script.

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

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

A using instrução não deve ser confundida com o modificador de using: escopo para variáveis. Para obter mais informações, consulte about_Remote_Variables.

Sintaxe de namespace

Para especificar namespaces do .NET dos quais resolver tipos:

using namespace <.NET-namespace>

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

Sintaxe do módulo

Para carregar classes 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 completa 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 com base no script que contém a instrução using.

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 seguintes chaves.

• ModuleName - necessário especifica o nome do módulo.
• GUID - Opcional especifica o GUID do módulo.
• Também é necessário especificar uma das três chaves abaixo. Essas chaves não podem ser usadas juntas.
  • ModuleVersion – especifica uma versão mínima aceitável do módulo.
  • RequiredVersion – especifica uma versão exata e necessária do módulo.
  • MaximumVersion – especifica a versão máxima aceitável do módulo.

A using module instrução importa classes do módulo raiz (ModuleToProcess) de um módulo de script ou módulo binário. Ele não importa consistentemente classes definidas em módulos aninhados ou classes definidas em scripts que são originados por pontos no módulo. As classes que você deseja que estejam disponíveis para usuários fora do módulo devem ser definidas 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 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 nenhuma classe atualizada.

Para garantir que você esteja executando a versão mais recente, você deve descarregar o módulo usando o Remove-Module cmdlet. Remove-Module remove o módulo raiz, todos os módulos aninhados e todas as classes definidas nos módulos. Em seguida, você pode recarregar o módulo e as classes usando Import-Module e a using module instrução.

Sintaxe do assembly

Para pré-carregar tipos de um assembly .NET:

using assembly <.NET-assembly-path>

Carregar um assembly pré-carrega os tipos .NET desse assembly em um script no momento da análise. Isso permite que você crie novas classes do PowerShell que usam tipos do assembly pré-carregado.

Se você não estiver criando novas classes do PowerShell, use o Add-Type cmdlet. Para obter mais informações, consulte de Tipo de Adição.

Exemplos

Exemplo 1 – 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 o using namespace System.Text e using namespace System.IO simplificam as referências a [UnicodeEncoding] in System.Text e [Stream] e a [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)
$hashfromstream = Get-FileHash -InputStream $memorystream `
  -Algorithm $algorithm
$hashfromstream.Hash.ToString()

Exemplo 2 – Carregar classes de um módulo de script

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

• CardGames.Deck
• CardGames.Card

Import-Module e a instrução #requires importam apenas 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 comando using module importa o módulo e também carrega as definições de classe.

using module CardGames
using namespace CardGames

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

Exemplo 3 – Carregar classes de um assembly

Este exemplo carrega um assembly para que suas classes possam ser usadas para criar novas classes do PowerShell. O script a seguir cria uma nova classe do PowerShell derivada da classe DirectoryContext .

using assembly 'C:\Program Files\PowerShell\7\System.DirectoryServices.dll'
using namespace System.DirectoryServices.ActiveDirectory

class myDirectoryClass : System.DirectoryServices.ActiveDirectory.DirectoryContext
{

  [DirectoryContext]$domain

  myDirectoryClass([DirectoryContextType]$ctx) : base($ctx)
  {
    $this.domain = [DirectoryContext]::new([DirectoryContextType]$ctx)
  }

}

$myDomain = [myDirectoryClass]::new([DirectoryContextType]::Domain)
$myDomain

domain                                                    Name UserName ContextType
------                                                    ---- -------- -----------
System.DirectoryServices.ActiveDirectory.DirectoryContext                    Domain