使用 ASP.NET Core MVC 创建自定义通道和组选项卡Create a Custom Channel and Group Tab with ASP.NET Core MVC

在此快速入门中,我们将介绍如何使用 c # 和 ASP.Net Core MVC 创建自定义频道/组选项卡。In this quickstart we'll walk-through creating a custom channel/group tab with C# and ASP.Net Core MVC. 我们还将使用 Microsoft 团队的应用 Studio 来完成你的应用程序清单,并将你的选项卡部署到团队。We'll also use App Studio for Microsoft Teams to finalize your app manifest and deploy your tab to Teams.

先决条件Prerequisites

  • 若要完成此快速入门,你将需要 Office 365 租户和配置了 "允许上载自定义应用程序" 的团队。To complete this quickstart you'll need an Office 365 tenant and a team configured with Allow uploading custom apps enabled. 若要了解详细信息,请参阅准备 Office 365 租户To learn more, see Prepare your Office 365 tenant.

    • 如果当前没有 Office 365 帐户,可以通过office 365 开发人员计划注册免费订阅。If you don't currently have an Office 365 account, you can sign up for a free subscription through the Office 365 Developer Program. 只要您使用它进行持续开发,订阅将保持活动状态。The subscription will remain active as long as you're using it for ongoing development.
  • 你将使用应用程序 Studio 将应用程序导入到团队。You'll use App Studio to import your application to Teams. 若要在团队应用程序的左下](~/assets/images/tab-images/storeApp.png)角安装应用程序 Studio 选择应用 ![商店应用程序,请搜索应用程序 studio。To install App Studio select Apps Store App at the bottom-left corner of the Teams app, and search for App Studio. 找到该磁贴后,选择它并在弹出窗口对话框中选择 "安装"。Once you find the tile, select it and choose install in the pop-up window dialog box.

此外,此项目要求在开发环境中安装以下各项:In addition, this project requires that you have the following installed in your development environment:

  • 安装了 .NET CORE 跨平台开发工作负载的 VISUAL Studio IDE 的当前版本。The current version the Visual Studio IDE with the .NET CORE cross-platform development workload installed. 如果你还没有 Visual Studio,可以免费下载并安装最新的Microsoft Visual Studio 社区版本。If you don't already have Visual Studio, you can download and install the latest Microsoft Visual Studio Community version for free.

  • Ngrok反向代理工具。The ngrok reverse proxy tool. 您将使用 ngrok 创建到本地运行的 web 服务器的公开可用 HTTPS 终结点的隧道。You'll use ngrok to create a tunnel to your locally running web server's publicly-available HTTPS endpoints. 你可以在此处下载它You can download it here.

获取源代码Get the source code

打开命令提示符并为您的选项卡项目创建一个新目录。Open a command prompt and create a new directory for your tab project. 我们提供了一个简单的 通道组选项卡 项目,可帮助你入门。We have provided a simple Channel Group Tab project to get you started. 若要检索源代码,可以下载 zip 文件夹并解压缩文件,或将示例存储库克隆到新目录:To retrieve the source code you can download the zip folder and extract the files or clone the sample repository into your new directory:

git clone https://github.com/OfficeDev/microsoft-teams-sample-tabs.git

拥有源代码后,打开 Visual Studio 并选择 " 打开项目或解决方案"。Once you have the source code, open Visual Studio and select Open a project or solution. 导航到 "选项卡应用程序目录",然后打开 " ChannelGroupTabMVC"。Navigate to the tab application directory and open ChannelGroupTabMVC.sln.

若要生成并运行应用程序,请按F5或从 "调试" 菜单中选择 "启动调试"。To build and run your application press F5 or choose Start Debugging from the Debug menu. 在浏览器中,导航到以下 Url 并验证应用程序是否已正确加载:In a browser, navigate to the URLs below and verify that the application loaded properly:

  • http://localhost:44360
  • http://localhost:44360/privacy
  • http://localhost:44360/tou

查看源代码Review the source code

Startup.csStartup.cs

