> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wrapper 範例

> 使用 Wrapper (wrappingGsdk) 範例，在不將 GSDK 呼叫新增至二進位檔的情況下，於 PlayFab 多人遊戲伺服器上執行現有的 Windows 或 Linux 遊戲伺服器。

Wrapper 範例 (也稱為 wrappingGsdk) 會包裝現有的遊戲，使其可用於部署使用 **Windows 作業系統**和 **Linux 作業系統**之遊戲伺服器的組建。

使用 wrapper 應用程式，您也能在 PlayFab 多人遊戲伺服器上使用您的遊戲伺服器組建。

<Info>
  Wrapper 是一種透過處理標準輸出和錯誤串流來呼叫 GSDK 方法的因應措施，並非供生產環境使用。
</Info>

## 範例內容

此範例包含兩個 .NET Core 主控台應用程式。

* Wrapper—將 PlayFab 遊戲伺服器 SDK (GSDK) 的最新 NuGet 套件與您的遊戲伺服器整合。此 wrapper 應用程式**並非供生產環境使用**
* Fakegame—不了解 GSDK 的基本遊戲伺服器。它就像您在使用 PlayFab 多人遊戲伺服器之前所擁有的典型遊戲伺服器。它會啟動接聽 TCP 連接埠 80 的 ASP.NET Core Web 伺服器 Kestrel。它旨在模擬完全不了解 GSDK 的遊戲伺服器。如果您沒有自己的遊戲伺服器，可以使用它。它有兩個我們可以使用的 GET 路由：/hello 用於取得簡單回應，/hello/terminate 可以終止伺服器。

## 需求

