Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Mr ChriZ]

What is the purpose of the template
This template should help allow for rapid development and distribution of C# Interface plugins for Media Center!

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.
I will then 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 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
• Those who install the plugin will require the latest .NET framework 2.0

Where can I get it?
The template is now on the JRiver Skins and Plugins Pages.
You can download it here

Documentation
Following this post are two more.  They contain documentation relating to this template.
The documentation is all new, and in part under construction.  Expect Errors and Ommissions...
The documentation may look intimidating, but once you get your head round it
you'll find it only takes you about 5 minutes to start developing new plugins =)
It is split up into the following sections:

• Orientation

This just goes through in detail what is included in the plugin, and how it works.  During reading this you shouldn't be changing anything....

• Template Setup

This section shows you how to set the plugin up ready for development.  Going through this you
will rename everything to match what you are doing.  I give examples as if I was making a Coffee Maker Plugin.
The instructions are for Visual Studio.  It shouldn't be difficult for #Develop users to find the equivilents.
However if difficulties are found just post a message.

• Usage

This section shows how the plugin is then used once setup....


Visual C# Express
Doof has had some success using this
with Microsoft's free C# Express.
Things have moved around a bit however so you may want to read some of his
posts, or contact him if you have issues.

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.

[/list][/list]

[Mr ChriZ]

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.
[li]Installation[/li]
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.
[li]MC_CSPlugin_Template[/li]
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 or Visual Studio 2005.
[/list]

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 once class at present.  If you want more you can add them at a later date.

Main Interface Partial Classes
Click the plus symbol next to MainInterface.cs on the Soloution Explorer.
You can see that this class is split into partial classes, spltting the form designer code
from the user code.  (This is a new feature in C# 2.0)

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.
[li]Interop Program ID Registration[/li]
This is for Interop Registration.  This is very important and discussed later.
[li]Attributes[/li]
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.
[li]Constructor[/li]
This is the main constructor for the plugin.  This creates the GUI (Windows Forms)controls.  I think I need to check up on when this is first called...
[li]Media Center Initialisation[/li]
Media 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.

[/list]

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, information about that plugin such as who made it and what it's called,
and also the ProgID which Media Center will use to access the plugin.
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 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

[li]Languages[/li]

Language for setup, defaults to English, play with this as need be.

[li]Files[/li]

The files that will be installed.  This defaults to all the files and folders that are contained
within the "Build Files" directory.

[li]Icons[/li]

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.

[li]Registry[/li]

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.

[li]Run[/li]

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. 

[li]UninstallRun[/li]

On Uninstall of the plugin we want it to be unregistered.  This just performs a REGASM /unregister
on the plugin
[/list]

[Mr ChriZ]

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_CSPlugin_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 MC_CSTemplate 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 MC_CSTemplate to the name of your project
Again we'll call this one "Coffee Maker Plugin project"

3. Rename MC_CSPlugin_Template.dll in "Build Files" to whatever your assembly's going to be called...
For example MC_CSPlugin_CoffeeMaker.dll
You might need to come back to this step, it will make more sense once you've done the source
code changes.

Source Code Changes
Open up the soloution(Not the project) in Visual Studio 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 MC_CSPlugin_Template.

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 suite...

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...
[li]Registry[/li]

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.
[li]Run/Uninstall[/li]

Change the DLL to match that of the assembly DLL.
[/list]

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.

[Mr ChriZ]

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 your 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.

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