Procedure di aggiornamento di Windows Universal Apps SDKWindows Universal Apps SDK Upgrade Procedures

Se nell'applicazione è già stata integrata una versione precedente dell'SDK, è necessario considerare i seguenti punti quando si aggiorna l'SDK.If you already have integrated an older version of Engagement into your application, you have to consider the following points when upgrading the SDK.

Se non sono state applicate alcune versioni dell'SDK, potrebbe essere necessario eseguire più procedure.You may have to follow several procedures if you missed several versions of the SDK. Se ad esempio si esegue la migrazione dalla versione 0.10.1 alla 0.11.0, sarà prima di tutto necessario eseguire la procedura per la migrazione "dalla 0.9.0 alla 0.10.1" e quindi la procedura per la migrazione "dalla 0.10.1 alla 0.11.0".For example if you migrate from 0.10.1 to 0.11.0 you have to first follow the "from 0.9.0 to 0.10.1" procedure then the "from 0.10.1 to 0.11.0" procedure.

Dalla versione 3.3.0 alla 3.4.0From 3.3.0 to 3.4.0

Log di testTest logs

I log della console generati da SDK possono essere abilitati/disattivati/filtrati.Console logs produced by the SDK can now be enabled/disabled/filtered. Per eseguire una personalizzazione, aggiornare la proprietà EngagementAgent.Instance.TestLogEnabled scegliendo uno dei valori disponibili nell'enumerazione EngagementTestLogLevel, ad esempio:To customize this, update the property EngagementAgent.Instance.TestLogEnabled to one of the value available from the EngagementTestLogLevel enumeration, for instance:

        EngagementAgent.Instance.TestLogLevel = EngagementTestLogLevel.Verbose;
        EngagementAgent.Instance.Init();

RisorseResources

La sovrimpressione Reach è stata migliorata.The Reach overlay has been improved. Fa parte delle risorse del pacchetto NuGet di SDK.It is part of the SDK NuGet package resources.

Durante l'aggiornamento alla nuova versione di SDK, è possibile scegliere se mantenere i file esistenti contenuti nella cartella della sovrimpressione delle risorse o meno:While upgrading to the new version of the SDK you can choose whether you want to keep your existing files from the overlay folder of your resources or not:

  • Se la sovrimpressione precedente è in funzione o si stanno integrando manualmente gli elementi WebView, è possibile decidere di mantenere i file esistenti per poter proseguire.If the previous overlay is working for you or you are integrating the WebView elements manually then you can decide to keep your exiting files, it will still work.
  • Se invece si vuole passare alla sovrimpressione nuova, è sufficiente sostituire l'intera cartella overlay delle risorse con quella nuova disponibile nel pacchetto SDK. Dopo aver completato l'aggiornamento, nelle app UWP è possibile ottenere la cartella della nuova sovrimpressione da %USERPROFILE%\.nuget\packages\MicrosoftAzure.MobileEngagement\3.4.0\content\win81\Resources).If you want to update to the new overlay, just replace the whole overlay folder from your resources with the new one from the SDK package (UWP apps: after the upgrade, you can get the new overlay folder from %USERPROFILE%\.nuget\packages\MicrosoftAzure.MobileEngagement\3.4.0\content\win81\Resources).

Avviso

Se si usa la sovrimpressione nuova, le personalizzazioni eseguite con la versione precedente saranno sovrascritte.Using the new overlay will overwrite any customizations made on the previous version.

Dalla versione 3.2.0 alla 3.3.0From 3.2.0 to 3.3.0

RisorseResources

Questo passaggio riguarda solo le risorse personalizzate.This step concerns customized resources only. Se sono state personalizzate le risorse fornite dall'SDK (html, immagini, sovrimpressioni) è necessario eseguirne il backup prima dell'aggiornamento e riapplicare la personalizzazione alle risorse aggiornate.If you have customized the resources provided by the SDK (html, images, overlay) then you have to backup them before upgrading and reapply your customization on upgraded resources.

Dalla versione 3.1.0 alla 3.2.0From 3.1.0 to 3.2.0

RisorseResources

Questo passaggio riguarda solo le risorse personalizzate.This step concerns customized resources only. Se sono state personalizzate le risorse fornite dall'SDK (html, immagini, sovrimpressioni) è necessario eseguirne il backup prima dell'aggiornamento e riapplicare la personalizzazione alle risorse aggiornate.If you have customized the resources provided by the SDK (html, images, overlay) then you have to backup them before upgrading and reapply your customization on upgraded resources.

l'integrazione di visualizzazione WebWebview integration

