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:
executeDataerrorSet Description:
Name and path of the XML lookup file used to remap messages. The default value is default_errors.Parent:
executeDataexecuteData 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:
executeDatamustHandleError 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:
executeDataRemarks
The user account that MPF is running under (normally MPFServiceAcct) must have read access to the lookup file.
See Also
Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.