此项目是从 ASP.NET Core 2.2 Web 应用程序空模板创建的,并且在安装程序中选中了 " 高级-配置为 HTTPS " 复选框。This project was created from an ASP.NET Core 2.2 Web Application empty template with the Advanced - Configure for HTTPS check box selected at setup. MVC 服务由依赖关系注入框架的 ConfigureServices() 方法注册。The MVC services are registered by the dependency injection framework's ConfigureServices() method. 此外,默认情况下,空模板不启用静态内容的服务,因此将静态文件中间件添加到 Configure() 方法中:Additionally, the empty template doesn't enable serving static content by default, so the static files middleware is added to the Configure() method:

public void ConfigureServices(IServiceCollection services)
  {
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
  }
public void Configure(IApplicationBuilder app)
  {
    app.UseStaticFiles();
    app.UseMvc();
  }

wwwroot 文件夹wwwroot folder

在 ASP.NET Core 中,web 根文件夹是应用程序查找静态文件的位置。In ASP.NET Core, the web root folder is where the application looks for static files.

Appmanifest.xml 文件夹AppManifest folder

此文件夹包含以下所需的应用程序包文件:This folder contains the following required app package files:

  • 以 192 x 192 像素为单位的 完整彩色图标A full color icon measuring 192 x 192 pixels.
  • 一个 透明的大纲图标 ,用于度量 32 x 32 像素。A transparent outline icon measuring 32 x 32 pixels.
  • 指定应用程序属性的文件 ** 上的manifest.js** 。A manifest.json file that specifies the attributes of your app.

需要将这些文件压缩到应用程序包中,以便在将选项卡上载到团队时使用。These files need to be zipped in an app package for use in uploading your tab to Teams.

.csproj.csproj

在 Visual Studio "解决方案资源管理器" 窗口中,右键单击该项目,然后选择 " 编辑项目文件"。In the Visual Studio Solution Explorer window right-click on the project and select Edit Project File. 在该文件的底部,您将看到在应用程序生成时创建和更新您的 zip 文件夹的代码:At the bottom of the file you'll see the code that creates and updates your zip folder when the application builds:

<PropertyGroup>
    <PostBuildEvent>powershell.exe Compress-Archive -Path \"$(ProjectDir)AppManifest\*\" -DestinationPath \"$(TargetDir)tab.zip\" -Force</PostBuildEvent>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="AppManifest\icon-outline.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\icon-color.png">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
    <EmbeddedResource Include="AppManifest\manifest.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </EmbeddedResource>
  </ItemGroup>

模型Models

ChannelGroup.cs 显示在配置过程中将从控制器调用的 Message 对象和方法。ChannelGroup.cs presents a Message object and methods that will be called from the Controllers during configuration.

视图Views

家庭版Home

ASP.NET Core 将称为 Index 的文件视为网站的默认/主页。ASP.NET Core treats files called Index as the default/home page for the site. 当浏览器 URL 指向网站的根目录时,将显示 索引. cshtml 将显示为应用程序的主页。When your browser URL points to the root of the site, Index.cshtml will be displayed as the home page for your application.

共享的内容Shared

分部视图标记 _Layout. cshtml 包含应用程序的整体页面结构和共享的可视化元素。The partial view markup _Layout.cshtml contains the application's overall page structure and shared visual elements. 它还将引用团队库。It will also reference the Teams Library.

控制器Controllers

这些控制器使用 ViewBag 属性将值动态转移到视图。The controllers use the ViewBag property to transfer values dynamically to the Views.

建立到您的选项卡的安全隧道Establish a secure tunnel to your tab

Microsoft 团队是完全基于云的产品,要求使用 HTTPS 终结点从云中获取你的选项卡内容。Microsoft Teams is an entirely cloud-based product and requires that your tab content be available from the cloud using HTTPS endpoints. 团队不允许本地托管。Teams doesn't allow local hosting. 您需要将您的选项卡发布到公用 URL,或使用将本地端口暴露给面向 internet 的 URL 的代理。You'll need to either publish your tab to a public URL, or use a proxy that will expose your local port to an internet-facing URL.

