Plugins Upload Guide

Concept

Enterprise customers are allowed to upload custom plugins for their private Photon Cloud.
Each plugin assembly is identified by a name, version and customer ID.
In addition, a key is required for authentication to upload plugins.
Several versions of the same plugin assembly can be used in parallel.
After the upload of a specific version is finished, the customers can configure their application to use that version through their customer dashboard.

Workflow

Prerequisites

Required Customer Data

To better illustrate the upload process, we will use example values throughout this section:

• Customer: "SampleCustomer"
• Key: "MyKey"
• Plugin: "MyPlugin"

Plugin Files

Compile the plugin code. The output must be located in a "bin" folder (no subfolders). Add the "bin" folder to a .zip file:

MyPlugin.zip
    - /bin
        – MyPlugin.dll
        – PhotonHivePlugin.dll
        – *.dll

Preparing PowerShell

1. Download the plugins upload zip file. Unblock the "Photon.PrivateCloud.Plugin.Client.SAS.zip" file and then extract its content.
2. Please make sure to synchronize date and time on the machine running the upload script. Otherwise, it might not work.
3. Open a new PowerShell window. It is recommended to start a new PowerShell session for the plugins upload.
4. If you have the default Windows PowerShell "Restricted" execution policy you need to change it.
   We recommend to set it to "RemoteSigned" using Set-ExecutionPolicy RemoteSigned. To
   get the current execution policy use Get-ExecutionPolicy.
   Read more about "Running Scripts" from Microsoft TechNet.
5. Import the modules needed from the script "Photon.PrivateCloud.Plugin.Client.SAS.psm1" as follows:

Import-Module .\Photon.PrivateCloud.Plugin.Client.SAS.psm1

The available commands imported in the module can be listed using:

Get-Module Photon.PrivateCloud.Plugin.Client.SAS | Select-Object -ExpandProperty ExportedCommands

To get help about a command just use Get-Help with the command name available from the previous list.

Example to get help about Add-PhotonPlugin:

Get-Help Add-PhotonPlugin -Detailed

Upload

Use the "Add-PhotonPlugin" command to upload the plugin:

Add-PhotonPlugin -Customer SampleCustomer -Plugin MyPlugin -File C:\MyPath\MyPlugin.zip -Key MyKey  

The upload-script will assign an auto-incremented version number.
It returns the assigned version number on success.

Example output after successful upload:

MD5 : 036eb2b33cbfbebdd5bf31474fbf53e4
Name : SampleCustomer/MyPlugin/1/MyPlugin.zip
LastModified : 3/25/16 7:49:58 PM +00:00
Length : 222222
Customer : SampleCustomer
Plugin : MyPlugin
Version : 1

Verify

When the upload is finished, the plugin gets deployed to your private Photon Cloud servers.
Check the status of the deployment for a specific version like this:

Get-PhotonPluginStatus -Customer SampleCustomer -Plugin MyPlugin -Key MyKey -Version 1 

If the number of available servers / number of finished servers are the same, the plugin is ready to use.

You can check all the available (uploaded) plugins for your account using this command:

Get-PhotonPluginList -Customer SampleCustomer [-Plugin MyPlugin] -Key MyKey

The "Plugin" parameter is optional.
Use it to check all versions of one plugin assembly by specifying its name.

Configure

Go to the dashboard and configure the Plugin to use the new version.
The version string must match the "Version" string from the scripts exactly.
Go to the "Plugins Manual to know more about Plugins configuration for Enterprise Cloud.

Example configuration values:

• AssemblyName = "MyPlugin.dll" (same as in Plugins SDK)
• Type = "MyPlugin.PluginFactory" (same as in Plugins SDK)
• Path = "SampleCustomer\MyPlugin"
• Version = "Version" (string from upload script)
• [CustomKey1] = [CustomValue1]
• ...

Removing Old Plugin Versions

If you have uploaded many versions of your plugin it is recommended to remove old ones which are not in use anymore.
If you don't do this and we are adding new servers to your Enterprise Cloud due to high load, the process may take longer than necessary due to synchronization of old plugin files to the new servers.

This is meant to be used for older versions of the plugin and not recent ones.
It also does not remove the plugin on your Enterprise Cloud servers but only on the storage from which it is being synced to the servers.

Here's the idea behind this functionality:
When the game is running in production our operations team or the autoscale feature may add/remove servers any time as necessary.
Every time we add a server all 'legit'/'valid' (not previously deleted) plugin versions are being synced to that server.
After a long development process the developer might end up with hundreds of plugin version and every time a server is being added it may take long to sync all those files. Therefore we recommend to clean up from time to time and to delete older versions.

This example shows you how to remove plugin versions 1 through 42:

Remove-PhotonPluginRange -Customer SampleCustomer -Plugin MyPlugin -Range 1,42 -Key MyKey -File MyPlugin.zip

Recommendations

Versioning

Currently Photon Plugins support only side-by-side assembly versioning: one plugin DLL version per AppId.

Here are two methods we recommend for rolling out new plugins versions:

A. "Compatible" plugins deploy: does not require new client version

1. Upload new version of plugins assembly.
2. On a staging AppId: test to verify that new version works as expected. (recommended)
3. Update production AppId configuration to use new plugins assembly version.

B. "Incompatible" plugins deploy: requires new client version

1. Upload new version of plugins assembly.
2. Setup a new production AppId.
3. Configure the new production AppId to use new plugins assembly version.

Static Fields

Same plugins assembly will be shared across rooms and applications.
Static fields of same plugin class will be shared as well.
If you cannot avoid using static fields, here is what you could do to avoid using same plugins assembly in two applications:

1. Upload same plugin files under two different plugin names:

   a- Upload plugin archive with name X
   b- Upload plugin archive with name Y

2. Same configuration for two apps except "Path":

   a- Configure app A to use plugin X: "Path": "{customerName}\X"
   b- Configure app B to use plugin Y: "Path": "{customerName}\Y"