Интеграция универсальных приложений Windows с Office Integrate with Office from Windows universal apps

Вы можете интегрировать сторонние приложения на универсальной платформе приложений Windows с Excel Mobile, русская версия, PowerPoint Mobile и Word Mobile. Универсальные приложения интегрируются с приложениями Office с помощью контрактов выбора файлов Windows, свойств Expando и контрактов обновления кэшированных файлов. You can integrate your Windows universal app platform third-party apps with Excel Mobile, PowerPoint Mobile, and Word Mobile. Universal apps integrate with Office apps via Windows file picker contracts, expando properties, and Cached File Updater contracts.

Когда вы интегрируете универсальное приложение с Excel, PowerPoint или Word Mobile, пользователи могут открывать предоставленные вашим приложением документы Office либо непосредственно в Office, либо используя Windows в вашем приложении. Кроме того, пользователи могут сохранять файлы в вашем универсальном приложении, которое отправляет их обратно в вашу службу. When you integrate your universal app with Excel, PowerPoint, or Word Mobile, your users can open Office documents that your app provides, either when they browse from within Office or when they use Windows to open files from within your app. Users can also save the file back to your universal app, which uploads the file back to your service.

Открытые таким образом файлы оказываются в списке последних использованных документов в Office, поэтому пользователи могут легко найти и открыть их. Files opened this way appear in the Recent list in Office, so your users can easily find and reopen them.

Для интеграции ваше универсальное приложение должно: This integration requires that your universal app:

использовать контракты выбора файлов в Windows; Implements the Windows file picker contracts.

иметь возможность хранения файлов (например, приложение с доступом к облачному хранилищу). Represents a file store (for example, an app that allows access to cloud storage).

Свойства Expando Expando properties

Универсальные приложения Windows могут использовать свойства Expando для передачи дополнительной информации, связанной с файлами. Сведения об использовании этих свойств в Windows см. в разделе «System.ExpandoProperties» статьи StorageItemContentProperties.SavePropertiesAsync. Windows universal apps can use Expando properties to communicate additional information that is associated with files. For information about how this works in Windows, see «System.ExpandoProperties» in StorageItemContentProperties.SavePropertiesAsync.

В таблице ниже описаны свойства, которые ваше приложение должно предоставить приложениям Office для применения сценариев открытия файлов. Если эти данные не предоставляются, все файлы в вашем приложении открываются как доступные только для чтения. То, смогут ли пользователи редактировать файлы, зависит от типа их лицензии Office, а также от типа документа, который они пытаются открыть. The following table describes the properties that your app has to provide to Office to enable file open scenarios. If this information is not provided, all files from your app are opened as read only. Whether users can open files for editing depends on the type of Office license they have and the type of document they’re trying to open.

Задайте эти свойства в наборе свойств System.ExpandoProperties. Set these properties in the System.ExpandoProperties property set.

Свойство Property	Описание Description	Тип Type	Пример Example
AppDisplayName AppDisplayName	Имя поставщика, которое видно пользователю. Отображается в различных местах в Office, например в списке последних использованных документов. Provider name to display to the user. Appears in multiple places in Office, such as the recent document list.	String String	Contoso Contoso
MicrosoftOfficeOwnershipType MicrosoftOfficeOwnershipType	Для лицензирования укажите тип владения/расположение документа: личный (принадлежит отдельному пользователю) или рабочий (принадлежит компании). Допустимые значения: 1 (личный) и 2 (рабочий). Например, если файл пользователя находится в хранилище компании Contoso, используйте значение «2» (рабочий). For licensing, indicate whether the document/location is Personal/Consumer or Work/Business. Allowed values are 1 (personal) and 2 (business). For example, if your user’s file is stored in Contoso Business, use the value «2» for business.	Unit32 Unit32	1 или 2 1 or 2 Например, если файл пользователя находится в хранилище компании Contoso, для него устанавливается значение 2 (рабочий). For example, if your user’s file is stored in Contoso Business, this file should be marked 2 for business.
MicrosoftOfficeTermsOfUse MicrosoftOfficeTermsOfUse	Юридическая часть, в которой вы заявляете, что предоставляемая вами информация соответствует нашим условиям использования. Эта часть не видна пользователю. Это соглашение между вами, поставщиком приложения и корпорацией Майкрософт. Legal text to declare that the information you provide is accurate per our terms of use. This text is not displayed to the user. It is an agreement between you, the application provider, and Microsoft. Ниже приведен пример. See the following for an example.	String String	Я соглашаюсь с условиями, размещенными на странице https://go.microsoft.com/fwlink/p/?LinkId=528381 I agree to the terms located in https://go.microsoft.com/fwlink/p/?LinkId=528381

