Informacje o zaawansowanych metodach funkcjiAbout Functions Advanced Methods

01/03/2018
Czas czytania: 4 min

Krótki opisShort description

Opisuje, jak funkcje określające CmdletBinding atrybut mogą używać metod i właściwości, które są dostępne dla skompilowanych poleceń cmdlet.Describes how functions that specify the CmdletBinding attribute can use the methods and properties that are available to compiled cmdlets.

Długi opisLong description

Funkcje, które określają CmdletBinding atrybut, mogą uzyskać dostęp do wielu metod i właściwości za pomocą $PSCmdlet zmiennej.Functions that specify the CmdletBinding attribute can access a number of methods and properties through the $PSCmdlet variable. Te metody obejmują następujące metody:These methods include the following methods:

Metody przetwarzania danych wejściowych, które są używane przez skompilowane polecenia cmdlet do wykonywania pracy.Input-processing methods that compiled cmdlets use to do their work.
ShouldProcessMetody i ShouldContinue , które są używane do uzyskiwania opinii użytkowników przed wykonaniem akcji.The ShouldProcess and ShouldContinue methods that are used to get user feedback before an action is performed.
ThrowTerminatingErrorMetoda generowania rekordów błędów.The ThrowTerminatingError method for generating error records.
Kilka Write metod, które zwracają różne typy danych wyjściowych.Several Write methods that return different types of output.

Wszystkie metody i właściwości klasy PSCmdlet są dostępne w zaawansowanych funkcjach.All the methods and properties of the PSCmdlet class are available to advanced functions. Aby uzyskać więcej informacji, zobacz System. Management. Automation. PSCmdlet.For more information, see System.Management.Automation.PSCmdlet.

Aby uzyskać więcej informacji na temat CmdletBinding atrybutu, zobacz about_Functions_CmdletBindingAttribute.For more information about the CmdletBinding attribute, see about_Functions_CmdletBindingAttribute. Dla klasy CmdletBindingAttribute zobacz System. Management. Automation. cmdlet. CmdletBindingAttribute.For the CmdletBindingAttribute class, see System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Metody przetwarzania danych wejściowychInput processing methods

Metody opisane w tej sekcji są określane jako metody przetwarzania danych wejściowych.The methods described in this section are referred to as the input processing methods. W przypadku funkcji te trzy metody są reprezentowane przez Begin , Process i End bloki funkcji.For functions, these three methods are represented by the Begin, Process, and End blocks of the function. Nie jest wymagane używanie żadnego z tych bloków w swoich funkcjach.You aren't required to use any of these blocks in your functions.

Uwaga

Te bloki są również dostępne dla funkcji, które nie używają CmdletBinding atrybutu.These blocks are also available to functions that don't use the CmdletBinding attribute.

RozpocznijBegin

Ten blok służy do zapewnienia opcjonalnego przetwarzania wstępnego dla funkcji.This block is used to provide optional one-time preprocessing for the function. Środowisko uruchomieniowe programu PowerShell używa kodu w tym bloku jednokrotnie dla każdego wystąpienia funkcji w potoku.The PowerShell runtime uses the code in this block once for each instance of the function in the pipeline.

ProcesProcess

Ten blok służy do dostarczania przetwarzania rekordów przez rekord dla funkcji.This block is used to provide record-by-record processing for the function. Możesz użyć Process bloku bez definiowania innych bloków.You can use a Process block without defining the other blocks. Liczba Process wykonań bloku zależy od sposobu korzystania z funkcji oraz od tego, jakie dane są odbierane przez funkcję.The number of Process block executions depends on how you use the function and what input the function receives.

Zmienna automatyczna $_ lub $PSItem zawiera bieżący obiekt w potoku do użycia w Process bloku.The automatic variable $_ or $PSItem contains the current object in the pipeline for use in the Process block. $inputZmienna automatyczna zawiera moduł wyliczający, który jest dostępny tylko dla bloków Functions i Script.The $input automatic variable contains an enumerator that's only available to functions and script blocks. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.For more information, see about_Automatic_Variables.

Wywołanie funkcji na początku lub poza potokiem wykonuje Process blok jeden raz.Calling the function at the beginning, or outside of a pipeline, executes the Process block once.
W obrębie potoku Process blok jest wykonywany jednokrotnie dla każdego obiektu wejściowego, który dociera do funkcji.Within a pipeline, the Process block executes once for each input object that reaches the function.
Jeśli dane wejściowe potoku, które docierają do funkcji, są puste, Process blok nie jest wykonywany.If the pipeline input that reaches the function is empty, the Process block does not execute.
- BeginBloki i End nadal są wykonywane.The Begin and End blocks still execute.

