使用 Windows PowerShell 來管理快取 (AppFabric 1.1)

  • 發行項

透過使用 Windows PowerShell，您可以管理快取叢集、快取主機以及快取本身。或者，您可以移至 [開始] 功能表，依序按一下 [所有程式] 及 [Microsoft AppFabric 1.1 for Windows Server]，然後按一下 [快取管理 Windows PowerShell]。

注意

您必須為某些管理命令，執行具有系統管理權限的 Windows PowerShell，才能正確運作。對於 [快取管理 Windows PowerShell] 捷徑，您必須在該捷徑上按一下滑鼠右鍵，然後選取 [以系統管理員身分執行]。

AppFabric 快取 PowerShell 命令有兩種主要類別：系統管理命令與設定命令。本主題著重於系統管理命令。如需有關設定命令的詳細資訊，請參閱使用 Windows PowerShell 設定快取組態 (AppFabric 1.1 快取)。此主題中的表格將管理命令細分成幾個類別。有些命令會出現在多個表格中，在應用於四種命令類別時顯示不同的參數：

  • 與快取叢集相關的命令

  • 與快取主機相關的命令

  • 與快取相關的命令

  • 主控台管理命令

AppFabric 1.1 2012 年 3 月更新 中的命名稱變更

AppFabric 1.1 2012 年 3 月更新 更新包括 AppFabric 之 Windows PowerShell 命令的名稱奱更。這些變更會改善命令的瞭解性及一致性。下列表格包括原始命令名稱 (RTM) 和 2012 年 3 月的命令名稱 (QFE)。

為了保存回溯相容性，會提供以舊命令名稱為別名的新命令 PowerShell 指令檔。任何參數名稱變更均已包含在 PowerShell 模組本身的別名中。

在 Windows PowerShell 工作階段中取得說明

下面資訊提供 AppFabric 快取功能的管理命令摘要。請務必了解，您也能在 Windows PowerShell 工作階段內取得說明。例如，下列命令可顯示所有系統管理命令：

get-command -module DistributedCacheAdministration

如果您需要特定命令的說明，您可以使用 get-help 命令來這樣做。例如，下列命令可顯示 New-Cache 命令的完整說明：

get-help New-Cache -full

重要考量

使用此主題所述的 Windows PowerShell 命令時，請務必考量下列幾點：

  • 使用這些 Windows PowerShell 命令之人員的安全性身分識別，必須具有快取叢集中所有快取伺服器的系統管理員權限。

  • 命令的參數值區分大小寫。例如，若建立名為 NamedCache1 的快取，則 Get-CacheConfig -CacheName namedcache1 命令將沒有作用。大小寫必須相符，如同在 Get-CacheConfig -CacheName NamedCache1 中。

  • 使用 Export-CacheClusterConfig 與 Import-CacheClusterConfig 命令來變更 XML 型叢集組態時，您可以變更 XML 檔案中的叢集組態設定 (XML 屬性)，但不支援透過插入或移除 XML 元素來新增或移除具名快取與快取主機。

  • Start-CacheCluster、Stop-CacheCluster 與 Restart-CacheCluster 快取叢集命令涉及在叢集中所有快取主機上，協調快取主機 Windows 服務的狀態。由主要主機執行叢集管理角色時，這些命令可能要花費較久的時間；必須有絕大多數的主要主機持續執行，以讓其餘快取主機能夠停止和啟動。

  • 請一律使用 Start-CacheCluster、Stop-CacheCluster 及 Restart-CacheCluster 快取叢集命令來啟動及停止快取服務。從服務系統管理工具啟動及停止服務可能會導致發生懸置。此外，必須使用系統管理權限從提高權限的 Windows PowerShell 工作階段執行這些命令。

  • Stop-CacheCluster 或 Restart-CacheCluster 快取叢集命令會造成從叢集中所有快取主機的記憶體排清所有資料。

  • Set-CacheConfig 與 Import-CacheClusterConfig 命令需要您使用 Restart-CacheCluster 來重新啟動快取叢集，所做的變更才會生效。

  • Remove-Cache 與 New-Cache 命令可用來變更具名快取組態，而不會影響到叢集中的其他具名快取。

