﻿主題
    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 (提供者) 