* [.NET Core 3.1 x64 SDK](https://dotnet.microsoft.com/download)

<Note>
  若要使用和檢視 PlayFab 多人遊戲伺服器，您需要從 Game Manager 啟用此功能。如需指示，請參閱[啟用 PlayFab 伺服器功能](/zh-TW/services/playfab/multiplayer/servers/enable-playfab-multiplayer-servers)。
</Note>

## 逐步解說

如需建置此範例的即時逐步解說，請查看我們在 Microsoft Game Dev 2021 的簡報 (大約從 2.52 開始)：

<iframe src="https://www.youtube.com/embed/kj2TcMlvWgk" width="100%" height="400" allowFullScreen frameBorder="0" />

<a id="acquire-and-build-wrapper-executable" />

## 取得並建置 Wrapper 可執行檔

* 使用標準 Git 方法或下載 zip 檔案，取得 [GSDK wrapper 範例](https://github.com/PlayFab/MpsSamples/tree/master/wrappingGsdk)
* 開啟命令提示字元，並使用 cd 命令將目錄路徑變更為 wrapper.csproj 檔案的位置。範例：**cd C:/ReplaceWithYourFilePath/wrappingGsdk/wrapper**
* 接著執行下列 .NET Core CLI 命令：

```
dotnet publish --self-contained -r win-x64 /p:PublishSingleFile=true /p:PublishTrimmed=true
```

wrapper 建置成功後，可執行檔會發佈在 ..\wrappingGsdk\wrapper\bin\Debug\netcoreapp3.1\win-x64\publish 資料夾中，如下圖所示。

<img src="https://mintcdn.com/microsoft-4404708b/U1LR64ZWxo45eXwl/images/playfab/multiplayer/servers/create-your-first-server/wrapper-exe-location.PNG?fit=max&auto=format&n=U1LR64ZWxo45eXwl&q=85&s=1667c376bbaa6670b270d5264513278c" alt="wrapper 可執行檔的發佈位置" width="1615" height="365" data-path="images/playfab/multiplayer/servers/create-your-first-server/wrapper-exe-location.PNG" />

## 建立遊戲伺服器資產

有兩種方式可以建立遊戲伺服器資產。

<a id="use-fakegame-game-server-with-the-wrapper" />

### 搭配 wrapper 使用 Fakegame 遊戲伺服器

使用 build.ps1 建置並封裝兩個專案 (wrapper 和 fakegame)。此指令碼會建立一個 drop 資料夾，其中包含含有必要檔案的 .zip 檔案。

* 開啟 PowerShell
* 使用 cd 命令將目錄路徑變更為 build.ps1 指令碼的位置。範例：cd C:/ReplaceWithYourFilePath/wrappingGsdk/
* 執行 **\build.ps1**
* 指令碼成功執行後，前往 ..\wrappingGsdk\drop\ 資料夾。您會發現已建立 **gameassets.zip** 檔案，其中包含模擬遊戲伺服器組建、wrapper 可執行檔 (在先前步驟中建置) 以及其他必要檔案。

### 搭配 wrapper 使用您自己的遊戲伺服器檔案

若要在評估中使用您的遊戲專案，請將 wrapper 和您的遊戲伺服器可執行檔放在同一個資料夾中。

* 依照[建置 wrapper 可執行檔](#acquire-and-build-wrapper-executable)中的指示操作
* 前往位於 ..\wrappingGsdk\wrapper\bin\Debug\netcoreapp3.1\win-x64\publish 的 wrapper 發佈位置
* 在另一個視窗中，前往您的遊戲伺服器組建以及執行遊戲伺服器組建所需的檔案。如果您不確定需要哪些檔案，請參閱[判斷所需的 DLL 檔案](/zh-TW/services/playfab/multiplayer/servers/determining-required-dlls)
* 將遊戲伺服器組建和所有必要檔案複製到 wrapper 發佈位置
* 選取 wrapper 發佈位置中的所有檔案
* 選取所有檔案後，按一下滑鼠右鍵，然後選取 **Send to** > **Compressed (zip) files to zip**。不要選取 wrapper 發佈資料夾並新增至 zip。這會導致不正確的對應。

<Tip>
  若要交叉檢查，請依照[搭配 wrapper 使用 Fakegame 遊戲伺服器](#use-fakegame-game-server-with-the-wrapper)中的指示建置 gameassets.zip，並將其作為參考。
</Tip>

## 建立並上傳 Linux 容器映像 (僅限 Linux 伺服器)

若要建立 Linux 容器映像，您需要 Dockerfile。Dockerfile 是沒有副檔名的文字檔，包含建置指定容器映像所需的所有命令。在此範例中，已為您建立此檔案。您只需建置容器映像並執行它即可。

如果您想要使用 Windows 開發裝置，則需要安裝 Windows 子系統 Linux 版 (WSL)。下方提供指示。如需詳細資訊，請參閱 [Windows 和 Linux 容器映像的差異](/zh-TW/services/playfab/multiplayer/servers/deploying-linux-based-builds#windows-and-linux-container-image-differences)。

1. [設定您的 Windows 開發裝置](/zh-TW/services/playfab/multiplayer/servers/deploying-linux-based-builds#set-up-your-windows-development-device) (選用)
2. [取得您的 PlayFab 容器登錄登入認證](/zh-TW/services/playfab/multiplayer/servers/deploying-linux-based-builds#get-your-playfab-container-registry-sign-in-credentials)
3. 使用現有的或建立您自己的 Dockerfile
   此步驟會因您使用的是 FakeGame 還是您自己的遊戲伺服器而有所不同。
   * 如果您使用的是 FakeGame，請確認您有 [Dockerfile](https://github.com/PlayFab/MpsSamples/blob/master/wrappingGsdk/Dockerfile)
   * 如果您使用的是您的遊戲或需要建立 Dockerfile，請參閱[建立您的 Dockerfile](/zh-TW/services/playfab/multiplayer/servers/deploying-linux-based-builds#create-a-dockerfile)。您可以使用 FakeGame 的 [Dockerfile](https://github.com/PlayFab/MpsSamples/blob/master/wrappingGsdk/Dockerfile) 作為起點。
4. 開啟已安裝 Docker 的 Linux 終端機，例如 Ubuntu。將 TAG 和 ACR 變數的值取代為您的值。然後執行下列命令。

```docker theme={null}
TAG="0.1"
ACR="customer5555555.azurecr.io"
docker login ${ACR}
```

<Tip>
  若要檢查 ACR 和 TAG 變數是否已正確定義，請執行 **echo $ACR__ 和 __echo $TAG**。
</Tip>

5. 輸入從先前步驟取得的使用者名稱和密碼。
6. 建置並上傳 Linux 容器映像。

執行下列命令以建置並上傳 Dockerfile。**docker build** 命令結尾有一個 "."。您必須位於與 Dockerfile 相同的資料夾/目錄中。如需詳細資料，請參閱[建置並上傳 Linux 容器映像](/zh-TW/services/playfab/multiplayer/servers/deploying-linux-based-builds#build-and-upload-linux-container-image)。

```docker theme={null}
docker build -t ${ACR}/wrapper:${TAG} .
docker push ${ACR}/wrapper:${TAG}
```

## 使用 Game Manager 或 API 部署組建

Windows 和 Linux 遊戲伺服器的部署組建程序相似。

### 部署 Windows 遊戲伺服器

這些步驟與 Windows Runner C# 範例相似。請依照這些步驟操作，差異如下所列。

* [使用 Game Manager 部署和設定伺服器](/zh-TW/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-game-manager)
* [使用 PowerShell/API 部署和設定伺服器](/zh-TW/services/playfab/multiplayer/servers/quickstart-for-multiplayer-servers-api-powershell)

如果您偏好在本機進行測試，請參閱[在本機對遊戲伺服器進行偵錯以及與 PlayFab 整合](/zh-TW/services/playfab/multiplayer/servers/locally-debugging-game-servers-and-integration-with-playfab)。

**此範例特有的設定**

* 啟動命令：
  * 使用 **C:\Assets\wrapper.exe -g C:\Assets\fakegame.exe arg1 arg2**
  * 如果您使用的是自己的遊戲伺服器組建，請將 fakegame.exe 取代為您的遊戲伺服器可執行檔名稱
* 網路設定：名稱：**gameport**，連接埠：**80**，通訊協定：**TCP**
* 資產：使用 FakeGame 時，請將 **gameassets.zip** 上傳為資產。

### 部署 Linux 遊戲伺服器

請依照下列一般步驟進行部署。

* [使用 Game Manager 部署和設定伺服器](/zh-TW/services/playfab/multiplayer/servers/deploy-using-game-manager)
* [使用 PowerShell/API 部署和設定伺服器](/zh-TW/services/playfab/multiplayer/servers/deploy-using-powershell-api)

**此範例特有的設定**

* 選取您上傳的容器
* 網路設定：名稱：**gameport**，連接埠：**80**，通訊協定：**TCP**
* 不需要上傳資產和設定 **Start Command**

<Note>
  在使用 RequestMultiplayerServer API 進行配置期間，您所連線的連接埠將不是 80。這是因為 PlayFab 多人遊戲伺服器服務會在 Azure Load Balancer (將您的連接埠公開至公用網際網路) 與在 Azure 虛擬機器上執行的遊戲伺服器之間建立對應。
</Note>

## 使用 LocalMultiplayerAgent 執行 wrapper

如果您想要在自訂遊戲伺服器上測試 GSDK 整合，強烈建議使用 LocalMultiplayerAgent。

如果您將 LocalMultiplayerAgent 與 Windows 容器搭配使用，則需要正確設定 MultiplayerSettings.json 檔案。您可以在下方找到範例，請特別注意 LocalFilePath 和 StartGameCommand 的值。別忘了將 fakegame.exe 取代為您的遊戲伺服器可執行檔名稱。

```json theme={null}
"AssetDetails": [
    {
        "MountPath": "C:\\Assets",
        "SasTokens": null,
        "LocalFilePath": "C:\\projects\\gsdkSamples\\wrappingGsdk\\drop\\gameassets.zip"
    }
],
"StartGameCommand": "C:\\Assets\\wrapper.exe -g C:\\Assets\\fakegame.exe",

// if you are using fakegameserver you should also configure port mapping for port 80
"PortMappingsList": [
            [
                {
                    "NodePort": 56100,
                    "GamePort": {
                        "Name": "gameport",
                        "Number": 80,
                        "Protocol": "TCP"
                    }
                }
            ]
        ]
```

您現在已準備好使用 LocalMultiplayerAgent 進行測試。如果您已正確設定，一旦 LocalMultiplayerAgent 啟動您的遊戲伺服器，您就可以透過 curl 在 **[http://localhost:56100/Hello](http://localhost:56100/Hello)** 連線至伺服器。

## 如何連線至 MPS 上的遊戲伺服器

若要與 MPS 上的遊戲伺服器建立連線，必須判斷適當的連接埠號碼。這項需求源自於多部虛擬機器 (每部可能執行許多遊戲伺服器執行個體) 在負載平衡器後方進行管理的設定。在這種設定中，單一公用 IP 連接埠可能對應至這些虛擬機器上的不同連接埠，每個連接埠都與不同的遊戲伺服器執行個體相關聯。

### 使用 Game Manager

您可以使用 Game Manager UI 配置遊戲伺服器並與其建立連線。

1. 登入 Game Manager
2. 前往 Multiplayer => Servers 頁面，選取您的組建
3. 前往 Servers 頁面，然後按一下 "Request server" 按鈕。
4. 在下一頁上，記下公用 **IPv4 位址**和**連接埠**。
5. 使用 curl 在 **http\://\[IPV4Address]:\[Ports->Num]/Hello** 進行連線。"

### 使用 MPS Allocator 範例

以下說明如何使用 [MPS Allocator 範例](/zh-TW/services/playfab/multiplayer/servers/mps-allocator-sample)配置遊戲伺服器並與其建立連線。

1. 編譯並執行 MPS Allocator 範例。
2. 套用 "ListBuildSummaries" 命令以檢視可用的組建及其對應的組建識別碼。
3. 叫用 "RequestMultiplayerServer" 以起始遊戲伺服器執行個體的要求。
4. 將所選的組建識別碼輸入 "ListMultiplayerServers" 命令，以產生可用伺服器的清單。
5. 選擇作用中的遊戲伺服器執行個體，然後使用先前步驟取得的組建和工作階段識別碼執行 "GetMultiplayerServerDetails"。
6. 記下回應中顯示的 **IPV4Address** 和 **Ports->Num**。
7. 使用 curl 在 **http\://\[IPV4Address]:\[Ports->Num]/Hello** 進行連線。

## 另請參閱

* [建立您的第一部伺服器](/zh-TW/services/playfab/multiplayer/servers/create-your-first-server)
* [資源和範例](/zh-TW/services/playfab/multiplayer/servers/server-samples-resources)
* [PlayFab 多人遊戲伺服器 SDK](/zh-TW/services/playfab/multiplayer/servers/server-sdks/overview)
* [API 參考](xref:titleid.playfabapi.com.multiplayer.multiplayerserver)


## Related topics

- [建立您的第一部伺服器](/zh-TW/services/playfab/multiplayer/servers/create-your-first-server.md)
- [使用 Game Manager 部署組建](/zh-TW/services/playfab/multiplayer/servers/deploy-using-game-manager.md)
- [使用 PowerShell/API 部署組建](/zh-TW/services/playfab/multiplayer/servers/deploy-using-powershell-api.md)
- [LocalMultiplayerAgent 概觀](/zh-TW/services/playfab/multiplayer/servers/LocalMultiplayerAgent/local-multiplayer-agent-overview.md)
- [使用 LocalMultiplayerAgent 對容器遊戲伺服器進行偵錯](/zh-TW/services/playfab/multiplayer/servers/LocalMultiplayerAgent/run-container-gameserver.md)