若要测试您的选项卡,您将使用ngrokTo test your tab you'll use ngrok. 在本地计算机上运行 ngrok 时,您的服务器的 web 终结点将可用。Your server's web endpoints will be available while ngrok is running on your local machine. 如果关闭 ngrok,Url 将在下次启动时有所不同。If you close ngrok, the URLs will be different the next time you start it.

  • 在项目目录的根目录中打开命令提示符,并运行以下命令:Open a command prompt in the root of your project directory and run the following command:
ngrok http https://localhost:443560 -host-header="localhost:44360"
  • Ngrok 将侦听来自 internet 的请求,并在其运行在端口44355上时将它们路由到您的应用程序。Ngrok will listen to requests from the internet and will route them to your application when it is running on port 44355. 它应类似于 https://y8rCgT2b.ngrok.io/y8rCgT2b 替换为 NGROK 字母数字 HTTPS URL 的位置。It should resemble https://y8rCgT2b.ngrok.io/ where y8rCgT2b is replaced by your ngrok alpha-numeric HTTPS URL.

  • 请务必在 ngrok 运行的同时保留命令提示符,并记下该 URL,稍后将需要它。Be sure to keep the command prompt with ngrok running and to make note of the URL — you'll need it later.

更新应用程序Update your application

选项卡中。 cshtml 应用程序为用户提供了两个选项按钮,用于显示带有红色或灰色图标的选项卡。Within Tab.cshtml the application presents the user with two option buttons for displaying the tab with either a red or gray icon. 选择 " 选择灰色 " 或 " 选择红色 " 按钮将触发 saveGray()saveRed() 分别设置 settings.setValidityState(true) 和启用 "配置" 页上的 " 保存 " 按钮。Choosing the Select Gray or Select Red button fires saveGray() or saveRed(), respectively, sets settings.setValidityState(true), and enables the Save button on the configuration page. 此代码使团队知道您已经满足配置要求,可以继续安装。This code lets Teams know that you have satisfied the configuration requirements and the installation can proceed. 在保存时设置的参数 settings.setSettingsOn save, the parameters of settings.setSettings are set. 最后, saveEvent.notifySuccess() 将调用,以指示内容 URL 已成功解析。Finally, saveEvent.notifySuccess() is called to indicate that the content URL has successfully resolved.

_Layout cshtml_Layout.cshtml

若要在团队中显示您的选项卡,您必须包含Microsoft 团队 JavaScript 客户端 SDK ,并microsoftTeams.initialize()在加载页面后包含一个调用。For your tab to display in Teams, you must include the Microsoft Teams JavaScript client SDK and include a call to microsoftTeams.initialize() after your page loads. 这就是选项卡和团队客户端之间的通信方式:This is how your tab and the Teams client communicate:

  • 导航到共享文件夹,打开 _Layout. cshtml,并将以下内容添加到<head>标记:Navigate to the Shared folder, open _Layout.cshtml, and add the following to the <head> tag:
<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.4.1.min.js"></script>
<script src="https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js"></script>

重要

请勿复制/粘贴此<script src="...">页面中的 url,因为它们可能不代表最新版本。Don't copy/paste the <script src="..."> URLs from this page, as they may not represent the latest version. 若要获取最新版本的 SDK,请始终转到: Microsoft 团队 JAVASCRIPT APITo get the latest version of the SDK, always go to: Microsoft Teams JavaScript API.

选项卡. cshtmlTab.cshtml

打开选项卡. cshtml并更新嵌入<script>的,如下所示:Open Tab.cshtml and update the embedded <script> as follows:

  • 在脚本的顶部,调用microsoftTeams.initialize()At the top of the script, call microsoftTeams.initialize().

  • 使用 HTTPS websiteUrl ngrok contentUrl URL 将每个函数中的和值更新到您的选项卡。Update the websiteUrl and contentUrl values in each function with the HTTPS ngrok URL to your tab.

