How to: Get Progress from the .NET Framework 4 Installer

Article
02/04/2013

The .NET Framework version 4 is a redistributable runtime. You can include (chain) the .NET Framework 4 setup process as a prerequisite part of your application's setup. To present a customized or unified setup experience, you may want to silently launch and track the .NET Framework 4 setup process while showing your own view of the setup progress. To enable silent tracking, the .NET Framework 4 setup process (the chainee, which can be watched) can write progress message to a memory-mapped I/O (MMIO) segment that your setup process (the watcher or chainer) can read. You can cancel the .NET Framework 4 setup process by writing an Abort message to the MMIO segment.

Invocation. To call the .NET Framework 4 setup process and receive progress information from the MMIO section, your setup program must do the following:
1. Call the .NET Framework 4 redistributable program; for example:
```
dotnetfx40x86.exe /q /pipe <section name>
```
  where section name is any name you want to use to identify your application. The chainee reads and writes to the MMIO section asynchronously, so you might find it convenient to use events and messages during that time. In the example, the chainee is created by a constructor that both allocates the MMIO section (YourSection) and defines an event (YourEvent). Please replace those names with names that are unique to your setup program.
2. Read from the MMIO section. In the .NET Framework 4, the download and installation operations are simultaneous: One part of the .NET Framework 4 might be installing while another part is downloading. As a result, progress is sent back (that is, written) to the MMIO section as a number that increases from 1 to 255. When 255 is written and the chainee exits, the installation is complete.
Exit codes. The following exit codes from the command to call the .NET Framework 4 redistributable program (see the previous example) indicate whether setup has succeeded or failed:
- 0 - Setup completed successfully.
- 3010 – Setup completed successfully; reboot is required.
- 1602 – Setup has been canceled.
- All other codes - Setup encountered errors; examine the log files created in %temp% for details.
Canceling setup. You can cancel setup at any time by using the Abort method to set the m_downloadAbort and m_ installAbort flags in the MMIO section. This will stop the .NET Framework 4 setup process.

Chainer Sample

The following example silently launches and tracks the .NET Framework 4 setup process while showing progress.

Caution
You must run the example as an administrator.

You can download the complete Visual Studio solution for the .NET Framework 4 Chainer Sample from the MSDN Developer Samples website.

The following sections describe the significant files in this example.

MmIoChainer.h

The MmIoChainer.h file contains the data structure definition and the base class from which the chainer class should be derived. The MMIO data structure consists of the following code.

// MMIO data structure for inter-process communication.
    struct MmioDataStructure
    {
        bool m_downloadFinished;        // Is download done yet?
        bool m_installFinished;         // Is installer operation done yet?
        bool m_downloadAbort;           // Set to cause downloader to abort.
        bool m_installAbort;            // Set to cause installer operation to abort.
        HRESULT m_hrDownloadFinished;   // HRESULT for download.
        HRESULT m_hrInstallFinished;    // HRESULT for installer operation.
        HRESULT m_hrInternalError;      // Internal error from MSI if applicable.
        WCHAR m_szCurrentItemStep[MAX_PATH];   // This identifies the windows installer step being executed if an error occurs while processing an MSI, for example, "Rollback".
        unsigned char m_downloadProgressSoFar; // Download progress 0 - 255 (0 to 100% done). 
        unsigned char m_installProgressSoFar;  // Install progress 0 - 255 (0 to 100% done).
        WCHAR m_szEventName[MAX_PATH];         // Event that chainer creates and chainee opens to sync communications.
    };

Following the data structure is the class structure for implementing a chainer. You derive your server class from the MmioChainer class to chain the .NET Framework 4 redistributable. The MmioChainerBase class is used by both the chainer and the chainee. In the following code, methods and members have been edited to keep the length of this example short.

// MmioChainerBase class manages the communication and synchronization data 
    // structures. It also implements common get accessors (for chainer) and set accessors(for chainee).
    class MmioChainerBase
    {
...

        // This is called by the chainer to force the chained setup to be canceled.
        void Abort()
        {
            //Don't do anything if it is invalid.
            if (NULL == m_pData)
            {
                return;
            }
...
            // Chainer told us to cancel.
            m_pData->m_downloadAbort= true;
            m_pData->m_installAbort = true;
        }
// Called when chainer wants to know if chained setup has finished both download and installation.
        bool IsDone() const 
        { 
...
        }

        // Called by the chainer to get the overall progress, i.e., the combination of the download and installation.
        unsigned char GetProgress() const 
        { 
...
        }


        // Get download progress.
        unsigned char GetDownloadProgress() const
        {
...
        }

        // Get installation progress.
        unsigned char GetInstallProgress() const
        {
...
        }

        // Get the combined setup result, installation taking priority over download if both failed.
        HRESULT GetResult() const
        { 
...
        }

...
    };

