Automating Module Installation

The Commerce Server SDK includes a COM object designed to help automate the installation of new Business Desk modules. This may be useful in situations where a new module needs to be added to a number of different instances of Business Desk. The source files for this COM object are located in the folder "<install folder>\SDK\Samples\Management\Business Desk Installer".

The BizDeskModuleInstall object is capable of being called from both C/C++ code, and automation clients such as Visual Basic.

Note that this object relies on the SiteConfig object to determine the list of applications installed in a site.

The BizDeskModuleInstall object is externally creatable. Create this object using the ProgID CommerceSDK.BizDeskModuleInstall.

The Type Library for this object, once built, will be: Microsoft Commerce Server 2000 SDK BizDesk Module Install Type Library. The DLL name is: BizDeskModuleInstall.dll.

The BizDeskModuleInstall object implements the following four methods:

Init, IsBizDesk, AddModule, RemoveModule

To see a sample of how these methods can be invoked, see the Sample Code section.

These methods can return a number of different custom COM errors, which can be found in the Error Table section at the end of this topic.

Init Method

Use this method to initialize the state of the BizDeskModuleInstall object, establishing the instance of the Business Desk upon which the other methods will operate.

Definition

HRESULT Init(

  BSTRbstrIisVDirName

)

Parameters

bstrIisVDirName

[in] A BSTR containing the name of the virtual directory in Internet Information Services (IIS) that corresponds to the application selected by the user.

IsBizDesk Method

Use this method to determine whether or not the selected IIS application is a Business Desk application. This is accomplished by determining whether the "./config/bizdesk.xml" file exists in the application.

Definition

HRESULTIsBizDesk(

  VARIANT* bRetVal

);

Parameters

bRetVal

[out, retval] The address of a Boolean used to return a value indicating whether or not the IIS virtual directory specified in the Init method contains an instance of the Business Desk. A value of True indicates that it is an instance of the Business Desk. A value of False indicates that it is not an instance of Business Desk.

AddModule Method

Use this method to add a new Business Desk module to the instance of the Business Desk specified in the call to the Init method.

Definition

HRESULTAddModule(

  BSTRbstrCategory,

  BSTRbstrConfigPath,

  VARIANTbOverwrite,

  VARIANT* bSuccess

);

Parameters

bstrCategory

[in] A BSTR containing the name of the category into which the new module should be installed.

bstrConfigPath

[in] A BSTR containing the full path to the module configuration file.

bOverwrite

[in] A Boolean value indicating whether or not to overwrite an existing module configuration file. A value of True indicates that any existing module configuration file will be overwritten. A value of False prevents any overwriting from occurring.

If an existing module configuration file is overwritten, a backup of that file will be placed in a "_backup" folder within the "config" folder.

bSuccess

[out, retval] The address of a Boolean used to return a value indicating whether the method was successful. A value of True indicates success. A value of False indicates a failure, in which case the HRESULT will contain further details.

RemoveModule Method

Use this method to remove the specified module from the instance of the Business Desk specified in the call to the Init method.

Definition

HRESULTRemoveModule(

  BSTRbstrCategory,

  BSTRbstrModulePath,

  VARIANT* bSuccess

);

Parameters

bstrCategory

[in] A BSTR containing the name of the category from which the specified module is to be removed.

If the category is empty after removing the module, the category will also be removed.

bstrModulePath

[in] A BSTR containing the path of the folder containing the files associated with the module being removed. The path must be specified relative to the "config" folder.

bSuccess

[out, retval] The address of a Boolean used to return a value indicating whether the method was successful. A value of True indicates success. A value of False indicates a failure, in which case the HRESULT will contain further details.

Sample Code

The following sample code shows how the methods of the BizDeskModuleInstall object can be invoked. This sample shows the invocation of the AddModule method, with the invocation of the RemoveModule method commented out.

Dim bRet As Boolean
Dim oBizInstall As Object
set oBizInstall = CreateObject ("CommerceSDK.BizDeskModuleInstall")
oBizInstall.Init "adbizdesk"
If oBizInstall.IsBizDesk Then
    bRet = oBizInstall.AddModule("MyCategory", _
                                 "d:\temp\module.xml", True)
    'bRet = oBizInstall.RemoveModule("MyCategory", "module.xml")
End If

Error Table

The following table describes the errors that can be returned from the methods of the BizDeskModuleInstall object.

All rights reserved.