Criar aplicativos hospedadosCreate hosted apps

A partir do Windows 10, versão 2004, você pode criar aplicativos hospedados.Starting in Windows 10, version 2004, you can create hosted apps. Um aplicativo hospedado compartilha o mesmo executável e definição como um aplicativo host pai, mas parece e se comporta como um aplicativo separado no sistema.A hosted app shares the same executable and definition as a parent host app, but it looks and behaves like a separate app on the system.

Aplicativos hospedados são úteis para cenários em que você deseja que um componente (como um arquivo executável ou um arquivo de script) se comporte como um aplicativo autônomo do Windows 10, mas o componente requer um processo de host para ser executado.Hosted apps are useful for scenarios where you want a component (such as an executable file or a script file) to behave like a standalone Windows 10 app, but the component requires a host process in order to execute. Por exemplo, um script do PowerShell ou Python poderia ser entregue como um aplicativo hospedado que exige a instalação de um host para ser executado.For example, a PowerShell or Python script could be delivered as a hosted app that requires a host to be installed in order to run. Um aplicativo hospedado pode ter seu próprio bloco inicial, identidade e profunda integração com os recursos do Windows 10, como tarefas em segundo plano, notificações, blocos e destinos de compartilhamento.A hosted app can have its own start tile, identity, and deep integration with Windows 10 features such as background tasks, notifications, tiles, and share targets.

O recurso aplicativos hospedados tem suporte de vários elementos e atributos no manifesto do pacote que permitem que um aplicativo hospedado use um executável e uma definição em um pacote de aplicativo host.The hosted apps feature is supported by several elements and attributes in the package manifest that enable a hosted app to use an executable and definition in a host app package. Quando um usuário executa o aplicativo hospedado, o sistema operacional inicia automaticamente o host executável sob a identidade do aplicativo hospedado.When a user runs the hosted app, the OS automatically launches the host executable under the identity of the hosted app. O host pode, então, carregar ativos visuais, conteúdo ou chamar APIs como o aplicativo hospedado.The host can then load visual assets, content, or call APIs as the hosted app. O aplicativo hospedado Obtém a interseção de recursos declarados entre o host e o aplicativo hospedado.The hosted app gets the intersection of capabilities declared between the host and hosted app. Isso significa que um aplicativo hospedado não pode solicitar mais recursos do que o fornecido pelo host.This means that a hosted app cannot ask for more capabilities than what the host provides.

Definir um hostDefine a host

O host é o executável principal ou o processo de tempo de execução para o aplicativo hospedado.The host is the main executable or runtime process for the hosted app. Atualmente, os únicos hosts com suporte são aplicativos da área de trabalho (.NET ou C++/Win32) que têm a identidade do pacote.Currently, the only supported hosts are desktop apps (.NET or C++/Win32) that have package identity. Não há suporte para aplicativos UWP como hosts no momento.UWP apps are not supported as hosts at this time. Há várias maneiras para um aplicativo de área de trabalho ter a identidade do pacote:There are several ways for a desktop app to have package identity:

  • A maneira mais comum de conceder identidade de pacote a um aplicativo de desktop é empacotá-lo em um pacote MSIX.The most common way to grant package identity to a desktop app is by packaging it in an MSIX package.
  • Em alguns casos, você também pode optar por conceder a identidade do pacote criando um pacote esparso.In some cases, you may alternatively choose to grant package identity by creating a sparse package. Essa opção será útil se você não puder adotar o empacotamento MSIX para implantar seu aplicativo de área de trabalho.This option is useful if you are unable to adopt MSIX packaging for deploying your desktop app.

O host é declarado em seu manifesto de pacote pela extensão uap10: HostRuntime .The host is declared in its package manifest by the uap10:HostRuntime extension. Essa extensão tem um atributo de ID que deve ser atribuído a um valor que também é referenciado pelo manifesto do pacote para o aplicativo hospedado.This extension has an Id attribute that must be assigned a value that is also referenced by the package manifest for the hosted app. Quando o aplicativo hospedado é ativado, o host é iniciado sob a identidade do aplicativo hospedado e pode carregar conteúdo ou binários do pacote do aplicativo hospedado.When the hosted app is activated, the host is launched under the identity of the hosted app and can load content or binaries from the hosted app package.

