about_Using

Krótki opis

Umożliwia określenie przestrzeni nazw do użycia w sesji.

Długi opis

Instrukcja using umożliwia określenie przestrzeni nazw do użycia w sesji. Dodawanie przestrzeni nazw upraszcza korzystanie z klas i elementów członkowskich platformy .NET i umożliwia importowanie klas z modułów skryptów i zestawów.

Instrukcje using muszą znajdować się przed wszelkimi innymi instrukcjami w skrypcie lub module. Nie można poprzedzić instrukcji bez komentarza, w tym parametrów.

Instrukcja using nie może zawierać żadnych zmiennych.

Instrukcja using nie jest taka sama jak modyfikator zakresu Using: dla zmiennych. Aby uzyskać więcej informacji, zobacz about_Remote_Variables.

Składnia przestrzeni nazw

Aby rozpoznać typy z przestrzeni nazw platformy .NET:

using namespace <.NET-namespace>

Określenie przestrzeni nazw ułatwia odwołowanie się do typów według ich krótkich nazw.

Przykład — dodawanie przestrzeni nazw dla rozpoznawania nazwy typu

Poniższy skrypt pobiera skrót kryptograficzny dla ciągu "Hello World".

Zwróć uwagę, jak using namespace System.Text i using namespace System.IO uprościć odwołania do [UnicodeEncoding] w System.Text i [Stream] oraz [MemoryStream] w 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()

Składnia modułu

Aby załadować klasy i wyliczenia z modułu programu PowerShell:

using module <module-name>

Wartość <module-name> może być nazwą modułu, pełną specyfikacją modułu lub ścieżką do pliku modułu.

Gdy <module-name> jest ścieżką, ścieżka może być w pełni kwalifikowana lub względna. Ścieżka względna jest rozpoznawana względem skryptu, który ma instrukcję using.

Gdy <module-name> jest specyfikacją nazwy lub modułu, program PowerShell wyszukuje PSModulePath dla określonego modułu.

Specyfikacja modułu to tabela skrótu zawierająca następujące klucze.

• ModuleName - Wymagane Określa nazwę modułu.
• GUID - Opcjonalne Określa identyfikator GUID modułu.
• Jest to również wymagane, aby określić co najmniej jeden z trzech poniższych kluczy.
  • ModuleVersion — określa minimalną akceptowalną wersję modułu.
  • MaximumVersion — określa maksymalną akceptowalną wersję modułu.
  • RequiredVersion — określa dokładną, wymaganą wersję modułu. Nie można tego używać z innymi kluczami wersji.

Import-Module i instrukcja #Requires importuje tylko funkcje modułu, aliasy i zmienne, zgodnie z definicją w module. Klasy i wyliczenia nie są importowane.

Instrukcja using module importuje klasy i wyliczenia z modułu głównego (ModuleToProcess) modułu skryptu lub modułu binarnego. Nie importuje spójnie klas ani wyliczeń zdefiniowanych w zagnieżdżonych modułach ani w skryptach, które są dot-source do modułu głównego. Zdefiniuj klasy i wyliczenia, które mają być dostępne dla użytkowników spoza modułu bezpośrednio w module głównym.

Podczas opracowywania modułu skryptu często wprowadza się zmiany w kodzie, a następnie ładują nową wersję modułu przy użyciu Import-Module z parametrem Force. Działa to tylko w przypadku zmian funkcji w module głównym. Import-Module nie ładuje ponownie żadnych zagnieżdżonych modułów. Ponadto nie ma możliwości załadowania zaktualizowanych klas ani wyliczenia.

Aby upewnić się, że używasz najnowszej wersji, musisz uruchomić nową sesję. Nie można zwolnić klas i wyliczenia zdefiniowanych w programie PowerShell i zaimportowanych z instrukcją using.

Przykład — ładowanie klas z modułu skryptu

W tym przykładzie moduł skryptu programu PowerShell o nazwie CardGames definiuje następujące klasy:

• Deck
• karty

Import-Module i instrukcja #Requires importuje tylko funkcje modułu, aliasy i zmienne, zgodnie z definicją w module. Klasy nie są importowane. Polecenie using module importuje moduł, a także ładuje definicje klas.

using module CardGames

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

Składnia zestawu

Poniższa składnia ładuje typy .NET z zestawu do skryptu na początku wykonywania. Musisz użyć w pełni kwalifikowanej ścieżki do pliku zestawu.

using assembly <.NET-assembly-path>

Instrukcja using assembly jest podobna do polecenia cmdlet Add-Type. Jednak polecenie cmdlet Add-Type dodaje typ w czasie wykonywania Add-Type, a nie na początku wykonywania skryptu. Aby uzyskać więcej informacji, zobacz Add-Type.

Przykład — ładowanie typów z zestawu

W tym przykładzie ładuje zestaw, aby jego klasy mogły być używane podczas przetwarzania danych. Poniższy skrypt konwertuje dane na format 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