Error Provider::TranslateUserError
Translates a user-specified error to another error, which is
useful when you know the specific error you want to raise. Mainly
used for localization. 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 |
errorMessageCode
|
Description:
Source error code to translate from; this can be an HRESULT in
either hexadecimal (0xFFFFFFFF) or decimal (+-9999999999) format.
To identify the target error code, the provider tries to match the
errorMessageCode from the input XML against a corresponding
errorCode in the lookup file.
Parent:
executeData
|
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
<errorMessageCode>1..1</errorMessageCode>
<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
TranslateUserError 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
|