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.
Arguments |
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.
|
Schema
Definition |
Input
<executeData>1..1
<errorMessageContext>1..1</errorMessageContext>
<locId>0..1</locId>
<errorSet>0..1</errorSet>
<mustHandleError>0..1</mustHandleError>
</executeData>
|
Sample
Code |
Example XML Request
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.
Example XML Response
TranslateProvisioningError does not return data.
|
Applies
To |
Error Provider
for:
- Hosted Messaging and Collaboration version 4.5
- Hosted Messaging and Collaboration version 4.0
- Hosted Messaging and Collaboration version 3.5
- Hosted Messaging and Collaboration version 3.0
- Windows-based Hosting version 4.5
- Windows-based Hosting version 4.0
- Windows-based Hosting version 3.5
- Windows-based Hosting for Applications version 1.0
|