In questa versione sono stati introdotti alcuni miglioramenti per la corrispondenza dei fattori di forma del dispositivo diversi.Some improvements to match different device form factors were introduced in this version. Assicurarsi che l'integrazione delle webview corrisponda a quanto segue:Make sure that your integration of the webview match the following:

Nella pagina XAML ():In your XAML page ():

        <WebView x:Name="engagement_notification_content" Visibility="Collapsed" Height="80" HorizontalAlignment="Right" VerticalAlignment="Top"/>
        <WebView x:Name="engagement_announcement_content" Visibility="Collapsed" HorizontalAlignment="Right" VerticalAlignment="Top"/> 

E nel file con estensione cs associato:And in your associated .cs file:

using Microsoft.Azure.Engagement;
using System;
using Windows.ApplicationModel.Core;
using Windows.UI.ViewManagement;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Navigation;

namespace My.Namespace.Example
{
        /// <summary>
        /// An empty page that can be used on its own or navigated to within a Frame.
        /// </summary>
        public sealed partial class ExampleEngagementReachPage : EngagementPage
        {
          public ExampleEngagementReachPage()
          {
            this.InitializeComponent();

            /* Set your webview elements to the correct size. */
            SetWebView(width, height);
          }

          #region to implement
          /* Attach events when page is navigated. */
          protected override void OnNavigatedTo(NavigationEventArgs e)
          {
            /* Update the webview when the app window is resized. */
            Window.Current.SizeChanged += DisplayProperties_OrientationChanged;

            /* Update the webview when the app/status bar is resized. */
#if WINDOWS_PHONE_APP || WINDOWS_UWP
            ApplicationView.GetForCurrentView().VisibleBoundsChanged += DisplayProperties_VisibleBoundsChanged; 
#endif
            base.OnNavigatedTo(e);
          }

          /* When page is left ensure to detach SizeChanged handler. */
          protected override void OnNavigatedFrom(NavigationEventArgs e)
          {
            Window.Current.SizeChanged -= DisplayProperties_OrientationChanged;
#if WINDOWS_PHONE_APP || WINDOWS_UWP
            ApplicationView.GetForCurrentView().VisibleBoundsChanged -= DisplayProperties_VisibleBoundsChanged;
#endif
            base.OnNavigatedFrom(e);
          }

          /* "width" and "height" are the current size of your application display. */
#if WINDOWS_PHONE_APP || WINDOWS_UWP
          double width = ApplicationView.GetForCurrentView().VisibleBounds.Width;
          double height = ApplicationView.GetForCurrentView().VisibleBounds.Height;
#else
          double width =  Window.Current.Bounds.Width;
          double height =  Window.Current.Bounds.Height;
#endif

          /// <summary>
          /// Set your webview elements to the correct size.
          /// </summary>
          /// <param name="width">The width of your current display.</param>
          /// <param name="height">The height of your current display.</param>
          private void SetWebView(double width, double height)
          {
            #pragma warning disable 4014
            CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal,
                    () =>
                    {
                      this.engagement_notification_content.Width = width;
                      this.engagement_announcement_content.Width = width;
                      this.engagement_announcement_content.Height = height;
                    });
          }

          /// <summary>
          /// Handler that takes the Windows.Current.SizeChanged and indicates that webviews have to be resized.
          /// </summary>
          /// <param name="sender">Original event trigger.</param>
          /// <param name="e">Window Size Changed Event arguments.</param>
          private void DisplayProperties_OrientationChanged(object sender, Windows.UI.Core.WindowSizeChangedEventArgs e)
          {
            double width = e.Size.Width;
            double height = e.Size.Height;

            /* Set your webview elements to the correct size. */
            SetWebView(width, height);
          }

#if WINDOWS_PHONE_APP || WINDOWS_UWP              
          /// <summary>
          /// Handler that takes the ApplicationView.VisibleBoundsChanged and indicates that webviews have to be resized
          /// </summary>
          /// <param name="sender">The related application view.</param>
          /// <param name="e">Related event arguments.</param>
          private void DisplayProperties_VisibleBoundsChanged(ApplicationView sender, Object e)
          {
            double width = sender.VisibleBounds.Width;
            double height = sender.VisibleBounds.Height;

            /* Set your webview elements to the correct size. */
            SetWebView(width, height);
          }
#endif
          #endregion
        }
}

Dalla versione 2.0.0 alla 3.0.0From 2.0.0 to 3.0.0

RisorseResources

Questo passaggio riguarda solo le risorse personalizzate.This step concerns customized resources only. Se sono state personalizzate le risorse fornite dall'SDK (html, immagini, sovrimpressioni) è necessario eseguirne il backup prima dell'aggiornamento e riapplicare la personalizzazione alle risorse aggiornate.If you have customized the resources provided by the SDK (html, images, overlay) then you have to backup them before upgrading and reapply your customization on upgraded resources.