與快取叢集相關的命令

下表列出可用來執行與叢集相關之操作的「快取管理 Windows Powershell」命令。

命令 (RTM) 命令 (QFE) 描述

Use-CacheCluster

Connect-AFCacheClusterConfiguration

將 Windows PowerShell 工作階段的內容設定至想要的快取叢集。

當您啟動 Windows PowerShell 工作階段時，您必須先執行此命令。如果是在快取主機執行，您可以不搭配參數來執行命令，因為系統已經從電腦上的快取組態取得參數。如果您是從非主機電腦執行命令，您可以使用以下參數來指定想要的快取叢集。

參數描述如下所示：

  • Provider：用來儲存叢集組態設定的提供者。視組態資訊儲存方式而定，這可以是 System.Data.SqlClient 或 XML。

  • ConnectionString：資料庫的連接字串或 XML 組態檔的位置。

Start-CacheCluster

Start-AFCacheCluster

啟動叢集中的所有快取服務。會先啟動主要主機。請注意，在重新開機之後不會自動啟動快取服務，因此必須呼叫 Start-CacheCluster 或 Start-CacheHost 來啟動服務。需要系統管理員權限才能執行此命令。

Stop-CacheCluster

Stop-AFCacheCluster

停止叢集中的所有快取服務。需要系統管理員權限才能執行此命令。

Restart-CacheCluster

Restart-AFCacheCluster

以正確的順序重新啟動叢集中所有快取服務。需要系統管理員權限才能執行此命令。

Get-CacheClusterHealth

Get-AFCacheClusterHealth

傳回快取叢集健康情況的統計資料。

Export-CacheClusterConfig

Export-AFCacheClusterConfiguration

設計來搭配 Import-CacheClusterConfig 使用，此命令可讓您使用 XML 來編輯叢集組態設定。如需詳細資訊，請參閱編輯叢集組態設定。

此命令會將目前存在於叢集中的叢集組態設定匯出至指定的 XML 型組態檔。不論您選擇將叢集組態設定儲存至何處 (SQL Server 或共用的網路資料夾)，都可以使用此命令。

參數描述如下所示：

  • File：要建立之 XML 型組態檔的完整路徑與名稱，描述目前的快取叢集組態設定。

範例：Export-CacheClusterConfig -File c:\Temp\CurrentClusterConfig.xml

Import-CacheClusterConfig

Import-AFCacheClusterConfiguration

設計來搭配 Export-CacheClusterConfig 使用，此命令可讓您使用 XML 來編輯叢集組態設定。如需詳細資訊，請參閱編輯叢集組態設定。

此命令會從指定的 XML 型組態檔匯入叢集組態設定。不論您選擇將叢集組態設定儲存至何處 (SQL Server 或共用的網路資料夾)，都可以使用此命令。

您必須使用 Restart-CacheCluster 重新啟動叢集，所做的變更才會生效。

參數描述如下所示：

  • File：XML 型組態檔的完整路徑與名稱，描述要套用到叢集的快取叢集組態設定。

  • Force：不提示您確認，就匯入組態檔。

  • RefreshNow：變更正在執行的叢集的快取叢集組態設定。此命令目前僅與記憶體管理相關的設定搭配使用。然而，即便如此，也必須重新開始個別快取主機，或將其新增至叢集，記憶體管理設定才會生效。

範例：Import-CacheClusterConfig -File c:\CurrentClusterConfig.xml

Grant-CacheAllowedClientAccount

Grant-AFCacheAllowedClientAccount

授與 Windows 帳戶存取快取叢集的權限。根據預設值，快取主機上的任何系統管理員帳戶都擁有快取叢集的存取權。您必須使用此命令，將其他帳戶明確地新增至允許的用戶端帳戶清單。

參數描述如下所示：

  • Account：要為其授與快取叢集存取權的 Windows 帳戶。

  • Force：不事先驗證帳戶是否存在，便新增指定的用戶端帳戶。