В приведенном ниже примере кода показано, как задать эти свойства. The following code example shows how to set these properties.

Контракты обновления кэшированных файлов Cached File Updater contracts

Если ваше приложение участвует в контрактах обновления кэшированных файлов, оно оповещается об изменениях, вносимых в файл другим универсальным приложением (например, Office). О том, как это работает в Windows, см. статью Класс CachedFileUpdater. If your universal app participates in Cached File Updater contracts, it will be notified of changes another universal app (such as Office) makes to the file. For information about how this works in Windows, see CachedFileUpdater class.

Office использует параметр AllowOnlyReaders для открытия файлов для чтения и записи, предоставляемых вашим универсальным приложением с помощью контрактов выбора файлов. Это означает, что при открытии файла в Office он не может быть перемещен, удален, переименован или изменен другим приложением, включая ваше собственное. Office выполняет автоматическое сохранение файла, но задает свойство CachedFileManager.DeferUpdates, чтобы предотвратить активацию вашего приложения до закрытия документа приложением Office или до приостановки Office операционной системой Windows (при переключении пользователя на другое приложение). Ваше приложение может вносить записи в файл только после его закрытия приложением Office. Office uses the AllowOnlyReaders option to open the read-write files your universal app provides via the file picker contracts. This means the file cannot be moved, deleted, renamed, or written to by another app, including your own, while it is open in Office. Office will autosave the file, but sets CachedFileManager.DeferUpdates to prevent activating your app until Office closes the document, or Office is suspended by Windows (when the user switches to another app). When Office closes the file, your app can write to it.

Ваше приложение должно управлять всеми операциями передачи данных в службе, включая скачивание, обновление или отправку файлов. Your app must handle all communication with your service, including download, refresh, and upload.

В таблицах ниже перечислены параметры, задаваемые для управления взаимодействием между вашим приложением и Office. The following tables lists the parameters to set to handle interactions between your app and Office.

Параметр Parameter	Описание Description
ReadActivationMode ReadActivationMode	Задайте параметр BeforeAccess, чтобы позволить приложению обновлять файл перед его отправкой в Office. Set BeforeAccess to allow your app to update the file before it sends it to Office.
WriteActivationMode WriteActivationMode	Задайте параметр ReadOnly, чтобы файл был доступен только для чтения. Задайте параметр AfterWrite, чтобы класс CacheFileUpdater всегда запускал ваше приложение после того, как приложение Office завершит работу с файлом. Set ReadOnly to make the file read only. Set AfterWrite to ensure that your app will be triggered by the CacheFileUpdater when Office is finished with the file. ПРИМЕЧАНИЕ. Если вы не зададите параметр AfterWrite, ваше приложение не будет передавать сведения об изменениях. Это значит, что изменения, вносимые пользователем, будут иметь только локальный характер. NOTE: If you do not set AfterWrite, your app will not be notified to upload the changes, which means that the user’s changes will only be local.
CachedFileOptions.RequireUpdateOnAccess CachedFileOptions.RequireUpdateOnAccess	Задайте это свойство, чтобы ваше приложение всегда обновляло файл после получения к нему доступа пользователем в списке последних использованных файлов. Set this property to ensure that your app can update the file when a user accesses it from the Recent list.