Dalla versione 1.1.1 alla 2.0.0From 1.1.1 to 2.0.0

La sezione seguente illustra come eseguire la migrazione di un'integrazione dell'SDK dal servizio Capptain offerto da Capptain SAS a un'app basata su Azure Mobile Engagement.The following describes how to migrate an SDK integration from the Capptain service offered by Capptain SAS into an app powered by Azure Mobile Engagement.

Importante

Capptain e Mobile Engagement sono servizi diversi e la procedura seguente illustra solo come eseguire la migrazione dell'app client.Capptain and Mobile Engagement are not the same services and the procedure given below only highlights how to migrate the client app. La migrazione dell'SDK nell'app NON comporta la migrazione dei dati dai server di Capptain ai server di Mobile EngagementMigrating the SDK in the app will NOT migrate your data from the Capptain servers to the Mobile Engagement servers

Se si esegue la migrazione da una versione precedente, consultare il sito web Capptain per eseguire prima la migrazione a 1.1.1, quindi applicare la procedura seguenteIf you are migrating from an earlier version, please consult the Capptain web site to migrate to 1.1.1 first then apply the following procedure

Pacchetto NuGetNuget package

Sostituire Capptain.WindowsPhone con il pacchetto NuGet MicrosoftAzure.MobileEngagement.Replace Capptain.WindowsPhone by MicrosoftAzure.MobileEngagement Nuget package.

Applicazione di Mobile EngagementApplying Mobile Engagement

L'SDK usa il termine Engagement.The SDK uses the term Engagement. È necessario aggiornare il progetto per tenere conto di questa modifica.You need to update your project to match this change.

È necessario disinstallare il pacchetto nuget corrente di Capptain.You need to uninstall your current Capptain nuget package. Si consideri che verranno rimosse tutte le modifiche nella cartella Risorse di Capptain.Consider that all your changes in Capptain Resources folder will be removed. Se si desidera mantenere tali file, eseguirne una copia.If you want to keep those files then make a copy of them.

Successivamente, installare il nuovo pacchetto NuGet di Microsoft Azure Engagement nel progetto.After that, install the new Microsoft Azure Engagement nuget package on your project. È possibile trovarlo direttamente su [sito Web di NuGet]You can find it directly on [nuget website]. o nell'indice qui.or here index. Questa operazione sostituisce tutti i file di risorse utilizzati da Engagement e aggiunge la nuova DLL di Engagement ai riferimenti del progetto.This action replaces all resources files used by Engagement and adds the new Engagement DLL to your project References.

È necessario eliminare i riferimenti del progetto rimuovendo i riferimenti DLL di Capptain.You have to clean your project references by deleting Capptain DLL references. Se non si effettua questa operazione, la versione di Capptain creerà un conflitto e si verificheranno errori.If you do not make this, the version of Capptain will conflict and errors will happen.

Se sono state personalizzate risorse Capptain, copiare il contenuto dei file precedenti e incollarlo in nuovi file di progetto.If you have customized Capptain resources, copy your old files content and paste them in the new Engagement files. Si noti che è necessario aggiornare sia i file xaml che i file cs.Please note that both xaml and cs files have to be updated.

