This project is read-only.

Pipeline Hints Overview

The PipelineHints assembly contains a set of custom attributes that you can decorate your contract assembly with to customize the output of the PipelineBuilder library. These attributes are needed when you want to change some of the default generation options (such as assembly name or namespaces) or when your contract assembly has certain features that require additional information in order to generate code for (such as events). The attributes in this assembly are all marked with [ConditionalCompile("DEBUG")] so they will only show up in the debug builds of your contract assembly (builds with the "DEBUG" constant defined) and so your released code will have no dependence on the PipelineHints assembly or any other assemblies shipped in this project.

In addition to the descriptions below we have uploaded a sample project that demonstrates the use of the most commonly used hints and features of the Pipeline Builder tool: Common Pipeline Scenarios

Commonly Used Hints

Naming Related Attributes

SegmentAssemblyName
Apply this attribute to name the assembly and project for a specific generated pipeline segment

Parameters:
  • String name: must be a valid assembly name
  • PipelineSegment segment:
    • Refer to a single assembly
    • HostSideAdapter and AddInSideAdapter are always valid
    • HostView and AddInView are valid unless the assembly has the ShareView attribute applied
    • Views is only valid if the assembly has the ShareView attribute applied
    • All invalid values are ignored

ShareViews
Apply this attribute on the contract assembly to indicate that the view assembly generated should be shared between hosts and add-ins.

Namespace
Apply this attribute to change the namespace for a specific type in the specified segment

Parameters
  • String name: must be a valid namespace name
  • PipelineSegment segment:
    • Refer to a single assembly
    • HostSideAdapter and AddInSideAdapter are always valid
    • HostView and AddInView are valid unless the assembly has the ShareView attribute applied
    • Views is only valid if the assembly has the ShareView attribute applied
    • All invalid values are ignored

Event Related Attributes

EventAdd
Apply this attribute to a method to indicate that it should be used to subscribe to events across the boundary.

Parameters:
  • String name: name that should be used to represent this event on the view
Requirements:
  • The marked method must return void
  • The marked method must have a single parameter whose type is marked with the EventHandler attribute
  • There must be a correpsonding method with the EventRemove method and the same name
  • There cannot be two EventAdd methods with the same name in the same type
  • This type must be represented as an interface in the view

EventRemove
Apply this attribute to a method to indicate that it should be used to un-subscribe to events across the boundary.

Parameters:
  • String name: name that should be used to represent this event on the view
Requirements:
  • The marked method must return void
  • The marked method must have a single parameter whose type is marked with the EventHandler attribute
  • There must be a correpsonding method with the EventAdd method and the same name
  • There cannot be two EventRemove methods with the same name in the same type
  • This type must be represented as an interface in the view

EventHandler
Apply this attribute to a type to indicate that it should represent an event handler delegate across the boundary

Requirements:
  • There must be exactly one method in this type
  • This method must have a single input parameter with a type that is marked with the EventArgs attribute
  • This method must have the return type of void unless the parameter type is marked as a cancelable event
  • This method must have the return type of bool if the parameter type is marked as a cancelable event

EventArgs
Apply this attribute to a type to indicate that it should be represented as an EventArgs type in the view. This causes an abstract base class deriving from EventArgs to be generated.

Optional Named Parameters
  • Cancelable: If this is set to true the base type used in the view is CancelableEventArgs instead. The "Canceled" value will only get propegated back to the source if the method on the corresponding EventHandler types has a bool return value

Event Attribute Use Snippet
Here is a small snippet putting all these event attributes together showing you how to define your contract, and use the attributes, for use in this tool:

    public interface IAppObjectContract : IContract
    {
        [EventAdd("DocumentOpened")]
        void DocumentOpenedEventAdd(IDocumentOpenedEventHandlerContract handler);
        [EventRemove("DocumentOpened")]
        void DocumentOpenedEventRemove(IDocumentOpenedEventHandlerContract handler);
        
        /*Other stuff*/
    }

    [EventHandler]
    public interface IDocumentOpenedEventHandlerContract : IContract
    {
        void Handler(IDocumentOpenedEventArgsContract args);
    }

    [EventArgs]
    public interface IDocumentOpenedEventArgsContract : IContract
    {
        string Name
        {
            get;
        }

        string Content
        {
            get;
        }
    }


This will cause the tool to output the following in the views, and build out the appropriate adapters in-between:
     public interface IAppObject {
        
        event System.EventHandler<DocumentOpenedEventArgs> DocumentOpened;
    }

    public abstract class DocumentOpenedEventArgs : System.EventArgs {
        
        public abstract string Name {
            get;
        }
        
        public abstract string Content {
            get;
        }
    }

Enums

PipelineSegment
  • None
  • HostView
  • AddInView
  • AddInSideAdapter
  • HostSideAdapter
  • Adapters
  • Views
  • All

Other Pipeline Hints

Comment
Apply this attribute on a type or member in your contract to add a comment to the corresponding type or member in the views.

Parameters:
  • String comment: must be a valid comment string

Custom Pipeline Attribute
Apply this attribute to a type in your contract to specify that you want to use your own custom code for that type the specified segments. The pipeline generator tool will not build the source code for that specified pipeline segment. However, even if you specify that you want to build custom adapters it will generate the static adapter class that other adapters use to access the adapters for your specified types and so you will still need to name your actual adapters with the same name the tool would have used.

Parameters:
  • PipelineSegment segment: Any valid PipelineSegment value

Inheritence Related Attributes

AllowViewUpCasting
This attribute can be used to allow consumers of the views to up-cast instances of the specified view type to a more derived type. When this attribute it specified for a type the Contract-To-View static adapter methods for this type attempt to find the most specific adapter available in order to allow maximum flexibility for consumers of the view. This does add a small performance cost to these static adapter methods so it is not on by default (please take a look at the generated code, with and without this attribute, before you decide to use it).

BaseClassAttribute
Apply this attribute to a contract interface in order to specify which type you want to use as its base type in its view type. This class was added to better support AbstractBaseClass views (as opposed to interfaces) and given the recomendation of using interfaces for views rather than abstract-base-classes we are considering removing this attribute.

Parameters:
  • Type baseClass: this type must be a contract interface and must be in the inheritence chain of the type the attribute is placed on

AbstractBaseClass
This attribute specifies that the views generated for this type should be abstract base classes rather than interfaces. This is generally not recomended but was made available for those who wanted it. This attribute can not be placed on interfaces that expose events (using EventAdd and EventRemove attributes) or on EventHandler or EventArgs contracts.

Last edited Jan 10, 2008 at 6:11 PM by JesseKaplan, version 20

Comments

No comments yet.