This is the general constructor for the provider. This constructor initializes the various member variables and loads the hash tables with the proper method signatures allowing for method dispatching when the provisioning engine calls the provider, including:

• Initializes member variables
• Initializes caching containers
• Populates method caches
• Validates method caches.
  • All named methods must implement a "process" method.
  • Process methods marked as "Read" should not implement any other methods (that is, rollback, prepare, commit)
  • Process methods marked as "Write" should also implement a rollback method but neither a prepare nor commit method
  • Process methods marked as "Two-phase" should also implement a rollback method, a prepare method, and a commit method

public Provider() : base()
{ }

The provider base class utilizes a combination of custom class and method attributes in order to emit MPF provider namespace data as well as proper dispatching of methods in response to MPF method calls. This section describes some of these attributes and their use within the provider base.

This custom attribute class is used to decorate types within the .NET assembly that represent individual providers. There can one or more types in the assembly so decorated. The constructor requires two input parameters, one representing the name of the provider namespace as it will be referenced by MPF and the second being a description of the namespace (the latter can be an empty string, however best practices dictate that a reasonably descriptive value be provided). An optional property named ReadOnly is provided to complete the schema support for namespaces; however, this value defaults to false and is not expected to be used.

The following is a sample of a class that has been decorated as a provider:

[ProviderAttribute("Sample Provider CS",
		"Simple provider demonstrating how to write a provider in .NET 2.0 and C#.")]
	public class SampleProviderCS : ManagedBase
	{
		...

This custom attribute class is similar to the class with the same name implemented in the original ManagedBase assembly with a few important changes.

The first (and possibly most significant) difference in the current implementation is that only process (execute) methods should be decorated whereas the previous implementation required every method exposed to MPF to be decorated. Any decorated method is assumed to be a process method and decorating methods of other types will cause the provider to fail.

The recommended naming convention for provider methods has been updated in this edition of the managed base. Each method exposed should be in the form of

<MpfMethodNameWithoutSpaces><MethodType>()

For example, a method referenced in MPF as Get Current Time should have a C# method name collection similar to the following:

GetCurrentTimeProcess(), GetCurrentTimeRollback(), GetCurrentTimePrepare(), and GetCurrentTimeCommit()

.

This sample uses the suffix of "Process" for what has commonly been referred to as the "execute" method, whereas previous versions utilized "Execute". The justification of this change was to make the terminology consistent with that of the MPF documentation and references. Also, not every method must implement all four of the method signatures listed above - the implementation requirements differ based on the method type; see following:

• Method Type = Read
  • Must implement a "Process" method
• Method Type = Write
  • Must implement a "Process" method
  • Must implement a "Rollback" method
• Method Type = TwoPhase
  • Must implement a "Process" method
  • Must implement a "Rollback" method
  • Must implement a "Prepare" method
  • Must implement a "Commit" method

While not recommended, there may be valid scenarios in which deviation from the naming convention recommended above. Support for deviation from the standard naming conventions is provided by means of additional properties that can be set on the ProviderMethodAttribute class. These properties are rollbackMethod, prepareMethod, and commitMethod. The application of each should be self explanatory and the value should be set to the string representation of the method name that should be called for the associated action. An example of a method decorated using one of these properties is illustrated below:

[ProviderMethodAttribute("Write Sample",
ProviderMethodType.MethodTypeWrite,
Description = "Sample illustrating structure for creating a write/rollback method.",
	 RollbackMethod = "MySampleRollback")]
	public void WriteSampleProcess(XmlDocument node)
	{
		 // perform a write action

The ProviderMethodAttribute constructor requires the name of the method as it is to be exposed to MPF and the method type (Read/Write/TwoPhase). A collection of additional properties such as AuditEnabled, PerformanceEnabled, etc. can also be set. For more information on the collection of properties available please see the object browser. For information on the meaning of each of these properties, see MPS SDK ReferenceA sample method and decoration using the minimum properties is illustrated below:

[ProviderMethodAttribute("Write Sample",
ProviderMethodType.MethodTypeWrite,
Description = "Sample illustrating structure for creating a write/rollback method.")]
	public void WriteSampleProcess(XmlDocument node)
	{
		 // perform a write action.

Throwing an exception within a provider automatically triggers rollback. Further, this allows the developer to return fragments of data that might help the consumer of the error to know what caused the error, what the data looked like at that point in time, and other types of data. Like anything else, features that are often viewed as good can be poorly implemented with the end result being seemingly worse than had the exception never been thrown. This problem has been exemplified in some of the existing providers that return "Unknown Error" or other such exceptions without providing any context to the caller to allow them to derive the actual cause of the error.

The driving goal of each provider author should be to evaluate each line of code such that if it can throw an error, that error should be caught, and then re-thrown with additional information providing the caller with everything the caller needs to adequately ascertain exactly what happened, at which point in the process it happened, what the state of data was at that point, and any additional information. It is imperative that provider authors return detailed and accurate exceptions. To assist in this effort, the following "rules" have been established and will be used as guidelines during code reviews.

• Implement inclusive validation on each line of code that does something "interesting" to ensure that the action that was to have happened did, in fact, happen as it should. Consider the following scenario:
  • Given a method that is designed to update properties on an object in Active Directory.
  • The constructor for System.DirectoryServices.DirectoryEntry will always return an object (uninitialized DirectoryEntry object) regardless of whether or not the path supplied to the constructor is valid (on invalid path, an uninitialized DirectoryEntry object is returned).
  • Far too often the return is checked simply with a "if-not-null" check and the logic flow continues. In this scenario this check is not sufficient as you were not returned the object actually desired. A further check is required.
  • If the appropriate checks are not performed, the code proceeds to set properties on the object and then fails when saving the changes.
  • The error returned to the user indicates that something with the "save" operation failed when in reality it should have indicated that the object was not successfully retrieved from the directory.
• Protect every line of code that does something "interesting" with an appropriate try/catch/finally statement.
• When catching and throwing an exception, provide the caller with all of the information necessary to understand what caused the error. This includes returning information such as the following:
  • Current state of the XML at the point that the exception was thrown
  • Current XPath to the object being manipulated (if applicable)
  • Current collection of associated parameters
• MPF is only going to output the "Message" property of the exception in the output stream so it does not make sense to create custom exception classes that add additional properties that hold custom information. You need to return the appropriate data in the Message property of the exception.
• Throw the right exception for the right problem. The following section (General Exceptions) deals with this in more detail, but the general idea is to avoid throwing "System.Exception" (actually, as a provider author you should never throw this exception) or some other generic exception when a more specific exception applies.

One of the desires of the architecture team is to provide consistent guidance with respect to what exceptions are thrown for various actions. It is fully expected that each provider will throw exceptions unique to that provider based on operations unique to the service or platform being provisioned. Excluding those unique scenarios, there are a number of operations that are common to all providers such as retrieving values (argument out of range, argument null, etc.). The goal of this section is to explain some of the common exceptions that should be thrown by provider authors during validation steps.

Exception	Description
System.InvalidOperationException (0x80131509)	This exception is thrown when a method call is invalid for the object's current state. This should be thrown when, for example, a system service is in a stopped state and someone attempts to pause the service. This operation is invalid for the given service.
System.ArgumentNullException (0x80004003)	This exception type should be thrown when a required argument is not supplied. An example would be a method called ControlService that expects the name of the service to be supplied. If the value is not supplied, and/or the node that should contain that value is missing, this exception should be thrown (rather than a "NullReferenceException").
System.ArgumentOutOfRangeException (0x80131502)	This exception should be thrown when the value of an input parameter is outside the allowable range of values as defined by the invoked method. For example, a method called Control Service might accept a control value of "Stop", "Start", "Pause", and "Continue". If the caller supplied a value of "Change" that would be outside of the allowable range and should therefore throw an ArgumentOutOfRangeException.
System.ApplicationException (0x80131600)	This is a generic application exception that should be thrown any time it is not possible to throw a more specific exception. Provider authors should never throw the generic System.ApplicationException. If a developer needs to throw a generic exception while also specifying a specific HResult, the ProviderException class is provided and defined below.
System.NotImplementedException	This is the exception that would be thrown by the base class when a method is called that is not defined in the provider.
ProviderException	During the development of providers, it is often desirable to be able to return custom exceptions, and, in particular, custom HResults. Since the ability to explicitly define the HResult of an exception is not available in standard exception classes, the base class provides a custom exception class that affords the developer this functionality. This is a generic exception class that inherits from ApplicationException and adds a single override that allows the setting of the HResult. Because the other overrides are consistent with the standard exceptions, the only constructor detailed here is the custom override. Input: message - Message to associate with the exception Result- Specific HResult to set for the exception Typical Usage throw new ProviderException("StartService Failed!", -999932);

Public Method Name