INTERACT FORUM
Windows => Plug-in Development => Topic started by: Mr ChriZ on June 20, 2006, 05:20:35 pm
-
Background Information
Following on from the C# Plugin Template,
I've made a VB.NET 2.0 Plugin Template.
I've also Converted the C# Documentation
to go with it. Although I've not got round to testing it thourighly yet.
I've done a fair amount of VB6 in the past, but no
VB.NET except this plugin. It's only been tested on one machine,
so there is a possability it won't work.
Please post any queries/thoughts suggestions in a new thread.
If you do get stuck do post a thread, don't give up :)
I or others can help with most the simple things.
What is the purpose of the template
This template should help allow for rapid development and distribution of VB.NET Interface plugins for Media Center!
The template is a barebones plugin. It is ready to install from the moment you download
the files. In Media Center it presents a blank grey background.
Full Source code is provided which can be modified for your very own MC plugin.
It also gives you full access to the Media Center interface SDK, so your ready
to go! No need to work out the complexities of getting .NET to interface with
MC! Detailed documentation will be included below which will lead you
how to setup the template for your very own .NET plugin.
It's all designed to be easy to understand. Any problems however just
post a new thread.
Why is this thread locked?
I think it would be better if discussions of problems
were in seperate threads, as this thread is already seriously long,
and any problems with the documentation will be amended as time
goes by rather than have a string of questions that new comers have
to read through to work out how to solve a problem.
I will amend this thread as necassery. (Citing anyone who inputs to it)
What does the template feature?
- The source code for a simple plugin which just displays
the main user interface, and obtains the reference to the Media Center Interface.
Full access to the SDK is provided and is picked up by both #Develops and Visual Studios Intellisense
- A script file for the InnoSetup (http://www.jrsoftware.org/isinfo.php) installation program,
which will create a setup program for the plugin (Also allows removal of plugin).
Pre-requesits
- The plugin is written in .NET 2.0, requiring either Visual Studio 2005
or #Develop Version 2.0.. - InnoSetup (http://www.jrsoftware.org/isinfo.php)
- Those who install the plugin will require the latest .NET framework 2.0
- Experience of coding in VB6/.NET is preferable. Any other language will probably do
Where can I get it?
you can download it here (http://accessories.musicex.com/mediacenter/mc_data/plugins/VBNetPluginTemplate.rar).
Documentation
Is below but needs testing, and maybe subject to modifications.
Visual Basic.NET Express Compatabillity
Unknown.
Desirables
Over time I intend to make improvements to the template
to simplify matters, and make things easier.
If you make any improvements you'd like to see
integrated, let me know :)
- Automatic plugin setup system
- Detection of Media Center running if Plugin already installed
- Closure of Media Center if necassery
- Detection of Media Center running
- Automatic detection of the .NET Framework
- Automatic installation of the .NET Framework if required
- Ideally this could be turned into a Visual Studio Template
which could simplify the process further.
-
Orientation
This will just give you a brief view of whats included in the template.
First of all extract the contents of the RAR file to a suitable directory.
Template Contents
You should find three folders
- Build Files: This folder contains what will eventually be installed on the target system.
All files which are in here will be picked up by the innosetup script. You can add and remove files as you wish. - Installation: This contains an InnoSetup script which will allow you to create a setup program
which will be run by the end user to install your plugin on there system.
(Of course you can distribute your plugin in any fashion you like, this is just a good way to do so).
If you don't use Innosetup you will have to create REG files which do what the innosetup script does for you.
Innosetup also compresses everything into one neat .EXE file.
The Installation folder also contains a folder called Output. This is where the installation Setup.exe will be placed.
- VB_NetPluginSoloution:This contains the source code which produces the plugin. It includes a soloution and a project which can be opened in both #Develop 2.0 (Yup #Develop will open VB.NET stuff!) or Visual Studio 2005. I'd imagine you can open it with VB.NET Express however I've not tried it
Source Code
Open up the soloution file in your chosen development environment.
I'm using Visual Studio 2005 so you'll have to find the counter parts for the
environment your using.
Classes
In the Soloution Explorer you will see a class called MainInterface.
There is only one class at present. If you want more you can add them at a later date.
Main Interface Panel
Double click on MainInterface. It will open up a form designer, and display a Panel.
This panel is the main Window area for the plugin. You can place any controls
you wish here.
Main Interface Source Code
If you now switch to code view by pressing F7 you will see the main code
for the class, but not the designer code. It's not doing much at present.
So the class is just 65 lines long.
I've used Regions to split the class up into the following sections
- Libraries:These are the using statements which tell the compiler which libraries are needed.
- Attributes:This contains the private attributes in use by our class. Currently there is only one. This is the reference to the Media Center Interface which allows us to control and access Media Center using the SDK.
- Media Center InitialisationMedia Center calls this function when the plugin is created. It is here that we set our Media Center Reference, so that we can permenantly access it.
Just above the class definition theres a line
<System.Runtime.InteropServices.ProgId("VB.Net_MCPlugin.Template")> _
This is for Interop Registration. This is very important and discussed later.
Register for COM Interop
Information
In order for the plugin to be registered with Media Center two things must occur:
- First of all the appropriate registry settings must be created which tell Media Center
that a plugin exists. The registry settings also contain information about the plugin such as who made it and what it's called, and also the ProgID which is a unique key Media Center will use to find the plugin and create it.
- Secondly the plugin must be registered in such away that the registry can correlate the
progID to a specific DLL. This is all related to the Component Object Model (COM).
In order for a .NET assembly to be registered in this way, it must use something called
COM Interop. To allow Media Center to see the plugin we must Register the plugin for COM Interop
The method of doing this normally is through a command line utility called REGASM.
The Innosetup script does this when a plugin is being installed.
When developing Visual Studio does allow you to Register the plugin everytime it is rebuilt.
The template comes with this setting turned on.
The Media Center Interface
JRiver provide a type library file which provides the interface to Media Center.
This has been wrapped into an assembly file. (How this is done can be seen in my Busybox.NET (http://yabb.jriver.com/interact/index.php?topic=31072.msg213612#msg213612) tutorial).
As part of the template there is provided a ready made wrapped assembly file - MediaJukebox.dll
The plugin also already includes all the necassery references to this DLL.
InnoSetup Script
The inno setup script Contains the following sections
- Setup: This area contains all the strings that are displayed during the setup process
Change these to suite your plugin, and information about yourself.
It also contains the default Directory for the plugin which is currently
..\Program Files\J River\Media Center 11\Plugins\TemplatePlugin - Languages:
Language for setup, defaults to English, play with this as need be. - Files: The files that will be installed. This defaults to all the files and folders that are contained
within the "Build Files" directory. - Icons: The icons that will be placed in the Start Menu, defaults to just the uninstall icon
since the plugins cannot usually be run on their own. - Registry: The registry entries that must be installed. These are particulariliy important because
they tell Media Center that the plugin exists, what it is called, and how it can be found.
Most of the values are just information that is provided about the plugin when viewed
in the plugin manager.
Two values which are more critical are the ProgID and the PluginMode.
The ProgID represents the ID for the plugin by which COM finds the plugin.
It MUST match the ProgID that is contained within MainInterface within the source code of the plugin, in order for
the plugin to be found.
The PluginMode specifys how the plugin should load on start up of Media Center. A value of 1 means
that the plugin loads once and will remain open even when the interface is not shown.
A value of 0 means the plugin will reload every time the user opens the interface, and close when the user
moves away from it. - Run: During installation of the plugin, it must be registered for COM interop, as detailed above in the
section Register For COM Interop. The run section has a REGASM command to do this. It does rely on the user
having the exact same version of the .NET framework. Any ideas on how this can be avoided
are appreciated. - UninstallRun: On Uninstall of the plugin we want it to be unregistered. This just performs a REGASM /unregister
on the plugin
-
Template Setup Instructions for Visual Studio 2005
Before doing any work creating the plugin you must first perform some renaming (Unless you want to distribute
a plugin called MC_VBPlugin_Template!
The following steps are best performed in order. Ideally in time they will be automated.
Folder/File Renaming
Make sure the soloution is closed in Visual Studio before performing this step.
1. Rename the folder which contains the soloution files from VB_NetPluginSoloution to the name of your project
I think appending the the name "soloution" is a nice convention.
For example "Coffee Maker Plugin Soloution"
2. Rename the folder which contains the project files from VB_NetPluginProject to the name of your project
Again we'll call this one "Coffee Maker Plugin project"
3. Remove the file MC_VBNETPlugin_Template.dll in "Build Files". You'll regenerate it in a bit.
Source Code Changes
Open up the soloution(Not the project) in Your chosen development environment (Again I will be using VS.NET 2005).
Visual Studio will complain it can't find the project, because we have just moved it.
In the Soloution Explorer you should see the project VB_NetPluginProject
1. Select this and remove it, by pressing delete then ok.
2. Now add the project back in by right clicking the soloution, and selecting "Add Existing Project"
Find the project file and press ok.
The project will be added back to the soloution, however it will be named incorrectly.
3. Rename the soloution within Visual Studio by selecting it from the soloution explorer, then press F2 and rename it.
4. Rename the project by selecting it from the soloution explorer, then press F2 and rename it.
5. Press Shift-F4. In the Application settings change the Assembly name (The name of the output DLL) and default namespace to suit...
6. Change the Prog ID in MainInterface.cs Line 28 to something appropriate for example:
[System.Runtime.InteropServices.ProgId ( "MCPlugin.CoffeeMakerPlugin" )]
7. Save the soloution.
InnoSetup Script Changes
- Setup: In the setup area you'll want to change the various attributes to your own name etc...
- Registry: Under Registry change the subkey to the name of your plugin. This if I remember correctly is the name
that Media Center uses for the plugin under Services and Plugins. Change Company, URL, and Copyright to the
appropriate Values. Change the ProgID to match that in the source code, as in Step 6 of the source code changes. These must be identical else Media Center will not find the plugin. - Run/Uninstall: Change the DLL to match that of the assembly DLL.
First time build on the Development machine
Perform a Clean Soloution from the build menu to remove all object files from
the bin debug folder. Now perform the build soloution.
First time registration on the Development machine
Open the setup script in the "Installation" folder with InnoSetup.
Press F9. The script will be run, a new setup file compiled, and then run.
Go through the setup process for the plugin.
You will see any flaws as you run through the setup.
At the end it should have registered the plugin with Media Center.
Checking the plugin in Media Center
Open Media Center up, and check the plugin now appears in plugin manager.
You may have to hide it then show it. It should then appear under services and plugins.
-
Usage
Before performing steps in this section, please make sure you have followed the setup steps
in the previous post!
Development
This bits up to you! :)
New Builds
Everytime you do a new build in Visual Studio the plugin will be re-registered because
the option Register for COM interop is turned on.
This means that Media Center is using the assembly file that is in the BIN\Debug directory.
If you try to rebuild while Media Center is open, it will fail.
First Close Media Center, then build, then test it by reopening.
Copying the correct files to the "Build Files" Directory
Once you're sure that your plugin is ready for distribution.
First remember to switch to release mode.
Perform a build within Visual Studio.
Now you need to copy the assembly file from Bin\Release
to "Build Files" and any dependancies.
Techically you can setup Visual Studio to do this for you,
however since only you know for sure which files that are in
the release directory should be installed I've left this out of the template
Building a new Setup.EXE
Open up the setup script in InnoSetup.
Press CTRL + F9. The new setup will be compiled.
Press F9 to test it out. You'll find the setup.exe under
Installation\Output\Setup.exe