Upgrading from v3 to v4

VBA-Web v4.* includes some great new features (Mac support, general VBA compatibility, and lots of updates and bugfixes)

Here's how to transition from v3.* based project to v4.*

1. Compile VBAProject

In later steps, the VBAProject will be compiled in an attempt to find items that need to changed. To make it easier to isolate only issues related to upgrading, compile your project before upgrading with Debug > Compile VBAProject to make sure there are no issues before starting the upgrade.

2. Remove Excel-REST

Remove RestHelpers, RestClient, RestRequest, RestResponse, and IAuthenticator from your project.

1. Open Visual Basic editor (Alt+F11 or Developer > Visual Basic)
2. Right-click each Module/Class to remove
3. Click "Remove (Filename)"

3. Install VBA-Web

Open VBA-Web - Installer.xlsm to install VBA-Web automatically in your workbook.

1. Browse for the workbook that you want to update

2. Select the components that you want to install

   • Install / Update VBA-Web installs the VBA-Web source
   • AsyncWrapper is used for providing async functionality (ExecuteAsync) in Windows-only workbooks
   • Select any authenticators that you want to install

3. Click Install / Update

4. Remove references to Excel-REST

1. Use VBA's find-and-replace (Ctrl+h or Edit > Replace) to replace the following:

   • RestHelpers -> WebHelpers
   • RestClient -> WebClient
   • RestRequest -> WebRequest
   • RestResponse -> WebResponse
   • IAuthenticator -> IWebAuthenticator
   • StatusCodes -> WebStatusCode
   • AvailableMethods -> WebMethod
   • AvailableFormats -> WebFormat

5. Update async functionality (optional)

Currently, async functionality is Windows-only and has been been moved out of the core VBA-Web source. Follow these steps to update any async code you may have:

1. Add WebAsyncWrapper to your project

2. Add an explicit reference to WinHTTP

   Tools > References and select Microsoft WinHTTP Services, version 5.1

3. Find each instance of ExecuteAsync in your project and replace with the following:

   ' Before
   Client.ExecuteAsync Request, "Callback", Array(Arg1, Arg2)
   
   ' After
   ' Create async wrapper that wraps Client
   Dim Wrapper As New WebAsyncWrapper
   Set Wrapper.Client = Client
   
   Wrapper.ExecuteAsync Request, "Callback", Array(Arg1, Arg2)

6. Replace/Remove VBA-Web Incompatibilities

Some of the API for Excel-REST has changed in the transition to VBA-Web to enable Mac functionality, upgrade internals, and remove bugs. Use the following steps to identify and fix these issues:

1. {format} UrlSegment is no longer automatically replaced in Resource, set format directly in Resource or use AddUrlSegment("format", "...")
2. Compile VBAProject to identify any compilation errors (Debug > Compile VBAProject)
3. Use the following mapping to resolve any issues:

WebHelpers

• Removed AddToDictionary (Use Dictionary.Add / Dictionary("...") directly)
• Removed BytesToHex
• Removed BytesToBase64
• Removed BytesToFormat
• Removed Base64_HMACSHA1
• Removed CombineObjects
• Removed CreateResponse
• Moved CreateResponseFromHttp > WebResponse.CreateFromHttp
• Moved CreateRequestFromOptions > WebRequest.CreateFromOptions
• Removed EncodeBase64
• Removed EncodeStringToBase64
• Removed ExecuteRequest (Handled directly in WebClient)
• Removed ExecuteRequestAsync (Handled directly in WebAsyncWrapper)
• Moved ExtractCookiesFromHeaders > WebResponse.ExtractCookies
• Moved ExtractHeadersFromResponseHeaders > WebResponse.ExtractHeaders
• Removed FilterObject
• Renamed FormatToContentType > FormatToMediaType
• Removed FormatToName
• Removed IncludesProtocol (Use GetUrlParts)
• Removed IsArray (Use VBA.IsArray)
• Removed HMACSHA1AsBytes
• Removed HMACSHA256AsBytes
• Removed MD5AsBytes
• Moved PrepareHttpRequest > WebClient.PrepareHttpRequest
• Removed PrepareProxyForHttpRequest
• Removed RemoveProtocol
• Removed SetHeaders
• Removed SortDictionary (Was never implemented)
• Renamed StringToBytes > StringToAnsiBytes
• Moved UpdateResponse > WebResponse.Update
• Renamed UrlParts > GetUrlParts and note that the returned Dictionary has an updated schema

WebClient

• Moved ExecuteAsync > WebAsyncWrapper.ExecuteAsync (See "Update async functionality" above)
• Changed ProxyBypassList from Variant to String

WebRequest

• Changes Headers, QuerystringParams, and Cookies from Dictionary to Collection
• Removed AddBody (use (Set) Request.Body = ... instead)
• Removed AddBodyString (use Request.Body = "..." instead)
• Removed AddParameter in favor of explicitly using AddQuerystringParam and AddBodyParameter
• Removed BaseUrl (Handled exclusively in WebClient)
• Removed FormatName
• Moved FullUrl > WebClient.GetFullUrl
• Removed IncludeCacheBreaker (No longer needed)
• Removed IncludeContentLength Always included, but value can be changed with ContentLength
• Removed MethodName (Use WebHelpers.MethodToName)
• Split Parameters into QuerystringParams and Body
• Removed RequireHTTPS (Explicitly use https in BaseUrl and/or Resource)
• Removed RootElement (No longer needed)
• Removed StartTimeoutTimer, StopTimeoutTimer, and TimedOut

IAuthenticator

• Removed BeforeOpen (use PrepareHttp and PrepareCurl instead)