QHELPER自动升级程序用户手册.docx

qupdater用户手册(2.96)一个免费的自动升级程序qupdater用户手册1. qupdater 网址：博客：电话：400-708-7116qq：603830878软件介绍图1. qupdater升级主界面qupdater是一个免费的自动升级程序。为您的软件集成稳定/高效的自动升级功能，是我们的宗旨。四步完成升级工作：检查新版本，下载解压到临时目录，检查本地文件，拷贝到工作目录。无需特别的服务器，普通的web服务即可，如iis、tomcat等。qupdater不关心您的软件升级过程，无论用户使用的是1.0/2,0什么的，直接对比分析用户使用的版本和最新版。服务器部署最新版的软件文件(压缩/不压缩都都可以)，qupdater对比分析服务器和客户的软件文件，不同就更新。可以删除不再使用的软件文件。可以更新运行中的dll/exe。可以创建快捷方式。可以修改/删除ini文件中的每一项。您不用关心qupdater自身的升级、他自己能做好这一切。多线程下载，并校验文件，不成功则多次尝试。自动升级核心程序qupdater.exe是用vc编写的,不依赖任何类库,稳定/高效。提供有专门的批量文件压缩工具，支持拖拽、导入剪切板中的文件。2. qupdater升级原理及过程2.1. qupdater工作原理图2. 不关心用户当前使用的版本图3. 直接对比分析用户的和最新的软件文件2.1.1. 服务器上部署最新版软件文件服务器部署最新的软件文件，不论经过多少此跳跃升级，直接对比用户当前使用的版本和最新版本的软件文件;服务器上通常会部署压缩后的文件，以节省用户的下载量，当然您不压缩也可以，qupdater会先尝试下载压缩的文件，再尝试下载原文件;qupdater.exe直接对比分析用户正使用的软件和服务器上的软件,当然对比依据是qupdater.xml文件。2.1.2. 程序清单文件qupdater.xml服务器上的qupdater.xml是最新版软件的文件清单；客户端的qupdater.xml，是用户正使用的软件文件清单；qupdater.xml记录有各个文件的版本号；升级程序对比客户端的和服务器上的二个xml清单文件，发现有更新(版本号不一致)或发现有新的文件，则下载、更新；qupdater支持删除不再使用的旧版软件文件（qupdater.xml的文件列表中，加删除标记）；qupdater可以为软件文件创建快捷方式；qupdater可以注册ocx或dll；qupdater可以在软件文件拷贝完毕后，运行指定的软件文件。2.2. 四步完成升级过程2.2.1. 检查获取更新文件列表图4. 升级第一步2.2.2. 下载程序文件到临时目录图5. 升级第二步2.2.3. 检查本地文件图6. 升级第三步2.2.4. 从临时目录拷贝文件/完成升级任务图7. 升级第四步2.3. 升级流程图图8. qupdater升级流程图2.4. 软件文件下载流程图以demo.exe的下载过程为例，说明程序文件的下载流程。qupdater下载任何文件，包括qupdater.xml文件的过程都是这样的。有一个特别的地方：不启动qupdater，检查升级文件个数时，只尝试下载一次,若下载不成功，则认为没有更新文件。图9. 以下载文件demo.exe为例说明下载流程2.5. qupdater.exe与其他程序通信qupdater.exe运行中，可以将更新内容、运行状态、下载过程等信息实时传递给其他应用程序，您甚至可以自己做一个升级过程的显示、观察界面；传递方式是：sendmessage，接受消息的对象必须是窗口。2.5.1. 向qupdater.exe传递窗口句柄向qupdater.exe传递窗口句柄的方法是，将窗口句柄格式化为文本后（一个数字），在qupdater.exe启动时，以命令行的方式传递个qupdater.exe。例如(c+代码)：shellexecute(null,”open”,”qupdater.exe”,” -silence -89765431”,null, sw_show);2.5.2. qupdater.exe传递出来的信息qupdater.exe在运行中以sendmessage的方式将运行中的实时信息传递给其他程序的窗口；如果您的窗口退出时，您希望升级终止，请设置如下标识（仅silence模式有效）setprop(this.handle, qupdater. exitwhenwndkilled,1974);如果您的窗口需要qupdater.exe，您还必须设置如下标识setprop(this.handle, qupdater. needmsg,1974);以下列举了qupdater.exe传递出来的4类信息：a. 传递工作过程，msg1974，wparam过程，lparam升级/下载的文件个数其中过程定义如下： public enum updatestep enumupdatenone=0,/升级未开始 enumupdatecheckremote=1,/检查更新文件前 enumupdatecheckremoteerror=2,/检查更新文件出错 enumupdatecheckremoteok=3,/检查更新文件成功后 enumupdatedownload=4,/下载文件前 enumupdatedownloaderror=5,/下载文件出错 enumupdatedownloadok=6,/下载文件成功后 enumupdatechecklocal=7,/检查本地文件前 enumupdatechecklocalerror=8,/检查本地文件出错 enumupdatechecklocalok=9,/检查本地文件成功后 enumupdatecopy=10,/从临时目录拷贝文件前 enumupdatecopyerror=11,/从临时目录拷贝文件出错 enumupdatecopyok=12,/ 从临时目录拷贝文件成功后 enumupdateend=13,/升级结束 b. 传递工作日志msg1975，wparam日志文本，lparam0图10. 传递出的工作日志c. 传递下载进度msg1976，wparam以下载文件个数，lparam要下载的文件总数图11. 传递出来的进度d. 传递升级信息msg1977，wparam更新说明文本，lparam0图12. 传递出的升级信息2.5.3. 升级过程的暂停和再启动您可以在接收消息的窗口设置标记来暂停和再启动升级过程；暂停setprop(this.handle, qupdater.paused,1974);继续setprop(this.handle, qupdater.paused,0);例如：您可以让用户看清更新说明后，再继续后面的升级过程；3. 服务器配置指南3.1. 用到的服务器qupdater无需特别的服务器，普通的web服务即可，如iis，tomcat等。qupdater是通过http下载软件文件的。因此，如果qupdater报告下载错误，您在ie的地址栏里输入网址，测试下载一下即可确定问题所在。3.2. 软件文件的部署软件文件在服务器上部署的目录结构和工作中的软件在本地目录结构是一样的。对于部署在system32等其他目录下的文件，qupdater提供了sys,win,desktop等字符串代替。为减少下载流量，所有的软件文件，都可以压缩后再部署到服务器上(也可不压缩)。压缩文件名称是原名后加”._.zip”后缀。qupdater优先尝试下载”._.zip”文件，下载不成功在尝试下载原文件。图13. 运行在本地的软件文件图14. 部署在服务器上的软件文件3.3. 压缩部署及压缩工具为节省下载流量，qupdater支持将软件文件压缩后部署到服务器上，qzip是qupdater自带的压缩工具，可以批量压缩软件文件。图15. 压缩工具3.3.1. 启动压缩工具您可以依次点击：开始程序qupdaterzip tool，来启动批量压缩工具。3.3.2. 可以通过复制粘贴的方法添加文件图16. 可以通过复制粘贴的方法添加文件3.3.3. 可以拖放文件、目录到qzipqzip支持拖放操作，可以直接拖动windows资源管理器中的目录或文件到qzip的界面上。3.3.4. 目录中文件有多种添加方案图17. 目录中文件的多种添加方案3.3.5. 压缩后的众多软件文件，依靠多线程技术分散下载图18. 压缩后的文件4. 客户端配置指南4.1. qupdater.ini文件配置说明图19. qupdater.ini样例4.1.1. 指定服务器地址(listurl)qupdater.ini updateinfolisturl,用于指定远程qupdater.xml文件的下载地址，qupdater.exe将先尝试下载/update/qupdatercn.xml._.zip再尝试下载/update/qupdatercn.xml图20. 指定远程qupdater.xml的下载位置4.1.2. 软件皮肤(skin)qupdater.ini qupdater skin当skin为空时，qupdater.exe工作时将使用默认的向导式界面；图21. 默认向导式界面当skin为mostsimple时，qupdater.exe将使用超级精简界面，工作在该界面模式下，qupdater按默认的工作方式自动完成一切更新操作，其过程无需人工参入；图22. 超级精简界面超级精简界面上没有任何按钮，工作时将自动关闭主程序，自动完成一切升级工作，遇到错误将自动退出；当skin为qupdater.exe所在目录的子目录，且子目录有一组皮肤(一组图片)时，qupdater.exe将使用这组图片作软件皮肤；图23. 自定义皮肤4.1.3. 极速检查更新(quickcheck)默认情况下，qupdater就是极速检查更新(2.93及以上版本支持)；qupdater.ini qupdater quickcheck,如果将quickcheck设置为false，qupdater就会取消极速检查更新模式；极速检查更新设计的目的是提高软件启动速度；极速检查更新，仅工作于版本检查时，即读取远程qupdater.xml，对比本地的qupdater.xml这一过程中；在这种模式下，qupdater检查更新时不访问网络，而是从缓存中读取qupdater.xml，同时启动一个新的进程去下载远程的qupdater.xml，并缓存起来，下次版本检查时，再读取新的缓存文件；这样qupdater检查更新时，所做的工作就是读缓存/对比版本/启动新进行下载qupdater.xml文件，并迅速返回；启动下载进程而不等待其返回，这就省去了下载等待的过程，极大地加速了启动过程；极速检查更新模式，软件新版本发布时，不是软件一启动就立即可以检查到更新，而是第二次及以后就可以检查到更新，因为第一次启动时，缓存的是以前的版本；4.1.4. 软件入口工作模式(mode=appenter, mode=appenternoprompt)qupdater.ini qupdater mode,如果将mode设置为appenter或者appenternoprompt， qupdater就会工作在软件入口模式。图24. 程序入口模式软件入口模式，有如下特征：1软件以qupdater.exe为进入系统的入口；2qupdater.exe没有检查到更新，就直接启动您的程序；3qupdater.exe检查到更新就进入升级界面；4软件入口工作模式，要求您必须在ini文件中填写applicationapplication和applicationname；5 appenter模式，检查到更新后会提示用户是否更新；6 appenternoprompt模式，检查到更新后不提示，直接启动更新界面；7软件入口模式，最大的好处是，不需要用户更改自己的程序代码；4.1.5. 无界面工作模式（mode=silence）qupdater.ini qupdater mode,如果将mode设置为silence，那么 qupdater工作时，将不弹出任何界面。图25. mode工作模式设置项4.1.6. 系统托盘区图标模式（mode=tryicon）qupdater.ini qupdater mode,如果将mode设置为tryicon，那么 qupdater工作时，将不弹出任何界面。图26. 托盘区图标模式在这种模式下，您可以设定qupdater.ini qupdater checktmspan的一个160直间的数字，来定时检查新版本，单位是分钟。如果您没有设定checktmspan的值，在您升级完成后，或者检查到无更新内容后，托盘图标将退出。4.1.7. 检查本地缺失的文件(checklostfile)qupdater.ini qupdater checklostfile,如果将checklostfile设置为false， qupdater工作时，将不会检查本地缺失的文件。qupdater如果发现文件缺失，就会下载并更新。checklostfile默认为true，即如果没填或填写不正确，就会检查缺失文件。图27. checklostfile检查本地缺失文件设置项4.1.8. 升级日志（log）qupdater.ini qupdater log,您可以在此指定一个文件名，qupdater工作时，会将升级日志写入该文件。图28. log日志文件设置项图29. 升级日志文件4.1.9. 指定软件名称及主程序文件名application,namequpdater.ini updateinfoapplication用于指定主程序文件名，您可以在安装程序中进行配置，也可以只写文件名，不写全路径，qupdater.exe将在qupdater.exe所在的目录中搜寻该程序文件。qupdater.ini updateinfoname用于指定软件名称。qupdater.exe完成升级工作后启动程序，依赖这些设置。图30. 指定软件名称及主程序文件名4.1.10. 指定qupdater.exe用到的语言包(language)qupdater.ini qupdaterlanguage 用于指定qupdater.exe界面的语言包。如果不指定语言包，qupdater.exe自动寻找qupdater.lan文件。qupdater.exe如果找不到语言包，将显示英文界面。语言包文件，应该部署在qupdater.exe所在的目录。图31. 指定语言包4.1.11. 升级过程中的事件updateeventqupdater升级的过程中，会抛出一些事件，您可以通过qupdater.ini设置，在qupdater升级的过程中处理一些自己的应用；例如：检查本地文件时，关闭更多的应用程序；升级完毕执行指定的程序；事件处理程序可以是一个exe程序、vbs脚本、js脚本，也可以是一个执行xml文件（关于执行xml文件，请参考其他文档）；图32. 设置事件处理程序qupdater的事件有如下一些：updatecheckremote：开始检查更新;updatecheckremoteerror：检查更新出错;updatecheckremoteok：检查更新成功;updatedownload：下载开始;updatedownloaderror：下载出错;updatedownloadok：下载完成;updatechecklocal：检查本地文件开始;updatechecklocalerror：检查本地文件有异常;updatechecklocalok：检查本地文件结束;updatecopy：开始拷贝文件;updatecopyerror：拷贝文件出错updatecopyok：拷贝文件结束;updateend：升级结束;4.1.12. 检查更新时显示界面qupdater检查更新时，默认会显示如下界面，可以通过修改配置文件qupdater.ini qupdater showwhencheck来开启和关闭检查更新界面；qupdatershowwhencheck=true图33. 检查更新时显示界面4.1.13. 检查.net框架qupdater.ini qupdaterdotnetfix，如果主程序需要.net framework支持，可以将该项设置为1.0/1.1/2.0/2.1/3.0/3.5，qupdater更新完毕，启动主程序前，会检查.net framework的版本，如果不符合要求，会弹出提示框，告知需要.net framework x.xx版本支持，避免出现不友好的红叉。图34. 检查.net框架检查.net框架通常与软件入口工作模式配合使用；4.2. 修改qupdater界面上的图片、图标4.2.1. 指定主界面用到的log图片qupdater左侧的logo图片，不需要qupdater.ini指定。qupdater启动时在其所在的目录下寻找名为qupdaterlog.bmp，qupdaterlog.gif，qupdaterlog.jpg，qupdaterlog.png的图片文件，任意找到一个，就加载。图35. qupdater中的logo图片4.2.2. 指定主节目上用的log图标qupdater上方的logo图标，不需要qupdater.ini指定。qupdater启动时在其所在的目录下寻找名为qupdatericon.bmp，qupdatericon.gif，qupdatericon.jpg，qupdatericon.png的文件，任意找到一个，就加载。图36. qupdater中的logo图标4.3. 修改qupdater界面语言qupdater安装包中带有简体中文版(qupdatercn.lan)、繁体中文版(qupdaterbig.lan)、英文版(qupdater.lan)，3个版本的界面语言包，当然您也可以制作自己的语言包。qupdater的默认语言为英文，您可以通过如下方法来改变界面语言。4.3.1. 修改qupdater.ini文件改变界面语言您可以修改qupdater.iniqupdater langage来指定语言包图37. 修改ini文件指定语言包4.3.2. 用指定的文件名存储语言包文件如果您没有在qupdater.ini文件中指定语言包，您也可以将一个名为qupdater.lan的语言包文件，放置的qupdater.exe所在目录下。qupdater.exe启动时，先看ini文件里有没有指定语言包，没有就去查找qupdater.lan文件，再没有，就是默认的英文界面了。4.4. 制作自己的语言包qupdater语言包格式如下图，保留等号左边的部分，将您翻译的部分放在等号右边即可。图38. 语言包格式4.5. 将qupdater打包到您的软件中下面列出的文件，是您制作安装包时要考虑的。4.5.1. qupdater.exe升级工作主文件，必不可少。qupdater.exe,可以自己升级自己，您不用在任何配置文件中指定什么。4.5.2. qupdater.ini升级配置文件，必不可少。4.5.3. 语言包(qupdater*.lan)语言包，可以没有，默认是英文界面。语言包可以在qupdater.ini配置文件中指定，也可以不指定。不指定时，在qupdater.exe所在目录中找到qupdater.lan就加载。指定时，就依据qupdater.ini文件中指定的文件名加载。4.5.4. logo图片/logo图标logo图片或logo图标，可以没有。qupdater左侧的logo图片，不需要qupdater.ini指定。qupdater启动时在其所在的目录下寻找名为qupdaterlog.bmp，qupdaterlog.gif，qupdaterlog.jpg，qupdaterlog.png的图片文件，任意找到一个，就加载。qupdater上方的logo图标，不需要qupdater.ini指定。qupdater启动时在其所在的目录下寻找名为qupdatericon.bmp，qupdatericon.gif，qupdatericon.jpg，qupdatericon.png的文件，任意找到一个，就加载。5. qupdater.xml详解5.1. 关于qupdater.xml文件的名称部署在服务器上的qupdater.xml文件名不一定是”qupdater.xml”,您也可以使用其他的文件名,只要在qupdater.ini里指定url路径即可.本地的qupdater.xml文件名一定是”qupdater.xml”,不可更改,qupdater.exe会从服务器上下载新的qupdater.xml,和本地的qupdater.xml文件分析对比,找到需要更新的文件.如果本地缺失qupdater.xml,qupdater.exe则认为远程qupdater.xml中指定的文件,都需要更新.5.2. qupdater.xml中的节点图39.5.3. xml文件description节点说明图40. 更新说明图41. 更新说明配置图42. 更新说明显示文本的依据description用于描述更新说明，如果没填写更新说明，qupdater将不会出现更新说明的界面；qupdater将对比远程和本地qupdater.xml文件中description的二个属性key、ver来确定是否显示该行文本。qupdater将依据key判断，显示新增的description，和版本不一致的description。description文本中出现的n，将会被回车替换。5.4. xml文件include节点说明图43. 包含文件用于包含一个文件清单；5.5. xml文件run节点说明图44. run节点run节点，用于执行一个程序，允许带参数；wait属性为true时，该程序执行完毕后，才会继续后面的工作；5.6. xml文件file节点说明5.6.1. xml文件file节ver说明用于描述文件的版本号；ver可以是任意字符串；不必是数字；qupdater发现不同，就升级，不比较大小的。图. xml文件file节desname说明软件文件的目标路径；目标路径和path不一致时才用到，可以规避某些web服务器，对路径中含有特殊字符串的不支持，如有些linux服务器, 路径中有”#”字符，就下载不了；一个文件可以有多个目标路径，如desname=“abd.dll,binddd.dll”。多个目标可以用逗号、分号，竖线分割。图46.图. 创建快捷方式(shortcut)qupdater拷贝完文件后，会为文件创建快捷方式，shortcut同dstname一样，可以指定多个，中间用逗号分割即可。图48. 创建快捷方式图49. 创建快捷方式并指定图标与shortcut配套使用的还有shortcuticon和iconindex二个属性，这些用于指定快捷方式的图标，图标文件可以是ico文件，也可以是exe、dll文件，如果是exe、dll文件，可以用iconindex指定图标在类库中的序号。5.6.4. 注册用户组件(dll/ocx)(action=register)register动作用作dll或ocx组件上， qupdater拷贝完程序文件后，将会注册该dll或ocx。图50. 注册文件5.6.5. 删除文件(action=delete)指定动作为删除，qupdater将不会下载文件，直接删除本地文件。图51. 删除文件5.7. qupdater.xml中用到的变量xml文件中的path,dstname,shortcut可以用如下字符代表特殊的路径，qupdater执行相关动作前，将会把这些字符串替换成相应的路径。5.7.1. winc:windows5.7.2. sysc:windowssystem325.7.3. appqupdater.exe文件所在的目录5.7.4. programfiles/pfc:program files5.7.5. document我的文件夹win7目录示例:c:users myaccount documentswinxp目录示例:c:documents and settings myaccount my documents5.7.6. commondesktop所有用户的桌面win7目录示例:c:userspublicdesktopwinxp目录示例:c:documents and settingsall users桌面5.7.7. desktop当前用户的桌面win7目录示例:c:users myaccount desktopwinxp目录示例:c:documents and settings myaccount 桌面5.7.8. commonprograms/startupprograms/startupprograms所有用户的”开始菜单”程序”所在的位置win7目录示例:c:programdatamicrosoftwindowsstart menuprogramswinxp目录示例:c:documents and settingsall users开始菜单程序5.7.9. programs当前用户的”开始菜单”程序”所在的位置win7目录示例:c:users myaccount appdataroamingmicrosoftwindowsstart menuprogramswinxp目录示例:c:documents and settings myaccount 开始菜单程序5.7.10. startmenu/startupmenu当前用户的”开始菜单”所在的位置win7目录示例:c:users myaccount appdataroamingmicrosoftwindowsstart menuwinxp目录示例:c:documents and settings myaccount 开始菜单5.7.11. commonstartmenu/commonstartupmenu所有用户的”开始菜单”所在的位置win7目录示例:c:programdatamicrosoftwindowsstart menuwinxp目录示例:c:documents and settingsall users开始菜单5.7.12. commonstartup所有用户的”开始菜单”程序”启动”所在的位置win7目录示例:c:programdatamicrosoftwindowsstart menuprogramsstartupwinxp目录示例:c:documents and settingsall users开始菜单程序启动5.7.13. startup当前用户的”开始菜单”程序”启动”所在的位置win7目录示例:c:users myaccount appdataroamingmicrosoftwindowsstart menuprogramsstartupwinxp目录示例:c:documents and settings myaccount 开始菜单程序启动5.8. 一个完整的qupdater.xml示例xxxx-xxxx-xxxx-xxxxxxxx 增加单个文件的多线程下载,至此,可以同时下载多个文件,每个文件又是多线程. 增加更新说明,说明文本放置在服务端qupdater.xml文件中. 更新语言包文件. 6. 零代码集成您可以参考软件示例中提供的代码调用qupdater，集成自动升级功能；也可以不增加/修改任何代码，实现集成；6.1. 软件入口工作模式qupdater有种工作模式叫“软件入口”工作模式；软件启动时，直接启动qupdater.exe，而不是自己的程序，qupdater.exe 没有检查到更新时直接启动您的程序；qupdater.exe 检查到更新就进入升级界面；6.2. 软件入口工作模式配置配置文件qupdater.ini- qupdater-mode,如果将mode 设置为appenter 或者appenternoprompt， qupdater 就会工作在软件入口模式。appenter 模式，检查到更新后会提示用户是否更新；appenternoprompt 模式，检查到更新后不提示，直接启动更新界面；软件入口工作模式，要求您必须在ini 文件中填写qupdater.ini-application-application 和qupdater.ini-application-name，以便qupdater可以找到您的主程序；软件入口模式，最大的好处是，不需要用户更改自己的程序代码；图52. 软件工