O exemplo a seguir demonstra como definir um host em um manifesto de pacote.The following example demonstrates how to define a host in a package manifest. A extensão uap10: HostRuntime é de todo o pacote e, portanto, é declarada como um filho do elemento Package .The uap10:HostRuntime extension is package-wide and is therefore declared as a child of the Package element.

<Package xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10">

  <Extensions>
    <uap10:Extension Category="windows.hostRuntime"  
        Executable="PyScriptEngine\PyScriptEngine.exe"  
        uap10:RuntimeBehavior="packagedClassicApp"  
        uap10:TrustLevel="mediumIL">
      <uap10:HostRuntime Id="PythonHost" />
    </uap10:Extension>
  </Extensions>

</Package>

Anote esses detalhes importantes sobre os elementos a seguir.Make note of these important details about the following elements.

ElementoElement DetalhesDetails
uap10:Extensionuap10:Extension A windows.hostRuntime categoria declara uma extensão em todo o pacote que define as informações de tempo de execução a serem usadas ao ativar um aplicativo hospedado.The windows.hostRuntime category declares a package-wide extension that defines the runtime information to be used when activating a hosted app. Um aplicativo hospedado será executado com as definições declaradas na extensão.A hosted app will run with the definitions declared in the extension. Ao usar o aplicativo host declarado no exemplo anterior, um aplicativo hospedado será executado como o executável PyScriptEngine.exe no nível de confiança mediumIL .When using the host app declared in the previous example, a hosted app will run as the executable PyScriptEngine.exe at the mediumIL trust level.

Os atributos executável, uap10: RuntimeBehaviore uap10: TrustLevel especificam o nome do binário do processo de host no pacote e como os aplicativos hospedados serão executados.The Executable, uap10:RuntimeBehavior, and uap10:TrustLevel attributes specify the name of the host process binary in the package and how the hosted apps will run. Por exemplo, um aplicativo hospedado usando os atributos no exemplo anterior será executado como o executável PyScriptEngine.exe no nível de confiança mediumIL.For example, a hosted app using the attributes in the previous example will run as the executable PyScriptEngine.exe at mediumIL trust level.
uap10:HostRuntimeuap10:HostRuntime O atributo ID declara o identificador exclusivo desse aplicativo host específico no pacote.The Id attribute declares the unique identifier of this specific host app in the package. Um pacote pode ter vários aplicativos de host, e cada um deve ter um elemento uap10: HostRuntime com uma IDexclusiva.A package can have multiple host apps, and each must have a uap10:HostRuntime element with a unique Id.

Declarar um aplicativo hospedadoDeclare a hosted app

Um aplicativo hospedado declara uma dependência de pacote em um host.A hosted app declares a package dependency on a host. O aplicativo hospedado utiliza a ID do host (ou seja, o atributo ID da extensão uap10: HostRuntime no pacote do host) para ativação em vez de especificar um ponto de entrada executável em seu próprio pacote.The hosted app leverages the host's ID (that is, the Id attribute of the uap10:HostRuntime extension in the host package) for activation instead of specifying an entry point executable in its own package. O aplicativo hospedado normalmente contém conteúdo, ativos visuais, scripts ou binários que podem ser acessados pelo host.The hosted app typically contains content, visual assets, scripts, or binaries that may be accessed by the host. O valor de TargetDeviceFamily no pacote do aplicativo hospedado deve ter como destino o mesmo valor que o host.The TargetDeviceFamily value in the hosted app package should target the same value as the host.