Revoke-CacheAllowedClientAccount

Revoke-AFCacheAllowedClientAccount

撤銷 Windows 帳戶存取快取叢集的權限。請注意，這將不會禁止快取主機上的系統管理員存取快取叢集。

參數描述如下所示：

  • Account：要為其授與快取叢集存取權的 Windows 帳戶。

Get-Cache

Get-AFCache

未搭配任何參數使用時，會列出快取叢集內所有快取的相關資訊。

注意

如需有關如何使用此命令來搭配 HostName 參數的詳細資訊，請參閱下表。

Update-CacheHostAllowedVersions

Update-AFCacheHostAllowedVersions

更新可存取快取叢集的快取主機和快取用戶端的版本範圍。目前，版本號碼與以下版本相關：

  • 1 = Windows Server AppFabric v1.0

  • 3 = Microsoft AppFabric 1.1 for Windows Server

參數描述如下所示：

  1. BeginClientVersion：快取用戶端版本範圍的起始值。

  2. EndClientVersion：快取用戶端版本範圍的結束值。

  3. BeginServerVersion：快取主機版本範圍的起始值。

  4. EndServerVersion：快取主機版本範圍的結束值。

如需相關資訊，請參閱AppFabric 快取叢集 (AppFabric 1.1) 的升級程序。

Stop-CacheNonUpdatedHosts

Stop-AFCacheNonUpdatedHosts

停止其版本不是指定版本值的快取主機。

參數描述如下所示：

  1. BeginServerVersion：快取主機版本範圍的起始值。

  2. EndServerVersion：快取主機版本範圍的結束值。

  3. HostTimeout：等候每個快取主機停止的逾時值 (以秒表示)。

  4. Version：快取主機的程式碼版本。

如需相關資訊，請參閱AppFabric 快取叢集 (AppFabric 1.1) 的升級程序。

Update-CacheConfigurationStore

Update-AFCacheConfigurationStore

升級 AppFabric 之後請更新快取組態儲存區。當升級至 Microsoft AppFabric 1.1 for Windows Server 時，對於將快取主機名稱翻譯為完整合格網域名稱 (FQDN) 同等物有明顯的影響。

與快取主機相關的命令

下表列出的命令可用來在 Windows PowerShell 中執行與快取主機相關的操作。

命令 (RTM) 命令 (QFE) 說明

Get-CacheHost

Get-AFCacheHost

列出所指定快取主機的相關資訊。如果未傳遞任何參數，會列出屬於快取叢集成員的所有快取服務。請注意，Shutting Down 的狀態表示正在進行正常關閉程序。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

範例：Get-CacheHost

Get-CacheHostConfig

Get-AFCacheHostConfiguration

傳回所指定快取主機的相關組態資訊。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

範例：Get-CacheConfig -HostName CacheServer1 -CachePort 22233

Set-CacheHostConfig

Set-AFCacheHostConfiguration

將快取主機組態更新為命令參數中指定的值。所有參數都可以省略，但 HostName 與 CachePort 除外。如需詳細資訊，請參閱編輯叢集組態設定。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機目前的快取連接埠號碼。

  • ClusterPortNumber：由快取主機使用的叢集連接埠號碼。

  • ArbitratorPortNumber：新的仲裁程式連接埠號碼。

  • ReplicationPortNumber：新的複寫連接埠號碼。

  • CacheSize：所配置以供在快取主機上儲存資料的總記憶體數量，單位為 MB。

  • IsLeadHost：快取主機的主要主機狀態 ("true" 或 "false")。

  • HWM：回收作業應開始將尚未到期的物件移出記憶體的記憶體高水位線百分比。

  • LWM：回收作業應開始將已到期的物件移出記憶體的記憶體低水位線百分比。在達到 HWM 之後，回收作業應停止將尚未到期的物件移出記憶體。

範例：Set-CacheConfig -HostName CacheServer1 -CachePort 22233 -LowWM 80

Start-CacheHost

Start-AFCacheHost

