Create a user handler

This task describes how to write a user handler for your script.

To create a user handler:

  1. Prerequisite: Import a WSDL file and create a standard Web Service call. For details, see Add Web Service script content.

  2. Define a user handler before the Web Service call:

    int MyScriptFunction(const char* pArgs, int isRequest)
{
...
}

  3. Call the handler function by specifying the function name as a value for the UserHandlerFunction argument. in the Web Service call.

    web_service_call(
    ...
    "UserHandlerFunction=MyScriptFunction", 
    "UserHandlerArgs=<handler arguments>", 
    

LAST);

  4. Evaluate the handler's return code to determine if it succeeded. Use the return codes as described in User handlers.

    //This function processes the SOAP envelope before sending it to the server.
int MyScriptFunction(const char* pArgs, int isRequest) 
{         
    if (isRequest == 1) {
        //Get the request that is going to be sent
        char* str = lr_eval_string("{SoapEnvelopeParam}");
        //Manipulate the string...
        //Assign the new request content
        lr_save_string(str, "SoapEnvelopeParam");
        return LR_HANDLER_SUCCEEDED_AND_MODIFIED;
    }
    return LR_HANDLER_SUCCEEDED;
}

  5. Create a DLL file. (Optional)

    To define a user handler through a DLL, locate the API header file, LrWsHandlerAPI.h in the product's include folder.

    You can use a sample Visual Studio project located in the samples/WebServices/SampleWsHandler folder as a template for creating a handler. The sample retrieves the request and response envelope and saves it to a parameter. To use this sample, open it in Visual Studio and modify it as required. If you do not need to save the request/response to a parameter, you can remove that section of the sample.

    After editing the sample, save it and compile the DLL. When you compile the project, Visual Studio places the <user_handler_name>.DLL file in the bin folder. If you compile the project from another location, or if you want to copy the DLL from one machine to another, make sure to place it in the bin folder.

  1. Configure the user handler. (Optional)

    Declare the DLL user handler globally or locally.

    To apply the user handler globally to all requests in the script, add the following section to the default.cfg file in the script's folder.

    [UserHandler]
Function=<name>
Args=<arguments>
Order=<BeforeSecurity/AfterSecurity/AfterAttachments>

    • Name. The name of the DLL.

    • Args. A list of the configuration arguments for the handler. Use the GetArguments method to retrieve the arguments in your handler.

    • Order. The order in which Vusers process the user handler in requests: Before Security, After Security, or After Attachments. You can also use this argument to override the transport layer, by entering the value Replace Transport.

      Note: Setting the UserHandlerFunction property of a web_service_call function, overrides the definitions in the .cfg file.

      By default, user handlers are processed before the security. For request messages, Vusers process the attachments handler after the security handler. For responses, Vusers process the handlers in a reversed order. In typical cases the order does not matter, so any value is acceptable.

      To override the Transport layer, specify Order=Replace Transport and specify the new transport handler. If you implement the transport handler as a separate DLL, the HandleRequest function is called, while the HandleResponse function is ignored.

      To use the handler locally, for a specific request, add the following arguments to the web_service_call function:

      UserHandlerName=<name1>
UserHandlerArgs=<args1>
UserHandlerOrder=<BeforeSecurity/AfterSecurity/AfterAttachments/Replace 
                                        Transport>

  2. Make sure that the user handler DLL is accessible to all load generator machines running scripts that call it. You may, for example, copy it to the product's /bin folder.

    If you copy the script to another machine, it retains the handler information, since it is defined in script's folder.

  3. Implement the user handler. (Optional)

    To implement a user handler, you use the entry functions HandleRequest or HandleResponse. Both functions have a single parameter, context, whose properties you can set in your handler. Use the Get functions to retrieve properties, and Set functions to pass information from the replay framework to the handlers or between the handlers.

    • GetEnvelope. Gets the envelope content. For example:
      const char * pEnvelope = context->GetEnvelope();

    • GetEnvelopeLength. Gets the envelope length

    • SetEnvelope. Sets the envelope content and length. For example:
      string str("MySoapEnvelope...");
      context->SetEnvelope(str.c_str(), str.length());

    • SetContentType. Sets a new value for HTTP header content type

    • LogMessage. Issues a message to the replay log

    • GetArguments. Gets the configuration arguments defined for the current handler in order to pass it to the DLL

    • GetProperty. Gets a custom property value

    • SetProperty. Sets a custom property value

    For more information, see the comments in the LrWsHandlerAPI.h file located in the product's include folder.

 

Back to top