{"id":4083,"date":"2010-02-02T14:12:00","date_gmt":"2010-02-02T14:12:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/vcblog\/2010\/02\/02\/atl-support-for-transaction-file-system\/"},"modified":"2019-02-18T18:45:40","modified_gmt":"2019-02-18T18:45:40","slug":"atl-support-for-transaction-file-system","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/atl-support-for-transaction-file-system\/","title":{"rendered":"ATL support for Transaction File System"},"content":{"rendered":"

Hello,<\/p>\n

<\/span><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

My name is Weidong Huang, and I am an SDET on the Visual C++ team. Today, I would like to talk a little about ATL support for Transaction File System in Visual Studio 2010.<\/p>\n

<\/span><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

What is Transactional File System?<\/p>\n

<\/span><\/b><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

Transactional File System is a new technology first introduced in Windows Vista. It enables you to roll back operations made on the file system and registry.  It is helpful in improving application reliability and data consistency without having to add your own tooling.  By using transactional file systems in VC++ you can treat a set of operations to files and registry as a transaction which can either be completed as a whole or reversed. <\/p>\n

<\/span><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

One example that could use Transactional File System:  A developer creates several new files, writes some information into them, deletes one existing file and wishes to either complete all the operations or do nothing at all.  He could use the Transactional File System to create a transaction, add all the steps into this transaction, commit it when everything works fine, or rollback if there is anything wrong with a step.   <\/span><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

What is implemented in Visual Studio 2010?<\/p>\n

<\/span><\/b><\/p>\n

\n

 <\/font><\/p>\n<\/p>\n

1.<\/font>      <\/span><\/span><\/span>Added a new ATL class “CAtlTransactionalManager”:  CAtlTransactionManager is a new class wrapping Transaction File System Windows APIs and provides most of Transactional File System functionalities that are implemented in VC++, including: <\/p>\n

<\/font><\/font><\/p>\n

·<\/font>         <\/span><\/span><\/span>File Operations: CreateFile, DeleteFile, FindFirstFile, GetFileAttributes, SetFileAttributes, MoveFile.<\/p>\n

<\/font><\/font><\/p>\n

·<\/font>         <\/span><\/span><\/span>Registry Operations: RegCreateKeyEx, RegDeleteKey, RegOpenKeyEx<\/font><\/font><\/p>\n

<\/p>\n

<\/font><\/font> <\/p>\n

2.<\/font>      <\/span><\/span><\/span>Added transaction support to Existing Classes and APIs, including:<\/p>\n

<\/font><\/font><\/p>\n

·<\/font>         <\/span><\/span><\/span>Classes: CFile, CStdioFile, CAtlFile, CFileFind by adding a constructor with TransactionManager as following format: <\/p>\n

<\/font><\/font><\/p>\n

CFile(CAtlTransactionManager *);<\/p>\n

<\/font><\/font><\/p>\n

CStdioFile(CAtlTransactionManager *);<\/p>\n

<\/font><\/font><\/p>\n

CAtlFile(CAtlTransactionManager *);<\/p>\n

<\/font><\/font><\/p>\n

CFileFind(CAtlTransactionManager *);<\/p>\n

<\/font><\/font><\/p>\n

·<\/font>         <\/span><\/span><\/span>APIs: AfxRegCreateKey, AfxRegOpenKey, AfxRegDeleteKey by adding a parameter TransactionManager to the API.<\/p>\n

<\/font><\/font><\/p>\n

\n

 <\/font><\/p>\n<\/p>\n

How to use Transaction File System?<\/p>\n

<\/span><\/b><\/p>\n

1.<\/font>      <\/span><\/span><\/span>With CAtlTransactionManager:<\/p>\n

<\/font><\/font><\/p>\n

(1)<\/font>   <\/span><\/span><\/span>Create a CAtlTransactionManager;<\/p>\n

<\/font><\/font><\/p>\n

(2)<\/font>   <\/span><\/span><\/span>Call functions in CAtlTransationManager to do operations on File or registry <\/p>\n

<\/font><\/font><\/p>\n

(3)<\/font>   <\/span><\/span><\/span>Call Transaction Manager Commit() to submit the change or RollBack() to reverse the change.<\/p>\n

<\/font><\/font><\/p>\n

Note: <\/span><\/b>Please refer to Walkthrough Step 2, 3, 4 and 5 for code example. <\/p>\n

<\/span><\/font><\/p>\n

\n

 <\/font><\/p>\n<\/p>\n

2.<\/font>      <\/span><\/span><\/span>With CFile, CStdioFile, CAtlFile, CFileFind:<\/p>\n

<\/font><\/font><\/p>\n

(1)<\/font>   <\/span><\/span><\/span>Create a CAtlTransactionManager;<\/p>\n

<\/font><\/font><\/p>\n

(2)<\/font>   <\/span><\/span><\/span>Create class with the Transaction Manager created in the first step;<\/p>\n

<\/font><\/font><\/p>\n

(3)<\/font>   <\/span><\/span><\/span>Call class member functions to do operations on File;<\/p>\n

<\/font><\/font><\/p>\n

(4)<\/font>   <\/span><\/span><\/span>Call Transaction Manager Commit() to submit the change or RollBack() to reverse the change.<\/p>\n

<\/font><\/font><\/p>\n

Note: <\/b>Please refer to Walkthrough Step6 for code example.<\/p>\n

<\/b><\/font><\/font><\/p>\n

3.<\/font>      <\/span><\/span><\/span>With Registry APIs:<\/p>\n

<\/font><\/font><\/p>\n

(1)<\/font>   <\/span><\/span><\/span>Create a CAtlTransactionManager;<\/p>\n

<\/font><\/font><\/p>\n

(2)<\/font>   <\/span><\/span><\/span>Call API functions with the Transaction Manager created in the first step to do operations on File;<\/p>\n

<\/font><\/font><\/p>\n

(3)<\/font>   <\/span><\/span><\/span>Call Transaction Manager Commit() to submit the change or RollBack() to reverse the change.<\/p>\n

<\/font><\/font><\/p>\n

What will happen in operating systems prior to Windows Vista?<\/p>\n

<\/span><\/b><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

Transactional File System is only supported in Windows Vista or up level OSes and not available on operating systems prior Vista such as Windows XP and Windows 2003.  Will the application crash if it uses Transactional System Functionality in an operating system that doesn’t support it?  The answer is no.  When creating CAtlTransactionManager, there is an option called “Fallback” which is use to control the behavior in operating systems prior to Vista.  By default, the fallback is TRUE which means you will get the same behavior just as that of non-transactional version if Transaction File System is not supported.  If you set the fallback to FALSE, then the operation will fail when it is not supported.<\/span> <\/p>\n

<\/span><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/p>\n

Walkthrough to use Transaction File System:<\/p>\n

<\/span><\/b><\/p>\n

<\/p>\n

 <\/p>\n

<\/span><\/b><\/p>\n

Here is the walkthrough to help you understand the usage of Transaction File System: <\/p>\n

<\/span><\/p>\n

Step1: Create project<\/span><\/h2>\n

1.<\/font>      <\/span><\/span><\/span>Create a default Dialog Type MFC Application call “TransactionalFileSystemDemo”.<\/p>\n

<\/font><\/font><\/p>\n

2.       <\/span><\/span><\/span>Double click the OK button in default dialog (not file dialog) and create the default event handler “<\/font>void<\/span> <\/span>CTransactionalFileSystemDemoDlg::OnBnClickedOk()”. All codes in following steps will be added to this function.<\/p>\n

<\/span><\/font><\/font><\/p>\n

Step2: Use CAtlTransactionManager to Commit File Transaction<\/span><\/h2>\n

<\/p>\n

<\/span> <\/h2>\n

Add codes<\/p>\n

<\/font><\/span><\/b><\/p>\n

(1)<\/font>   <\/span><\/span><\/span>Add following code to CTransactionalFileSystemDemoDlg::OnBnClickedOk()<\/p>\n

<\/font><\/font><\/p>\n

                        CAtlTransactionManager tmFileCommit1;<\/p>\n

<\/span><\/b><\/p>\n

                        HANDLE hFile;<\/p>\n

<\/span><\/b><\/p>\n

                        hFile = tmFileCommit1.CreateFile(_T(“c:\\TransactionFileSystemDemo\\file1.txt”), GENERIC_READ | GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_TEMPORARY, NULL);<\/p>\n

<\/span><\/b><\/p>\n

                        CloseHandle(hFile);<\/p>\n

<\/span><\/b><\/p>\n

                        hFile = tmFileCommit1.CreateFile(_T(“c:\\TransactionFileSystemDemo\\file2.txt”), GENERIC_READ | GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_TEMPORARY, NULL);<\/p>\n

<\/span><\/b><\/p>\n

                        CloseHandle(hFile);<\/p>\n

<\/span><\/b><\/p>\n

                        hFile = tmFileCommit1.CreateFile(_T(“c:\\TransactionFileSystemDemo\\file3.txt”), GENERIC_READ | GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_TEMPORARY, NULL);<\/p>\n

<\/span><\/b><\/p>\n

                        CloseHandle(hFile);<\/p>\n

<\/span><\/b><\/p>\n

                        WIN32_FIND_DATA nextFile;<\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit1.FindFirstFile(_T(“c:\\TransactionFileSystemDemo\\file1.txt”), &nextFile);<\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit1.SetFileAttributes(_T(“c:\\TransactionFileSystemDemo\\file1.txt”), FILE_ATTRIBUTE_READONLY);<\/p>\n

<\/span><\/b><\/p>\n

                        DWORD dwAttributes = tmFileCommit1.GetFileAttributes(_T(“c:\\TransactionFileSystemDemo\\file1.txt”));<\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit1.Commit();<\/span><\/p>\n

<\/span><\/b><\/p>\n

Result<\/p>\n

<\/span><\/b><\/p>\n

                 &nb\nsp;      CAtlTransactionManager tmFileCommit2;<\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit2.DeleteFile(_T(“c:\\TransactionFileSystemDemo\\file2.txt”));<\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit2.MoveFile(_T(“c:\\TransactionFileSystemDemo\\file3.txt”), _T(“c:\\TransactionFileSystemDemo\\file4.txt”));<\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit2.Commit();<\/span><\/p>\n

<\/span><\/b><\/p>\n

                        tmFileCommit2.Close();<\/span><\/b><\/p>\n

<\/span><\/p>\n

Experience:<\/span><\/h2>\n

1.<\/font>      <\/span><\/span><\/span>Create new folder “c:\\TransactionFileSystemDemo”;<\/p>\n

<\/font><\/font><\/p>\n

2.<\/font>      <\/span><\/span><\/span>Build the project, set break point at “tmFileCommit1.Commit()” and “tmFileCommit2.Commit()”.<\/p>\n

<\/font><\/font><\/p>\n

3.<\/font>      <\/span><\/span><\/span>Debug the application, click the default “OK” button and stop at the first break point;<\/p>\n

<\/font><\/font><\/p>\n

a.<\/font>       <\/span><\/span><\/span>Watch the value of nextFile and dwAttributes, they should have expected values.<\/p>\n

<\/font><\/font><\/p>\n

b.<\/font>      <\/span><\/span><\/span>Open Explorer and check folder “c:\\TransactionFileSystemDemo”: no file should be created.<\/p>\n

<\/font><\/font><\/p>\n

4.<\/font>      <\/span><\/span><\/span>Continue debug and go one more step, stop just after “tmFileCommit1.Commit()”<\/p>\n

<\/font><\/font><\/p>\n

a.<\/font>       <\/span><\/span><\/span>Check folder “c:\\TransactionFileSystemDemo”: file1.txt, file2.txt and file3.txt should be created in this folder.<\/p>\n

<\/font><\/font><\/p>\n

5.<\/font>      <\/span><\/span><\/span>Continue debug and stop at the second break point;<\/p>\n

<\/font><\/font><\/p>\n

a.<\/font>       <\/span><\/span><\/span>Check folder “c:\\TransactionFileSystemDemo”: file1.txt, file2.txt and file3.txt are still there.<\/p>\n

<\/font><\/font><\/p>\n

6.<\/font>      <\/span><\/span><\/span>Continue debug and go one more step, stop just after “tmFileCommit1.Commit()”<\/p>\n

<\/font><\/font><\/p>\n

a.        <\/span><\/span><\/span>Check folder “c:\\TransactionFileSystemDemo”: file1.txt should be deleted and file3.txt should be renamed to file4.txt.<\/font><\/font><\/p>\n

<\/p>\n

<\/span><\/font><\/font><\/p><\/p>\n","protected":false},"excerpt":{"rendered":"

Hello,   My name is Weidong Huang, and I am an SDET on the Visual C++ team. Today, I would like to talk a little about ATL support for Transaction File System in Visual Studio 2010.   What is Transactional File System?   Transactional File System is a new technology first introduced in Windows Vista. […]<\/p>\n","protected":false},"author":289,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-4083","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-cplusplus"],"acf":[],"blog_post_summary":"

Hello,   My name is Weidong Huang, and I am an SDET on the Visual C++ team. Today, I would like to talk a little about ATL support for Transaction File System in Visual Studio 2010.   What is Transactional File System?   Transactional File System is a new technology first introduced in Windows Vista. […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/4083","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/289"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=4083"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/4083\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/35994"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=4083"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=4083"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=4083"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}