Creating a Component

The VWW SDK provides all you need to get started making your own component.

Prepare Your Environment

To get started you'll need to have Visual Studio 2017 installed. You'll also need to install the Razor Generator visual studio extension. This extension helps when extending the admin by compiling your MVC razor views into source files automatically so they're included in your component.

Install The SDK Visual Studio Extension

In the VWW SDK folder ComponentDev is a file VWW.SDK.VisualStudio.vsix. With Visual Studio closed, run this installer to add the VWW SDK extension. This extension adds a project template that helps you get started creating a new component.

Create A Solution For Your Components

You'll need a Visual Studio solution, properly configured, to help you build your components properly. A pre-configured solution has been created for you in the SDK in the Solutions\VWW.ComponentDev folder. This is simply a "Blank Solution" which you could create yourself from the Visual Studio template of the same name (File -> New -> Project..., then search for "blank solution").

What's really important here is the NuGet.config file in the parent folder (Solutions). This file helps Visual Studio find our NuGet package library when adding core libraries to your project. If you prefer to make your own solution in some other location, copy this NuGet.config file to the root of your solution (or a parent folder) and update the VWW CoreLibs package source to point at the NugetFeed folder in the SDK (probably with an absolute path). Please note there are two places in the file where the VWW CoreLibs package source is specified: under the packageSources node and also under the activePackageSource node. Make sure you update both.

Also note: The Solutions\VWW.ComponentDev folder is ignored with a .gitignore entry, but you may want to ignore changes to the solution file in your local repo by executing the following command from the solution folder: git update-index --skip-worktree VWW.ComponentDev.sln

Create Your First Component Project

Open your Blank Solution or the SDK provided one (Solutions\VWW.ComponentDev\VWW.ComponentDev.sln). Right-click on the solution in the solution exporer and select Add -> New Project.... In the Add New Project dialog, search for "vww". The only result should be "VWW Component With WebViews", click once on this template item, and below, you'll be able to provide a project name.

We recommend a good naming convention like <Company>.Components.<ComponentName>. Our in-house components are named things like VWW.Components.GameCloud. A short first tag is probably best. This name becomes the name of your assembly, and the root namespace in your C# project.

When you press create you'll be presented with a small dialog asking for a few template strings to help generate your component project:

• Type Name - This should be a valid C# type name and should usually be the same as the last part of your assembly name (GameCloud in the example of one of our components above)
• Display Name - This is the human readable name of your component.
• Short Name - This short name is used for your component's URL path prefix and database schema root, and other places where a short prefix is helpful. It should distinguish your component from others, but have no spaces and be short (between 2 and 8 characters).

When you press Finish, your project will be created. This step will take a while as various NuGet package references are added to your project. Be patient.

Build your component

Your component should be ready to build immediately. Build the solution. A Post-Build copies your component assembly to the Components folder in the root of your solution folder (the parent folder of your component project folder). The idea is that if you have more than one component project in your solution, all the components build into this folder for easy deployment.

Each component builds into a sub-folder of the Components folder with a GUID as its name. The GUID is your component's "Component ID". This ID is assigned at project template execution in the step above and should never be changed. You can find your component ID by looking in the AssemblyInfo.cs file in your project. There is an assembly-level attribute VWWComponent(<GUID>); that marks your assembly as a VWW component and sets its ID.

Deploy Your Component

There are 2 ways to deploy your component:

1. If you have access to the filesystem where your servers run from, you can copy a component's GUID-named folder directly to your server's Components folder.
2. You can deploy a component using the Component Updater tool included in the SDK.
   • Create yourself a Remote Application API Key via your admin. Go to Misc -> API Management and press the New Remote Application button. Enter a name for the new API key (Component Updater will do) and click Add. You can now click on your new remote application key and see its URL, Key, and Secret. You'll need these for the next step.
   • The Component Updater tool is in your SDK folder at ComponentDev\ComponentUpdater\VWW.Utilities.ComponentUpdater.exe and if you wanted to publish component 845E1F53-47EE-4B5C-88C8-DC4278C22B7C, you would run the command like this:
     VWW.Utilities.ComponentUpdater.exe -c 845E1F53-47EE-4B5C-88C8-DC4278C22B7C -a -r <YOUR_COMPONENTS_FOLDER&gt -b <Url> -k <Key> -s <Secret>

In either case, assuming this is the first time you've published, the component will be imported the next time the service provider is restarted, or a new component scan is initiated from the admin. From the admin, go to Components -> Installed Components and scroll down to the section Detected Components Not Loaded. Here you will see any detected new components. You can press the Rescan button to trigger an immediate re-scan.

Enable Your Component

Next you must enable your new component. From the admin go to Components -> Installed Components and scroll down to the section Detected Components Not Loaded. Find your component and press the Enable button beside it. You will be asked if you'd like to immediately restart the service provider it get your component loaded, otherwise it will be loaded on the next system restart. You can trigger a system restart at a convenient time from the same page by pressing the System Restart button.

Once the system restart is complete, you should see your new component section in the admin, and your component should start doing whatever it does. You can look for debug messages in the various debug logs as well.

Pro Tip: You can enable your component and restart the service provider as part of the Component Updater command (described in Deploy Your Component above) by passing the -e and -x switches.

Update Your Component

Once you've got your component installed and loaded by the server, you'll probably want to update it from time to time (or constantly during development). To do just repeat the steps above in Deploy Your Component. When you're ready, restart your server and the new code will take effect. If you're using the Component Updater, you don't need to use the -a switch (add missing), and you may want to use the -x switch (restart) to trigger an immediate server restart on update.

Pro Tip: You can add a post-build command to your component project so that when it builds successfully, it automatically executes the Component Updater to upload your updated component, and restart the server all in once step. This should only be done against a development server, but can really help with rapid build, deploy, test cycles.