Cmdlet 延伸代理程式

  • 發行項

適用於：Exchange Server 2013

Cmdlet 延伸代理程式是在 Cmdlet 執行時，由 Exchange Server 2013 Cmdlet 叫用的 Microsoft Exchange 2013 中的元件。 顧名思義，Cmdlet 延伸代理程式會透過協助處理資料或根據 Cmdlet 的需求執行其他動作，來延伸叫用它們之 Cmdlet 的功能。 Cmdlet 延伸代理程式適用於任何伺服器角色。

代理程式可以修改、取代或擴充 Exchange 管理命令介面 Cmdlet 的功能。 代理程式可以提供命令沒有提供之必要參數的值、覆寫使用者提供的值、在 Cmdlet 執行時於 Cmdlet 工作流程外執行其他動作等等。

例如， New-Mailbox Cmdlet 會接受 Database 參數， 指定要在其中建立新信箱的信箱資料庫。 在 Microsoft Exchange Server 2007 中，如果您在執行New-Mailbox Cmdlet 時未指定Database參數，則命令會失敗。 不過，在 Exchange 2013 中， New-Mailbox Cmdlet 會在 Cmdlet 執行時叫 Mailbox Resources Management 用代理程式。 如果未指定 Database 參數， Mailbox Resources Management 代理程式會自動決定適當的信箱資料庫，以在該信箱上建立新的信箱，並將該值插入 Database 參數。

Cmdlet 延伸代理程式只能由 Exchange 2013 與 Microsoft Exchange Server 2010 Cmdlet 叫用。 Exchange 2007 Cmdlet 以及其他 Microsoft 與協力廠商所提供的 Cmdlet 則無法叫用 Cmdlet 延伸代理程式。 指令碼也無法直接叫用 Cmdlet 延伸代理程式。 不過，如果指令碼包含 Exchange 2013 Cmdlet，則這些 Cmdlet 可繼續呼叫 Cmdlet 延伸代理程式。

要尋找與 Cmdlet 延伸代理程式相關的管理工作嗎？ 請參閱管理指令程式延伸代理程式。

代理程式優先順序

代理程式的優先順序會決定 Cmdlet 執行時叫用代理程序的順序。 優先順序較高 (較接近零) 的代理程式會先被叫用。 當兩個或多個代理程式嘗試設定相同內容的值時，代理程式的優先順序就變得很重要。 嘗試設定內容值時優先順序最高的代理程式會成功，優先順序較低的代理程式對設定相同內容的所有後續嘗試會被忽略。 例如，如果優先順序為 3 的代理程式修改了物件的 Name 內容，而另一個優先順序為 6 的代理程式修改相同物件，則優先順序為 6 的代理程式所做的修改會被忽略。

如果您想要使用 Scripting agent 來設定其他較高優先順序代理程式可能設定的屬性值，您有下列選項：

  • 停用目前設定該內容的代理程式。

  • Scripting agent將 設定為高於您要取代之現有代理程式的優先順序。

  • 將代理程式的優先順序保持不變，並確定在 執行的 Scripting agent 腳本遵循其他代理程式所提供的值。

警告

Changing the priority or replacing the functionality of a built-in agent is an advanced operation. 請確定您完全了解所要進行的變更。

如需變更代理程式優先順序的詳細資訊，請參閱管理指令程式延伸代理程式。

內建的代理程式

Exchange 2013 包括可在 Cmdlet 執行時叫用的數個代理程式。 下表列出代理程式、其順序以及代理程式預設是否啟用。 您無法向執行 Exchange 2013 的伺服器新增或移除代理程式。 不過，您可以使用 Scripting agent 來執行Windows PowerShell腳本，以擴充使用它的 Cmdlet 功能。 如需 的詳細 Scripting agent 資訊，請參閱本主題稍後的一節。

如果您想要將特定代理程式的功能取代為您在使用 呼叫的自訂腳本中提供的功能，您可以啟用或停用大部分的代理程式，或變更代理程式的 Scripting agent 優先順序。 但是，某些代理程式無法停用。 無法停用的代理程式稱為 系統代理 程式，並將其 IsSystem 屬性設定為 $True 。 下表提供關於 Exchange 2013 Cmdlet 延伸代理程式的資訊，包括系統代理程式在內。

