Desenvolver funções definidas pelo usuário do .NET Standard para tarefas do Azure Stream Analytics (Preview)

O Azure Stream Analytics oferece uma linguagem de consulta semelhante ao SQL para realizar transformações e cálculos sobre fluxos de dados de eventos. Existem muitas funções incorporadas, mas alguns cenários complexos exigem flexibilidade adicional. Com as funções definidas pelo utilizador (UDF) do .NET Standard, pode invocar as suas próprias funções escritas em qualquer linguagem padrão .NET (C#, F#, etc.) para expandir a linguagem de consulta Stream Analytics. Os UDFs permitem-lhe realizar cálculos matemáticos complexos, importar modelos de ML personalizados usando ML.NET e usar lógica de imputação personalizada para dados em falta. O recurso UDF para trabalhos do Stream Analytics está atualmente em pré-visualização e não deve ser utilizado em cargas de trabalho de produção.

Regiões

A funcionalidade .NET de função definida pelo utilizador é ativada para trabalhos na cloud que correm em clusters de Stream Analytics. Os trabalhos que correm no SKU multi-inquilino Standard podem tirar partido desta funcionalidade nas seguintes regiões públicas:

• E.U.A. Centro-Oeste
• Europa do Norte
• E.U.A. Leste
• E.U.A. Oeste
• E.U.A. Leste 2
• Europa Ocidental

Se estiver interessado em usar esta funcionalidade noutra região, pode pedir acesso.

Caminho do pacote

O formato de qualquer pacote UDF tem o caminho /UserCustomCode/CLR/*. As Bibliotecas de Ligação Dinâmica (DLLs) e os recursos são copiados na pasta /UserCustomCode/CLR/*, o que ajuda a isolar as DLLs do utilizador das DLLs do sistema e do Azure Stream Analytics. Este caminho do pacote é usado para todas as funções, independentemente do método utilizado para as empregar.

Tipos suportados e mapeamento

Para que os valores do Azure Stream Analytics sejam usados em C#, precisam de ser organizados de um ambiente para o outro. O marshaling ocorre para todos os parâmetros de entrada de uma UDF. Cada tipo Azure Stream Analytics tem um tipo correspondente em C# mostrado na tabela abaixo:

O mesmo se aplica quando os dados precisam de ser convertidos de C# para Azure Stream Analytics, isto ocorre no valor de saída de uma UDF. A tabela abaixo mostra que tipos são suportados:

Desenvolver um UDF em Visual Studio Code

As ferramentas do Visual Studio Code para o Azure Stream Analytics facilitam a escrita de UDFs, testar os seus trabalhos localmente (mesmo offline) e publicar os seus trabalhos de Stream Analytics no Azure.

Existem duas formas de implementar UDFs padrão .NET nas ferramentas Visual Studio Code.

• UDF a partir de DLLs locais
• UDF a partir de um projeto local

Projeto local

As funções definidas pelo utilizador podem ser escritas num assembly que é posteriormente referenciado numa consulta do Azure Stream Analytics. Esta é a opção recomendada para funções complexas que requerem todo o poder de uma linguagem .NET Standard para além da sua linguagem de expressão, como lógica procedural ou recursão. UDFs de um projeto local também podem ser utilizados quando for necessário partilhar a lógica de funções entre várias consultas do Azure Stream Analytics. Adicionar UDFs ao seu projeto local dá-lhe a capacidade de depurar e testar as suas funções localmente.

Para referenciar um projeto local:

1. Crie uma nova biblioteca de classes padrão .NET na sua máquina local.
2. Escreve o código na tua aula. Lembre-se que as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.
3. Adicione um novo ficheiro de configuração da função CSharp no seu projeto Azure Stream Analytics e faça referência ao projeto da biblioteca de classes CSharp.
4. Configure o caminho de montagem no ficheiro de configuração do trabalho, JobConfig.json, na secção CustomCodeStorage . Este passo não é necessário para testes locais.

DLLs locais

Também pode referenciar DLLs locais que incluem as funções definidas pelo utilizador.

Example

Neste exemplo, CSharpUDFProject é um projeto de biblioteca de classes C# e ASAUDFDemo é o projeto Azure Stream Analytics, que irá referenciar CSharpUDFProject.

A UDF seguinte tem uma função que multiplica um inteiro por si própria para produzir o quadrado do inteiro. As classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.

using System;

namespace CSharpUDFProject
{
    // 
    public class Class1
    {
        public static Int64 SquareFunction(Int64 a)
        {
            return a * a;
        }
    }
}

Os passos seguintes mostram-lhe como adicionar uma função C# UDF ao seu projeto de Stream Analytics.

1. Clique com o botão direito na pasta Funções e escolha Adicionar item.

   

2. Adicione uma função C# chamada SquareFunction ao seu projeto Azure Stream Analytics.

   

   

3. Na configuração da função C#, selecione Escolher caminho de projeto de biblioteca para escolher o seu projeto C# na lista suspensa e selecione Construir projeto para construir o seu projeto. Depois escolhe Select class e Select method para selecionar a classe relacionada e o nome do método na lista suspensa. Para se referir aos métodos, tipos e funções na consulta Stream Analytics, as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.

   

   Se quiseres usar o UDF C# de uma DLL, seleciona Choose library dll path para escolher a DLL. Depois escolhe Select class e Select method para selecionar a classe relacionada e o nome do método na lista suspensa.

   

4. Invoque UDF na sua consulta de Azure Stream Analytics.

    SELECT price, udf.SquareFunction(price)
    INTO Output
    FROM Input 
   

5. Antes de submeter o trabalho para o Azure, configure o caminho do pacote no ficheiro de configuração do trabalho, JobConfig.json, na secção CustomCodeStorage . Utilize Selecionar da sua subscrição no CodeLens para escolher a sua subscrição, a conta de armazenamento, e o nome do container na lista suspensa. Deixar Path como predefinição. Este passo não é necessário para testes locais.

   

Desenvolver uma Função Definida pelo Usuário (UDF) no Visual Studio

Existem três formas de implementar UDFs nas ferramentas do Visual Studio.

• Ficheiros CodeBehind num projeto ASA
• UDF a partir de um projeto local
• Um pacote existente a partir de uma conta de armazenamento Azure

CodeBehind

Pode escrever funções definidas por utilizador no CodeBehind do Script.asql. As ferramentas do Visual Studio compilam automaticamente o ficheiro CodeBehind num ficheiro assembly. Os conjuntos são embalados como um ficheiro zip e carregados na sua conta de armazenamento quando submete o seu trabalho no Azure. Pode aprender a escrever um UDF em C# usando o CodeBehind seguindo o tutorial do UDF em C# para trabalhos de Stream Analytics Edge .

Projeto local

Para referenciar um projeto local no Visual Studio:

1. Crie uma nova biblioteca de classes padrão .NET na sua solução
2. Escreve o código na tua aula. Lembre-se que as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.
3. Construa o seu projeto. As ferramentas vão empacotar todos os artefactos da pasta bin num ficheiro zip e carregar o ficheiro zip para a conta de armazenamento. Para referências externas, use assembly reference em vez do pacote NuGet.
4. Consulte a nova classe no seu projeto Azure Stream Analytics.
5. Adicione uma nova função no seu projeto Azure Stream Analytics.
6. Configure o caminho de montagem no ficheiro de configuração do trabalho, JobConfig.json. Defina o caminho de montagem para Local Project Reference ou CodeBehind.
7. Reconstruir tanto o projeto de funções como o projeto Azure Stream Analytics.

Example

Neste exemplo, o UDFTest é um projeto de biblioteca de classes C# e o ASAUDFDemo é o projeto Azure Stream Analytics, que irá referenciar o UDFTest.

1. Constrói o teu projeto C#, que te permitirá adicionar uma referência ao teu UDF C# a partir da consulta Azure Stream Analytics.

   

2. Adicione a referência ao projeto C# no projeto ASA. Clique com o botão direito no nó Referências e escolha Adicionar Referência.

   

3. Escolha o nome do projeto C# da lista.

   

4. Deves ver o UDFTest listado em Referências no Explorador de Soluções.

   

5. Clique com o botão direito na pasta Funções e escolha Novo Item.

   

6. Adicione uma função C#SquareFunction.json ao seu projeto Azure Stream Analytics.

   

7. Clique duas vezes na função no Explorador de Soluções para abrir o diálogo de configuração.

   

8. Na configuração da função C#, escolha Carregar da Referência de Projeto ASA e os nomes do assembly, da classe e do método relacionados na lista pendente. Para se referir aos métodos, tipos e funções na consulta Stream Analytics, as classes devem ser definidas como públicas e os objetos devem ser definidos como públicos estáticos.

   

Pacotes existentes

Pode criar UDFs .NET Standard em qualquer IDE que preferir e invocá-los a partir da sua consulta Azure Stream Analytics. Primeiro, compila o teu código e empacota todas as DLLs. O formato do pacote tem o caminho /UserCustomCode/CLR/*. Depois, faz upload UserCustomCode.zip para a raiz do contentor na tua conta de armazenamento Azure.

Depois de os pacotes assembly zip serem carregados para a sua conta de armazenamento Azure, pode usar as funções nas consultas Azure Stream Analytics. Tudo o que precisa de fazer é incluir a informação de armazenamento na configuração do trabalho Stream Analytics. Não podes testar a função localmente com esta opção porque as ferramentas do Visual Studio não descarregam o teu pacote. O caminho do pacote é interpretado diretamente pelo serviço.

Para configurar o caminho de montagem no ficheiro de configuração do trabalho, JobConfig.json:

Expanda a secção Configuração de Código Definido pelo Utilizador e preencha a configuração com os seguintes valores sugeridos:

Registo de utilizadores

O mecanismo de registo permite-lhe capturar informações personalizadas enquanto um trabalho está a correr. Pode usar dados de registo para depurar ou avaliar a correção do código personalizado em tempo real.

A StreamingContext classe permite-lhe publicar informação de diagnóstico usando a StreamingDiagnostics.WriteError função. O código abaixo mostra a interface exposta pelo Azure Stream Analytics.

public abstract class StreamingContext
{
    public abstract StreamingDiagnostics Diagnostics { get; }
}

public abstract class StreamingDiagnostics
{
    public abstract void WriteError(string briefMessage, string detailedMessage);
}

StreamingContext é passada como parâmetro de entrada ao método UDF e pode ser usada dentro da UDF para publicar informação de registo personalizada. No exemplo abaixo, MyUdfMethod define uma entrada de dados , que é fornecida pela consulta, e uma entrada de contexto como o StreamingContext, fornecido pelo motor de execução.

public static long MyUdfMethod(long data, StreamingContext context)
{
    // write log
    context.Diagnostics.WriteError("User Log", "This is a log message");
    
    return data;
}

O StreamingContext valor não precisa de ser passado pela consulta SQL. O Azure Stream Analytics fornece automaticamente um objeto de contexto se houver um parâmetro de entrada. O uso do MyUdfMethod não muda, como mostrado na consulta seguinte:

SELECT udf.MyUdfMethod(input.value) as udfValue FROM input

Pode aceder às mensagens de registo através dos registos de diagnóstico.

Limitações

A pré-visualização da UDF apresenta atualmente as seguintes limitações:

• Os UDFs do .NET Standard só podem ser criados em Visual Studio Code ou Visual Studio e publicados no Azure. As versões apenas de leitura dos UDFs do .NET Standard podem ser visualizadas em Funções no portal Azure. A autoria de funções padrão .NET não é suportada no portal Azure.

• O editor de consultas do portal Azure mostra um erro ao usar o .NET Standard UDF no portal.

• Acione endpoints REST externos, por exemplo, ao realizar uma consulta de IP reverso ou ao extrair dados de referência de uma fonte externa.

• Como o código personalizado partilha o contexto com o motor Azure Stream Analytics, o código personalizado não pode referenciar nada que tenha um namespace/dll_name conflituoso com o código do Azure Stream Analytics. Por exemplo, não podes referenciar o Json do Newtonsoft.

• Os ficheiros de suporte incluídos no projeto são copiados para o ficheiro zip User Custom Code, que é usado quando publica o trabalho na cloud. Quando descompactados, todos os ficheiros nas subpastas são copiados diretamente para a raiz da pasta User Custom Code na cloud. O fecho é "achatado" quando descomprimido.

• O User Custom Code não suporta pastas vazias. Não adicione pastas vazias aos ficheiros de suporte no projeto.

Próximos passos

• Tutorial: Escreva uma função definida pelo utilizador em C# para um trabalho Azure Stream Analytics (Pré-visualização)
• Tutorial: Azure Stream Analytics Funções definidas pelo utilizador em JavaScript
• Criar uma tarefa "Azure Stream Analytics" no Visual Studio Code