Error Provider::TranslateProvisioningError

Translates an MPF error raised by a calling procedure and uses a lookup file to translate it into a message that is more meaningful for the current context. For example, this procedure can be used to translate a potentially confusing low-level error to a friendly message. Used by Microsoft® Provisioning Framework (MPF). 

To remap errors with this procedure, create a separate XML lookup file for every language. The directory Microsoft Provisioning\Samples\SampleWebSite\StringCache\1033 (usually a subdirectory of Program Files) contains a template file, default_errors.xml. Alternately, you can use the format from the following example, which is excerpted from this file.

<Items>
  <Item name="adduser|0x82101391">
	<message>Sample error message.</message>
	<errorCode>0x82102101</errorCode>
</Item>
  <Item name="createorg|0x82101001">
	<message>Another sample error message.</message>
	<errorCode>0x82102102</errorCode>
  </Item>
</Items>

Each Item node corresponds to one entry in the file. The name attribute expects data in the format error message context|source error code. The message and errorCode child nodes specify the translated error description and code, respectively. The message node can be an arbitrary string. The errorCode node specifies an HRESULT in either hexadecimal (0xFFFFFFFF) or decimal (+-9999999999) format.

After creating the new file, register it in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Provisioning\Providers\Error Provider\RootFolder key.

Note  When implementing the file, it is advisable to change the file name, file location, and registry key name to ones that are more meaningful and secure.

XML Input Schema

The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.

<executeData>1..1
  <errorMessageContext>1..1</errorMessageContext>
  <locId>0..1</locId>
  <errorSet>0..1</errorSet>
  <mustHandleError>0..1</mustHandleError>
</executeData>

XML Output Schema

TranslateProvisioningError does not return data.

Elements and Attributes

The following table describes the XML elements and attributes. Unless otherwise indicated, the data type is string.

Element Description, relationships, and attributes
errorMessageContext Description:
String that uniquely identifies the context of the error message, such as the name of a namespace, procedure, or registry subkey. This node is necessary because multiple sources may generate the same error code but require different error descriptions.

For example, the two procedures SignupUser and ChangeUser may both call an AddRowToTable procedure that throws error 0x8004123. The XML lookup file represents this error as follows for each error context:

<Items>
  <Item name="SignupUser|0x8004123">
	<message>Signup database not found.</message>
	<errorCode>0x82102101</errorCode>
  </Item>
  <Item name="ChangeUser|0x8004123">
	<message>User database not found.</message>
	<errorCode>0x82102102</errorCode>
  </Item>
</Items>

In a request to sign up a user, the errorMessageContext node would be set to SignupUser to retrieve the correct error description for that type of request. Similarly, in a request to change a user, errorMessageContext would be ChangeUser.

Parent:
executeData

errorSet Description:
Name and path of the XML lookup file used to remap messages. The default value is default_errors.

Parent:
executeData

executeData Description:
 Encapsulates the procedure's input data.

Children:
 errorMessageContext (minOccurs="1" maxOccurs="1")
errorSet (minOccurs="0" maxOccurs="1")
locId (minOccurs="0" maxOccurs="1")
mustHandleError (minOccurs="0" maxOccurs="1")
locId Description:
Locale ID of the remapped error to return. Optional; identifies the language and format for the error and associates the lookup file to the registry. The default value is 1033.

Parent:
executeData

mustHandleError Description:
Determines how to resolve errors when a mapping does not exist in the lookup file. This setting is useful for debugging.

If mustHandleError=0 (false), the provider passes the original error (code and description) but changes the error source to Error Provider.

If mustHandleError=1 (true), the provider changes the original error to the generic error E_FAIL (0x80004005) and the corresponding error description from the configuration database.

If a value is specified for the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Provisioning\Providers\Error Provider\MustHandleError, it overrides any corresponding value in the request. Otherwise, the default request value is 0.

Parent:
executeData

Remarks

The user account that MPF is running under (normally MPFServiceAcct) must have read access to the lookup file.

See Also

Error Provider, SetError, TranslateUserError

Up Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.