代理程式的設定會儲存在組織層級。 啟用或停用代理程式或設定其優先順序時，您可以跨組織中的每個伺服器來設定該代理程式的設定。 例外狀況是將腳本新增至 Scripting agent 。 您必須個別更新每個伺服器上的指令碼。 如需設定腳本以搭配 Scripting agent 使用的詳細資訊，請參閱本主題稍後的一節。

警告

如果您沒有完全了解每個代理程式的功能以及它們與 Exchange Cmdlet 互動的方式，變更代理程式的優先順序，或者啟用或停用代理程式可能會造成無法預期的結果。 在您變更任何代理程式的設定之前，請確定您完全了解您想要的變更與結果，並確認您的自訂指令碼會如預期般運作。

Exchange 2013 Cmdlet 延伸代理程式

代理程式名稱 Priority (優先順序) 預設啟用 系統代理程式
Admin Audit Log agent 255 True 是
Scripting agent 6 False 否
Mailbox Resources Management agent 5 True 否
OAB Resources Management agent 4 True 否
Query Base DN agent 3 True 否
Provisioning Policy agent 2 True 否
Rus agent 1 True 否
Mailbox Creation Time agent 0 True 否

指令碼處理代理程式

您可以在 Exchange 2013 中使用 Scripting agent Cmdlet 延伸模組代理程式，將您自己的腳本邏輯插入 Exchange Cmdlet 的執行中。 Scripting agent使用 ，您可以新增條件、覆寫值，以及設定報告。

警告