啟動指定的快取服務。在快取伺服器重新開機之後，需要執行此命令以允許快取服務重新加入執行中的快取叢集。請注意，如果快取叢集當機，則您應該改用 Start-CacheCluster 命令。此外，在重新開機之後不會自動啟動快取服務，因此必須呼叫 Start-CacheHost 或 Start-CacheCluster 來啟動服務。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

  • HostTimeout：啟動指定之快取主機的逾時值 (秒)。預設是 60 秒。

範例：Start-CacheHost -HostName CacheServer1 -CachePort 22233

Stop-CacheHost

Stop-AFCacheHost

停止指定的快取服務。

注意

如果快取主機 Windows 服務正在執行叢集管理角色，且停止該快取主機會造成整個叢集關閉，Stop-CacheHost 命令就不會停止該快取主機。如需詳細資訊，請參閱主要主機與叢集管理 (AppFabric 1.1 快取)。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

  • HostTimeout：啟動指定之快取主機的逾時值 (秒)。

  • Graceful：指定應該啟動正常關閉程序。正常關閉程序會先將快取項目移至其他快取主機，然後才停止快取服務。如此可避免資料遺失，並省去讓快取用戶端重新填入這些項目的需要。請注意可使用 New-CacheCluster 命令的 GracefulShutdownEnabled 選項建立快取叢集，讓正常關機為 Stop-CacheHost 的預設行為。這也需要快取叢集來指定 GracefulShutdownTimeout。

    警告

    僅在您已驗證有足夠伺服器和剩餘記憶體來處理已移至執行中伺服器的快取項目時，才能起始正常關閉。否則，正常關閉可能懸置且必須取消。

範例：Stop-CacheHost -HostName CacheServer1 -CachePort 22233

Stop-CacheHostShutdown

Stop-AFCacheHostShutdown

取消進行中的正常關閉程序。快取主機會維持執行，而且不會遺失任何資料。完成時可能會視需要執行一般的負載平衡。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

Restart-CacheHost

Restart-AFCacheHost

重新啟動指定的快取服務。設定與 Stop-CacheHost 的設定相同。

Get-CacheStatistics

Get-AFCacheStatistics

顯示所指定快取主機的統計資料，包括：總大小 (位元組) 以及快取物件、區域、具名快取、要求與遺漏的快取數目。

注意

如需有關如何使用此命令來搭配 CacheName 參數的詳細資訊，請參閱下表。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

範例：Get-CacheStatistics -HostName CacheServer1 -CachePort 22233

Get-Cache

Get-AFCache

列出位於所指定快取主機上的所有快取與區域。

參數描述如下所示：

  • HostName：快取主機的名稱。

  • CachePort：快取主機的連接埠號碼。

範例：Get-Cache -HostName CacheServer1 -CachePort 22233

Get-CacheRegion

Get-AFCacheRegion

傳回快取叢集中所有區域的清單。區域只能由快取用戶端建立或移除。但快取叢集會決定其位在哪部快取主機。所有參數都可以省略。

注意

如需有關如何使用此命令來搭配 CacheName 參數的詳細資訊，請參閱下表。

參數描述如下所示：

  • MaxRegions：要顯示的區域數目上限。這無法與 MaxRegionsPerHost 參數搭配使用。

  • MaxRegionsPerHost：快取叢集中的每部主機要顯示的區域數目上限。

範例：Get-CacheRegion -MaxRegionsPerHost 4

與快取相關的命令

下表列出的命令可用來在 Windows PowerShell 中執行與快取相關的操作。

命令 (RTM) 命令 (QFE) 說明

New-Cache

New-AFCache

在叢集執行時建立新的具名快取。所有值都可以省略，但 CacheName 除外。

注意

具名快取限制為 128 個。