Pacotes de aplicativos hospedados podem ser assinados ou não assinados:Hosted app packages can be signed or unsigned:

  • Os pacotes assinados podem conter arquivos executáveis.Signed packages may contain executable files. Isso é útil em cenários que têm um mecanismo de extensão binária, que permite que o host carregue uma DLL ou um componente registrado no pacote do aplicativo hospedado.This is useful in scenarios that have a binary extension mechanism, which enables the host to load a DLL or registered component in the hosted app package.
  • Pacotes não assinados só podem conter arquivos não executáveis.Unsigned packages can only contain non-executable files. Isso é útil em cenários em que o host só precisa carregar imagens, ativos e conteúdo ou arquivos de script.This is useful in scenarios where the host only needs to load images, assets and content or script files. Os pacotes não assinados devem incluir um OID valor especial em seu elemento de identidade ou não poderão ser registrados.Unsigned packages must include a special OID value in their Identity element or they won’t be allowed to register. Isso impede que os pacotes não assinados entrem em conflito ou falsifiquem a identidade de um pacote assinado.This prevents unsigned packages from conflicting with or spoofing the identity of a signed package.

Para definir um aplicativo hospedado, declare os seguintes itens no manifesto do pacote:To define a hosted app, declare the following items in the package manifest:

O exemplo a seguir demonstra as seções relevantes de um manifesto de pacote para um aplicativo hospedado não assinado.The following example demonstrates the relevant sections of a package manifest for an unsigned hosted app.

<Package xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10">

  <Identity Name="NumberGuesserManifest"
    Publisher="CN=AppModelSamples, OID.2.25.311729368913984317654407730594956997722=1"
    Version="1.0.0.0" />

  <Dependencies>
    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.19041.0" MaxVersionTested="10.0.19041.0" />
    <uap10:HostRuntimeDependency Name="PyScriptEnginePackage" Publisher="CN=AppModelSamples" MinVersion="1.0.0.0"/>
  </Dependencies>

  <Applications>
    <Application Id="NumberGuesserApp"  
      uap10:HostId="PythonHost"  
      uap10:Parameters="-Script &quot;NumberGuesser.py&quot;">
    </Application>
  </Applications>

</Package>

Anote esses detalhes importantes sobre os elementos a seguir.Make note of these important details about the following elements.

ElementoElement DetalhesDetails
IdentidadeIdentity Como o pacote do aplicativo hospedado neste exemplo não está assinado, o atributo do Publicador deve incluir a OID.2.25.311729368913984317654407730594956997722=1 cadeia de caracteres.Because the hosted app package in this example is unsigned, the Publisher attribute must include the OID.2.25.311729368913984317654407730594956997722=1 string. Isso garante que o pacote não assinado não possa falsificar a identidade de um pacote assinado.This ensures that the unsigned package cannot spoof the identity of a signed package.
TargetDeviceFamilyTargetDeviceFamily O atributo MinVersion deve especificar 10.0.19041.0 ou uma versão do sistema operacional posterior.The MinVersion attribute must specify 10.0.19041.0 or a later OS version.
uap10:HostRuntimeDependencyuap10:HostRuntimeDependency Esse elemento de elemento declara uma dependência no pacote do aplicativo host.This element element declares a dependency on the host app package. Isso consiste no nome e no Editor do pacote do host, e a MinVersion depende.This consists of the Name and Publisher of the host package, and the MinVersion it depends on. Esses valores podem ser encontrados no elemento Identity no pacote do host.These values can be found under the Identity element in the host package.
AplicativoApplication O atributo uap10: hostid expressa a dependência no host.The uap10:HostId attribute expresses the dependency on the host. O pacote do aplicativo hospedado deve declarar esse atributo em vez dos atributos de ponto de entrada e executáveis usuais para um elemento Application ou Extension .The hosted app package must declare this attribute instead of the usual Executable and EntryPoint attributes for an Application or Extension element. Como resultado, o aplicativo hospedado herda os atributos Executable, EntryPoint e Runtime do host com o valor de hostid correspondente.As a result, the hosted app inherits the Executable, EntryPoint and runtime attributes from the host with the corresponding HostId value.