Al termine di queste operazioni, è necessario sostituire i riferimenti di Capptain precedenti con i nuovi riferimenti di Engagement.When those steps are completed you only have to replace old Capptain references by the new Engagement references.

  1. Tutti gli spazi dei nomi Capptain devono essere aggiornati.All Capptain namespaces have to be updated.

    Prima della migrazione:Before migration:

     using Capptain.Agent;
     using Capptain.Reach;
    

    Dopo la migrazione:After migration:

     using Microsoft.Azure.Engagement;
    
  2. Tutte le classi Capptain che contengono "Capptain" devono contenere "Engagement".All Capptain classes that contain "Capptain" should contain "Engagement".

    Prima della migrazione:Before migration:

     public sealed partial class MainPage : CapptainPage
     {
       protected override string GetCapptainPageName()
       {
         return "Capptain Demo";
       }
       ...
     }
    

    Dopo la migrazione:After migration:

     public sealed partial class MainPage : EngagementPage
     {
       protected override string GetEngagementPageName()
       {
         return "Engagement Demo";
       }
       ...
     }
    
  3. Per i file xaml cambiano anche attributi e spazio dei nomi di Capptain.For xaml files Capptain namespace and attributes also change.

    Prima della migrazione:Before migration:

     <capptain:CapptainPage
     ...
     xmlns:capptain="clr-namespace:Capptain.Agent;assembly=Capptain.Agent.WP"
     ...
     </capptain:CapptainPage>
    

    Dopo la migrazione:After migration:

     <engagement:EngagementPage
     ...
     xmlns:engagement="clr-namespace:Microsoft.Azure.Engagement;assembly=Microsoft.Azure.Engagement.EngagementAgent.WP"
     ...
     </engagement:EngagementPage>
    
  4. Modifiche alle pagine di sovrimpressioneOverlay page changes

    Importante

    Anche la sovrimpressione cambia.Overlay also changes. Il nuovo spazio dei nomi è Microsoft.Azure.Engagement.Overlay.Its new namespace is Microsoft.Azure.Engagement.Overlay. Deve essere usato sia nei file xaml sia nei file cs.It has to be used in both xaml and cs files. Inoltre, CapptainGrid deve essere denominato EngagementGrid e capptain_notification_content e capptain_announcement_content sono denominati engagement_notification_content e engagement_announcement_content.Moreover CapptainGrid is to be named EngagementGrid, capptain_notification_content and capptain_announcement_content are named engagement_notification_content and engagement_announcement_content.

    Per la sovrimpressione:For overlay :

     <capptain:CapptainPageOverlay
       xmlns:capptain="using:Capptain.Overlay"
       ...
     </capptain:CapptainPageOverlay>
    

    Diventa:It becomes :

     <EngagementPageOverlay
       engagement="using:Microsoft.Azure.Engagement.Overlay"
       ...
     </engagement:EngagementPageOverlay>
    
  5. Per altre risorse come le immagini di Capptain e i file HTML, tenere presente che sono state rinominate per l'utilizzo di "Engagement".For the other resources like Capptain pictures and HTML files, please note that they also have been renamed to use "Engagement".

Dichiarazione di progettoProject declaration

In Package.appxmanifest File Type Associations è stato aggiornato da:On Package.appxmanifest File Type Associations has been updated from :

  • capptain_reach_content in engagement_reach_contentcapptain_reach_content to engagement_reach_content
  • capptain_log_file in engagement_log_filecapptain_log_file to engagement_log_file

ID applicazione / chiave SDKApplication ID / SDK Key

Engagement utilizza una stringa di connessione.Engagement uses a connection string. Non è necessario specificare un ID applicazione e una chiave SDK con Mobile Engagement, è sufficiente specificare una stringa di connessione.You don't have to specify an application ID and an SDK key with Mobile Engagement, you only have to specify a connection string. È possibile configurarla nel file EngagementConfiguration.You can set it up on your EngagementConfiguration file.

La configurazione di Engagement può essere impostata nel file Resources\EngagementConfiguration.xml del progetto.The Engagement configuration can be set in your Resources\EngagementConfiguration.xml file of your project.

Modificare questo file per specificare:Edit this file to specify:

  • La stringa di connessione dell'applicazione tra i tag <connectionString> and <\connectionString>.Your application connection string between tags <connectionString> and <\connectionString>.

Se si desidera specificarla in fase di esecuzione, è possibile chiamare il metodo seguente prima dell'inizializzazione dell'agente di Engagement:If you want to specify it at runtime instead, you can call the following method before the Engagement agent initialization:

/* Engagement configuration. */
EngagementConfiguration engagementConfiguration = new EngagementConfiguration();
engagementConfiguration.Agent.ConnectionString = "Endpoint={appCollection}.{domain};AppId={appId};SdkKey={sdkKey}";

/* Initialize Engagement agent with above configuration. */
EngagementAgent.Instance.Init(args, engagementConfiguration);

La stringa di connessione per l'applicazione viene visualizzata nel portale di Azure classico.The connection string for your application is displayed on the Azure Classic Portal.

Modifica del nome di elementiItems name change

Tutti gli elementi denominati capptain sono stati rinominati in engagement.All items named capptain have been named engagement. Lo stesso vale per Capptain, che è stato ridenominato in Engagement.Similarly for Capptain to Engagement.

Esempi di elementi di Capptain di uso comune:Examples of commonly used Capptain items :

  • CapptainConfiguration è diventato EngagementConfigurationCapptainConfiguration now named EngagementConfiguration
  • CapptainAgent è diventato EngagementAgentCapptainAgent now named EngagementAgent
  • CapptainReach è diventato EngagementReachCapptainReach now named EngagementReach
  • CapptainHttpConfig è diventato EngagementHttpConfigCapptainHttpConfig now named EngagementHttpConfig
  • GetCapptainPageName è diventato GetEngagementPageNameGetCapptainPageName now named GetEngagementPageName

Si noti la ridenominazione influisce anche sui metodi sottoposti a override.Note that rename also affects overridden methods.