參數描述如下所示：

  • CacheName：快取的名稱。

  • Secondaries：值為 1 可以啟用高可用性功能。值為 0 可以停用高可用性功能。預設值為 0。

  • NotificationsEnabled：True 值可啟用快取通知功能，而 False 值可將它停用。

  • Eviction：LRU 值可啟用「最近最少使用」收回。None 值可停用收回。預設值為 LRU。

    警告

    None 值可能會導致快取主機發生記憶體不足的情形。

  • TimeToLive：快取中儲存之物件在過期前的預設逾時值 (分鐘)。預設值為 10。

  • Expirable：True 值會啟用過期，而 False 會停用過期。預設值為 True。

  • MinSecondaries：要讓對某個項目的寫入操作成功，該項目必須擁有的次要複本最小數目。預設值為 0。

  • WriteBehindEnabled：啟用事後寫入功能。預設值為 false。

  • WriteBehindInterval：快取項目在寫入至快取的多久時間 (秒數) 後應寫入至提供者。最小值為 60，預設值為 300。

  • WriteBehindRetryInterval：當連線至事後寫入 (write-behind) 提供者失敗時，每次重試之間等候的間隔 (秒)。預設值為 60，等同於最小值。

  • WriteBehindRetryCount：重試連線至事後寫入 (write-behind) 提供者的最大次數。預設值為 -1，表示不限制重試次數。

  • ReadThroughEnabled：啟用貫穿式讀取 (read-through) 功能。預設值為 false。

  • Provider Type：提供者組件類型的完整格式名稱。此提供者會實作事後寫入 (write-behind) 和貫穿式讀取 (read-through) 功能。名稱會區分大小寫。例如：RTProvider.Provider, RTProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=80e2cb5f6ba933f0.

  • ProviderSettings：一或多個金鑰/值配對，指定提供者的連線資訊。例如：@{"setting1"="value1";"setting2"="value2"}.

範例：New-Cache -CacheName NamedCache1 -Secondaries 1 -TimeToLive 15

Remove-Cache

Remove-AFCache

移除具名快取，如 CacheName 參數所指定。

參數描述如下所示：

  • CacheName：快取的名稱。

範例：Remove-Cache -CacheName NamedCache1

Get-CacheConfig

Get-AFCacheConfiguration

傳回 CacheName 參數所指定具名快取的組態詳細資料。

參數描述如下所示：

  • CacheName：快取的名稱。

範例：Get-CacheConfig -CacheName NamedCache1

Set-CacheConfig

Set-AFCacheConfiguration

更新具名快取的組態設定，如 CacheName 參數所指定。

使用 CacheName 參數來變更快取時，快取叢集不能是執行中狀態。或者，您可能想要考慮使用 Remove-Cache 與 New-Cache 命令。這些命令可以用來變更具名快取組態，而不會因為需要停止叢集而影響到叢集中的其他具名快取。

如需詳細資訊，請參閱使用 Windows PowerShell 來編輯快取組態設定。

參數描述如下所示：

  • CacheName：快取的名稱。

  • Secondaries：值為 1 可以啟用高可用性功能。值為 0 可以停用高可用性功能。預設值為 0。請注意，此功能只支援執行 Windows Server Enterprise Edition 或 DataCenter Edition 的快取主機。

  • NotificationsEnabled：True 值可啟用快取通知功能，而 False 值可將它停用。

  • Eviction：LRU 值可啟用「最近最少使用」收回。None 值可停用收回。預設值為 LRU。

    警告

    None 值可能會導致快取主機發生記憶體不足的情形。

  • TimeToLive：快取中儲存之物件在過期前的預設逾時值 (分鐘)。預設值為 10。

  • Expirable：True 值會啟用過期，而 False 會停用過期。預設值為 True。

  • MinSecondaries：要讓對某個項目的寫入操作成功，該項目必須擁有的次要複本最小數目。預設值為 0。

  • WriteBehindEnabled：啟用事後寫入功能。預設值為 false。

  • WriteBehindInterval：快取項目在寫入至快取的多久時間 (秒數) 後應寫入至提供者。最小值為 60，預設值為 300。

  • WriteBehindRetryInterval：當連線至事後寫入 (write-behind) 提供者失敗時，每次重試之間等候的間隔 (秒)。預設值為 60，等同於最小值。

  • WriteBehindRetryCount：重試連線至事後寫入 (write-behind) 提供者的最大次數。預設值為 -1，表示不限制重試次數。

  • ReadThroughEnabled：啟用貫穿式讀取 (read-through) 功能。預設值為 false。

  • Provider Type：提供者組件類型的完整格式名稱。此提供者會實作事後寫入 (write-behind) 和貫穿式讀取 (read-through) 功能。名稱會區分大小寫。例如：RTProvider.Provider, RTProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=80e2cb5f6ba933f0.

  • ProviderSettings：一或多個金鑰/值配對，指定提供者的連線資訊。例如：@{"setting1"="value1";"setting2"="value2"}.

  • RefreshNow：更新執行中快取叢集上的事後寫入 (write-behind) 和貫穿式讀取 (read-through) 設定。此開關無法更新其他設定。

