VBP Object Model

[JonSmith]

I'm not a find it by wandering through kinda guy. I'd rather have the info in a form that I can look it over and then see possibilities.
Is there a detailed listing of the VBP object model? I have some pretty detailed enhancements coming up to our build process and I anticipate making quite a few user actions. Before Kinook pipes up with "Read the Code Luke" the provided examples of user actions and the VBP objects are insufficient. I don't care if it's a beta copy or some developers personal list - anything is better than the scant docs provided on these topics.
Thanks!
Jon

[kinook]

I hate to disappoint, but the existing object model documentation (which does list the entire API), sample user actions, and dozens of VBP actions implemented in script code are all that is available in this area.

http://www.visualbuild.com/Manual/objectmodel.htm
http://www.visualbuild.com/Manual/userdefaction.htm

[JonSmith]

Originally posted by kinook
[B]I hate to disappoint, but the existing object model documentation (which does list the entire API), sample user actions, and dozens of VBP actions implemented in script code are all that is available in this area.

I guess my biggest beef is that very little is explained in requirements, limitations and other nice to know details of writing custom actions. The example in VB.Net for example has a function with several args - is this required? Optional? What's the limits? The code is presented as-is with no explanatory comments and a bare minimum of trivial code (hello). Yeah I could probably spend a week playing around with variants to see what works and what doesn't, but it would be nice to have a fence so I don't *have* to expend that time. Like - can I call UI elements? What are the threading implications? In all honesty I probably wouldn't be so grumpy if I had a lot more time.
How 'bout some more meaningful examples with comments?
Thanks!

[kinook]

Originally posted by JonSmith
I guess my biggest beef is that very little is explained in requirements, limitations and other nice to know details of writing custom actions. The example in VB.Net for example has a function with several args - is this required? Optional? What's the limits?

Custom actions components must implement the ICustomAction interface defined in the 'Visual Build 6 Professional Objects' type library, which defines one BuildStep method taking two required parameters. VB.NET:

Public Function BuildStep(ByVal Builder As VisBuildSvr.Builder, ByVal [step] As VisBuildSvr.IStep) As VisBuildSvr.StepStatusEnum Implements VisBuildSvr.ICustomAction.BuildStep

http://www.visualbuild.com/Manual/userdefaction.htm

The code is presented as-is with no explanatory comments and a bare minimum of trivial code (hello). Yeah I could probably spend a week playing around with variants to see what works and what doesn't, but it would be nice to have a fence so I don't *have* to expend that time. Like - can I call UI elements?

A custom action does not have access to the VBP GUI app, nor should it assume it even exists (a build could be run from the console app or directly from the object model). The step's properties can be accessed from the custom action via the provided Step object (use ExpProperty, as shown in the samples, to retrieve a value with all macros/script expanded).

What are the threading implications?

With VBP v6.3 or later, custom actions are called from the build thread within a COM single-threaded apartment (STA). Other threads will not access/modify VBP objects while the custom action code is executing.
http://www.visualbuild.com/Manual/threading.htm

In all honesty I probably wouldn't be so grumpy if I had a lot more time.
How 'bout some more meaningful examples with comments?
Thanks!

We'll add this to our request list. Thanks.

[JonSmith]

I'm attempting to create an action based on COM. It took me a bit to sort of figure the relationship between the action & component looking at the example. I still don't have something right because I get an "Invalid class string" message when I try to invoke it. To save time - is there a step-by-step procedure for creating a user action? I had assumed that the ProgID is specified in the VS project using: System.Runtime.InteropServices.ProgId("classname")
When I created the user action in VBP I set the ProgID to the string in my code as above "classname" (which is just used for illustration of course).
Jon

[kinook]

1) Are you creating the action as a .NET assembly (using COM Interop)? What language? If C# or VB.NET, to create the action component itself, you can start with the sample user action of the corresponding language (NETAction/VBNetAction under Samples\User Actions). Rename the project, modify the ProgId in the Test.cs/Test.vb file in the project as desired, etc.

2) After creating and compiling your user action component, you need to register it with COM. You can do this with the COM Register action (check the .NET assembly and Create a Codebase entry options).

3) Next, you need to create the VBP action which tells VBP about your component. In VBP, right-click in the Actions pane and choose Insert Action, fill in the fields (the only required fields are General | Name, Component | Action Type [COM Component], Component | ProgID [as defined in your project] and any properties for the action on the GUI tab), and OK the dialog.

http://www.visualbuild.com/Manual/actionspane.htm

4) Then you can insert a step for the new user action into a project and run it within a build.

The Samples\User Actions\User Actions.bld demonstrates automating the registration (with COM and VBP) and execution of a compiled user action (C# .NET Action / VB.NET Action sections).

http://www.visualbuild.com/Manual/userdefaction.htm

[JonSmith]

Originally posted by kinook
[B]Are you creating the action as a .NET assembly (using COM Interop)? What language? If C# or VB.NET, to create the action component itself, you can start with the sample user action of the corresponding language (NETAction/VBNetAction under Samples\User Actions).

Sorry if my post was vague - I did mentioned that I modified the example. The idea I'm trying to get across is that I think a bit more explanation would be nice as the code does not make the relationships between the COM object and the user action clear. I did modify the ProgID and the result was a message saying it had issues with what I had done. Seriously your docs try to boil down writing and using COM actions within VBP in half a page. I think that it needs a bit more explantion. Can you provide a more detailed example with some descriptive text?
Thanks,
Jon

[kinook]

I explained it in more detail in my previous post. Which step are you stuck on?

[JonSmith]

Originally posted by kinook
I explained it in more detail in my previous post. Which step are you stuck on?

Nevermind - this back and forth is pointless. I guess the concept of a tutorial with more than a basic overview is out of reach.

[kinook]

Assuming you're using VB.NET,

1) Open Windows Explorer and navigate to C:\Program Files\VisBuildPro6\Samples\User Actions
2) Copy and paste the VBNETAction folder
3) Rename 'Copy of VBNETAction' to 'MyNewAction'
4) In the MyNewAction folder, rename VBNetAction.vbproj to MyNewAction.vbproj
5) Select all files in the folder, right-click -> Properties, uncheck Read-only and click OK
6) Delete the bin subfolder
7) Open MyNewAction.vbproj in Visual Studio 2003 or later
8) In Project | Properties -> Application, change Assembly name and Root namespace to MyTestAction
8) From the Solution Explorer, Open test.vb and replace VBNETAction.Test with MyTestAction.Test and "VB.NET custom action" with "my test action"
9) Build the solution
10) Open Visual Build, create a new project, and save in the MyNewAction folder
11) Insert a COM Register action, enter a Filename of %PROJDIR%\bin\MyTestAction.dll, check the .NET assembly and Create a codebase entry fields, and OK
12) Right-click in the Actions pane, and choose Insert Action
13) In the Action Properties dialog, enter a Name of MyTestAction on the General tab, add a new tab/property named Msg on the GUI tab, and Action type of COM Component and ProgId of MyTestAction.Test on the Component tab, and OK the dialog
14) In the Actions pane, double-click on the MyTestAction action to insert a new action of that type, and on the 2nd tab of the Step Properties dialog, enter some text, and OK the dialog
15) Building the project should result in build output of "Hello from my test action in project <whatever text you entered in the action GUI>"