2017年9月20日,星期三

使用Azure App Insights跟踪应用程序/ Web部件/配置代码中的事件

在我最近的帖子中 Add Azure App Insights or Google 分析工具 to your SharePoint pages with an SPFx Application Customizer 我们专注于 页面跟踪/分析 App Insights的功能。但是我真正认为很棒的是能够跟踪代码正在发生的事情– whether it’仅表示您的Web部件已执行或您的应用已启动(因此您可以获得计数),或者您向用户显示了错误消息(包含详细信息),或者可能是为了了解用户在您的应用中导航的位置或他们选择了哪些选项。例如,我们在一个特定的应用程序中有一个选项卡式界面,’d非常希望知道实际上有多少用户导航到第二和第三选项卡(我敢打赌)。好吧,App Insights事件跟踪非常适合这些情况以及更多情况。我用此列表完成了最后一篇文章:

  • 服务器端应用程序(Office 365 / SharePoint加载项)
    • 有多少次应用启动?由谁/在哪里?
    • 应用内发生了什么(例如,正在单击哪些按钮/正在使用哪些功能)?
  • SPFx /图
    • 我们的Web部件每天获得多少次执行?
    • 我的Web部件在客户端执行需要多长时间?
    • 我的异步调用需要多长时间(例如,到图表)?它们对世界各地的用户有何不同?
  • 供应代码
    • 我们每天/每周/每月创建几个站点?
    • 我们在配置期间遇到了多少次问题?
    • 置备需要多长时间?
  • 一般
    • 我们向用户显示错误消息多少次?

你明白了。

快速入门概述(适用于JavaScript / SPFx)

请记住,要使用App Insights,您需要Azure订阅和要创建的App Insights资源–这将为您提供从Azure门户获取的检测密钥(请参阅 我最后的帖子 更多细节)。如果你’正在使用JavaScript / TypeScript / SPFx’可以安装的npm软件包:

npm i applicationinsights-js --save

从那里,您将需要几行帮助您入门。模块顶部的import语句:

import {AppInsights} from "applicationinsights-js";

..然后是引用您的App Insights密钥的初始引导程序代码:

let appInsightsKey: string = "[YOUR KEY FROM THE AZURE PORTAL HERE]";

AppInsights.downloadAndSetup({ instrumentationKey: appInsightsKey });

现在,您可以将代码中发生的各种情况记录到App Insights中。本质上,当我们想记录发生了什么事情时,我们在一行中插入一行-让我们看一些示例。

例子1–记录对Microsoft Graph的调用(使用SPFx代码)

下面的代码以SPFx代码获取当前用户的日历事件,该代码取自 SPFx React样本之一。这是Microsoft Graph的相当典型的用法,此处使用的日志记录方法可用于许多类似的情况。它在React组件中的事实并不重要,但是要重点关注的是对App Insights的调用-请注意,’我还在做的是记录拨打电话所花费的时间,以及发现我的Web部件被使用了很多次之后,我还开始了解到Graph的通话对世界各地的用户花费了多长时间。为此,我只需在调用之前创建一个时间戳,然后再创建一个 在承诺中,一旦获取数据即执行和subtract the difference:

然后,在App Insights中,我可以看到Web部件每次执行的事件以及调用图形所花费的时间:

SNAGHTML1f5d5c2c

SNAGHTML203e67e

正如我在上一篇App Insights帖子中所显示的那样,当您积累数据时,可以使用‘Analytics’App Insights中的“部分”以根据需要进行过滤和排序(例如,在“ timeTaken’ value):

SNAGHTML1f6b05fa

例子2–在站点设置/模板代码中记录呼叫

以便’s是登录SPFx的示例。作为不同的口味,让’说您正在基于模板创建一些SharePoint网站–也许作为自助式网站创建工具的一部分。您可能对以下内容感兴趣:

  • 正在创建多少个站点?有什么细节?  
  • Office 365需要多长时间创建基本网站集?
  • 您的模板要花多长时间?

在这种情况下,您’我可能会在C#代码中使用PnP Core库– so you’将需要来自以下位置的App Insights nuget包: //www.nuget.org/packages/Microsoft.ApplicationInsights/

要开始使用C#代码,您需要’需要一些引导代码:

// 在  top of class..
using Microsoft.ApplicationInsights;

// to initialize..
TelemetryClient telemetry = new TelemetryClient(); 
telemetry.InstrumentationKey = APP_INSIGHTS_KEY;

作为第一种情况,让’s说您要记录创建网站集的事实以及该步骤花费了多长时间。如果你’重新使用PnP设置代码,它可能类似于以下内容– the key things are:

  • 简单使用.NET秒表时钟进行计时
  • 的制作‘metrics’ and ‘properties’字典将详细信息传递给App Insights
  • 使用TrackEvent()方法实际记录数据

如果使用PnP设置代码,则可能会得到以下结果: 

This would then show up in App Insights with details of the SharePoint URL, and the time taken for site collection creation (shown here 在里面 分析工具 tool):

SNAGHTML16524535

我们也可以将其扩展到PnP模板。以类似的方式,我将在PnP'ApplyProvisioningTemplate'调用周围添加日志记录语句,并且可能还会记录任何错误。

代码示例:

如预期的那样,然后您可以获取所应用模板的详细信息以及所记录的任何详细信息(本例中为站点URL,模板ID和处理时间):

SNAGHTML1f82d233

概要

App Insights非常适合将其集成到各种Office 365和SharePoint开发人员中。通过简单地在代码中添加几条语句,您可以稍后对其进行报告,并获得比所可能具有的更好的可见性。无论’Web部件的执行情况,发生的错误或用户沿着应用程序中的特定路径浏览的频率,’这是轻松构建此登录的好方法。就实用性而言,您当然需要Azure订阅,并且如果您每月(在撰写本文时)传递的数据量超过1GB,则App Insights是收费的,并且您的数据仅保留90天。但是,你不’不需要构建任何类型的前端或查询工具,您就可以获取图表/图表,每周摘要电子邮件,并且重要的是, 警报 如果不满足您定义的任何条件。此外,还有很多方法可以与数据集成(包括BLOB下载以使数据保留更长时间)。综合考虑,这些功能都很棒。

我认为Office 365和SharePoint开发人员肯定没有充分利用App Insights,但是有很多可能性。一世’我期待将其纳入我们的更多解决方案中!

2017年9月11日,星期一

管理跨SharePoint网站的租户范围的SPFx扩展

正如我在 使用SPFx应用程序自定义程序将JavaScript(例如标头)添加到网站中的每个页面, ’现在可以*在全球范围内*部署SPFx扩展名(例如页面页眉,页脚或其他随机的JavaScript片段),或在*许多* SharePoint网站上进行受控部署-无需将应用程序安装到每个单独的网站。这是个好消息,到目前为止,这对于现代网页来说还是一个空白。 SPFx 网页部分 在SPFx中,部署在租户范围的部署将出现在选择器中的所有位置 扩展名 您仍然需要在本地做一些事情,’s “associate”您的扩展程序包含网站/网站/列表/字段。对于应用程序定制程序,它’此步骤可让您精确控制使用扩展程序的站点。为此,您需要在网站或网站上添加CustomAction,并在ClientSideComponentId属性(SPFx的新增功能)中指定扩展的GUID。虽然我’在本文中,我们将重点放在网站级别的自定义(应用程序自定义程序)上,’类似的故事 SPFx字段定制器 也(在字段上指定了ClientSideComponentId)并且 SPFx命令集定制器 (在列表上指定了带有ClientSideComponentId的CustomAction)。所有这些可以通过以下两种方式完成:

  • 使用CSOM或REST–也许用PowerShell或C#代码
  • 作为PnP XML的一部分,如果您要将自定义模板应用于网站–XML模式和PnP Core设置库现在支持此功能(自2017年9月版起)

在这篇文章中,我’将提供一些PowerShell和C#代码,以帮助您在站点中应用应用程序定制程序–您可以为其他类型的定制器进行修改而不会带来太多麻烦。但是,在所有情况下都有一些先决条件-在某些方面,关联步骤是您要做的最后一件事。因此,让我们快速介绍一下:

租户范围的SPFx扩展-概述/先决条件