Вызов Office из вашего приложения Invoking Office from your app

When a user opens an Office document from your app, the document can open in Excel Mobile, PowerPoint Mobile, and Word Mobile. For example, when a user selects a *.docx file in your app, Word Mobile launches with the *.docx file opened. The Office app that opens is based on which app the user associated with the file type. When a user opens an Office document from your app, the document can open in Excel Mobile, PowerPoint Mobile, and Word Mobile. For example, when a user selects a *.docx file in your app, Word Mobile launches with the *.docx file opened. The Office app that opens is based on which app the user associated with the file type.

Для открытия файлов из вашего приложения в Office рекомендуется использовать метод LaunchFileAsync(). Мы не рекомендуем использовать метод LaunchUriAsync() для запуска файла, так как вместо приложения Office он будет запускать приложение, зарегистрированное для схемы URI (браузер). Хотя метод LaunchUriAsync() с параметром LauncherOptions.ContentType() может вызвать приложение Office, в этом случае открываемый файл помечается в Office как временный и доступный только для чтения. To open a file from your app in Office, we recommend that you use LaunchFileAsync() to launch the file. We don’t recommend that you use LaunchUriAsync() to launch the file because that will cause the application registered for the URI scheme to launch (the browser) instead of Office. Although LaunchUriAsync() with the LauncherOptions.ContentType() option can invoke Office, in this case the file opened is marked as temporary and is read-only in Office.

Дополнительные сведения см. в статье Класс Launcher. For more information, see Launcher class.

Временные файлы и файлы доступные только для чтения Temporary and read-only files

В своем приложении задайте атрибут FILE_ATTRIBUTE_TEMPORARY для временных файлов и атрибут FILE_ATTRIBUTE_READONLY для файлов, доступных только для чтения. Set the FILE_ATTRIBUTE_TEMPORARY attribute on temporary files and the FILE_ATTRIBUTE_READONLY attribute on read-only files in your app.

Файлы с заданным атрибутом FILE_ATTRIBUTE_TEMPORARY или FILE_ATTRIBUTE_READONLY открываются в Office как доступные только для чтения. Кроме того, при заданном атрибуте FILE_ATTRIBUTE_TEMPORARY файл не отображается в списке последних использованных документов. Files that have the FILE_ATTRIBUTE_TEMPORARY or FILE_ATTRIBUTE_READONLY attributes set open as read-only in Office. The FILE_ATTRIBUTE_TEMPORARY also prevents the file from appearing in the Recent list.

Дополнительные сведения об атрибутах см. в статье Функция SetFileAttributes. For more information about file attributes, see SetFileAttributes function.

Наши рекомендации Other best practices

Чтобы добиться оптимальной целостности файлов, например при конфликтующих изменениях или ошибках, используйте указанные ниже рекомендации. To optimize for file consistency, for example when conflicting edits or errors occur, apply the following best practices:

Предотвращение конфликтов сохранения Prevent save conflicts.

Приостановите отправку данных при возникновении конфликтов с сервером, чтобы избежать разветвления (оно допускается, только если в приложении Office больше нет открытых файлов, доступных для записи). Обычно если файл из вашего приложения открывается в Office, ваше приложение активируется только после закрытия Office или после его приостановки операционной системой Windows. Pause uploads when server conflicts occur to avoid forking (only fork when Office no longer has a write file open). Typically, if a file from your app is open in Office, your app is activated only when Office closes or is suspended by Windows.

Если для устранения конфликтов вам нужен пользовательский интерфейс, используйте всплывающие уведомления. If you need UI to handle conflicts, implement toast notifications. Полный пользовательский интерфейс не будет доступен, когда набор Office заблокирован. Full UI is not available when Office is suspended.

Устранение ошибок Handle errors.

• При снятии блокировки следует уведомить пользователей о возникшем конфликте и сообщить им о способах решения проблемы в своем приложении. When a lock is released, notify users of the conflict and provide a path to resolve it within your app.