O atributo uap10: Parameters especifica parâmetros que são passados para a função de ponto de entrada do executável do host.The uap10:Parameters attribute specifies parameters that are passed to the entry point function of the host executable. Como o host precisa saber o que fazer com esses parâmetros, há um contrato implícito entre o host e o aplicativo hospedado.Because the host needs to know what to do with these parameters, there is an implied contract between the host and hosted app.

Registrar um pacote de aplicativo hospedado não assinado em tempo de execuçãoRegister an unsigned hosted app package at run time

Um benefício da extensão uap10: HostRuntime é que ele permite que um host gere dinamicamente um pacote de aplicativo hospedado em tempo de execução e registre-o usando a API do PackageManager , sem a necessidade de conectá-lo.One benefit of the uap10:HostRuntime extension is that it enables a host to dynamically generate a hosted app package at runtime and register it by using the PackageManager API, without needing to sign it. Isso permite que um host gere dinamicamente o conteúdo e o manifesto para o pacote do aplicativo hospedado e, em seguida, registre-o.This enables a host to dynamically generate the content and manifest for the hosted app package and then register it.

Use os métodos a seguir da classe PackageManager para registrar um pacote de aplicativo hospedado não assinado.Use the following methods of the PackageManager class to register an unsigned hosted app package. Esses métodos estão disponíveis a partir do Windows 10, versão 2004.These methods are available starting in Windows 10, version 2004.

  • AddPackageByUriAsync: registra um pacote MSIX não assinado usando a propriedade AllowUnsigned do parâmetro Options .AddPackageByUriAsync: Registers an unsigned MSIX package by using the AllowUnsigned property of the options parameter.
  • RegisterPackageByUriAsync: executa um registro de arquivo de manifesto de pacote flexível.RegisterPackageByUriAsync: Performs a loose package manifest file registration. Se o pacote for assinado, a pasta que contém o manifesto deverá incluir um arquivo. P7X e um catálogo.If the package is signed, the folder containing the manifest must include a .p7x file and catalog. Se não for assinado, a propriedade AllowUnsigned do parâmetro Options deverá ser definida.If unsigned, the AllowUnsigned property of the options parameter must be set.

Requisitos para aplicativos hospedados não assinadosRequirements for unsigned hosted apps

  • Os elementos Application ou Extension no manifesto do pacote não podem conter dados de ativação, como os atributos Executable, EntryPointou TrustLevel .The Application or Extension elements in the package manifest cannot contain activation data such as the Executable, EntryPoint, or TrustLevel attributes. Em vez disso, esses elementos podem conter apenas um atributo uap10: hostid que expressa a dependência no host e um atributo Uap10: Parameters .Instead, these elements can only contain a uap10:HostId attribute that expresses the dependency on the host and a uap10:Parameters attribute.
  • O pacote deve ser um pacote principal.The package must be a main package. Ele não pode ser um pacote, um pacote de estrutura, um recurso ou um pacotes opcionais.It cannot be a bundle, framework package, resource, or optional package.

Requisitos para um host que instala e registra um pacote de aplicativo hospedado não assinadoRequirements for a host that installs and registers an unsigned hosted app package

AmostraSample

Para um aplicativo de exemplo totalmente funcional que se declara como um host e, em seguida, registra dinamicamente um pacote de aplicativo hospedado em tempo de execução, consulte o exemplo de aplicativo hospedado.For a fully functional sample app that declares itself as a host and then dynamically registers a hosted app package at runtime, see the hosted app sample.

O hostThe host

O host é denominado PyScriptEngine.The host is named PyScriptEngine. Este é um wrapper escrito em C# que executa scripts Python.This is a wrapper written in C# that runs python scripts. Quando executado com o -Register parâmetro, o mecanismo de script instala um aplicativo hospedado que contém um script Python.When run with the -Register parameter, the script engine installs a hosted app containing a python script. Quando um usuário tenta iniciar o aplicativo hospedado recentemente instalado, o host é iniciado e executa o script Python NumberGuesser .When a user tries to launch the newly installed hosted app, the host is launched and executes the NumberGuesser python script.

