Практическое руководство. Получение хода выполнения установщика .NET Framework 4

Статья
08/11/2011

.NET Framework 4 — это распространяемый пакет среды выполнения. Процесс установки .NET Framework 4 можно включить в качестве обязательного компонента (элемента цепочки) в процесс установки приложения. Чтобы создать специальную или универсальную процедуру установки, может потребоваться автоматический запуск и отслеживание процесса установки .NET Framework 4 с одновременным отображением собственного представления хода выполнения установки. Чтобы обеспечить автоматическое отслеживание, процесс установки .NET Framework 4 (элемент цепочки (chainee), который может находиться под наблюдением) может записывать сообщения о ходе выполнения в сопоставленный с памятью сегмент ввода-вывода (MMIO), содержимое которого может считываться процессом установки приложения (наблюдателем, или формирователем цепочки (chainer)). Процесс установки .NET Framework 4 можно отменить, записав в сегмент MMIO сообщение Abort.

Вызов. Чтобы вызвать процесс установки .NET Framework 4 и получать информацию о ходе выполнения из раздела MMIO, программа установки приложения должна выполнить следующие действия.
1. Вызов распространяемой программы .NET Framework 4; например:
```
dotnetfx40x86.exe /q /pipe <section name>
```
  где имя раздела — любое имя, которое требуется использовать для идентификации приложения. Элемент цепочки выполняет чтение из раздела MMIO и запись в раздел MMIO асинхронно, поэтому в течение этого времени удобно использовать события и сообщения. В данном примере элемент цепочки создается конструктором, который выделяет раздел MMIO (YourSection) и определяет событие (YourEvent). Эти имена следует заменить на имена, уникальные для программы установки приложения.
2. Чтение из раздела MMIO. В платформе .NET Framework 4 операции загрузки и установки выполняются одновременно: один компонент .NET Framework 4 может устанавливаться, а другой — загружаться. В результате данные о ходе выполнения отправляются назад (записываются) в раздел MMIO в виде числа, значение которого увеличивается от 1 до 255. Когда записано число 255 и элемент цепочки завершает работу, установка завершается.
Коды выхода. Следующие коды выхода от команды вызова распространяемой программы .NET Framework 4 (см. предыдущий пример) указывают, успешно ли выполнена установка.
- 0 — установка выполнена успешно.
- 3010 — установка выполнена успешно; требуется перезагрузка.
- 1642 — установка отменена.
- Все другие коды — в процессе установки произошли ошибки; для получения подробных сведений просмотрите файлы журналов, созданные в папке %temp%.
Отмена установки. Установку можно в любое время отменить, используя метод Abort для установки флагов m_downloadAbort и m_ installAbort в разделе MMIO. В результате процесс установки .NET Framework 4 остановится.

Пример формирователя цепочки

В следующем примере выполняются автоматический запуск и отслеживание процесса установки .NET Framework 4 с отображением хода выполнения.

Внимание
Этот пример следует запускать в качестве администратора.

Полное решение Visual Studio для примера Chain Installer for .NET Framework 4 можно загрузить из коллекции кодов Майкрософт.

В следующих подразделах описываются важные файлы данного примера.

MmIoChainer.h

Файл MmIoChainer.h содержит определение структуры данных и базовый класс, из которого должен быть получен класс формирователя цепочки. Структура данных MMIO состоит из следующего кода.

// 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.
    };

После структуры данных следует структура класса для реализации формирователя цепочки. Чтобы включить распространяемый пакет .NET Framework 4 в цепочку, класс сервера создается как производный от класса MmioChainer. Класс MmioChainerBase используется и формирователем цепочки, и элементом цепочки. В следующем коде методы и члены изменены, чтобы пример был коротким.

// 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
        { 
...
        }

...
    };

Формирователь цепочки реализуется следующим образом.

// 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);
        }
    };

Элемент цепочки создается как производный от того же базового класса.

// 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

Для отображения информации о ходе выполнения можно получить из класса MmioChainer и переопределить соответствующие методы. Следует иметь в виду, что класс MmioChainer уже обеспечивает блокировку метода Run(), который будет вызываться производным классом. Класс Server в следующем коде запускает указанную программу установки, отслеживает ход ее выполнения и возвращает код выхода.

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);
    }
...
};

Данные о ходе выполнения будут беззнаковыми данными типа char в диапазоне от 0 (0%) до 255 (100%). Выходные данные метода Finished — HRESULT.

Важно
Распространяемый пакет .NET Framework 4 обычно записывает много сообщений о ходе выполнения и одно сообщение, указывающее о завершении (на стороне формирователя цепочки).Он также выполняет асинхронное чтение, осуществляя поиск записи Abort.Если распространяемый пакет получает запись Abort, он отменяет установку и (в конечном счете) записывает окончательную запись с E_ABORT в качестве данных.

Распространяемый пакет .NET Framework 4 обычно записывает много сообщений о ходе выполнения и одно сообщение, указывающее о завершении (на стороне формирователя цепочки).Он также выполняет асинхронное чтение, осуществляя поиск записи Abort.Если распространяемый пакет получает запись Abort, он отменяет установку и (в конечном счете) записывает окончательную запись с E_ABORT в качестве данных.

Типовой сервер создает случайное имя файла MMIO, файл (как показано в предыдущем примере кода в Server::CreateSection) и запускает распространяемый пакет с помощью CreateProcess, передавая имя канала с параметром "-pipe someFileSectionName". Методы OnProgress и Finished сервера содержат код, зависящий от сервера.

IprogressObserver.h

Наблюдатель за ходом выполнения уведомляется о ходе выполнения (0-255) и о завершении установки.

#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

Значение HRESULT передается методу Finished. В следующем коде показана основная точка входа в программу.

// 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);
}

Измените путь к исполняемому файлу (Setup.exe в данном примере), чтобы указать его правильное расположение, или измените код, чтобы понять его. Этот код следует запускать в качестве администратора.

См. также

Основные понятия

Развертывание .NET Framework и приложений

Другие ресурсы

Руководство по развертыванию .NET Framework для разработчиков

Журнал изменений

Дата	Журнал	Причина
Июль 2010	Добавлен раздел.	Улучшение информации.

Июль 2010

Добавлен раздел.

Улучшение информации.

Поделиться через