您的代码现在应如下所示, y8rCgT2b替换为您的 ngrok URL:Your code should now look like the following with y8rCgT2b replaced with your ngrok URL:

    microsoftTeams.initialize();

    let saveGray = () => {
        microsoftTeams.settings.registerOnSaveHandler(function (saveEvent) {
            microsoftTeams.settings.setSettings({
                websiteUrl: `https://y8rCgT2b.ngrok.io`,
                contentUrl: `https://y8rCgT2b.ngrok.io/gray/`,
                entityId: "grayIconTab",
                suggestedDisplayName: "MyNewTab"
            });
            saveEvent.notifySuccess();
        });
    }

    let saveRed = () => {
        microsoftTeams.settings.registerOnSaveHandler(function (saveEvent) {
            microsoftTeams.settings.setSettings({
                websiteUrl: `https://y8rCgT2b.ngrok.io`,
                contentUrl: `https://y8rCgT2b.ngrok.io/red/`,
                entityId: "redIconTab",
                suggestedDisplayName: "MyNewTab"
            });
            saveEvent.notifySuccess();
        });
    }

请务必保存更新的选项卡. cshtmlMake sure to save the updated Tab.cshtml.

生成并运行应用程序Build and run your application

  • 在 Visual Studio 中按F5,或从 "调试" 菜单中选择 "启动调试"。In Visual Studio press F5, or choose Start Debugging from the Debug menu. 通过在命令提示符窗口中提供的 ngrok HTTPS URL 打开浏览器并转到内容页,验证ngrok是否正在运行并正常运行。Verify that ngrok is running and working properly by opening your browser and going to your content page via the ngrok HTTPS URL that was provided in your command prompt window.

提示

您需要在 Visual Studio 和 ngrok 中同时运行应用程序,才能完成此快速入门。You need to have both your application in Visual Studio and ngrok running to complete this quickstart. 如果需要在 Visual Studio 中停止运行应用程序以使用它,请继续运行 ngrokIf you need to stop running your application in Visual Studio to work on it keep ngrok running. 它将继续侦听,并将在 Visual Studio 中重新启动时继续路由应用程序的请求。It will continue to listen and will resume routing your application's request when it restarts in Visual Studio. 如果您必须重新启动 ngrok 服务,它将返回一个新的 URL,您必须使用新的 URL 更新应用程序。If you have to restart the ngrok service it will return a new URL and you'll have to update your application with the new URL.

将您的选项卡上传给具有应用程序 Studio 的团队Upload your tab to Teams with App Studio

备注

我们使用应用程序 Studio 编辑您的清单 json文件并将已完成的包上载到团队。We use App Studio to edit your manifest.json file and upload the completed package to Teams. 如果愿意,也可以手动编辑清单 json文件。You can also manually edit the manifest.json file if you prefer. 如果这样做,请务必再次生成解决方案,以创建要上载的tab .zip文件。If you do, be sure to build the solution again to create the tab.zip file to upload.

  • 打开 Microsoft 团队客户端。Open the Microsoft Teams client. 如果您使用的是基于 web 的版本,则可以使用浏览器的开发人员工具检查您的前端代码。If you use the web based version you can inspect your front-end code using your browser's developer tools.

  • 打开应用程序 studio 并选择 "清单编辑器" 选项卡。Open App studio and select the Manifest editor tab.

  • 选择 "在清单编辑器中导入现有的应用程序磁贴" 以开始更新选项卡的应用程序包。源代码附带其自己完整的清单。Select the Import an existing app tile in the Manifest editor to begin updating the app package for your tab. The source code comes with its own partially complete manifest. 您的应用程序包的名称为 "tab .zip"。The name of your app package is tab.zip. 应在此处找到:It should be found here:

/bin/Debug/netcoreapp2.2/tab.zip
  • 选项卡上传到应用程序 Studio。Upload tab.zip to App Studio.

使用清单编辑器更新应用程序包Update your app package with Manifest editor

将应用程序包上载到应用程序 Studio 后,需要完成对其进行配置。Once you've uploaded your app package into App Studio, you'll need to finish configuring it.

  • 在清单编辑器的 "欢迎" 页的右面板中,为新导入的选项卡选择磁贴。Select the tile for your newly imported tab in the right panel of the Manifest editor welcome page.

清单编辑器的左侧有一个步骤列表,在右侧是需要为每个步骤的值提供值的属性的列表。There's a list of steps in the left-hand side of the Manifest editor, and on the right, a list of properties that need to have values for each of those steps. 大部分信息已由您的清单 json提供,但有几个字段需要更新:Much of the information has been provided by your manifest.json but there are a few fields that you'll need to update:

详细信息:应用程序详细信息Details: App details

  • 在 "标识" 下,选择 "生成" 以将占位符 id 替换为您的选项卡所需的 GUID。Under Identification select Generate to replace the placeholder id with the required GUID for your tab.

  • 在 "开发人员信息" 下,使用您的ngrok HTTPS URL 更新网站 URL字段。Under Developer information update the Website URL field with your ngrok HTTPS URL.

  • 在 "应用程序 url " 下,使用您的ngrok HTTPS Url 更新隐私声明使用条款url 字段。Under App URLs update the Privacy statement and Terms of use URL fields with your ngrok HTTPS URL. 请记住将 /privacy/tou路径包含在 url 的末尾。Remember to include the /privacy and /tou paths at the end of the URLs.

功能:选项卡Capabilities: Tabs

在 "选项卡" 部分:In the Tabs section:

  • 在 "团队" 选项卡下选择 "添加"。Under Team Tab select Add.

  • 在 "团队" 选项卡弹出窗口中,将配置 URL更新为https://<yourngrokurl>/tabIn the Team tab pop-up window update the Configuration URL to https://<yourngrokurl>/tab.

  • 最后,请确保可以更新配置? 将选中 "团队" 和 "组" 聊天框,然后选择 "保存"。Finally, make sure the can update configuration? Team, and Group chat boxes are checked and select Save.

完成:域和权限Finish: Domains and permissions

在 "域和权限" 部分中,"选项卡" 字段中的域应包含不带 HTTPS 前缀<yourngrokurl>.ngrok.io/的 ngrok URL。In the Domains and permissions section, the Domains from your tabs field should contain your ngrok URL without the HTTPS prefix - <yourngrokurl>.ngrok.io/.

测试和分发:测试和分发Test and distribute: Test and distribute

重要

在右侧的 "说明" 字段中,将看到以下警告:In the Description field on the right you'll see the following warning:

⚠ "validDomains" 数组不能包含隧道站点 ..."⚠ "The 'validDomains' array cannot contain a tunneling site..."

在测试选项卡时可以忽略此警告。This warning can be ignored while testing your tab.

在 "测试和分发" 部分:In the Test and distribute section:

  • 选择“安装”。Select Install.

  • 在弹出窗口的 "添加到团队" 或 "聊天" 字段中,输入您的团队并选择 "安装"。In the pop-up window's Add to a team or chat field enter your team and select Install.

  • 在下一个弹出窗口中,选择要在其中显示选项卡的团队频道,然后选择 "设置"。In the next pop-up window choose the team channel where you would like the tab displayed and select Set up.

  • 在最终弹出窗口中,选择选项卡页的值(红色或灰色图标),然后选择 "保存"。In the final pop-up window select a value for the tab page (either a red or gray icon) and select Save.

若要查看您的选项卡,请导航到安装它的团队,然后从选项卡栏中选择它。To view your tab, navigate to the team you installed it on, and select it from the tab bar. 应显示在配置过程中选择的页面。The page that you chose during configuration should be displayed.

将您的选项卡上传给具有应用程序 Studio 的团队Upload your tab to Teams with App Studio

备注

我们使用应用程序 Studio 编辑您的清单 json文件并将已完成的包上载到团队。We use App Studio to edit your manifest.json file and upload the completed package to Teams. 如果愿意,也可以手动编辑清单 json文件。You can also manually edit the manifest.json file if you prefer. 如果这样做,请务必再次生成解决方案,以创建要上载的tab .zip文件。If you do, be sure to build the solution again to create the tab.zip file to upload.

  • 打开 Microsoft 团队客户端。Open the Microsoft Teams client. 如果您使用的是基于 web 的版本,则可以使用浏览器的开发人员工具检查您的前端代码。If you use the web based version you can inspect your front-end code using your browser's developer tools.

  • 打开应用程序 Studio 应用,然后选择 "清单编辑器" 选项卡。Open the App Studio app and select the Manifest editor tab.

  • 选择 "在清单编辑器中导入现有的应用程序磁贴" 以开始更新选项卡的应用程序包。源代码附带其自己完整的清单。Select the Import an existing app tile in the Manifest editor to begin updating the app package for your tab. The source code comes with its own partially complete manifest. 您的应用程序包的名称为 "tab .zip"。The name of your app package is tab.zip. 应在此处找到:It should be found here:

/bin/Debug/netcoreapp2.2/tab.zip
  • 选项卡上传到应用程序 Studio。Upload tab.zip to App Studio.

使用清单编辑器更新应用程序包Update your app package with Manifest editor

将应用程序包上载到应用程序 Studio 后,需要完成对其进行配置。Once you've uploaded your app package into App Studio, you'll need to finish configuring it.

  • 在清单编辑器的 "欢迎" 页的右面板中,为新导入的选项卡选择磁贴。Select the tile for your newly imported tab in the right panel of the Manifest editor welcome page.

清单编辑器的左侧有一个步骤列表,在右侧是需要为每个步骤的值提供值的属性的列表。There's a list of steps in the left-hand side of the Manifest editor, and on the right, a list of properties that need to have values for each of those steps. 大部分信息已由您的清单 json提供,但有几个字段需要更新:Much of the information has been provided by your manifest.json but there are a few fields that you'll need to update:

详细信息:应用程序详细信息Details: App details

  • 在 "标识" 下,选择 "生成" 以生成应用程序的新应用 Id。Under Identification select Generate to generate a new App Id for your app.

  • 在 "开发人员信息" 下,使用您的ngrok HTTPS URL 更新网站 URL字段。Under Developer information update the Website URL field with your ngrok HTTPS URL.

  • "应用程序 url " 下, https://<yourngrokurl>/privacy更新隐私声明,并将https://<yourngrokurl>/tou 使用条款更新为>。Under App URLs update the Privacy statement to https://<yourngrokurl>/privacy and Terms of use to https://<yourngrokurl>/tou>.

功能:选项卡Capabilities: Tabs

在 "选项卡" 部分:In the Tabs section:

  • 在 "团队" 选项卡下选择 "添加"。Under Team Tab select Add.

  • 在 "团队" 选项卡弹出窗口中,将配置 URL更新为https://<yourngrokurl>/tabIn the Team tab pop-up window update the Configuration URL to https://<yourngrokurl>/tab.

  • 最后,请确保可以更新配置? 将选中 "团队" 和 "组" 聊天框,然后选择 "保存"。Finally, make sure the can update configuration? Team, and Group chat boxes are checked and select Save.

完成:域和权限Finish: Domains and permissions

在 "域和权限" 部分中,"选项卡" 字段中的域应包含不带 HTTPS 前缀<yourngrokurl>.ngrok.io/的 ngrok URL。In the Domains and permissions section, the Domains from your tabs field should contain your ngrok URL without the HTTPS prefix - <yourngrokurl>.ngrok.io/.

完成:测试和分发Finish: Test and distribute

重要

在右侧的 "说明" 字段中,将看到以下警告:In the Description field on the right you'll see the following warning:

⚠ "validDomains" 数组不能包含隧道站点 ..."⚠ "The 'validDomains' array cannot contain a tunneling site..."

在测试选项卡时可以忽略此警告。This warning can be ignored while testing your tab.

在 "测试和分发" 部分:In the Test and distribute section:

  • 选择“安装”。Select Install.

  • 在弹出窗口的 "添加到团队" 或 "聊天" 字段中,输入您的团队并选择 "安装"。In the pop-up window's Add to a team or chat field enter your team and select Install.

  • 在下一个弹出窗口中,选择要在其中显示选项卡的团队频道,然后选择 "设置"。In the next pop-up window choose the team channel where you would like the tab displayed and select Set up.

  • 在最终弹出窗口中,选择选项卡页的值(红色或灰色图标),然后选择 "保存"。In the final pop-up window select a value for the tab page (either a red or gray icon) and select Save.

若要查看您的选项卡,请导航到安装它的团队,然后从选项卡栏中选择它。To view your tab, navigate to the team you installed it on, and select it from the tab bar. 应显示在配置过程中选择的页面。The page that you chose during configuration should be displayed.