[TUTORIAL] Context Menu to export EML files

Question

Hello there folks!
I'm pretty new to the topic of C3PO, GW and all the Novell stuff and one of my tasks was to "code an export mechanism for GW8 thats lats us save e-mails to our storage system". Ok, that was a hammer. But wrapping my head around it and starting to error out the things got me pretty far and I guessed it was tutorial material. So here we go:
@Moderators: This is the thread that has everything in it. the other one can be deleted.
This tutorial is intendend for C# only. I don't like VB and I'm too dumb for C++ so if you need it for another dialect you need to work it out your self.
Agenda:
Needed packages
C3PO wizard
Loading to Visual Studio 2010
Needed Imports/References
Simple MessageBoxing
Export Code
Registering and caching the .DLL
Testing (please help me with a better way here)
1. Needed packages
the novell-gwc3po-devel-2012.11.15.zip file (unzip this after downloading)
an installed version of Visual Studio 2012 C# (or if you want to work with a different dialect choose another)
cmd access to some of the registering tools:
It may be the best thing to set tose paths up in you env variables. Allthough when running the cmd with administrator privileges you can't use regasm from env variables and need to cd to the directory.
RegAsm (regasm.exe): C:\Windows\Microsoft.NET\Framework\v4.0.30319 (the version depends on the target)
GACUtil (gacutil.exe): C:\Program Files(x86)\Micrsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\ (this path is also dependent on your target framework version, I chose .NET4)
StrongName (sn.exe): C:\Program Files(x86)\Micrsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\ (this path is also dependent on your target framework version, I chose .NET4)
a good beverage :D (you should obtain multiple of these :D)
2. The C3PO wizard
In my case I wanted to add the functionality via the context menu. So the code executes when right-clicking on one or multiple messages displays another menu item and is clickable.
This is pretty easy to realize via the C3PO wizard. You'll find it in the downloaded and extracted novell-gwc3po-devel-2012.11.15.zip from above. Start it (it is located in extracted-zip-folder/gwc3po-FILES/C3POWizard/C3POWizard.exe) and setup your project:
Setup the project in the wizard step 1
I usually setup the Wizard inside my Visual Studio 2010 projects folder, create a new folder there with the name of the project and check the options i want to have.
In the next step I chose which type of View should display my custom context menu. Since I was only interested in exporting and working with e-mails I chose "GW.MESSAGE.MAIL" and added it to the bottom list via, you guessed it, "Add".
Setup theView that invokes the new context menu item
In the next step you I had to setup a new entry for the context menu. You could make side-droppable menus here etc. But for me a simple "Add Menu" was enough. Give it a name of your choice (beware: I'm yet to find out where to change this setting in the source files).
Creating a Menu Item in step 3
Click through next and the wizard will sum up you choices. In the next dialog window you will be prompted to specify the language you want the code to be generated. I chose .NET C#.
In the prompt after that you will be asked if the wizard should create a .DLL-project. You click yes.
Quit the wizard with the "Done" button.
3. Loading to Visual Studio 2010
Open up your Visual Studio and go to File -> Open Project. Navigate to the folder where you just created the files with the C3PO-Wizard. and open up the .csproj file.
All the files get loaded and it seems quite well. but now it's time for some other stuff: Signing, or better, providing a key for signing.
Allthough the README.txt (also in your project folder) states this is not neccessarily needed I did not get it to work without a key file.
Open up a terminal and tpye in sn /? to see if the environment variables work. If not you can yuse the abolute path to sn (see: 1: Needed packages). If everything works as expected you can generate your keyfile with sn -k <PathToYourProject>\Archive.snk.
In Visual Studio, go to Project -> <ProjectName>-Properties -> Signing -> Sign assembly [x] -> Search and pick the .snk-file you just created.
Good. A first compilation of the project with F6 should rumble through without problems. Go to <ProjectFolder>\bin\Release and copy the .dll files to <GroupWiseInstallPath>.
After that you need to open a cmd windows as administrator and cd to the RegAsm.exe directory and execute the following: [I]regasm "<GroupWiseInstallPath>\<TheDllName>.dll". Then execute gacutil -i "<GroupWiseInstallPath>\<TheDllName>.dll".
RegAsm will register the extension to the Windows registry and GACUtil will cache the .dll content to make it available to GroupWise.
You need to re-cache the .dll everytime you compile in VS. So basically the workflow is Compile -> Copy dll to GroupWise directory -> re-cache with gacutil -i -> Start Groupwise
I have not found a method to post-build execute a script that does that. Problem is the copying and the gacutil caching (both must be done as administrator).
IIf everything worked you see a new entry in the context menu when right-clicking a mail in Groupwise. When you click it, there will appear a message box.
The MessageBox is defined in GWCommand.cs L. ~125
4. Needed Imports/References
Since we got the skeleton to compile and function properly, it's time to get our own code in there. FOr rapid prototyping I do all the stuff in GWCommand.cs.
Go to Project -> add Reference -> COM and select "C3POTypeLibrary", "GroupWareTypeLibrary, "GroupWiseCommander", "GroupWiseConnectorLibrary" and click OK. The selected entries now appear in the project explorer.
5. Simple MessageBoxing
A thing I like to do (because I'm not a very good programmer) is to get all sorts of infos to get displayed with
Code:
MessageBox.Show();
Just fling it in the code and see what get's where etc. An important thing is allready in the comments of the file.
It is this line:
Code:
C3POTypeLibrary.IGWClientState6 myCL = (C3POTypeLibrary.IGWClientState6)WIASSArchivButton.g_C3POManager.ClientState;
. Uncomment it and play around with the myCL-object in your code.
The myCL has some properties we will use later on such as myCL.SelectedMessages which is exactly what we need for our archive functionality.
6. Export Code
Now we get to the code:
With the
Code:
ClientState
dug up in the code we can pass the
Code:
SelectedMessages
into a
Code:
MessageList
. Over this MessageList we will iterate and save each
Code:
Message
with the so called
Code:
GroupWiseCommander
to our disk. well that sounds simple. And, well after digging through a lot of threads here on the forum and the documentation, it is.
Here is the Execute() method from GWCommand.cs:
It has comments that should serve as a documentation.
Code:
public void Execute()
try
switch (m_PersistentID)
case WIASSArchivButton.vWIASS:
//C3PO WIZARD Put execute command code here for WIASS Context menu.
/* this was in the comments and is essential!
* the myCL object provides us everything we need to interact with the messages */
C3POTypeLibrary.IGWClientState6 myCL = (C3POTypeLibrary.IGWClientState6)WIASSArchivButton.g_C3POManager.ClientState;
// get the selected messages
object o = myCL.SelectedMessages;
// and convert the SelectedMessages to a MessagesList
MessageList ml = (MessageList)o;
// iterate over all the selected Messages
// this was tricky: the index of the MessageList starts by 1 and not at 0
for (int i = 1; i <= ml.Count; i++)
// the .Item() method expects either a string or a long
// see http://www.novell.com/documentation/developer/groupwise_sdk/gwsdk_gwobjapi/data/h20s5bdo.html
long index = (long)i;
// instantiate a Message object to get access to the different properties like subject, sender etc
GroupwareTypeLibrary.Message oMessage = (GroupwareTypeLibrary.Message)ml.Item(index);
// instantiate a GroupWiseCommander
// this is the interface to the TOKEN API
// TOKENS: https://www.novell.com/developer/documentation/gwtoken/index.html
GroupWiseCommander.GWCommander cmdr = new GroupWiseCommander.GWCommander();
// the GWCommander has an Execute() method that is able to take certain tokens kind of like SQL
// lets build the token (the complete list is huge and awesome) to save our Messages
// ItemSaveMessage(): https://www.novell.com/developer/documentation/gwtoken/gwtokens/data/hbt0bd7x.html
string tokenCommand = "ItemSaveMessage(\"" + oMessage.MessageID + "\"; \"C:\\archiv\\" + oMessage.MessageID + ".eml\"; 900)";
/* what happens here ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ is that we build us a TOKEN command that the
* GWCommander is able to execute.
* the actual command is ItemSaveMassge()
* everything between the semi-colons are the parameters:
* \"" + oMessage.MessageID + "\" : builds an ANSISTRING of the MessageID which we get from the oMessage onject
* \"C:\\archiv\\" + oMessage.MessageID + ".eml\" : build an ANSISTRING of the output filename
* 900 is the type we want to export. 900 stands for Mime
* CAUTION:In this example I use C:\archive\ as the destination folder. It must exist and be writable to the program
// now that we have setup our command we can get it executed by the commander
// the result is sort of a callback variable
string result ="";
cmdr.Execute(tokenCommand, out result);
/* here can the error handling be done with the result string
break;
default:
MessageBox.Show("Unsupported Case", "Error", MessageBoxButtons.OK);
break;
//A way to get the GroupWise client state with newest interface
//C3POTypeLibrary.IGWClientState6 myCL = (C3POTypeLibrary.IGWClientState6)WIASSArchivButton.g_C3POManager.ClientState;
//uncomment the code below to unblock the base command
//IGWCommand baseCmd = (IGWCommand)WIASSArchivButton.g_C3POManager.CreateGWCommand(m_objBaseCmd);
//baseCmd.Execute();
catch (Exception e)
MessageBox.Show("Error Executing GWCommand: " + m_PersistentID.ToString() + " Error: " + e.Message);
return;
7. Registering and caching the .DLL
After that you need to open a cmd windows as administrator and cd to the RegAsm.exe directory and execute the following: regasm "<GroupWiseInstallPath>\<TheDllName>.dll". Then execute gacutil -i "<GroupWiseInstallPath>\<TheDllName>.dll".
RegAsm will register the extension to the Windows registry and GACUtil will cache the .dll content to make it available to GroupWise.
You need to re-cache the .dll everytime you compile in VS. So basically the workflow is Compile -> Copy dll to GroupWise directory -> re-cache with gacutil -i -> Start Groupwise
8. Testing (please help me with a better way here)
Is there a good way to hook every thing up together to jsut stay in VS , compile, files get copied, registered, cached and GW starts?
Thanks for reading!
I wrote this up to have a documentation for myself and others. please let em know if you need help or anything is missing or not clear. It's certainly not a total noob guide and I expect a bit of knowledge to be honest.
Regards
Sebastian

Answer 1

Originally Posted by Username951
Multiple email selection should be possible, but only those emails that are fitting some requirements should be stored finally in database.
One requirement is for example that a keyword like "ISSUE" appears in the email subject
(followed by a ":", a "space" and some characters that can be converted to an integer value),
multiple, leading "Fwd: " and/or "Re: " should be handled well,
subject should be handled case-in-sensitive.
This sounds like you should implement some sort of SelectedMessagesValidator class just to keep it clean.
Originally Posted by Username951
So here are my find outs, remarks, etc.:
1.) Visual Studio should be started under admin. rights.
Then you can write a post-build event (batch) that copies, "regasm"s and "gacutil"s everything.
As said this works fine for me.
But note that unfortunately the paths to "regasm" and "gacutil" changed
(compared to the time where you wrote your tutorial).
Definitely. That way, as you mentioned, the post build scripts integrate very well.
Originally Posted by Username951
2.) The "Novell C3PO" wizard was downloaded and worked out as described in our tutorial.
One important step was to use "GW.MESSAGE.MAIL" and not "...BROWSER..." or something else.
I can not figure out, where you have the GW.BROWSER thing from, but in my examples I allways used GW.MESSAGES.MAIL
Originally Posted by Username951
The wizard created finally the basic C# (.NET framework 2.0) project.
This project was loaded in Visual Studio 2013, automatically converted to "newest version"
and finally was a ".sln" made.
Yes. You can leave it at 2.0. I just have the 4.5 installed so i will target this version
Originally Posted by Username951
"oracle.dataaccess"
-> Note that the "Copy Local" property must be set to "true"!
(This property will be reset to "false" after a successful (re)build.
So check this and change it to "true" for the first build!
This must be made only once because after a successful build is this .dll known;
keywords: GAC -> cached
But note that "successful" means also that the post-build event ran flawless!)
This is quite specific to your case since my example on exports a flat EML file to the hard drive
Originally Posted by Username951
2.) regasm.exe needs strong names.
So a "cmd" with admin. right was opened,
a
"C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A\bin\NETFX 4.5.1 Tools\sn.exe" -k "C:\Users\<username>\Documents\Visual Studio 2013\Projects\GWSaveToDatabase\GWSaveToDatabase.sn k"
fired
and the created "GWSaveToDatabase.snk" file added to the solution.
I don't want to be picky, but it's gacutil that needs the strong names. ragasm is not complaining
Originally Posted by Username951
(Development) Remarks
1.) While I used the "C3PO" wizard first time I used "Add Menu" item - as you said in your tutorial! :-(
And that is definitely wrong!
See:
The result was a C# project that does not show any new context menu entry.
So I tried at the next wizard run "Add Menu Item".
The wizard created again a C# project but still no new context menu entry in the GroupWise client.
(And that after all needed steps
like
copy to GroupWise installation path,
regasm and gacutil over all .dlls
etc.
were successful be made).
It took a complete day to get the idea to "merge" the two wizard created projects!
Why merging?
Because the second project contained a "const" which were used in the switch statement of the "Execute()" method
(with the same meaning like your "WIASSArchivButton.vWIASS" - see your code snippet above!)
and the "CustomizeContextMenu(...)" method in "CommandFactory.cs" looked also different
while the first project does not contained something similar.
( For example:
The "CustomizeContextMenu(...)" method had more statements.
And that made more sense to me compared to the first wizeard created C# project.
Since I uploaded a better example this is obsolete.
Originally Posted by Username951
So I ASSUME that the second project would work but it does not because of regasm / gacutil behaviour.
Means I believe it would work when all
with regasm registered
and
with gacutil to the cache added "things"
would be "un-registerd" and "un-cached".
This is, as I assume, due to the Interop.C3POTypeLibrary.dll. This must me cached every time the project is build. maybe you could use gacutil -i Interop.C3POTypeLibrary.dll -f to force the recaching
Originally Posted by Username951
So, finally I took the second, wizard created C# project and copied the "const", adjusted the "Execute()"
and "CustomizeContextMenu(...)" methods, etc.
After that the context menu were shown in the GroupWise client!
Thats is correct. But I never had to do this. The thing is, that the "Add Menu Item" is giving you the opputunity to specify a command, which the "Add Menu" doesn't.
Originally Posted by Username951
2.) The next issue was that the context menu was added as often as many emails were selected.
Means: For example: Three selected emails ends up in three time added context menu.
Solution:
Checking
var existsAlready = menuItems.Item("...");
if (existsAlready != null)
return;
in "CustomizeContextMenu(...)" method and leaving the method under shown circumstances.
I added a fix for this in the second post, but it isn't working in GW2012 anymore. I have a very ubly fix for that in my new code.
Originally Posted by Username951
3.) The by the wizard created registry path contained the version number "5.0".
This may confuse but it is finally ok. No need to change here anything!
On the other side:
It will NOT work when the registry entry
"SOFTWARE\\Novell\\GroupWise\\5.0\\C3PO\\DataTypes \\...."
will be changed/"adjusted to that GroupWise client version you are currently using"!
This is all part of the official documentation and wasn't touched by Novell since quite a long time.
I think i will make a github repository in the futer as a proof of concept and kind of a accessable documentation for everyone.