The chainer is implemented as follows.

// This is the class that the consumer (chainer) should derive from.
    class MmioChainer : protected MmioChainerBase
    {
    public:
        // Constructor
        MmioChainer (LPCWSTR sectionName, LPCWSTR eventName)
            : MmioChainerBase(CreateSection(sectionName), CreateEvent(eventName))
        {
            Init(eventName);
        }

        // Destructor
        virtual ~MmioChainer ()
        {
            ::CloseHandle(GetEventHandle());
            ::CloseHandle(GetMmioHandle());
        }

    public: // The public methods:  Abort and Run
        using MmioChainerBase::Abort;
        using MmioChainerBase::GetInstallResult;
        using MmioChainerBase::GetInstallProgress;
        using MmioChainerBase::GetDownloadResult;
        using MmioChainerBase::GetDownloadProgress;
        using MmioChainerBase::GetCurrentItemStep;

        HRESULT GetInternalErrorCode()
        {
            return GetInternalResult();
        }

        // Called by the chainer to start the chained setup. This blocks until setup is complete.
        void Run(HANDLE process, IProgressObserver& observer)
        {
            HANDLE handles[2] = { process, GetEventHandle() };

            while(!IsDone())
            {
                DWORD ret = ::WaitForMultipleObjects(2, handles, FALSE, 100); // INFINITE ??
                switch(ret)
                {
                case WAIT_OBJECT_0:
                    { // Process handle closed.  Maybe it blew up, maybe it's just really fast.  Let's find out.
                        if (IsDone() == false) // Not a good sign
                        {
                            HRESULT hr = GetResult();
                            if (hr == E_PENDING) // Untouched
                                observer.Finished(E_FAIL);
                            else
                                observer.Finished(hr);

                            return;
                        }
                        break;
                    }
                case WAIT_OBJECT_0 + 1:
                    observer.OnProgress(GetProgress());
                    break;
                default:
                    break;
                }
            }
            observer.Finished(GetResult());
        }

    private:
        static HANDLE CreateSection(LPCWSTR sectionName)
        {
            return ::CreateFileMapping (INVALID_HANDLE_VALUE,
                NULL, // Security attributes
                PAGE_READWRITE,
                0, // high-order DWORD of maximum size
                sizeof(MmioDataStructure), // Low-order DWORD of maximum size.
                sectionName);
        }
        static HANDLE CreateEvent(LPCWSTR eventName)
        {
            return ::CreateEvent(NULL, FALSE, FALSE, eventName);
        }
    };

The chainee derives from the same base class.

// This class is used by the chainee.
    class MmioChainee : protected MmioChainerBase
    {
    public:
        MmioChainee(LPCWSTR sectionName)
            : MmioChainerBase(OpenSection(sectionName), OpenEvent(GetEventName(sectionName)))
        {
        }

        virtual ~MmioChainee()
        {
        }

    private:
        static HANDLE OpenSection(LPCWSTR sectionName)
        {
            return ::OpenFileMapping(FILE_MAP_WRITE, // Read/write access.
                FALSE,          // Do not inherit the name.
                sectionName);
        }

        static HANDLE OpenEvent(LPCWSTR eventName)
        {        
            return ::OpenEvent (EVENT_MODIFY_STATE | SYNCHRONIZE,
                FALSE,
                eventName);
        }

        static CString GetEventName(LPCWSTR sectionName)
        {
            CString cs = L"";

            HANDLE handle = OpenSection(sectionName);
            if (NULL == handle)
            {
                DWORD dw;
                dw = GetLastError();
                printf("OpenFileMapping fails with last error: %08x",dw);
            }
            else
            {
                const MmioDataStructure* pData = MapView(handle);
                if (pData)
                {
                    cs = pData->m_szEventName;
                    ::UnmapViewOfFile(pData);
                }
                ::CloseHandle(handle);
            }

            return cs;
        }
    };

ChainingdotNet4.cpp

You can derive from the MmioChainer class and override the appropriate methods to display progress information. Note that MmioChainer already provides a blocking Run() method that the derived class will call. The Server class in the following code launches the specified setup program, monitors its progress, and returns an exit code.