Ważne

Jeśli parametr funkcji jest ustawiony na akceptowanie danych wejściowych potoku, a Process blok nie jest zdefiniowany, przetwarzanie rekordów przez rekord nie powiedzie się.If a function parameter is set to accept pipeline input, and a Process block isn't defined, record-by-record processing will fail. W takim przypadku funkcja zostanie wykonana tylko raz, niezależnie od danych wejściowych.In this case, your function will only execute once, regardless of the input.

EndEnd

Ten blok służy do zapewnienia opcjonalnego przetwarzania jednokrotnego dla funkcji.This block is used to provide optional one-time post-processing for the function.

Poniższy przykład przedstawia kontur funkcji, która zawiera Begin blok jednorazowego przetwarzania wstępnego, Process blok do przetwarzania wielu rekordów oraz End blok jednorazowego przetwarzania po raz.The following example shows the outline of a function that contains a Begin block for one-time preprocessing, a Process block for multiple record processing, and an End block for one-time post-processing.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

Uwaga

Użycie albo Begin bloku lub End wymaga zdefiniowania wszystkich trzech bloków.Using either a Begin or End block requires that you define all three blocks. W przypadku używania wszystkich trzech bloków cały kod programu PowerShell musi znajdować się w jednym z bloków.When using all three blocks, all PowerShell code must be inside one of the blocks.

Metody potwierdzaniaConfirmation methods

ShouldProcessShouldProcess

Ta metoda jest wywoływana, aby zażądać potwierdzenia od użytkownika przed wykonaniem przez funkcję akcji, która mogłaby zmienić system.This method is called to request confirmation from the user before the function performs an action that would change the system. Funkcja może być kontynuowana na podstawie wartości logicznej zwróconej przez metodę.The function can continue based on the Boolean value returned by the method. Tę metodę można wywołać tylko z wewnątrz Process{} bloku funkcji.This method can only be called only from within the Process{} block of the function. CmdletBindingAtrybut musi również deklarować, że funkcja obsługuje ShouldProcess (jak pokazano w poprzednim przykładzie).The CmdletBinding attribute must also declare that the function supports ShouldProcess (as shown in the previous example).

Aby uzyskać więcej informacji na temat tej metody, zobacz System. Management. Automation. cmdlet. ShouldProcess.For more information about this method, see System.Management.Automation.Cmdlet.ShouldProcess.

Aby uzyskać więcej informacji na temat żądania potwierdzenia, zobacz żądanie potwierdzenia.For more information about how to request confirmation, see Requesting Confirmation.

ShouldContinueShouldContinue

Ta metoda jest wywoływana w celu zażądania drugiego komunikatu potwierdzenia.This method is called to request a second confirmation message. Powinien być wywoływany, gdy ShouldProcess Metoda zwraca $true .It should be called when the ShouldProcess method returns $true. Aby uzyskać więcej informacji na temat tej metody, zobacz System. Management. Automation. cmdlet. ShouldContinue.For more information about this method, see System.Management.Automation.Cmdlet.ShouldContinue.

Metody błędówError methods

Funkcja może wywołać dwie różne metody w przypadku wystąpienia błędów.Functions can call two different methods when errors occur. Gdy wystąpi błąd niepowodujący zakończenia, funkcja powinna wywołać WriteError metodę, która jest opisana w Write sekcji metod.When a non-terminating error occurs, the function should call the WriteError method, which is described in the Write methods section. Gdy wystąpi błąd kończący, a funkcja nie może być kontynuowana, powinna wywołać ThrowTerminatingError metodę.When a terminating error occurs and the function can't continue, it should call the ThrowTerminatingError method. Można również użyć Throw instrukcji do kończenia błędów i polecenia cmdlet Write-Error dla błędów niepowodujących zakończenia.You can also use the Throw statement for terminating errors and the Write-Error cmdlet for non-terminating errors.

Aby uzyskać więcej informacji, zobacz System. Management. Automation. cmdlet. ThrowTerminatingError.For more information, see System.Management.Automation.Cmdlet.ThrowTerminatingError.

Metody zapisuWrite methods

Funkcja może wywołać następujące metody, aby zwrócić różne typy danych wyjściowych.A function can call the following methods to return different types of output. Zwróć uwagę, że nie wszystkie dane wyjściowe przechodzą do następnego polecenia w potoku.Notice that not all the output goes to the next command in the pipeline. Można również użyć różnych Write poleceń cmdlet, takich jak Write-Error .You can also use the various Write cmdlets, such as Write-Error.

WriteCommandDetailWriteCommandDetail

Aby uzyskać informacje na temat WriteCommandDetails metody, zobacz System. Management. Automation. cmdlet. WriteCommandDetail.For information about the WriteCommandDetails method, see System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebugWriteDebug

Aby podać informacje, które mogą być używane do rozwiązywania problemów z funkcją, należy wywołać WriteDebug metodę.To provide information that can be used to troubleshoot a function, make the function call the WriteDebug method. WriteDebugMetoda wyświetla komunikaty debugowania dla użytkownika.The WriteDebug method displays debug messages to the user. Aby uzyskać więcej informacji, zobacz System. Management. Automation. cmdlet. WriteDebug.For more information, see System.Management.Automation.Cmdlet.WriteDebug.

WriteErrorWriteError

Funkcje powinny wywołać tę metodę, gdy wystąpią błędy niepowodujące zakończenia, a funkcja została zaprojektowana w celu kontynuowania przetwarzania rekordów.Functions should call this method when non-terminating errors occur and the function is designed to continue processing records. Aby uzyskać więcej informacji, zobacz System. Management. Automation. cmdlet. WriteError.For more information, see System.Management.Automation.Cmdlet.WriteError.

Uwaga

Jeśli wystąpi błąd kończący, funkcja powinna wywołać metodę ThrowTerminatingError .If a terminating error occurs, the function should call the ThrowTerminatingError method.

WriteObjectWriteObject

WriteObjectMetoda umożliwia wysyłanie obiektu do następnego polecenia w potoku.The WriteObject method allows the function to send an object to the next command in the pipeline. W większości przypadków WriteObject jest to metoda, która ma być używana, gdy funkcja zwraca dane.In most cases, WriteObject is the method to use when the function returns data. Aby uzyskać więcej informacji, zobacz System. Management. Automation. PSCmdlet. WriteObject.For more information, see System.Management.Automation.PSCmdlet.WriteObject.

WriteProgressWriteProgress

W przypadku funkcji z akcjami, które wymagają długiego czasu, ta metoda umożliwia wywołanie metody w celu WriteProgress wyświetlenia informacji o postępie.For functions with actions that take a long time to complete, this method allows the function to call the WriteProgress method so that progress information is displayed. Można na przykład wyświetlić procent ukończonych.For example, you can display the percent completed. Aby uzyskać więcej informacji, zobacz System. Management. Automation. PSCmdlet. WriteProgress.For more information, see System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerboseWriteVerbose

Aby uzyskać szczegółowe informacje o tym, co robi funkcja, należy wywołać WriteVerbose metodę w celu wyświetlenia pełnych komunikatów dla użytkownika.To provide detailed information about what the function is doing, make the function call the WriteVerbose method to display verbose messages to the user. Domyślnie pełne komunikaty nie są wyświetlane.By default, verbose messages aren't displayed. Aby uzyskać więcej informacji, zobacz System. Management. Automation. PSCmdlet. WriteVerbose.For more information, see System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarningWriteWarning

Aby podać informacje o warunkach, które mogą spowodować nieoczekiwane wyniki, należy wywołać metodę WriteWarning w celu wyświetlenia komunikatów ostrzegawczych dla użytkownika.To provide information about conditions that may cause unexpected results, make the function call the WriteWarning method to display warning messages to the user. Domyślnie wyświetlane są komunikaty ostrzegawcze.By default, warning messages are displayed. Aby uzyskać więcej informacji, zobacz System. Management. Automation. PSCmdlet. WriteWarning.For more information, see System.Management.Automation.PSCmdlet.WriteWarning.

Uwaga

Możesz również wyświetlać komunikaty ostrzegawcze, konfigurując $WarningPreference zmienną lub korzystając z Verbose Debug opcji wiersza polecenia i.You can also display warning messages by configuring the $WarningPreference variable or by using the Verbose and Debug command-line options. Aby uzyskać więcej informacji na temat $WarningPreference zmiennej, zobacz about_Preference_Variables.for more information about the $WarningPreference variable, see about_Preference_Variables.

Inne metody i właściwościOther methods and properties

Aby uzyskać informacje o innych metodach i właściwościach, do których można uzyskać dostęp za pomocą $PSCmdlet zmiennej, zobacz System. Management. Automation. PSCmdlet.For information about the other methods and properties that can be accessed through the $PSCmdlet variable, see System.Management.Automation.PSCmdlet.

Na przykład właściwość ParameterSetName umożliwia wyświetlenie używanego zestawu parametrów.For example, the ParameterSetName property allows you to see the parameter set that is being used. Zestawy parametrów umożliwiają tworzenie funkcji, która wykonuje różne zadania na podstawie parametrów określonych podczas uruchamiania funkcji.Parameter sets allow you to create a function that performs different tasks based on the parameters that are specified when the function is run.