主題
    about_Functions

簡短描述
    描述如何在 Windows PowerShell 中建立和使用函數。


完整描述
    函數是具有您所指派之名稱的陳述式清單。當您執行函數時,要輸入函數名稱。清
    單中的陳述式就會執行,如同您在命令提示字元輸入陳述式一樣。

    與 Cmdlet 一樣,函數可以擁有參數。這些參數可以為具名、位置、切換或動態參
    數。可以從命令列或管線讀取函數參數。

    函數所傳回的值則可加以顯示、指派給變數,或是傳遞給其他函數或 Cmdlet。

    函數的陳述式清單可以包含具有 Begin、Process 和 End 關鍵字的不同類型的陳述
    式清單。這些陳述式清單會以不同的方式處理來自管線的輸入。

    篩選器是使用 Filter 關鍵字的特殊函數類型。

    函數也可以具有與 Cmdlet 相同的功能。您不需使用 C# 程式設計,就可以建立功
    能與 Cmdlet 相同的函數。如需詳細資訊,請參閱 about_Functions_Advanced。


  語法
      函數的語法如下:

          function [<範圍:>]<名稱> 
          [([type]$parameter1[,[type]$parameter2])] 
          {
              param([type]$parameter1 [,[type]$parameter2])

              dynamicparam {<陳述式清單>}
  
              begin {<陳述式清單>}
              process {<陳述式清單>}
              end {<陳述式清單>}
          }


      函數包括下列項目:

          - Function 關鍵字
          - 範圍 (選擇性)
          - 您選取的名稱
          - 任何數量的具名參數 (選擇性)
          - 包含在大括號 ({}) 中的一或多個 Windows PowerShell 命令 


      如需函數中的 Dynamicparam 關鍵字和動態參數的詳細資訊,請參閱 
      about_Functions_Advanced_Parameters。


  簡單函數
      函數不必複雜,也可以很有用。下列函數會取得不屬於目前系統的 System 帳戶
      的環境變數: 

          function other_env 
          { 
             get-wmiObject win32_environment | 
                where {$_.username -ne "<System>"}
          }

      若要執行此函數,請輸入 "other_env"。

      您可以建立工具箱,其中納入有用的小函數。請將這些函數新增到 Windows 
      PowerShell 設定檔,如 about_Profiles 和本主題稍後內容所述。


  具有參數的函數
      您可以將參數搭配函數使用,包括具名參數、位置參數、切換參數和動態參數等。
      如需 函數中的動態參數的詳細資訊,請參閱 
      about_Functions_Advanced_Parameters。


  具名參數
      您可以定義任何數量的具名參數。您可以包含具名參數的預設值,如本主題稍後內
      容所述。

      您可以使用 Param 關鍵字在大括號中定義參數,如下列範例語法所示:
    
          function <name> { 
               param ([type]$parameter1[,[type]$parameter2])
               <statement list> 
          }


      您也可以不用 Param 關鍵字而在大括號外定義參數,如下列範例語法所示:

          function <名稱> [([type]$parameter1[,[type]$parameter2])] { 
              <陳述式清單> 
          }


      這兩種方法之間並無差異, 請依您的喜好選擇。

      當您執行函數時,為參數所提供的值會指派給包含參數名稱的變數。該變數的值可
      用於函數中。

      以下範例示範稱為 Small_files 的函數。這個函數具有 $size 參數。會顯示所有
      小於 $size 參數值的檔案,並且排除目錄:

          function small_files {
              param ($size)
              Get-ChildItem c:\ | where {
                  $_.length -lt $size -and !$_.PSIsContainer} 
          }


      在此函數中,您可以使用 $size 變數,也就是為參數所定義的名稱。

      若要使用此函數,請輸入下列命令:
 
          C:\PS> function small_files -size 50


      您也可以輸入具名參數的值,而不輸入參數名稱。例如,下列命令的結果,與為 
      Size 參數命名的命令相同:

          C:\PS> function small_files 50


      若要定義參數的預設值,請在參數名稱之後輸入等號及值,如下列 Small_files
      範例的變化形式所示:

          function small_files ($size = 100) {
              Get-ChildItem c:\ | where {
                  $_.length -lt $size -and !$_.PSIsContainer} 
          }


      如果您輸入 "small_files" 而不提供值,則函數會指派 100 給 $size。如果您提
      供值,則函數會使用該值。


  位置參數
      位置參數是不具參數名稱的參數。Windows PowerShell 會使用參數值順序,將每個
      參數值與函數中的一個參數建立關聯。

      當您使用位置參數時,請在函數名稱之後輸入一或多個值。位置參數值會指派給
      $args 陣列變數。接在函數名稱後的值會指派給 $args array, $args[0] 中的
      第一個位置。

      下列 Extension 函數會將 .txt 副檔名新增到您提供的檔案名稱:

          function extension {
              $name = $args[0] + ".txt"
              $name
          }

          C:\PS> extension myTextFile
          myTextFile.txt
   
      函數可使用一個以上的位置參數。下列範例顯示任何以函數名稱所輸入的值。

          function repeat { foreach ($arg in $args) { "輸入為 $arg" } }

          C:\PS>repeat 一 
          輸入為一

          C:\PS> repeat 一二三
          輸入為一
          輸入為二 
          輸入為三


      此函數可用於任何數量的值。此函數可將每個值指派到 $args 陣列中的位置。


  切換參數
      切換參數是不需要值的參數。相反地,您要輸入函數名稱,後面接著切換參數的
      名稱。

      若要定義切換參數,請在參數名稱之前指定類型 [switch],如下列範例所示:

          function switchExample {
              param ([switch]$on)
              if ($on) { "開啟" }
              else { "關閉" }
          }


      當您在函數名稱之後輸入 On 切換參數時,該函數會顯示「開啟」。沒有切換參
      數時,會顯示「關閉」。

          C:\PS> SwitchExample -on
          開啟

          C:\PS> SwitchExample
          關閉

      您也可以在執行函數時將布林值指派給切換參數,如下列範例所示:

          C:\PS> SwitchExample -on:$true
          Switch on

          C:\PS> SwitchExample -on:$false
          Switch off


  經由管線將物件輸出至函數
      任何函數都可以使用來自管線的輸入。您可以使用 Begin、Process 和 End 關
      鍵字,對函數處理來自管線之輸入的方式進行控管。下列範例語法會示範這三個
      關鍵字:

          function <名稱> { 
              begin {<陳述式清單>}
              process {<陳述式清單>}
              end {<陳述式清單>}
          }

      Begin 陳述式清單只會在函數起始處執行一次。

      Process 陳述式清單會針對管線中的每個命令執行一次。
      在 Process 區塊執行時,每個管線物件都會指派到 $_ 自動變數,且一次指派一
      個管線物件。

      在函數收到管線中的所有物件之後,End 陳述式清單會執行一次。如果沒有使用任
      何 Begin、Process 和 End 關鍵字,則所有的陳述式都會被視為 End 陳述式清單。

      下列函數會使用 Process 關鍵字。此函數會顯示來自管線的範例:

          function pipelineFunction 
          { 
              process {"值為:$_"} 
          }


      若要示範此函數,請輸入以逗號建立的數字陣列,如下列範例所示:

          C:\PS> 1,2,4 | pipelineFunction
          值為:1
          值為:2
          值為:4


      當您在管線中使用函數時,傳入函數的物件會指派給 $input 自動變數。函數會在
      從管線傳來任何物件之前,執行具有 Begin 關鍵字的陳述式。而在從管線收到所
      有物件之後,函數就會執行具有 End 關鍵字的陳述式。

      下列範例示範具有 Begin 和 End 關鍵字的 $input 自動變數。

          function PipelineBeginEnd 
          {
              begin {"開始:輸入為 $input"} 
              end {"結束:輸入為 $input" } 
          }


      如果此函數是藉由管線而執行,則會顯示下列結果:

          C:\PS> 1,2,4 | PipelineBeginEnd
          開始:輸入為 
          結束:輸入為 1 2 4


      當 Begin 陳述式執行時,函數沒有來自管線的輸入。End 陳述式會在函數具有這
      些值之後執行。

      如果函數具有 Process 關鍵字,則函數會讀取 $input 中的資料。下列範例具有 
      Process 陳述式清單:

          function PipelineInput
          {
              process {"正在處理:$_ " }
              end {"結束:輸入為:$input" } 
          } 

      在此範例中,每個經由管道輸出至函數的物件都會傳送到 Process 陳述式清單。
      Process 陳述式會在每個物件上執行,一次執行一個物件。當函數到達 End 關鍵
      字時,$input 自動變數是空的。

          C:\PS> 1,2,4 | PipelineInput
          正在處理:1 
          正在處理:2 
          正在處理:4 
          結束:輸入為:


  篩選器
      篩選器是在管線中的每個物件上執行的函數類型。篩選器類似於所有陳述式都位於 
      Process 區塊中的函數。

      篩選器的語法如下所示: 

          filter [<範圍:>]<名稱> {<陳述式清單>}

      下列的篩選器會從管線取得記錄項目,然後再顯示整個項目或只顯示項目的訊息部
      分:

          filter ErrorLog ([switch]$message)
          {
              if ($message) { out-host -inputobject $_.Message } else 
              { $_ }  
          }


  函數範圍
      函數會存在於當初建立時所在的範圍。

      如果函數是指令碼的一部分,則該函數可提供該指令碼內的陳述式使用。根據預
      設,指令碼中的函數不可用於命令提示字元。

      您可以指定函數的範圍。例如,在下列範例中,函數會新增到全域範圍: 

 
          function global:get-dependentsvs { get-service | where 
          {$_.dependentservices} }


      當函數位於全域範圍時,您可以在指令碼、函數和命令提示字元使用函數。

      函數通常會建立範圍。在函數中建立的項目 (例如變數) 只能存在於函數範圍中。

      如需 Windows PowerShell 中的範圍的詳細資訊,請參閱 about_Scope。

        
  使用 Function: 磁碟機尋找及管理函數:在 Windows PowerShell 中所有的函數和篩
  選器都會自動儲存在 Function: 磁碟機中。這個磁碟機會由 Windows PowerShell 
  Function 提供者公開。

      參考 Function: 磁碟機時,請在 Function 之後輸入冒號,就如同您在參照電腦的
      C 或 D 磁碟機時的做法。

      下列命令會顯示 Windows PowerShell 目前工作階段中的所有函數:

          C:\PS>  dir function:


      函數中的命令會以指令碼區塊的形式儲存在函數的定義屬性中。例如,若要顯示 
      Windows PowerShell 所隨附的 Help 函數中的命令,請輸入:

          (dir function:help).definition

      如需 Function: 磁碟機的詳細資訊,請參閱 Function。


  在新的工作階段中重複使用函數
      在 Windows PowerShell 命令提示字元輸入函數時,該函數就會變成目前工作階段的
      一部分, 在該工作階段結束之前都可以使用。

      若要在所有的 Windows PowerShell 工作階段中使用某函數,請將其新增到
      Windows PowerShell 設定檔。如需設定檔的詳細資訊,請參閱 about_Profiles。

      您也可以將函數儲存在 Windows PowerShell 指令檔中。請在文字檔中輸入函數,
      然後以 .ps1 副檔名儲存該檔案。


  撰寫函數的說明
    Get-Help Cmdlet 會取得函數以及 Cmdlet、提供者和指令碼的說明。若要取得函數
    的說明,請輸入 Get-Help,後面接著函數名稱。

    例如,若要取得 MyDisks 函數的說明,請輸入:

        get-help MyDisks

    您可以使用下列兩種方法之一來撰寫函數的說明:

    --  以註解為基礎的函數說明

        您可以在註解中使用特殊的關鍵字來建立說明主題。若要建立以註解為基礎的函
        數說明,註解必須放在函數主體的起始或結尾處,或放在函數關鍵字之前的行
        中。如需以註解為基礎之說明的詳細資訊,請參閱 about_Comment_Based_Help。

    --  以 XML 為基礎的函數說明

        您可以建立以 XML 為基礎的說明主題,例如通常會為 Cmdlet 所建立的說明類
        型。如果您要將說明主題當地語系化為多種語言,就必須使用以 XML 為基礎的說
        明。

        若要將函數與以 XML 為基礎的說明主題建立關聯,請使用 .ExternalHelp 說明
        註解關鍵字。如需 ExternalHelp 關鍵字的詳細資訊,請參閱 
        about_Comment_Based_Help。如需以 XML 為基礎之說明的詳細資訊,請參閱 
        MSDN 中的<如何撰寫 Cmdlet 說明>。



請參閱 
    about_Automatic_Variables 
    about_Comment_Based_Help
    about_Functions_Advanced 
    about_Functions_CmdletBindingAttribute
    about_Parameters
    about_Profiles
    about_Scopes
    about_Script_Blocks
    Function (提供者) 





目錄