从SPFx v1.2起可以使用SPFx扩展和Webpart。大致来说,使用本文中的脚本/代码所需的先决条件是:-

  • 您指定了 "skipFeatureDeployment": true 在里面 package-solution.json 文件
  • 该应用程序已打包,然后安装到应用程序目录中,管理员选中了“使该解决方案可用于组织中的所有站点”框(如下图所示)
  • SPFx应用程序的JavaScript软件包已部署到CDN或其他Web托管位置

这是管理员在安装到App Catalog时将看到的内容,以及在安装时出现的复选框(他们需要检查) "skipFeatureDeployment": true:

SNAGHTMLf7281c2

PnP XML选项

在本文中,我将重点介绍C#/ PowerShell选项,但是’一个PnP XML选项,它也非常有用。这使您可以将关联作为自定义网站模板的一部分包括在内,因此对于从此类模板新创建的任何网站都非常有用。实际上,您也可以使用它来应用‘partial’模板添加到现有站点,但是我认为大多数人可能会选择PowerShell或C#代码。我想在这里传达的主要信息是可以从 版本2.18.1709 从...开始 即插即用核心 (2017年9月版)。 2017-05模式有地方指定 ClientSideComponentId 属性在CustomAction和字段上,因为’关联由什么组成。在Web级别提供应用程序定制程序的XML摘录为:

在下一节中,我’首先介绍PowerShell,然后介绍C#。

使用PowerShell代码和PnP PowerShell

以下是一些PowerShell函数,可通过在根网站级别添加自定义操作来在整个站点中添加,删除和列出SPFx全局扩展–调整是否需要其他东西。我在这里使用一个简单的站点URL数组,但是您可以随意填充该数组。其他说明:

  • 我正在使用 PnP PowerShell cmdlet 在这里-如果您还没有安装它们,则需要安装它们,然后通过 连接即插即用 等等
  • 在撰写本文时,我对它们提供的PnP cmdlet有一个问题(Add-PnPCustomAction),所以我在'add'方法中使用了直接CSOM。 我提出了GitHub问题 关于此问题(也在下面脚本的注释中指出),我敢肯定他们会尽快修复(或告诉我我做错了;),但直接CSOM方法也可以工作)
输出:

在以下位置注册全球部署的扩展 addSpfxExtensionCustomAction(ctx) 会给:

SNAGHTMLf6529dd

在网站上列出扩展程序:

Get-PnPCustomAction -Web $ ctx.Web |哪里对象{$ _。Location -eq"ClientSideExtension.ApplicationCustomizer" }

会给:

SNAGHTMLf67a240

删除扩展

Remove-CustomActionForSPFxExt $ spfxExtName $ site $ ctx

会给:

SNAGHTMLf69e124

使用C#代码和PnP内核

但是,也许您想使用C#代码而不是PowerShell。一些注意事项:-

  • 我在这里使用PnP Core库-您需要将NuGet软件包安装到解决方案/ Azure Function /如果没有的话,无论如何。从这里得到 //www.nuget.org/packages/SharePointPnPCoreOnline
  • 与上面的PowerShell相比,我在这里仅处理一个站点,但是将代码扩展为可在所需的任何站点上运行将是微不足道的

样例代码:

输出:

当你’d期望,在以下位置注册全球部署的扩展程序 addSpfxExtensionCustomAction(ctx) 会给:

SNAGHTMLf59848b

在网站上列出扩展 getCustomActions(ctx) 会给:

SNAGHTMLf55b850

删除扩展 removeSpfxExtensionCustomAction() 会给:

SNAGHTMLf5790d9

另外的选择– CLI scripts

另一种选择是,请注意我尊敬的同事 瓦尔达曼·德什潘德 它还具有超酷的CLI工具,可帮助您管理SPFx扩展。他’如此时髦;)他的脚本也提供了管理SPFx命令集定制器的功能。看到 //github.com/vman/spfx-extensions-cli 更多细节。

概要

对于租户范围的SPFx应用程序自定义程序,您需要确保使用它的网站或网站具有带有扩展程序的ClientSideComponentId的CustomAction(除了处理其他先决步骤,即获取应用程序包和相应的JavaScript捆绑包) 。尽管此代码未解决,但它’对于SPFx字段自定义程序和命令集自定义程序也采用类似的方法。希望本文介绍的选项(以及潜在的PnP令人敬畏)是有用的。