當您啟用 Scripting agent Cmdlet 擴充代理程式時，每次在執行 Exchange 2013 的伺服器上執行 Cmdlet 時，就會叫用代理程式。 這不只包括您直接在 Exchange 管理命令介面中執行的 Cmdlet，還包括 Exchange 服務所執行的 Cmdlet，以及由 EAC) (Exchange 系統管理中心。 強烈建議您在將更新的組態檔複製到 Exchange 2013 伺服器並啟 Scripting agent 用 Cmdlet 擴充代理程式之前，先測試腳本和對組態檔所做的任何變更。

每次執行 Exchange Cmdlet 時，Cmdlet 都會叫用 Scripting agent Cmdlet 擴充代理程式。 當叫用此代理程式時，該 Cmdlet 會檢查 Cmdlet 是否設定叫用任何指令碼。 如果應該針對 Cmdlet 執行指令碼，該 Cmdlet 會嘗試叫用指令碼中定義的任何 API。 下列 API 可以使用，而且是以下列順序叫用：

  1. ProvisionDefaultProperties：此 API 可用來在建立物件時設定物件的屬性值。 當您設定值時，該值會傳回給 Cmdlet，而且該 Cmdlet 會在內容上設定該值。 如果使用者未指定值，您可以在內容上填入值，或者也可以覆寫由使用者指定的值。 此 API 會採用較高優先順序代理程式所設定的值。 Cmdlet Scripting agent 擴充代理程式不會覆寫較高優先順序代理程式所設定的值。

  2. UpdateAffectedIConfigurable：此 API 可用於在完成所有其他處理之後，在物件上設定屬性值，但 Validate 尚未叫用 API。 此 API 會採用較高優先順序代理程式所設定的值。 Cmdlet Scripting agent 擴充代理程式不會覆寫較高優先順序代理程式所設定的值。

  3. 驗證：此 API 可用來驗證 Cmdlet 即將設定之物件屬性上的值。 在 Cmdlet 寫入任何資料之前，即呼叫此 API。 您可以設定允許 Cmdlet 成功或失敗的驗證檢查。 如果 Cmdlet 通過此 API 中的驗證檢查，該 Cmdlet 即可寫入資料。 如果 Cmdlet 的驗證檢查失敗，它會傳回此 API 中定義的任何錯誤。

  4. OnComplete：此 API 會在所有 Cmdlet 處理完成之後使用。 它可以用來執行處理後的工作，例如將資料寫入外部資料庫。

注意事項

執行 Scripting agent 具有動詞命令的 Cmdlet 時，不會叫用 Get Cmdlet 擴充代理程式。

指令碼處理代理程式組態檔

組 Scripting agent 態檔包含您想要 Scripting agent 執行 的所有腳本。 組態檔中的指令碼是包含在 XML 標記內；XML 標記用來定義指令碼的開始與結束，以及傳遞資料至指令碼所需的各種輸入參數。 指令碼是以 Windows PowerShell 語法撰寫。 組態檔是一個 XML 檔，使用下表中的元素或屬性。

指令碼處理代理程式組態檔的屬性

元素 屬性 描述
Configuration 不適用 此元素包含 Cmdlet 延伸模組代理程式可以執行的所有腳本 Scripting agent 。 標記 Feature 是這個標記的子系。

組態檔中只有一個 Configuration 標籤。
Feature 不適用 此元素包含與功能相關的一組指令碼。 在子標記中定義的 ApiCall 每個腳本，都會擴充 Cmdlet 執行管線的特定部分。 此標記包含 Name 和 Cmdlets 屬性。

標籤下 Configuration 可以有多個 Feature 標籤。
Name 此屬性包含功能的名稱。 使用此屬性可協助識別哪一個功能是由標記中所含之指令碼所延伸的。
Cmdlets 此屬性包含 Exchange Cmdlet 的清單 (此功能延伸中的一組指令碼會使用這些 Cmdlet)。 您可以使用分號分隔每個 Cmdlet 來指定多個 Cmdlet。
ApiCall 不適用 此元素包含可延伸 Cmdlet 一部分執行管線的指令碼。 每個指令碼是由其所延伸之 Cmdlet 執行管線中的 API 呼叫名稱所定義。 下列為可延伸的 API 名稱：
  • ProvisionDefaultProperties
  • UpdateAffectedIConfigurable
  • Validate
  • OnComplete
Name 此屬性包含延伸 Cmdlet 執行管線之 API 呼叫的名稱。
Common 不適用 此元素包含組態檔中之任何指令碼可使用的功能。

每個 Exchange 2013 伺服器都會在 資料夾中 %ExchangeInstallPath%CmdletExtensionAgents 包含 ScriptingAgentConfig.xml.sample 檔案。 如果您啟用 Scripting Agent Cmdlet 延伸代理程式，則每個 Exchange 2013 Server 上的這個檔案都必須重新命名為 ScriptingAgentConfig.xml。 範例組態檔包含可用來協助了解如何新增指令碼至組態檔的範例指令碼。

當您新增指令碼至組態檔後，或者對組態檔做了變更，必須更新組織中每個 Exchange 2013 Server 上的的檔案。 若要確定每部伺服器都包含 Cmdlet 擴充功能代理程式執行的腳本最新版本， Scripting Agent 則必須這麼做。

通常在指令碼中使用的某些字元，在 XML 中也具有特殊意義。 若要在指令碼中使用那些字元，請使用逸出序列。 例如，下列字元使用逸出序列：

  • 請不要使用大於符號 ( > ) ，而是使用 >
  • 不要使用小於符號 () < ，而是使用 $lt;
  • 請不要使用連字號串 ( & ) ，而是使用 &amp;

啟用指令碼處理代理程式

Scripting agent預設會停用 Cmdlet 擴充代理程式。 當您啟用 時 Scripting agent ，代理程式會針對整個 Exchange 2013 組織啟用。 啟用 Scripting agent 之前，請確認 Scripting agent 組態檔已正確地重新命名，並已在每個 Exchange 2013 伺服器上使用您的腳本進行更新。 如果您未正確重新命名組態檔或從另一部 Exchange 2013 Server 將組態檔複製到此電腦上，則每當執行 Cmdlet 時，您都會收到一則錯誤訊息。

若要啟用 Scripting agent ，您必須執行下列動作：

  1. 將 ScriptingAgentConfig.xml.sample 檔案 %ExchangeInstallPath%Bin\CmdletExtensionAgents 重新命名為組織中每個 Exchange 2013 伺服器上的ScriptingAgentConfig.xml。

    注意事項

    您可以將組態檔從一個 Exchange 2013 Server 複製到其他 Exchange 2013Server。 複製之前，請確定更新要複製的組態檔。

  2. 將您的指令碼新增至組織中每個 Exchange 2013 Server 上已重新命名的組態檔。

  3. 啟用 Scripting agent Cmdlet 擴充代理程式。 如需啟用 Cmdlet 延伸代理程式的詳細資訊，請參閱 管理指令程式延伸代理程式。

指令碼處理代理程式的優先順序

根據預設， Scripting agent Cmdlet 擴充代理程式會在所有其他代理程式之後執行，但代理程式除外 Scripting agent 。 如果您想要建立腳本來取代現有的代理程式，您必須停用其他代理程式，或變更任一代理程式的優先順序， Scripting agent 讓 Cmdlet 擴充代理程式先執行。 如需關於如何停用或變更代理程式優先順序的詳細資訊，請參閱 管理指令程式延伸代理程式。