class Server : public ChainerSample::MmioChainer, public ChainerSample::IProgressObserver
{
public:
    // Mmiochainer will create section with given name. Create this section and the event name.
    // Event is also created by the Mmiochainer, and name is saved in the mapped data structure.
    Server():ChainerSample::MmioChainer(L"TheSectionName", L"TheEventName")
 // Customize for your event names.
    {}

    bool Launch(const CString& args)
    {
        CString cmdline = L"Setup.exe -pipe TheSectionName " + args; // Customize with name and location of setup .exe file that you want to run.
        STARTUPINFO si = {0};
        si.cb = sizeof(si);
        PROCESS_INFORMATION pi = {0};

        // Launch the Setup.exe that installs the .NET Framework 4.
        BOOL bLaunchedSetup = ::CreateProcess(NULL, 
                                 cmdline.GetBuffer(),
                                 NULL, NULL, FALSE, 0, NULL, NULL, 
                                 &si,
                                 &pi);

        // If successful 
        if (bLaunchedSetup != 0)
        {
            IProgressObserver& observer = dynamic_cast<IProgressObserver&>(*this);
            Run(pi.hProcess, observer);

            // To get the return code of the chainee, check exit code
            // of the chainee process after it exits.
            DWORD exitCode = 0;

            // Get the true return code.
            ::GetExitCodeProcess(pi.hProcess, &exitCode);
            printf("Exit code: %08X\n  ", exitCode);

            // Get internal result.
            // If the failure is in an MSI/MSP payload, the internal result refers to the error messages listed at
            // https://msdn.microsoft.com/en-us/library/aa372835(VS.85).aspx
            HRESULT hrInternalResult = GetInternalResult(); 
            printf("Internal result: %08X\n",hrInternalResult);




            ::CloseHandle(pi.hThread);
            ::CloseHandle(pi.hProcess);
        }
        else
        {
            printf("CreateProcess failed");
            ReportLastError();
        }

        return (bLaunchedSetup != 0);
    }

private: // IProgressObserver
    virtual void OnProgress(unsigned char ubProgressSoFar)
    {
        printf("Progress: %i\n  ", ubProgressSoFar);

        // Testing: BEGIN - To test Abort behavior, uncomment the following code:
        //if (ubProgressSoFar > 127)
        //{
        //    printf("\rDeliberately Aborting with progress at %i  ", ubProgressSoFar);
        //    Abort();
        //}
        // Testing END
    }

    virtual void Finished(HRESULT hr)
    {
        // This HRESULT is communicated over MMIO and may be different from process
        // exit code of the chainee Setup.exe.
        printf("\r\nFinished HRESULT: 0x%08X\r\n", hr);
    }
...
};

Progress data will be an unsigned char between 0 (0%) and 255 (100%). The output from the Finished method is an HRESULT.

Important
The .NET Framework 4 redistributable typically writes many progress messages and a single message that indicates completion (on the chainer side). It also reads asynchronously, looking for Abort records. If it receives an Abort record, it cancels the installation, and (eventually) writes a finished record with E_ABORT as its data.

A typical server creates a random MMIO file name, creates the file (as shown in the previous code example, in Server::CreateSection), and launches the redistributable by using CreateProcess, passing the pipe name with the "-pipe someFileSectionName" switch. The server’s OnProgress and Finished methods contain server-specific code.

IprogressObserver.h

The progress observer gets notified of progress (0-255) and when the installation has finished.

#ifndef IPROGRESSOBSERVER_H
#define IPROGRESSOBSERVER_H

#include <oaidl.h>

namespace ChainerSample
{
    class IProgressObserver
    {
    public:
        virtual void OnProgress(unsigned char) = 0; // 0 - 255:  255 == 100%
        virtual void Finished(HRESULT) = 0;         // Called when operation is complete.
    };
}
#endif

The HRESULT is passed to the Finished method.The following code shows the main entry point to the program.

// Main entry point for program.
int __cdecl main(int argc, _In_count_(argc) char **_argv)
{
    CString args;
    if (argc > 1)
    {
        args = CString(_argv[1]);
    }

    return Server().Launch(args);
}

Change the path of the executable (Setup.exe in the example) to point to its correct location, or change the code to figure it out. You must run the code as an administrator.

How to: Get Progress from the .NET Framework 4 Installer

Chainer Sample

MmIoChainer.h

ChainingdotNet4.cpp

IprogressObserver.h

See Also

Concepts

Other Resources

Additional resources