O manifesto do pacote para o aplicativo host (o arquivo Package. appxmanifest na pasta PyScriptEnginePackage) contém uma extensão uap10: HostRuntime que declara o aplicativo como um host com a ID PythonHost e o executável PyScriptEngine.exe.The package manifest for the host app (the Package.appxmanifest file in the PyScriptEnginePackage folder) contains a uap10:HostRuntime extension that declares the app as a host with the ID PythonHost and the executable PyScriptEngine.exe.

Observação

Neste exemplo, o manifesto do pacote é chamado Package. appxmanifest e faz parte de um projeto de empacotamento de aplicativos do Windows.In this sample, the package manifest is named Package.appxmanifest and it is part of a Windows Application Packaging Project. Quando esse projeto é compilado, ele gera um manifesto chamado AppxManifest.xml e cria o pacote MSIX para o aplicativo host.When this project is built, it generates a manifest named AppxManifest.xml and builds the MSIX package for the host app.

O aplicativo hospedadoThe hosted app

O aplicativo hospedado consiste em um script Python e em artefatos de pacote, como o manifesto do pacote.The hosted app consists of a python script and package artifacts such as the package manifest. Ele não contém nenhum arquivo PE.It doesn’t contain any PE files.

O manifesto do pacote para o aplicativo hospedado (o arquivo NumberGuesser/AppxManifest.xml) contém os seguintes itens:The package manifest for the hosted app (the NumberGuesser/AppxManifest.xml file) contains the following items:

  • O atributo Publisher do elemento Identity contém o OID.2.25.311729368913984317654407730594956997722=1 identificador, que é necessário para um pacote não assinado.The Publisher attribute of the Identity element contains the OID.2.25.311729368913984317654407730594956997722=1 identifer, which is required for an unsigned package.
  • O atributo uap10: hostid do elemento Application identifica PythonHost como seu host.The uap10:HostId attribute of the Application element identifies PythonHost as its host.

Execute o exemploRun the sample

O exemplo requer a versão 10.0.19041.0 ou posterior do Windows 10 e o SDK do Windows.The sample requires version 10.0.19041.0 or later of Windows 10 and the Windows SDK.

  1. Baixe o exemplo em uma pasta em seu computador de desenvolvimento.Download the sample to a folder on your development computer.

  2. Abra a solução PyScriptEngine. sln no Visual Studio e defina o projeto PyScriptEnginePackage como o projeto de inicialização.Open the PyScriptEngine.sln solution in Visual Studio and set the PyScriptEnginePackage project as the startup project.

  3. Compile o projeto PyScriptEnginePackage .Build the PyScriptEnginePackage project.

  4. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto PyScriptEnginePackage e escolha implantar.In Solution Explorer, right-click the PyScriptEnginePackage project and choose Deploy.

  5. Abra uma janela de prompt de comando no diretório em que você copiou os arquivos de exemplo e execute o comando a seguir para registrar o aplicativo NumberGuesser de exemplo (o aplicativo hospedado).Open a Command Prompt window to the directory where you copied the sample files and run the following command to register the sample NumberGuesser app (the hosted app). Altere D:\repos\HostedApps para o caminho em que você copiou os arquivos de exemplo.Change D:\repos\HostedApps to the path where you copied the sample files.

    D:\repos\HostedApps>pyscriptengine -Register D:\repos\HostedApps\NumberGuesser\AppxManifest.xml
    

    Observação

    Você pode executar pyscriptengine na linha de comando porque o host no exemplo declara um AppExecutionAlias.You can run pyscriptengine on the command line because the host in the sample declares an AppExecutionAlias.

  6. Abra o menu Iniciar e clique em NumberGuesser para executar o aplicativo hospedado.Open the Start menu and click NumberGuesser to run the hosted app.