使用 ASP 创建自定义个人选项卡。Create a Custom Personal Tab with ASP. NET Core MVCNET Core MVC

在此快速入门中,我们将介绍如何使用 c # 和 ASP 创建自定义个人选项卡。In this quickstart we'll walk-through creating a custom personal tab with C# and ASP. Net Core MVC。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 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. 导航到 "选项卡应用程序目录",然后打开 " PersonalTabMVC"。Navigate to the tab application directory and open PersonalTabMVC.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 to verify that the application loaded properly:

  • http://localhost:44335
  • http://localhost:44335/privacy
  • http://localhost:44335/tou

查看源代码Review the source code

Startup.csStartup.cs

此项目是从 ASP 创建的。This project was created from an ASP. NET Core 2.2 Web 应用程序空模板,并在安装程序中选中 "对 HTTPS 进行高级配置 " 复选框。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 中。In ASP. NET Core,web 根文件夹是应用程序查找静态文件的位置。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. Microsoft 团队将加载 contentUrl 清单中指定的项,将其嵌入 IFrame 中,并在您的选项卡中呈现。Microsoft Teams will load the contentUrl specified in your manifest, embed it in an IFrame, and render it in your tab.

.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

PersonalTab.cs显示一个 Message 对象和方法,当用户在PersonalTab视图中选择一个按钮时,将从PersonalTabController中调用该对象和方法。PersonalTab.cs presents a Message object and methods that will be called from PersonalTabController when a user selects a button in the PersonalTab View.

视图Views

家庭版Home

这家.ASP. NET Core 将称为 Index 的文件视为网站的默认/主页。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.

更新应用程序Update your application

_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 app communicate:

  • 导航到共享文件夹,打开 _Layout. cshtml,并将以下内容添加到 " <head>标签" 部分:Navigate to the Shared folder, open _Layout.cshtml, and add the following to the <head> tags section:
`<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>`

PersonalTabPersonalTab.cshtml

打开PersonalTab ,并通过调用<script> microsoftTeams.initialize()更新嵌入的标记。Open PersonalTab.cshtml and update the embedded <script> tags by calling microsoftTeams.initialize().

请务必保存更新后的PersonalTabMake sure to save your updated PersonalTab.cshtml.

建立到您的选项卡的安全隧道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:44345 -host-header="localhost:44345"
  • Ngrok 将侦听来自 internet 的请求,并在其运行在端口44325上时将它们路由到您的应用程序。Ngrok will listen to requests from the internet and will route them to your application when it is running on port 44325. 它应类似于 https://y8rPrT2b.ngrok.io/y8rPrT2b 替换为 NGROK 字母数字 HTTPS URL 的位置。It should resemble https://y8rPrT2b.ngrok.io/ where y8rPrT2b is replaced by your ngrok alpha-numeric HTTPS URL.

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

  • 通过在命令提示符窗口中提供的 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 中运行应用程序以完成此快速入门。TIP] You need to have both your application in Visual Studio and ngrok running to complete this quickstart. 如果需要在 Visual Studio 中停止运行应用程序以进行处理,请 保持 ngrok 运行状态If 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 every place that uses that URL.

运行应用程序Run your application

  • 在 Visual Studio 中,按F5或从应用程序的 "调试" 菜单中选择 "启动调试"。In Visual Studio press F5 or choose Start Debugging from your application's Debug menu.

将您的选项卡上传给具有应用程序 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. 如果愿意,您还可以手动编辑清单 jsonYou can also manually edit manifest.json 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

在 "应用程序详细信息" 部分:In the App details section:

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

  • 在 "开发人员信息" 下,使用您的ngrok HTTPS url 更新网站 URLUnder Developer information update the Website URL 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 Add a personal tab select Add. 将显示一个弹出对话框窗口。You will be presented with a pop-up dialogue window.

  • 填写 "名称" 字段。Complete the Name field.

  • 填写 "实体 Id " 字段。Complete the Entity Id field.

  • 使用将内容 URL字段更新为https://<yourngrokurl>/personalTabUpdate the Content URL field with to https://<yourngrokurl>/personalTab.

  • 将 "网站 URL " 字段保留为空。Leave the Website URL field blank.

  • 选择“保存”。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 make sure that Add for you is set to Yes and Add to a team or chat is set to No.

  • 选择“安装”。Select Install.

  • 在下一个弹出窗口中,选择 "打开",您的选项卡将显示出来。In the next pop-up window select Open and your tab will be displayed.

查看您的个人选项卡View your personal tab

  • 在位于 "团队" 应用程序最左侧的导航栏中,选择 "" ...菜单。In the navigation bar located at the far-left of the Teams App, select the ... menu. 将显示个人应用程序的列表。You'll be presented with a list of personal apps.

  • 从列表中选择要查看的选项卡。Select your tab from the list to view.