範例：Set-CacheConfig -CacheName NamedCache1 -TimeToLive 30

Get-CacheStatistics

Get-AFCacheStatistics

傳回具名快取的統計資料，如 CacheName 參數所指定。

注意

如需有關如何使用此命令來搭配 HostName 與 CachePort 參數的詳細資訊，請參閱上表。

參數描述如下所示：

  • CacheName：快取的名稱。

範例：Get-CacheStatistics -CacheName NamedCache1

Get-CacheRegion

Get-AFCacheRegion

傳回具名快取中所有區域的清單，如 CacheName 參數所指定。區域只能由快取用戶端建立或移除。快取叢集可控制每個區域會位在哪部快取主機。

注意

如需有關如何使用此命令來搭配 HostName 與 CachePort 參數的詳細資訊，請參閱上表。

參數描述如下所示：

  • CacheName：快取的名稱。

範例：Get-CacheRegion -CacheName NamedCache1

主控台管理命令

下表列出的命令可用來執行與管理 Windows PowerShell 快取管理工具相關的操作。

命令 (RTM) 命令 (QFE) 說明

Set-CacheLogging

Set-AFCacheLogging

此命令可為 Windows PowerShell 快取管理工具工作階段啟用檔案型記錄功能。使用此命令初始化的事件追蹤功能，只會從呼叫時開始持續至 Windows PowerShell 工作階段期間結束。

根據預設值，記錄功能是在 VERBOSE 等級啟用。預設記錄檔位於使用者的 %temp% 目錄，名稱含有前置詞 DCacheAdministration，後面接著處理序識別碼與建立時間戳記。

如果已有名稱相同的檔案，Windows PowerShell 會嘗試附加到該記錄檔。

參數描述如下所示：

  • LogLevel：指定追蹤所擷取之事件類型的事件等級。有效值為 NONE、ERROR、WARNING、INFO 與 VERBOSE。

  • File：應寫入記錄的絕對資料夾或檔案路徑。如果未指定檔案名稱，檔名將會預設為 DCacheAdminTrace[<ProcessId>].log，其中 <ProcessId> 是 Windows PowerShell 工作階段的 Windows 處理序識別碼 。指定的所有檔案名稱都會附加 ".log"。

此範例建立會擷取警告與錯誤訊息的檔案 c:\WarningLog.log。

Set-CacheLogging -LogLevel WARNING -File c:\WarningLog

此命令只會追蹤 Windows PowerShell 工作階段的事件，不會追蹤快取用戶端或快取主機的事件。

Clear-CacheLogging

Clear-AFCacheLogging

停止由 Set-CacheLogging 啟動的記錄。

Invoke-CacheGC

Invoke-AFCacheGarbageCollector

在快取叢集上手動叫用記憶體回收功能，以釋放未使用的記憶體。這只適用於特殊情況。記憶體回收功能一般是由 .NET Framework 與 AppFabric 快取叢集的記憶體管理功能管理。

exit

exit

結束 Windows PowerShell 工作階段。

cls

cls

清除 Windows PowerShell 畫面。

另請參閱

概念

使用 Windows PowerShell 設定快取組態 (AppFabric 1.1 快取)
組態設定
AppFabric 快取組態選項
針對 AppFabric 快取功能進行疑難排解
AppFabric 快取概念 (AppFabric 1.1 快取)
開發快取用戶端

  2012-04-05